From 3ad69cf26a061afb89e80647e03b48326b10fb0e Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 16:06:49 +0800
Subject: [PATCH 001/133] Executors move files through in-container exec so
 symlinks cannot reach the host; 12 contract questions

---
 packages/server/src/executor/contract.ts | 212 ++++++++++++++++++++++-
 packages/server/src/executor/docker.ts   | 211 +++++++++++++++++++---
 packages/server/src/executor/executor.ts |  33 ++++
 packages/server/src/executor/fake.ts     |  83 ++++++++-
 4 files changed, 504 insertions(+), 35 deletions(-)

diff --git a/packages/server/src/executor/contract.ts b/packages/server/src/executor/contract.ts
index 2da84cf..3c2f7e5 100644
--- a/packages/server/src/executor/contract.ts
+++ b/packages/server/src/executor/contract.ts
@@ -1,7 +1,16 @@
 import { randomUUID } from 'node:crypto';
-import { EXEC_OUTPUT_LIMIT_BYTES } from '@dormice/shared';
+import {
+  EXEC_OUTPUT_LIMIT_BYTES,
+  FILE_SIZE_LIMIT_BYTES,
+} from '@dormice/shared';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import type { ContainerState, Executor } from './executor';
+import {
+  type ContainerState,
+  type Executor,
+  FileNotFoundError,
+  FileTooLargeError,
+  NotAFileError,
+} from './executor';
 
 /**
  * What a contract run needs beyond the executor itself: a way to stage the
@@ -376,5 +385,204 @@ export function describeExecutorContract(
       },
       timeoutMs,
     );
+
+    it(
+      'writeFiles then readFile round-trips text',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: '/home/user/hello.txt', content: Buffer.from('hello\n') },
+        ]);
+        const read = await executor.readFile(id, '/home/user/hello.txt');
+        expect(read.toString('utf8')).toBe('hello\n');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'file content round-trips byte-exact, binary included',
+      async () => {
+        const id = await fresh();
+        // Every byte value, repeated — any encoding sloppiness (utf8 coercion,
+        // base64 mangling, CR/LF translation) breaks the exact comparison.
+        const bytes = Buffer.alloc(256 * 64);
+        for (let i = 0; i < bytes.length; i++) bytes[i] = i % 256;
+        await executor.writeFiles(id, [
+          { path: '/home/user/blob.bin', content: bytes },
+        ]);
+        const read = await executor.readFile(id, '/home/user/blob.bin');
+        expect(read.equals(bytes)).toBe(true);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'writeFiles writes the whole batch',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: '/home/user/a.txt', content: Buffer.from('a') },
+          { path: '/home/user/b.txt', content: Buffer.from('b') },
+          { path: '/home/user/c.txt', content: Buffer.from('c') },
+        ]);
+        expect(
+          (await executor.readFile(id, '/home/user/a.txt')).toString(),
+        ).toBe('a');
+        expect(
+          (await executor.readFile(id, '/home/user/b.txt')).toString(),
+        ).toBe('b');
+        expect(
+          (await executor.readFile(id, '/home/user/c.txt')).toString(),
+        ).toBe('c');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'relative paths resolve against /home/user',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: 'rel.txt', content: Buffer.from('via relative') },
+        ]);
+        const read = await executor.readFile(id, '/home/user/rel.txt');
+        expect(read.toString('utf8')).toBe('via relative');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'writeFiles creates missing parent directories',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          {
+            path: '/home/user/deep/er/nested.txt',
+            content: Buffer.from('deep'),
+          },
+        ]);
+        const read = await executor.readFile(
+          id,
+          '/home/user/deep/er/nested.txt',
+        );
+        expect(read.toString('utf8')).toBe('deep');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'writing an existing path overwrites it',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: '/home/user/v.txt', content: Buffer.from('first') },
+        ]);
+        await executor.writeFiles(id, [
+          { path: '/home/user/v.txt', content: Buffer.from('second') },
+        ]);
+        const read = await executor.readFile(id, '/home/user/v.txt');
+        expect(read.toString('utf8')).toBe('second');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'files live on the disk: they survive stop, start, even a vanished container',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: '/home/user/keep.txt', content: Buffer.from('still here') },
+        ]);
+        await executor.freeze(id);
+        await executor.stop(id);
+        // The container object itself is lost (a prune) — the disk, which
+        // holds the files, is the sandbox's actual body.
+        await subject.vanishContainer(id);
+        await executor.start(id);
+        const read = await executor.readFile(id, '/home/user/keep.txt');
+        expect(read.toString('utf8')).toBe('still here');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'readFile on a missing path throws FileNotFoundError',
+      async () => {
+        const id = await fresh();
+        const missing = '/home/user/absent.txt';
+        const error = await executor.readFile(id, missing).catch((e) => e);
+        expect(error).toBeInstanceOf(FileNotFoundError);
+        expect(error.message).toBe(`no such file: ${missing}`);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'readFile on a directory throws NotAFileError',
+      async () => {
+        const id = await fresh();
+        // /home/user exists as a directory in every sandbox by construction.
+        const error = await executor.readFile(id, '/home/user').catch((e) => e);
+        expect(error).toBeInstanceOf(NotAFileError);
+        expect(error.message).toBe('not a regular file: /home/user');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'writeFiles onto a directory throws NotAFileError',
+      async () => {
+        const id = await fresh();
+        const error = await executor
+          .writeFiles(id, [{ path: '/home/user', content: Buffer.from('x') }])
+          .catch((e) => e);
+        expect(error).toBeInstanceOf(NotAFileError);
+        expect(error.message).toBe('not a regular file: /home/user');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'readFile refuses an over-limit file with its actual size, never truncates',
+      async () => {
+        const id = await fresh();
+        // One byte over the line. The executor's write path is deliberately
+        // uncapped (the protocol schema is the write-cap adjudicator), which
+        // is exactly what lets the exam stage an over-limit file to read.
+        const size = FILE_SIZE_LIMIT_BYTES + 1;
+        await executor.writeFiles(id, [
+          { path: '/home/user/big.bin', content: Buffer.alloc(size) },
+        ]);
+        const error = await executor
+          .readFile(id, '/home/user/big.bin')
+          .catch((e) => e);
+        expect(error).toBeInstanceOf(FileTooLargeError);
+        expect(error.message).toBe(
+          `file too large: /home/user/big.bin is ${size} bytes, limit ${FILE_SIZE_LIMIT_BYTES}`,
+        );
+      },
+      timeoutMs * 4,
+    );
+
+    it(
+      'rejects file operations on a container that is not running',
+      async () => {
+        const paused = await fresh();
+        await executor.freeze(paused);
+        await expect(
+          executor.writeFiles(paused, [
+            { path: 'x.txt', content: Buffer.from('x') },
+          ]),
+        ).rejects.toThrow(/is paused, expected running/);
+        await expect(executor.readFile(paused, 'x.txt')).rejects.toThrow(
+          /is paused, expected running/,
+        );
+
+        await expect(executor.readFile(randomUUID(), 'x.txt')).rejects.toThrow(
+          /is absent, expected running/,
+        );
+      },
+      timeoutMs,
+    );
   });
 }
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 9a4ebbb..a923782 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -9,14 +9,22 @@ import {
 } from 'node:fs/promises';
 import path from 'node:path';
 import { Writable } from 'node:stream';
-import { EXEC_OUTPUT_LIMIT_BYTES } from '@dormice/shared';
+import {
+  EXEC_OUTPUT_LIMIT_BYTES,
+  FILE_SIZE_LIMIT_BYTES,
+  resolveSandboxPath,
+} from '@dormice/shared';
 import Docker from 'dockerode';
 import { execa } from 'execa';
-import type {
-  ContainerState,
-  ExecOptions,
-  ExecResult,
-  Executor,
+import {
+  type ContainerState,
+  type ExecOptions,
+  type ExecResult,
+  type Executor,
+  FileNotFoundError,
+  FileTooLargeError,
+  type FileToWrite,
+  NotAFileError,
 } from './executor';
 
 /**
@@ -45,6 +53,45 @@ export function containerName(sandboxId: string): string {
   return `sbx-${sandboxId}`;
 }
 
+/**
+ * In-container deadline for file operations, same mechanism as exec's
+ * (host-side disconnects cannot kill an in-container process). Not a user
+ * knob: 16 MiB on a local ext4 is subsecond work — this guard only exists
+ * so a pathological target cannot hang the daemon's request forever.
+ */
+const FILE_OP_TIMEOUT_SECONDS = 60;
+
+/**
+ * The file-op scripts talk back through exit codes of our choosing — private
+ * numbers between the daemon and its own script, no user command runs inside.
+ * They map 1:1 onto the typed file errors both executors must throw.
+ */
+const NO_SUCH_FILE_EXIT = 44;
+const NOT_A_FILE_EXIT = 45;
+const TOO_LARGE_EXIT = 46;
+
+/**
+ * $1 = absolute path. Refuses a target that exists but is not a regular
+ * file (directory, FIFO — `cat >` into a FIFO would block forever), creates
+ * the parents, then streams stdin into the file. Runs as uid 1000, so
+ * in-sandbox permissions apply honestly, and path resolution — symlinks
+ * included — happens inside the container, where there is no host to
+ * escape to.
+ */
+const WRITE_FILE_SCRIPT = [
+  `[ ! -e "$1" ] || [ -f "$1" ] || exit ${NOT_A_FILE_EXIT}`,
+  'mkdir -p -- "$(dirname -- "$1")" && exec cat > "$1"',
+].join('\n');
+
+/** $1 = absolute path, $2 = size limit in bytes. Size gate before content: an over-limit file is refused, never truncated. */
+const READ_FILE_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  `[ -f "$1" ] || exit ${NOT_A_FILE_EXIT}`,
+  'size=$(stat -c %s -- "$1") || exit 1',
+  `[ "$size" -le "$2" ] || { echo "$size" >&2; exit ${TOO_LARGE_EXIT}; }`,
+  'exec cat -- "$1"',
+].join('\n');
+
 /**
  * Docker reports seven statuses; the executor's contract knows three. With
  * RestartPolicy "no" a container never restarts on its own, so everything
@@ -94,8 +141,12 @@ class CappedBuffer extends Writable {
     callback();
   }
 
+  bytes(): Buffer {
+    return Buffer.concat(this.chunks);
+  }
+
   text(): string {
-    return Buffer.concat(this.chunks).toString('utf8');
+    return this.bytes().toString('utf8');
   }
 }
 
@@ -269,8 +320,8 @@ export class DockerExecutor implements Executor {
     // The deadline lives in-container, via GNU timeout: closing the
     // host-side stream cannot kill the in-container process (measured in
     // the predecessor system); only an in-container SIGKILL can. 137 = killed.
-    const exec = await container.exec({
-      Cmd: [
+    const run = await this.runInContainer(container, sandboxId, {
+      cmd: [
         'timeout',
         '--signal=KILL',
         String(opts.timeoutSeconds),
@@ -278,28 +329,140 @@ export class DockerExecutor implements Executor {
         '-c',
         opts.command,
       ],
+      outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+      workingDir: opts.cwd,
+      env: opts.env,
+    });
+    return {
+      exitCode: run.exitCode,
+      stdout: run.stdout.text(),
+      stderr: run.stderr.text(),
+      stdoutTruncated: run.stdout.truncated,
+      stderrTruncated: run.stderr.truncated,
+    };
+  }
+
+  async writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void> {
+    const containerId = await this.expectState(sandboxId, 'running');
+    const container = this.docker.getContainer(containerId);
+    // In array order, failing fast — the batch saves round-trips, it is not
+    // a transaction; earlier files stay written, as the protocol documents.
+    for (const file of files) {
+      const path = resolveSandboxPath(file.path);
+      const run = await this.runInContainer(container, sandboxId, {
+        cmd: [
+          'timeout',
+          '--signal=KILL',
+          String(FILE_OP_TIMEOUT_SECONDS),
+          'bash',
+          '-c',
+          WRITE_FILE_SCRIPT,
+          'bash',
+          path,
+        ],
+        outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+        stdin: file.content,
+      });
+      if (run.exitCode === NOT_A_FILE_EXIT) {
+        throw new NotAFileError(`not a regular file: ${path}`);
+      }
+      if (run.exitCode !== 0) {
+        throw new Error(
+          `writing ${path} in ${sandboxId} failed (exit ${run.exitCode}): ${run.stderr.text().trim()}`,
+        );
+      }
+    }
+  }
+
+  async readFile(sandboxId: string, path: string): Promise<Buffer> {
+    const resolved = resolveSandboxPath(path);
+    const containerId = await this.expectState(sandboxId, 'running');
+    const container = this.docker.getContainer(containerId);
+    const run = await this.runInContainer(container, sandboxId, {
+      cmd: [
+        'timeout',
+        '--signal=KILL',
+        String(FILE_OP_TIMEOUT_SECONDS),
+        'bash',
+        '-c',
+        READ_FILE_SCRIPT,
+        'bash',
+        resolved,
+        String(FILE_SIZE_LIMIT_BYTES),
+      ],
+      outputCap: FILE_SIZE_LIMIT_BYTES,
+    });
+    if (run.exitCode === NO_SUCH_FILE_EXIT) {
+      throw new FileNotFoundError(`no such file: ${resolved}`);
+    }
+    if (run.exitCode === NOT_A_FILE_EXIT) {
+      throw new NotAFileError(`not a regular file: ${resolved}`);
+    }
+    if (run.exitCode === TOO_LARGE_EXIT) {
+      const size = Number(run.stderr.text().trim());
+      throw new FileTooLargeError(
+        `file too large: ${resolved} is ${size} bytes, limit ${FILE_SIZE_LIMIT_BYTES}`,
+      );
+    }
+    if (run.exitCode !== 0) {
+      throw new Error(
+        `reading ${resolved} in ${sandboxId} failed (exit ${run.exitCode}): ${run.stderr.text().trim()}`,
+      );
+    }
+    if (run.stdout.truncated) {
+      // The size gate passed but the file grew past the cap before cat
+      // finished — rare, but delivering a silently cut file is never right.
+      throw new FileTooLargeError(
+        `file too large: ${resolved} exceeds limit ${FILE_SIZE_LIMIT_BYTES}`,
+      );
+    }
+    return run.stdout.bytes();
+  }
+
+  /**
+   * The one exec pipeline: start, demux, optionally feed stdin (ending the
+   * stream is what delivers EOF to the in-container reader), wait for the
+   * stream, then poll for the exit code — the engine records it a beat
+   * after the stream ends, the same measured lag as kill vs exited in
+   * stop(). Tty stays off: the multiplexed stream is what demuxStream can
+   * split back into distinct stdout and stderr.
+   */
+  private async runInContainer(
+    container: Docker.Container,
+    sandboxId: string,
+    spec: {
+      cmd: string[];
+      outputCap: number;
+      stdin?: Buffer;
+      workingDir?: string;
+      env?: Record<string, string>;
+    },
+  ): Promise<{ exitCode: number; stdout: CappedBuffer; stderr: CappedBuffer }> {
+    const exec = await container.exec({
+      Cmd: spec.cmd,
+      AttachStdin: spec.stdin !== undefined,
       AttachStdout: true,
       AttachStderr: true,
-      WorkingDir: opts.cwd,
-      Env: opts.env
-        ? Object.entries(opts.env).map(([key, value]) => `${key}=${value}`)
+      WorkingDir: spec.workingDir,
+      Env: spec.env
+        ? Object.entries(spec.env).map(([key, value]) => `${key}=${value}`)
         : undefined,
       User: 'user',
     });
-    // Tty stays off: the multiplexed stream is what demuxStream can split
-    // back into distinct stdout and stderr.
-    const stream = await exec.start({});
-    const stdout = new CappedBuffer(EXEC_OUTPUT_LIMIT_BYTES);
-    const stderr = new CappedBuffer(EXEC_OUTPUT_LIMIT_BYTES);
+    const stream = await exec.start(
+      spec.stdin !== undefined ? { hijack: true, stdin: true } : {},
+    );
+    const stdout = new CappedBuffer(spec.outputCap);
+    const stderr = new CappedBuffer(spec.outputCap);
     this.docker.modem.demuxStream(stream, stdout, stderr);
+    if (spec.stdin !== undefined) {
+      stream.end(spec.stdin);
+    }
     await new Promise<void>((resolve, reject) => {
       stream.on('end', resolve);
       stream.on('close', resolve);
       stream.on('error', reject);
     });
-    // The engine records the exit code a beat after the stream ends — the
-    // same measured lag as kill vs exited in stop(). Poll briefly instead
-    // of reading a null.
     let info = await exec.inspect();
     for (let i = 0; info.Running || info.ExitCode === null; i++) {
       if (i >= 20) {
@@ -310,13 +473,7 @@ export class DockerExecutor implements Executor {
       await new Promise((resolve) => setTimeout(resolve, 50));
       info = await exec.inspect();
     }
-    return {
-      exitCode: info.ExitCode,
-      stdout: stdout.text(),
-      stderr: stderr.text(),
-      stdoutTruncated: stdout.truncated,
-      stderrTruncated: stderr.truncated,
-    };
+    return { exitCode: info.ExitCode, stdout, stderr };
   }
 
   private imagePath(sandboxId: string): string {
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index 3963e22..b85dd98 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -28,6 +28,21 @@ export interface ExecResult {
   stderrTruncated: boolean;
 }
 
+export interface FileToWrite {
+  /** Absolute, or relative to /home/user — resolveSandboxPath's rules. */
+  path: string;
+  content: Buffer;
+}
+
+/**
+ * The file-op error taxonomy, shared by both executors down to the message
+ * (the contract exam holds them to it) and mapped to HTTP statuses by the
+ * route: not found -> 404, not a regular file -> 400, too large -> 413.
+ */
+export class FileNotFoundError extends Error {}
+export class NotAFileError extends Error {}
+export class FileTooLargeError extends Error {}
+
 /**
  * The executor is where lifecycle decisions become physical reality:
  * containers created, paused, stopped. The daemon's decision logic (the
@@ -86,4 +101,22 @@ export interface Executor {
    * drained and dropped, and the truncation reported.
    */
   exec(sandboxId: string, opts: ExecOptions): Promise<ExecResult>;
+  /**
+   * Writes every file in the batch, in order, failing fast — earlier files
+   * stay written (a batch saves round-trips, it is not a transaction).
+   * Parent directories are created; existing files are overwritten. Requires
+   * state `running`, like exec. Paths resolve inside the container — a
+   * symlink planted by the sandbox can only point at the sandbox's own view,
+   * never the host's; this is why file I/O goes through the container and
+   * not through the host-side mount. No size check here: the protocol
+   * schema is the single write-cap adjudicator.
+   */
+  writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void>;
+  /**
+   * Returns one file's bytes. Requires state `running`. Throws the typed
+   * file errors above; a file over FILE_SIZE_LIMIT_BYTES is refused, never
+   * truncated — a truncated file is a corrupt file. The read cap lives here
+   * and not in the schema because only the executor can observe the size.
+   */
+  readFile(sandboxId: string, path: string): Promise<Buffer>;
 }
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index 37d2d55..4f54d93 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -1,11 +1,26 @@
-import { EXEC_OUTPUT_LIMIT_BYTES } from '@dormice/shared';
-import type {
-  ContainerState,
-  ExecOptions,
-  ExecResult,
-  Executor,
+import {
+  EXEC_OUTPUT_LIMIT_BYTES,
+  FILE_SIZE_LIMIT_BYTES,
+  resolveSandboxPath,
+} from '@dormice/shared';
+import {
+  type ContainerState,
+  type ExecOptions,
+  type ExecResult,
+  type Executor,
+  FileNotFoundError,
+  FileTooLargeError,
+  type FileToWrite,
+  NotAFileError,
 } from './executor';
 
+/**
+ * Directories the base image guarantees in every sandbox. The fake's
+ * filesystem is otherwise implicit — a directory exists exactly when some
+ * file lives under it, which is all mkdir -p semantics leave observable.
+ */
+const BUILTIN_DIRS = new Set(['/', '/home', '/home/user', '/tmp']);
+
 /**
  * In-memory stand-in for the Docker+gVisor executor. Not a throwaway: it is
  * the permanent test double — unit tests and local development run on it;
@@ -18,6 +33,13 @@ import type {
 export class FakeExecutor implements Executor {
   private readonly containers = new Map<string, ContainerState>();
   private readonly disks = new Set<string>();
+  /**
+   * Keyed like disks, not containers: files are the disk's content, so they
+   * survive stop, start, and a vanished container object, and die only when
+   * the disk does. That is the "the disk is the sandbox's body" invariant,
+   * modeled where it physically lives.
+   */
+  private readonly files = new Map<string, Map<string, Buffer>>();
 
   /** Test hook: what does "reality" say about this sandbox? */
   stateOf(sandboxId: string): ContainerState | undefined {
@@ -48,6 +70,7 @@ export class FakeExecutor implements Executor {
       throw new Error(`container ${sandboxId} already exists`);
     }
     this.disks.add(sandboxId);
+    this.files.set(sandboxId, new Map());
     this.containers.set(sandboxId, 'running');
   }
 
@@ -90,6 +113,7 @@ export class FakeExecutor implements Executor {
     // hearing.
     const hadContainer = this.containers.delete(sandboxId);
     const hadDisk = this.disks.delete(sandboxId);
+    this.files.delete(sandboxId);
     if (!hadContainer && !hadDisk) {
       throw new Error(`container ${sandboxId} is absent, cannot destroy`);
     }
@@ -107,6 +131,7 @@ export class FakeExecutor implements Executor {
   async removeDisk(sandboxId: string): Promise<void> {
     // Idempotent by contract: an absent disk already is the goal state.
     this.disks.delete(sandboxId);
+    this.files.delete(sandboxId);
   }
 
   async exec(sandboxId: string, opts: ExecOptions): Promise<ExecResult> {
@@ -127,6 +152,52 @@ export class FakeExecutor implements Executor {
     }
   }
 
+  async writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void> {
+    this.expect(sandboxId, 'running');
+    const disk = this.files.get(sandboxId) ?? new Map<string, Buffer>();
+    this.files.set(sandboxId, disk);
+    for (const file of files) {
+      const path = resolveSandboxPath(file.path);
+      if (this.isDirectory(disk, path)) {
+        throw new NotAFileError(`not a regular file: ${path}`);
+      }
+      // Copy on the way in: the caller's buffer is theirs to reuse.
+      disk.set(path, Buffer.from(file.content));
+    }
+  }
+
+  async readFile(sandboxId: string, path: string): Promise<Buffer> {
+    this.expect(sandboxId, 'running');
+    const disk = this.files.get(sandboxId) ?? new Map<string, Buffer>();
+    const resolved = resolveSandboxPath(path);
+    const content = disk.get(resolved);
+    if (content !== undefined) {
+      if (content.length > FILE_SIZE_LIMIT_BYTES) {
+        throw new FileTooLargeError(
+          `file too large: ${resolved} is ${content.length} bytes, limit ${FILE_SIZE_LIMIT_BYTES}`,
+        );
+      }
+      return Buffer.from(content);
+    }
+    if (this.isDirectory(disk, resolved)) {
+      throw new NotAFileError(`not a regular file: ${resolved}`);
+    }
+    throw new FileNotFoundError(`no such file: ${resolved}`);
+  }
+
+  /**
+   * A path is a directory when the image ships it or some file lives under
+   * it — the same observable truth mkdir -p leaves behind on a real disk.
+   */
+  private isDirectory(disk: Map<string, Buffer>, path: string): boolean {
+    if (BUILTIN_DIRS.has(path)) return true;
+    const prefix = path === '/' ? '/' : `${path}/`;
+    for (const existing of disk.keys()) {
+      if (existing.startsWith(prefix)) return true;
+    }
+    return false;
+  }
+
   private expect(sandboxId: string, wanted: ContainerState): void {
     const actual = this.containers.get(sandboxId);
     if (actual !== wanted) {

From c5fc5eb0e07dd5947608679cc2195dece3b1108b Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 16:06:49 +0800
Subject: [PATCH 002/133] POST /writeFiles and /readFile run inside the key's
 slot, typed file errors map onto 404/400/413

---
 packages/server/src/app.test.ts         | 170 +++++++++++++++++++++++-
 packages/server/src/routes/sandboxes.ts | 118 ++++++++++++++--
 2 files changed, 273 insertions(+), 15 deletions(-)

diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index dc1ef39..853c99b 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -1,5 +1,8 @@
 import { fileURLToPath } from 'node:url';
-import { DEFAULT_LIFECYCLE_POLICY } from '@dormice/shared';
+import {
+  DEFAULT_LIFECYCLE_POLICY,
+  FILE_SIZE_LIMIT_BYTES,
+} from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { buildApp } from './app';
 import { loadConfig } from './config';
@@ -545,6 +548,171 @@ describe('POST /execCommand', () => {
   });
 });
 
+describe('POST /writeFiles and /readFile', () => {
+  it('round-trips content through base64, resolving paths to absolute', async () => {
+    const { app } = testApp();
+    await acquire(app, { userKey: 'alice' });
+    // Every byte value: any utf8 coercion or base64 sloppiness breaks this.
+    const bytes = Buffer.alloc(256);
+    for (let i = 0; i < 256; i++) bytes[i] = i;
+
+    const write = await rpc(app, '/writeFiles', {
+      userKey: 'alice',
+      files: [
+        {
+          path: 'notes.txt',
+          contentBase64: Buffer.from('hi\n').toString('base64'),
+        },
+        {
+          path: '/home/user/blob.bin',
+          contentBase64: bytes.toString('base64'),
+        },
+      ],
+    });
+    expect(write.statusCode).toBe(200);
+    expect(write.json()).toEqual({
+      files: [
+        { path: '/home/user/notes.txt' },
+        { path: '/home/user/blob.bin' },
+      ],
+    });
+
+    const read = await rpc(app, '/readFile', {
+      userKey: 'alice',
+      path: 'blob.bin',
+    });
+    expect(read.statusCode).toBe(200);
+    expect(read.json().path).toBe('/home/user/blob.bin');
+    expect(Buffer.from(read.json().contentBase64, 'base64').equals(bytes)).toBe(
+      true,
+    );
+  });
+
+  it('answers an unknown key with a 404 on both verbs, never a silent create', async () => {
+    const { app } = testApp();
+    const write = await rpc(app, '/writeFiles', {
+      userKey: 'nobody',
+      files: [{ path: 'x', contentBase64: 'eA==' }],
+    });
+    expect(write.statusCode).toBe(404);
+    const read = await rpc(app, '/readFile', { userKey: 'nobody', path: 'x' });
+    expect(read.statusCode).toBe(404);
+    expect(read.json().message).toMatch(/no sandbox for key/);
+  });
+
+  it('wakes a frozen sandbox before touching files', async () => {
+    const { app, db, executor, locks } = testApp();
+    const created = (await acquire(app, { userKey: 'alice' })).json();
+    await scanOnce(
+      db,
+      executor,
+      locks,
+      after(
+        created.sandbox.lastActiveAt,
+        DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
+      ),
+    );
+    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+
+    const res = await rpc(app, '/writeFiles', {
+      userKey: 'alice',
+      files: [{ path: 'woke.txt', contentBase64: 'eA==' }],
+    });
+    expect(res.statusCode).toBe(200);
+    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('running');
+  });
+
+  it('maps the typed file errors onto 404, 400 and 413', async () => {
+    const { app, executor } = testApp();
+    const created = (await acquire(app, { userKey: 'alice' })).json();
+
+    const missing = await rpc(app, '/readFile', {
+      userKey: 'alice',
+      path: 'absent.txt',
+    });
+    expect(missing.statusCode).toBe(404);
+    expect(missing.json().message).toBe('no such file: /home/user/absent.txt');
+
+    const directory = await rpc(app, '/readFile', {
+      userKey: 'alice',
+      path: '/home/user',
+    });
+    expect(directory.statusCode).toBe(400);
+    expect(directory.json().message).toBe('not a regular file: /home/user');
+
+    // Staged straight through the executor: its write path is deliberately
+    // uncapped (the schema is the write-cap adjudicator), which is what
+    // lets an over-limit file exist to be read.
+    const size = FILE_SIZE_LIMIT_BYTES + 1;
+    await executor.writeFiles(created.sandbox.sandboxId, [
+      { path: 'big.bin', content: Buffer.alloc(size) },
+    ]);
+    const big = await rpc(app, '/readFile', {
+      userKey: 'alice',
+      path: 'big.bin',
+    });
+    expect(big.statusCode).toBe(413);
+    expect(big.json().message).toBe(
+      `file too large: /home/user/big.bin is ${size} bytes, limit ${FILE_SIZE_LIMIT_BYTES}`,
+    );
+  });
+
+  it('rejects an over-limit write with a 400 from the schema, not a body-limit 413', async () => {
+    // One byte over, as base64 — ~21 MiB of body. Passing the raised route
+    // bodyLimit and failing the per-file refine proves both gates sit where
+    // they should: total bytes at the body limit, per-file size in the schema.
+    const { app } = testApp();
+    await acquire(app, { userKey: 'alice' });
+    const res = await rpc(app, '/writeFiles', {
+      userKey: 'alice',
+      files: [
+        {
+          path: 'big.bin',
+          contentBase64: Buffer.alloc(FILE_SIZE_LIMIT_BYTES + 3).toString(
+            'base64',
+          ),
+        },
+      ],
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().message).toMatch(/exceeds the \d+-byte limit/);
+  });
+
+  it('rejects malformed requests with the protocol {message} shape', async () => {
+    const { app } = testApp();
+    await acquire(app, { userKey: 'alice' });
+    const bad = [
+      ['/writeFiles', { userKey: 'alice', files: [] }],
+      ['/writeFiles', { userKey: 'alice' }],
+      [
+        '/writeFiles',
+        { userKey: 'alice', files: [{ path: '', contentBase64: 'eA==' }] },
+      ],
+      [
+        '/writeFiles',
+        {
+          userKey: 'alice',
+          files: [{ path: 'a\0b', contentBase64: 'eA==' }],
+        },
+      ],
+      [
+        '/writeFiles',
+        {
+          userKey: 'alice',
+          files: [{ path: 'x', contentBase64: '!!not-b64' }],
+        },
+      ],
+      ['/readFile', { userKey: 'alice' }],
+      ['/readFile', { userKey: 'alice', path: '' }],
+    ] as const;
+    for (const [url, payload] of bad) {
+      const res = await rpc(app, url, payload as Record<string, unknown>);
+      expect(res.statusCode).toBe(400);
+      expect(Object.keys(res.json())).toEqual(['message']);
+    }
+  });
+});
+
 describe('POST /listSandboxes', () => {
   it('requires a token', async () => {
     const res = await testApp().app.inject({
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index 15761a5..ba346df 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -6,9 +6,15 @@ import {
   execCommandResponseSchema,
   type LifecyclePolicy,
   listSandboxesResponseSchema,
+  readFileRequestSchema,
+  readFileResponseSchema,
   releaseSandboxRequestSchema,
   releaseSandboxResponseSchema,
+  resolveSandboxPath,
   type Sandbox,
+  WRITE_FILES_BODY_LIMIT_BYTES,
+  writeFilesRequestSchema,
+  writeFilesResponseSchema,
 } from '@dormice/shared';
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import { ZodError, z } from 'zod';
@@ -22,7 +28,12 @@ import {
   touch,
 } from '../db/ledger';
 import type { SandboxRow } from '../db/schema';
-import type { Executor } from '../executor/executor';
+import {
+  type Executor,
+  FileNotFoundError,
+  FileTooLargeError,
+  NotAFileError,
+} from '../executor/executor';
 import { httpError } from '../http-error';
 import type { KeyedQueue } from '../keyed-queue';
 import { releaseSandbox, wakeSandbox } from '../lifecycle';
@@ -132,6 +143,23 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     });
   }
 
+  // Shared by every verb that uses an existing sandbox (exec, file ops):
+  // 404 for an unknown key — these verbs are not creators, an unknown key
+  // is more likely a typo than an intent to build a sandbox as a side
+  // effect — then wake whatever cold state the sandbox is in and refresh
+  // its idle clock. Must be called while holding the key's queue slot.
+  async function wakeForUse(userKey: string): Promise<SandboxRow> {
+    const existing = findByUserKey(db, userKey);
+    if (!existing) {
+      throw httpError(
+        404,
+        `no sandbox for key "${userKey}" — acquire it first`,
+      );
+    }
+    const awake = await wakeSandbox(db, executor, existing);
+    return touch(db, awake.sandboxId);
+  }
+
   // Native API convention: RPC style — every operation is a POST to a
   // camelCase verb route, input and output entirely in the body, route name
   // identical to the SDK method name. By construction this can never collide
@@ -208,19 +236,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       // whole duration. The heartbeat keeps the scanner away; a concurrent
       // release mid-exec destroys the container and this exec fails with
       // the executor's honest error — accepted, not defended against.
-      const row = await locks.run(userKey, async () => {
-        const existing = findByUserKey(db, userKey);
-        if (!existing) {
-          // exec is not a creator: an unknown key here is more likely a
-          // typo than an intent to build a sandbox as a side effect.
-          throw httpError(
-            404,
-            `no sandbox for key "${userKey}" — acquire it first`,
-          );
-        }
-        const awake = await wakeSandbox(db, executor, existing);
-        return touch(db, awake.sandboxId);
-      });
+      const row = await locks.run(userKey, () => wakeForUse(userKey));
 
       const stopHeartbeat = startExecHeartbeat(
         db,
@@ -247,6 +263,80 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     },
   );
 
+  // Maps the executor's typed file errors onto HTTP, message untouched.
+  function throwFileHttpError(error: unknown): never {
+    if (error instanceof FileNotFoundError) throw httpError(404, error.message);
+    if (error instanceof NotAFileError) throw httpError(400, error.message);
+    if (error instanceof FileTooLargeError) throw httpError(413, error.message);
+    throw error;
+  }
+
+  // Both file verbs run ENTIRELY inside the key's queue slot, unlike exec:
+  // a file operation's work is bounded (16 MiB against a local ext4 —
+  // seconds at worst), so holding the slot is cheap and buys the same
+  // guarantees acquire enjoys — the scanner cannot freeze the sandbox
+  // mid-write and a concurrent release queues up behind us instead of
+  // destroying the container under our feet. No heartbeat needed.
+  app.post(
+    '/writeFiles',
+    {
+      // The one total gate for a batch; per-file size is the schema's job.
+      bodyLimit: WRITE_FILES_BODY_LIMIT_BYTES,
+      schema: {
+        body: writeFilesRequestSchema,
+        response: { 200: writeFilesResponseSchema },
+      },
+    },
+    async (request) => {
+      const { userKey, files } = request.body;
+      return locks.run(userKey, async () => {
+        const row = await wakeForUse(userKey);
+        try {
+          await executor.writeFiles(
+            row.sandboxId,
+            files.map((file) => ({
+              path: file.path,
+              content: Buffer.from(file.contentBase64, 'base64'),
+            })),
+          );
+        } catch (error) {
+          throwFileHttpError(error);
+        }
+        touch(db, row.sandboxId);
+        return {
+          files: files.map((file) => ({ path: resolveSandboxPath(file.path) })),
+        };
+      });
+    },
+  );
+
+  app.post(
+    '/readFile',
+    {
+      schema: {
+        body: readFileRequestSchema,
+        response: { 200: readFileResponseSchema },
+      },
+    },
+    async (request) => {
+      const { userKey, path } = request.body;
+      return locks.run(userKey, async () => {
+        const row = await wakeForUse(userKey);
+        let content: Buffer;
+        try {
+          content = await executor.readFile(row.sandboxId, path);
+        } catch (error) {
+          throwFileHttpError(error);
+        }
+        touch(db, row.sandboxId);
+        return {
+          path: resolveSandboxPath(path),
+          contentBase64: content.toString('base64'),
+        };
+      });
+    },
+  );
+
   app.post(
     '/releaseSandbox',
     {

From 4a537a002cc4391138d43068f4bfb0176e2062a7 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 16:06:49 +0800
Subject: [PATCH 003/133] SDK writeFiles/readFile: strings travel as UTF-8,
 bytes byte-exact

---
 e2e/src/native.test.ts          | 69 +++++++++++++++++++++++++++++++++
 packages/sdk/src/client.test.ts | 34 ++++++++++++++++
 packages/sdk/src/client.ts      | 54 ++++++++++++++++++++++++++
 packages/sdk/src/index.ts       |  2 +
 4 files changed, 159 insertions(+)

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index b946f02..173e215 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -203,4 +203,73 @@ describe('native API over a real daemon', () => {
     expect(woken.sandbox.sandboxId).toBe(created.sandbox.sandboxId);
     expect(woken.sandbox.state).toBe('active');
   });
+
+  it('writes files in and reads them back byte-exact', async () => {
+    await client().acquireSandbox('files-key');
+    const bytes = new Uint8Array(256);
+    for (let i = 0; i < 256; i++) bytes[i] = i;
+
+    const written = await client().writeFiles('files-key', [
+      { path: 'hello.txt', content: 'hello from e2e\n' },
+      // A nested relative path: parents are created, /home/user is the base.
+      { path: 'nested/dir/blob.bin', content: bytes },
+    ]);
+    expect(written.files).toEqual([
+      { path: '/home/user/hello.txt' },
+      { path: '/home/user/nested/dir/blob.bin' },
+    ]);
+
+    const text = await client().readFile('files-key', '/home/user/hello.txt');
+    expect(new TextDecoder().decode(text.content)).toBe('hello from e2e\n');
+    const blob = await client().readFile('files-key', 'nested/dir/blob.bin');
+    expect(blob.content).toEqual(bytes);
+  });
+
+  it('surfaces the honest errors: missing file 404, directory 400', async () => {
+    await client().acquireSandbox('files-err-key');
+    await expect(
+      client().readFile('files-err-key', 'absent.txt'),
+    ).rejects.toMatchObject({
+      status: 404,
+      message: 'no such file: /home/user/absent.txt',
+    });
+    await expect(
+      client().readFile('files-err-key', '/home/user'),
+    ).rejects.toMatchObject({
+      status: 400,
+      message: 'not a regular file: /home/user',
+    });
+  });
+
+  it('reading a file wakes a frozen sandbox, and the file survived the cold', async () => {
+    await client().acquireSandbox('files-wake-key', {
+      freezeAfterSeconds: 1,
+      stopAfterSeconds: null,
+      archiveAfterSeconds: null,
+    });
+    await client().writeFiles('files-wake-key', [
+      { path: 'keep.txt', content: 'still here' },
+    ]);
+    // Watch it actually freeze from outside, on real wall-clock time.
+    const deadline = Date.now() + 15_000;
+    for (;;) {
+      const cold = (await client().listSandboxes()).find(
+        (s) => s.userKey === 'files-wake-key',
+      );
+      if (cold?.state === 'frozen') break;
+      if (Date.now() > deadline) {
+        throw new Error(
+          `sandbox never reached frozen; last observed: ${cold?.state}`,
+        );
+      }
+      await sleep(0.25);
+    }
+
+    const read = await client().readFile('files-wake-key', 'keep.txt');
+    expect(new TextDecoder().decode(read.content)).toBe('still here');
+    const observed = (await client().listSandboxes()).find(
+      (s) => s.userKey === 'files-wake-key',
+    );
+    expect(observed?.state).toBe('active');
+  });
 });
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 3cb60b9..994a502 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -212,6 +212,40 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
     );
   });
 
+  it('writes files — string and bytes — and reads them back exact', async () => {
+    await client.acquireSandbox('files-key');
+    const bytes = new Uint8Array(256);
+    for (let i = 0; i < 256; i++) bytes[i] = i;
+
+    const written = await client.writeFiles('files-key', [
+      // Multi-byte text: proves strings go through as UTF-8, not mangled.
+      { path: 'notes.txt', content: 'hello 文件\n' },
+      { path: '/home/user/blob.bin', content: bytes },
+    ]);
+    expect(written.files).toEqual([
+      { path: '/home/user/notes.txt' },
+      { path: '/home/user/blob.bin' },
+    ]);
+
+    const text = await client.readFile('files-key', 'notes.txt');
+    expect(text.path).toBe('/home/user/notes.txt');
+    expect(new TextDecoder().decode(text.content)).toBe('hello 文件\n');
+
+    const blob = await client.readFile('files-key', 'blob.bin');
+    expect(blob.content).toEqual(bytes);
+  });
+
+  it('surfaces the 404 for a missing file', async () => {
+    await client.acquireSandbox('files-key');
+    await expect(
+      client.readFile('files-key', 'no-such.txt'),
+    ).rejects.toMatchObject({
+      name: 'DormiceApiError',
+      status: 404,
+      message: 'no such file: /home/user/no-such.txt',
+    });
+  });
+
   it('releases a sandbox and reports idempotently', async () => {
     const created = await client.acquireSandbox('frank');
     expect(await client.releaseSandbox('frank')).toEqual({ released: true });
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index dff788b..4346046 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -7,8 +7,11 @@ import {
   type LifecyclePolicyOverride,
   listSandboxesResponseSchema,
   type ReleaseSandboxResponse,
+  readFileResponseSchema,
   releaseSandboxResponseSchema,
   type Sandbox,
+  type WriteFilesResponse,
+  writeFilesResponseSchema,
 } from '@dormice/shared';
 import { Agent, fetch, type Response } from 'undici';
 
@@ -32,6 +35,20 @@ export interface DormiceOptions {
   timeoutMs?: number;
 }
 
+export interface FileToWrite {
+  /** Absolute, or relative to /home/user. */
+  path: string;
+  /** A string is written as its UTF-8 bytes; a Uint8Array is written as-is. */
+  content: string | Uint8Array;
+}
+
+export interface ReadFileResult {
+  /** The path as resolved inside the sandbox, always absolute. */
+  path: string;
+  /** The file's exact bytes. Text? `new TextDecoder().decode(content)`. */
+  content: Uint8Array;
+}
+
 export interface ExecCommandOptions {
   /** In-container deadline; on expiry the command is SIGKILLed (exit 137). */
   timeoutSeconds?: number;
@@ -126,6 +143,43 @@ export class Dormice {
     return execCommandResponseSchema.parse(data);
   }
 
+  /**
+   * Writes a batch of files into the sandbox behind a user key, waking a
+   * cold sandbox first. Parents are created, existing files overwritten.
+   * Per-file cap is 16 MiB — content travels as base64 inside JSON; a big
+   * batch on a slow link may need a larger client `timeoutMs`.
+   */
+  async writeFiles(
+    userKey: string,
+    files: FileToWrite[],
+  ): Promise<WriteFilesResponse> {
+    const data = await this.rpc('writeFiles', {
+      userKey,
+      files: files.map((file) => ({
+        path: file.path,
+        contentBase64: Buffer.from(
+          typeof file.content === 'string'
+            ? new TextEncoder().encode(file.content)
+            : file.content,
+        ).toString('base64'),
+      })),
+    });
+    return writeFilesResponseSchema.parse(data);
+  }
+
+  /**
+   * Reads one file's bytes out of the sandbox. A file over the 16 MiB cap
+   * is refused by the daemon (413), never truncated.
+   */
+  async readFile(userKey: string, path: string): Promise<ReadFileResult> {
+    const data = await this.rpc('readFile', { userKey, path });
+    const parsed = readFileResponseSchema.parse(data);
+    return {
+      path: parsed.path,
+      content: new Uint8Array(Buffer.from(parsed.contentBase64, 'base64')),
+    };
+  }
+
   /** Native API convention: every operation is POST /<method>, body in, body out. */
   private async rpc(
     method: string,
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index 828851b..5f1cda1 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -7,4 +7,6 @@ export {
   DormiceApiError,
   type DormiceOptions,
   type ExecCommandOptions,
+  type FileToWrite,
+  type ReadFileResult,
 } from './client';

From c450f473422c407b6eaa7d9c724909d1032fc4cd Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 16:06:49 +0800
Subject: [PATCH 004/133] CLI: dor sandbox push and pull move one file each
 way, pull prints raw bytes

---
 e2e/src/cli.test.ts               | 24 +++++++++++++++
 packages/cli/src/commands.test.ts | 29 ++++++++++++++++++
 packages/cli/src/commands.ts      | 42 +++++++++++++++++++++++++-
 packages/cli/src/main.ts          | 49 +++++++++++++++++++++++++++++++
 4 files changed, 143 insertions(+), 1 deletion(-)

diff --git a/e2e/src/cli.test.ts b/e2e/src/cli.test.ts
index 09afcd3..3416576 100644
--- a/e2e/src/cli.test.ts
+++ b/e2e/src/cli.test.ts
@@ -1,5 +1,8 @@
 import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 import { Dormice } from '@dormice/sdk';
@@ -71,6 +74,27 @@ describe('dor CLI against a real daemon', () => {
     ).rejects.toMatchObject({ code: 3 });
   });
 
+  it('sandbox push and pull move a file in and back out through the real binary', async () => {
+    const sdk = new Dormice({
+      endpoint: inject('dormiceEndpoint'),
+      token: inject('dormiceToken'),
+    });
+    await sdk.acquireSandbox('cli-files-key');
+    const local = path.join(
+      await mkdtemp(path.join(tmpdir(), 'dor-e2e-')),
+      'in.txt',
+    );
+    await writeFile(local, 'through the CLI\n');
+
+    const pushed = await cli('sandbox', 'push', 'cli-files-key', local);
+    // No remotePath given: the local file name lands under /home/user.
+    expect(pushed.stdout).toContain('Wrote /home/user/in.txt (16 bytes).');
+
+    // No localPath given: raw bytes to stdout, untouched.
+    const pulled = await cli('sandbox', 'pull', 'cli-files-key', 'in.txt');
+    expect(pulled.stdout).toBe('through the CLI\n');
+  });
+
   it('fails honestly when the environment is missing', async () => {
     await expect(
       run('node', [CLI, 'sandbox', 'ls'], {
diff --git a/packages/cli/src/commands.test.ts b/packages/cli/src/commands.test.ts
index 29bab27..e95794f 100644
--- a/packages/cli/src/commands.test.ts
+++ b/packages/cli/src/commands.test.ts
@@ -11,8 +11,11 @@ import {
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import {
   clientFromEnv,
+  pullSavedMessage,
   sandboxExec,
   sandboxLs,
+  sandboxPull,
+  sandboxPush,
   sandboxRelease,
 } from './commands';
 
@@ -125,6 +128,32 @@ describe('sandbox commands over real HTTP', () => {
     await client.releaseSandbox('dave');
   });
 
+  it('push reports the resolved path and byte count', async () => {
+    await client.acquireSandbox('pusher');
+    const message = await sandboxPush(
+      client,
+      'pusher',
+      new TextEncoder().encode('hi'),
+      'notes.txt',
+    );
+    expect(message).toBe('Wrote /home/user/notes.txt (2 bytes).');
+    await client.releaseSandbox('pusher');
+  });
+
+  it('pull hands back the exact bytes; the save message is separate', async () => {
+    await client.acquireSandbox('puller');
+    const bytes = new Uint8Array([0, 1, 254, 255]);
+    await client.writeFiles('puller', [{ path: 'data.bin', content: bytes }]);
+
+    const result = await sandboxPull(client, 'puller', 'data.bin');
+    expect(result.path).toBe('/home/user/data.bin');
+    expect(result.content).toEqual(bytes);
+    expect(pullSavedMessage(result, 'local.bin')).toBe(
+      'Pulled /home/user/data.bin -> local.bin (4 bytes).',
+    );
+    await client.releaseSandbox('puller');
+  });
+
   it('release reports both outcomes of the idempotent destroy', async () => {
     await client.acquireSandbox('carol');
     expect(await sandboxRelease(client, 'carol')).toBe(
diff --git a/packages/cli/src/commands.ts b/packages/cli/src/commands.ts
index d1ba2c4..36d3210 100644
--- a/packages/cli/src/commands.ts
+++ b/packages/cli/src/commands.ts
@@ -1,4 +1,4 @@
-import { Dormice, type Sandbox } from '@dormice/sdk';
+import { Dormice, type ReadFileResult, type Sandbox } from '@dormice/sdk';
 
 /**
  * Builds the API client from the environment. The daemon's address and
@@ -97,6 +97,46 @@ export async function sandboxExec(
   return { stdout: result.stdout, stderr, exitCode: result.exitCode };
 }
 
+/**
+ * `dor sandbox push <userKey> <localPath> [remotePath]`: one local file into
+ * the sandbox. The bytes arrive here already read — main.ts owns the
+ * filesystem, this function owns the API call and the message.
+ */
+export async function sandboxPush(
+  client: Dormice,
+  userKey: string,
+  content: Uint8Array,
+  remotePath: string,
+): Promise<string> {
+  const { files } = await client.writeFiles(userKey, [
+    { path: remotePath, content },
+  ]);
+  const written = files[0]?.path ?? remotePath;
+  return `Wrote ${printable(written)} (${content.length} bytes).`;
+}
+
+/**
+ * `dor sandbox pull <userKey> <remotePath> [localPath]`: one file out of the
+ * sandbox. Returns the exact bytes; main.ts decides between a local file and
+ * raw stdout — raw on purpose, the same rule as exec output: these are the
+ * operator's own bytes, not a place to strip control characters.
+ */
+export async function sandboxPull(
+  client: Dormice,
+  userKey: string,
+  remotePath: string,
+): Promise<ReadFileResult> {
+  return client.readFile(userKey, remotePath);
+}
+
+/** The message printed instead of raw bytes when pull saves to a local file. */
+export function pullSavedMessage(
+  result: ReadFileResult,
+  localPath: string,
+): string {
+  return `Pulled ${printable(result.path)} -> ${localPath} (${result.content.length} bytes).`;
+}
+
 /** `dor sandbox release <userKey>`: destroy the sandbox behind a key, idempotently. */
 export async function sandboxRelease(
   client: Dormice,
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index c1f8ce5..be41fd0 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -3,11 +3,16 @@
 // guess) and `dor` (the short name people actually type). It only wires
 // commander to the functions in commands.ts and prints their output —
 // everything testable lives there.
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
 import { Command } from 'commander';
 import {
   clientFromEnv,
+  pullSavedMessage,
   sandboxExec,
   sandboxLs,
+  sandboxPull,
+  sandboxPush,
   sandboxRelease,
 } from './commands';
 
@@ -55,6 +60,50 @@ sandbox
     },
   );
 
+sandbox
+  .command('push')
+  .description(
+    'Copy a local file into the sandbox behind a key (wakes it first)',
+  )
+  .argument('<userKey>', 'the user key whose sandbox receives the file')
+  .argument('<localPath>', 'local file to send')
+  .argument(
+    '[remotePath]',
+    'destination inside the sandbox; relative paths land under /home/user (default: the local file name)',
+  )
+  .action(async (userKey: string, localPath: string, remotePath?: string) => {
+    const content = await readFile(localPath);
+    console.log(
+      await sandboxPush(
+        clientFromEnv(process.env),
+        userKey,
+        content,
+        remotePath ?? path.basename(localPath),
+      ),
+    );
+  });
+
+sandbox
+  .command('pull')
+  .description('Copy a file out of the sandbox behind a key (wakes it first)')
+  .argument('<userKey>', 'the user key whose sandbox holds the file')
+  .argument('<remotePath>', 'file inside the sandbox; relative to /home/user')
+  .argument('[localPath]', 'where to save it; omitted = raw bytes to stdout')
+  .action(async (userKey: string, remotePath: string, localPath?: string) => {
+    const result = await sandboxPull(
+      clientFromEnv(process.env),
+      userKey,
+      remotePath,
+    );
+    if (localPath === undefined) {
+      // Raw on purpose, like exec output: the operator's own file's bytes.
+      process.stdout.write(result.content);
+      return;
+    }
+    await writeFile(localPath, result.content);
+    console.log(pullSavedMessage(result, localPath));
+  });
+
 sandbox
   .command('release')
   .description('Destroy the sandbox behind a user key (idempotent)')

From ab272b57ef771f283f1123d9dd18d50832a1cf4e Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 18:52:54 +0800
Subject: [PATCH 005/133] Executors learn the E2B verbs: streaming exec, dir
 metadata family, uncapped file streams
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

execStream delivers output chunk by chunk through callbacks and returns a
handle (wait for the exit code) — deliberately handle-shaped so process
management verbs can grow on it later. The buffered exec is now the same
pipeline with capped sinks; the fake's pocket interpreter gained ';'
sequencing so the contract can time real chunk gaps, and a timeout now
keeps already-delivered chunks, matching the real executor.

listDir/statEntry/makeDir/move/remove run in-container like every file
verb (find -printf and stat --printf, private exit codes for the typed
errors); readFileStream/writeFileStream are the uncapped paths — the disk
quota is the only ceiling, backpressure travels through the hijacked
stream into the container. The fake's disk model materializes directories
(and ships lost+found, the mkfs artifact every real disk root carries).

Contract grows 32 -> 44 questions; all pass on the fake, real-machine
exam pending.
---
 packages/server/src/executor/contract.ts | 289 ++++++++++++++
 packages/server/src/executor/docker.ts   | 484 +++++++++++++++++++++--
 packages/server/src/executor/executor.ts | 126 +++++-
 packages/server/src/executor/fake.ts     | 452 +++++++++++++++++----
 4 files changed, 1245 insertions(+), 106 deletions(-)

diff --git a/packages/server/src/executor/contract.ts b/packages/server/src/executor/contract.ts
index 3c2f7e5..3d2385f 100644
--- a/packages/server/src/executor/contract.ts
+++ b/packages/server/src/executor/contract.ts
@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { Readable } from 'node:stream';
 import {
   EXEC_OUTPUT_LIMIT_BYTES,
   FILE_SIZE_LIMIT_BYTES,
@@ -9,6 +10,7 @@ import {
   type Executor,
   FileNotFoundError,
   FileTooLargeError,
+  NotADirectoryError,
   NotAFileError,
 } from './executor';
 
@@ -386,6 +388,68 @@ export function describeExecutorContract(
       timeoutMs,
     );
 
+    it(
+      'execStream delivers output live, chunk by chunk',
+      async () => {
+        const id = await fresh();
+        const chunks: Array<{ text: string; at: number }> = [];
+        const handle = await executor.execStream(id, {
+          command: 'echo first; sleep 1; echo second',
+          timeoutSeconds: 30,
+          onStdout: (c) => {
+            chunks.push({ text: c.toString('utf8'), at: Date.now() });
+          },
+          onStderr: () => {},
+        });
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(0);
+        expect(chunks.map((c) => c.text).join('')).toBe('first\nsecond\n');
+        // The anti-buffering assertion: with the sleep between the echoes,
+        // live delivery shows a real gap between the first and last chunk.
+        // A buffered implementation delivers everything at once — gap zero.
+        const at = chunks.map((c) => c.at);
+        expect(Math.max(...at) - Math.min(...at)).toBeGreaterThanOrEqual(500);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'execStream reports a nonzero exit through wait, not an error',
+      async () => {
+        const id = await fresh();
+        const handle = await executor.execStream(id, {
+          command: 'exit 7',
+          timeoutSeconds: 30,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await expect(handle.wait()).resolves.toEqual({ exitCode: 7 });
+      },
+      timeoutMs,
+    );
+
+    it(
+      'execStream timeout kills in-container; chunks already delivered stay delivered',
+      async () => {
+        const id = await fresh();
+        const seen: string[] = [];
+        const before = Date.now();
+        const handle = await executor.execStream(id, {
+          command: 'echo early; sleep 5',
+          timeoutSeconds: 1,
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        const { exitCode } = await handle.wait();
+        expect(Date.now() - before).toBeLessThan(4_000);
+        expect(exitCode).toBe(137);
+        expect(seen.join('')).toBe('early\n');
+      },
+      timeoutMs,
+    );
+
     it(
       'writeFiles then readFile round-trips text',
       async () => {
@@ -584,5 +648,230 @@ export function describeExecutorContract(
       },
       timeoutMs,
     );
+
+    it(
+      'statEntry reports a file with its real metadata',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: '/home/user/s.txt', content: Buffer.from('12345') },
+        ]);
+        // Relative path resolves like every other file verb.
+        const entry = await executor.statEntry(id, 's.txt');
+        expect(entry).toMatchObject({
+          name: 's.txt',
+          path: '/home/user/s.txt',
+          type: 'file',
+          sizeBytes: 5,
+          mode: 0o644,
+          owner: 'user',
+          group: 'user',
+        });
+        // Written moments ago; both executors report a live clock.
+        expect(
+          Math.abs(Date.parse(entry.modifiedTime) - Date.now()),
+        ).toBeLessThan(60_000);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'statEntry reports directories and refuses missing paths',
+      async () => {
+        const id = await fresh();
+        const home = await executor.statEntry(id, '/home/user');
+        expect(home).toMatchObject({
+          name: 'user',
+          path: '/home/user',
+          type: 'dir',
+          mode: 0o755,
+          owner: 'user',
+        });
+
+        const missing = '/home/user/nope';
+        const error = await executor.statEntry(id, missing).catch((e) => e);
+        expect(error).toBeInstanceOf(FileNotFoundError);
+        expect(error.message).toBe(`no such file: ${missing}`);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'listDir walks exactly as deep as asked, sorted by path',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: '/home/user/a.txt', content: Buffer.from('a') },
+          { path: '/home/user/sub/b.txt', content: Buffer.from('b') },
+        ]);
+        // Depth 1: the file, the created dir — and lost+found, the mkfs
+        // artifact every real disk root carries; the listing shows reality.
+        const one = await executor.listDir(id, '/home/user', 1);
+        expect(one.map((e) => [e.path, e.type])).toEqual([
+          ['/home/user/a.txt', 'file'],
+          ['/home/user/lost+found', 'dir'],
+          ['/home/user/sub', 'dir'],
+        ]);
+        const two = await executor.listDir(id, '/home/user', 2);
+        expect(two.map((e) => e.path)).toEqual([
+          '/home/user/a.txt',
+          '/home/user/lost+found',
+          '/home/user/sub',
+          '/home/user/sub/b.txt',
+        ]);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'listDir refuses files and missing paths with the right errors',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: '/home/user/plain.txt', content: Buffer.from('x') },
+        ]);
+        const onFile = await executor
+          .listDir(id, '/home/user/plain.txt', 1)
+          .catch((e) => e);
+        expect(onFile).toBeInstanceOf(NotADirectoryError);
+        expect(onFile.message).toBe('not a directory: /home/user/plain.txt');
+
+        const onMissing = await executor
+          .listDir(id, '/home/user/void', 1)
+          .catch((e) => e);
+        expect(onMissing).toBeInstanceOf(FileNotFoundError);
+        expect(onMissing.message).toBe('no such file: /home/user/void');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'makeDir creates with parents, and reports "already there" as false',
+      async () => {
+        const id = await fresh();
+        expect(await executor.makeDir(id, '/home/user/mk/deep')).toBe(true);
+        expect(
+          await executor.statEntry(id, '/home/user/mk/deep'),
+        ).toMatchObject({ type: 'dir', owner: 'user' });
+        // Again: already exists — false, not an error, whatever is there.
+        expect(await executor.makeDir(id, '/home/user/mk/deep')).toBe(false);
+        await executor.writeFiles(id, [
+          { path: '/home/user/mk/file.txt', content: Buffer.from('f') },
+        ]);
+        expect(await executor.makeDir(id, '/home/user/mk/file.txt')).toBe(
+          false,
+        );
+      },
+      timeoutMs,
+    );
+
+    it(
+      'move renames a file and refuses a missing source',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: '/home/user/m1.txt', content: Buffer.from('payload') },
+        ]);
+        const moved = await executor.move(
+          id,
+          '/home/user/m1.txt',
+          '/home/user/m2.txt',
+        );
+        expect(moved).toMatchObject({
+          path: '/home/user/m2.txt',
+          type: 'file',
+          sizeBytes: 7,
+        });
+        const gone = await executor
+          .readFile(id, '/home/user/m1.txt')
+          .catch((e) => e);
+        expect(gone).toBeInstanceOf(FileNotFoundError);
+        expect(
+          (await executor.readFile(id, '/home/user/m2.txt')).toString(),
+        ).toBe('payload');
+
+        const missing = await executor
+          .move(id, '/home/user/void.txt', '/home/user/x.txt')
+          .catch((e) => e);
+        expect(missing).toBeInstanceOf(FileNotFoundError);
+        expect(missing.message).toBe('no such file: /home/user/void.txt');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'remove takes a file, takes a tree, refuses what is not there',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: '/home/user/r/a.txt', content: Buffer.from('a') },
+          { path: '/home/user/r/sub/b.txt', content: Buffer.from('b') },
+          { path: '/home/user/single.txt', content: Buffer.from('s') },
+        ]);
+        await executor.remove(id, '/home/user/single.txt');
+        await executor.remove(id, '/home/user/r');
+        const statR = await executor
+          .statEntry(id, '/home/user/r')
+          .catch((e) => e);
+        expect(statR).toBeInstanceOf(FileNotFoundError);
+
+        const again = await executor.remove(id, '/home/user/r').catch((e) => e);
+        expect(again).toBeInstanceOf(FileNotFoundError);
+        expect(again.message).toBe('no such file: /home/user/r');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'the streaming file path is the uncapped one: over-limit content round-trips byte-exact',
+      async () => {
+        const id = await fresh();
+        // Past the buffered API's 16 MiB line — only the stream may carry it.
+        const size = FILE_SIZE_LIMIT_BYTES + 5;
+        const big = Buffer.alloc(size);
+        for (let i = 0; i < size; i += 4096) big[i] = i % 251;
+        const half = Math.floor(size / 2);
+        await executor.writeFileStream(
+          id,
+          '/home/user/big-stream.bin',
+          Readable.from([big.subarray(0, half), big.subarray(half)]),
+        );
+        const chunks: Buffer[] = [];
+        await executor.readFileStream(id, '/home/user/big-stream.bin', (c) => {
+          chunks.push(Buffer.from(c));
+        });
+        expect(Buffer.concat(chunks).equals(big)).toBe(true);
+        // The buffered read still refuses it: two paths, two contracts.
+        await expect(
+          executor.readFile(id, '/home/user/big-stream.bin'),
+        ).rejects.toThrow(FileTooLargeError);
+      },
+      timeoutMs * 4,
+    );
+
+    it(
+      'streaming file verbs throw the same typed errors as the buffered ones',
+      async () => {
+        const id = await fresh();
+        const missing = await executor
+          .readFileStream(id, '/home/user/void.bin', () => {})
+          .catch((e) => e);
+        expect(missing).toBeInstanceOf(FileNotFoundError);
+        expect(missing.message).toBe('no such file: /home/user/void.bin');
+
+        const onDir = await executor
+          .readFileStream(id, '/home/user', () => {})
+          .catch((e) => e);
+        expect(onDir).toBeInstanceOf(NotAFileError);
+        expect(onDir.message).toBe('not a regular file: /home/user');
+
+        const writeDir = await executor
+          .writeFileStream(id, '/home/user', Readable.from([Buffer.from('x')]))
+          .catch((e) => e);
+        expect(writeDir).toBeInstanceOf(NotAFileError);
+        expect(writeDir.message).toBe('not a regular file: /home/user');
+      },
+      timeoutMs,
+    );
   });
 }
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index a923782..de87865 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -18,13 +18,18 @@ import Docker from 'dockerode';
 import { execa } from 'execa';
 import {
   type ContainerState,
+  DiskFullError,
   type ExecOptions,
   type ExecResult,
+  type ExecStreamHandle,
+  type ExecStreamOptions,
   type Executor,
   FileNotFoundError,
   FileTooLargeError,
   type FileToWrite,
+  NotADirectoryError,
   NotAFileError,
+  type SandboxEntry,
 } from './executor';
 
 /**
@@ -92,6 +97,100 @@ const READ_FILE_SCRIPT = [
   'exec cat -- "$1"',
 ].join('\n');
 
+const NOT_A_DIR_EXIT = 47;
+const ALREADY_EXISTS_EXIT = 48;
+
+/**
+ * Streaming file transfers have no size cap, so their in-container deadline
+ * must fit a quota-sized file crawling to a slow client — generous, but
+ * still a bound so a wedged transfer cannot hold an exec forever.
+ */
+const STREAM_FILE_OP_TIMEOUT_SECONDS = 3600;
+
+/** Ceiling for one directory listing; past it the listing errors instead of silently losing entries. */
+const LIST_OUTPUT_LIMIT_BYTES = 8 * 1024 * 1024;
+
+/** $1 = absolute path. READ_FILE_SCRIPT without the size gate — the streaming read is the uncapped path. */
+const READ_FILE_STREAM_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  `[ -f "$1" ] || exit ${NOT_A_FILE_EXIT}`,
+  'exec cat -- "$1"',
+].join('\n');
+
+/**
+ * $1 = absolute dir, $2 = depth. One NUL-terminated record per entry, tab
+ * separated with the path last, so a path containing tabs still parses
+ * (nothing else can contain a tab, and a path cannot contain a NUL).
+ */
+const LIST_DIR_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  `[ -d "$1" ] || exit ${NOT_A_DIR_EXIT}`,
+  `exec find "$1" -mindepth 1 -maxdepth "$2" -printf '%y\\t%s\\t%T@\\t%m\\t%u\\t%g\\t%p\\0'`,
+].join('\n');
+
+/** $1 = absolute path. --printf, not -c: only --printf interprets \t. */
+const STAT_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  `exec stat --printf '%F\\t%s\\t%Y\\t%a\\t%U\\t%G' -- "$1"`,
+].join('\n');
+
+/** $1 = absolute path. Exists (whatever it is) -> "already there", else mkdir -p. */
+const MAKE_DIR_SCRIPT = [
+  `[ ! -e "$1" ] || exit ${ALREADY_EXISTS_EXIT}`,
+  'exec mkdir -p -- "$1"',
+].join('\n');
+
+/** $1 = source, $2 = destination. -T = rename(2) semantics: never "move into". */
+const MOVE_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  'exec mv -T -- "$1" "$2"',
+].join('\n');
+
+const REMOVE_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  'exec rm -rf -- "$1"',
+].join('\n');
+
+/** One `find -printf` record (see LIST_DIR_SCRIPT) -> entry. */
+function entryFromFindRecord(record: string): SandboxEntry {
+  const fields = record.split('\t');
+  const [kind = '', size = '', mtime = '', mode = '', owner = '', group = ''] =
+    fields;
+  // The path is everything after the sixth tab — its own tabs survive.
+  const path = fields.slice(6).join('\t');
+  return {
+    name: path.slice(path.lastIndexOf('/') + 1) || '/',
+    path,
+    type: kind === 'f' ? 'file' : kind === 'd' ? 'dir' : 'other',
+    sizeBytes: Number(size),
+    modifiedTime: new Date(Number(mtime) * 1000).toISOString(),
+    mode: Number.parseInt(mode, 8),
+    owner,
+    group,
+  };
+}
+
+/** One `stat --printf` line (see STAT_SCRIPT) -> entry. */
+function entryFromStatLine(resolved: string, line: string): SandboxEntry {
+  const [kind = '', size = '', mtime = '', mode = '', owner = '', group = ''] =
+    line.split('\t');
+  return {
+    name: resolved.slice(resolved.lastIndexOf('/') + 1) || '/',
+    path: resolved,
+    // %F says "regular file" or "regular empty file" — both are files.
+    type: kind.startsWith('regular')
+      ? 'file'
+      : kind === 'directory'
+        ? 'dir'
+        : 'other',
+    sizeBytes: Number(size),
+    modifiedTime: new Date(Number(mtime) * 1000).toISOString(),
+    mode: Number.parseInt(mode, 8),
+    owner,
+    group,
+  };
+}
+
 /**
  * Docker reports seven statuses; the executor's contract knows three. With
  * RestartPolicy "no" a container never restarts on its own, so everything
@@ -150,6 +249,33 @@ class CappedBuffer extends Writable {
   }
 }
 
+/**
+ * A Writable that hands each chunk to a callback — the streaming sink for
+ * exec output and file downloads. When the callback returns a promise it is
+ * awaited before the next chunk is accepted: that is how a slow consumer's
+ * backpressure travels through demux all the way to the in-container writer.
+ */
+class CallbackSink extends Writable {
+  constructor(
+    private readonly onChunk: (chunk: Buffer) => void | Promise<void>,
+  ) {
+    super();
+  }
+
+  override _write(
+    chunk: Buffer,
+    _encoding: BufferEncoding,
+    callback: (error?: Error | null) => void,
+  ): void {
+    Promise.resolve()
+      .then(() => this.onChunk(chunk))
+      .then(
+        () => callback(),
+        (err) => callback(err instanceof Error ? err : new Error(String(err))),
+      );
+  }
+}
+
 interface DockerApiError {
   statusCode: number;
 }
@@ -342,6 +468,29 @@ export class DockerExecutor implements Executor {
     };
   }
 
+  async execStream(
+    sandboxId: string,
+    opts: ExecStreamOptions,
+  ): Promise<ExecStreamHandle> {
+    const containerId = await this.expectState(sandboxId, 'running');
+    const container = this.docker.getContainer(containerId);
+    const shell = opts.loginShell ? ['bash', '-l', '-c'] : ['bash', '-c'];
+    const wait = await this.startInContainer(container, sandboxId, {
+      cmd: [
+        'timeout',
+        '--signal=KILL',
+        String(opts.timeoutSeconds),
+        ...shell,
+        opts.command,
+      ],
+      stdout: new CallbackSink(opts.onStdout),
+      stderr: new CallbackSink(opts.onStderr),
+      workingDir: opts.cwd,
+      env: opts.env,
+    });
+    return { wait: async () => ({ exitCode: await wait() }) };
+  }
+
   async writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void> {
     const containerId = await this.expectState(sandboxId, 'running');
     const container = this.docker.getContainer(containerId);
@@ -419,25 +568,291 @@ export class DockerExecutor implements Executor {
     return run.stdout.bytes();
   }
 
-  /**
-   * The one exec pipeline: start, demux, optionally feed stdin (ending the
-   * stream is what delivers EOF to the in-container reader), wait for the
-   * stream, then poll for the exit code — the engine records it a beat
-   * after the stream ends, the same measured lag as kill vs exited in
-   * stop(). Tty stays off: the multiplexed stream is what demuxStream can
-   * split back into distinct stdout and stderr.
-   */
+  async readFileStream(
+    sandboxId: string,
+    path: string,
+    onChunk: (chunk: Buffer) => void | Promise<void>,
+  ): Promise<void> {
+    const resolved = resolveSandboxPath(path);
+    const containerId = await this.expectState(sandboxId, 'running');
+    const container = this.docker.getContainer(containerId);
+    const stderr = new CappedBuffer(EXEC_OUTPUT_LIMIT_BYTES);
+    const wait = await this.startInContainer(container, sandboxId, {
+      cmd: [
+        'timeout',
+        '--signal=KILL',
+        String(STREAM_FILE_OP_TIMEOUT_SECONDS),
+        'bash',
+        '-c',
+        READ_FILE_STREAM_SCRIPT,
+        'bash',
+        resolved,
+      ],
+      stdout: new CallbackSink(onChunk),
+      stderr,
+    });
+    const exitCode = await wait();
+    if (exitCode === NO_SUCH_FILE_EXIT) {
+      throw new FileNotFoundError(`no such file: ${resolved}`);
+    }
+    if (exitCode === NOT_A_FILE_EXIT) {
+      throw new NotAFileError(`not a regular file: ${resolved}`);
+    }
+    if (exitCode !== 0) {
+      throw new Error(
+        `reading ${resolved} in ${sandboxId} failed (exit ${exitCode}): ${stderr.text().trim()}`,
+      );
+    }
+  }
+
+  async writeFileStream(
+    sandboxId: string,
+    path: string,
+    content: NodeJS.ReadableStream,
+  ): Promise<void> {
+    const resolved = resolveSandboxPath(path);
+    const containerId = await this.expectState(sandboxId, 'running');
+    const container = this.docker.getContainer(containerId);
+    const run = await this.runInContainer(container, sandboxId, {
+      cmd: [
+        'timeout',
+        '--signal=KILL',
+        String(STREAM_FILE_OP_TIMEOUT_SECONDS),
+        'bash',
+        '-c',
+        WRITE_FILE_SCRIPT,
+        'bash',
+        resolved,
+      ],
+      outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+      stdin: content,
+    });
+    if (run.exitCode === NOT_A_FILE_EXIT) {
+      throw new NotAFileError(`not a regular file: ${resolved}`);
+    }
+    if (run.exitCode !== 0) {
+      const message = run.stderr.text().trim();
+      if (/no space left/i.test(message)) {
+        throw new DiskFullError(`no space left on device: ${resolved}`);
+      }
+      throw new Error(
+        `writing ${resolved} in ${sandboxId} failed (exit ${run.exitCode}): ${message}`,
+      );
+    }
+  }
+
+  async listDir(
+    sandboxId: string,
+    path: string,
+    depth: number,
+  ): Promise<SandboxEntry[]> {
+    const resolved = resolveSandboxPath(path);
+    const containerId = await this.expectState(sandboxId, 'running');
+    const container = this.docker.getContainer(containerId);
+    const run = await this.runInContainer(container, sandboxId, {
+      cmd: [
+        'timeout',
+        '--signal=KILL',
+        String(FILE_OP_TIMEOUT_SECONDS),
+        'bash',
+        '-c',
+        LIST_DIR_SCRIPT,
+        'bash',
+        resolved,
+        String(depth),
+      ],
+      outputCap: LIST_OUTPUT_LIMIT_BYTES,
+    });
+    if (run.exitCode === NO_SUCH_FILE_EXIT) {
+      throw new FileNotFoundError(`no such file: ${resolved}`);
+    }
+    if (run.exitCode === NOT_A_DIR_EXIT) {
+      throw new NotADirectoryError(`not a directory: ${resolved}`);
+    }
+    if (run.exitCode !== 0) {
+      throw new Error(
+        `listing ${resolved} in ${sandboxId} failed (exit ${run.exitCode}): ${run.stderr.text().trim()}`,
+      );
+    }
+    if (run.stdout.truncated) {
+      // Losing entries silently would make the listing a lie.
+      throw new Error(
+        `listing ${resolved} in ${sandboxId} exceeded ${LIST_OUTPUT_LIMIT_BYTES} bytes — use a smaller depth`,
+      );
+    }
+    return run.stdout
+      .bytes()
+      .toString('utf8')
+      .split('\0')
+      .filter((record) => record.length > 0)
+      .map(entryFromFindRecord)
+      .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  }
+
+  async statEntry(sandboxId: string, path: string): Promise<SandboxEntry> {
+    const resolved = resolveSandboxPath(path);
+    const containerId = await this.expectState(sandboxId, 'running');
+    const container = this.docker.getContainer(containerId);
+    const run = await this.runInContainer(container, sandboxId, {
+      cmd: [
+        'timeout',
+        '--signal=KILL',
+        String(FILE_OP_TIMEOUT_SECONDS),
+        'bash',
+        '-c',
+        STAT_SCRIPT,
+        'bash',
+        resolved,
+      ],
+      outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+    });
+    if (run.exitCode === NO_SUCH_FILE_EXIT) {
+      throw new FileNotFoundError(`no such file: ${resolved}`);
+    }
+    if (run.exitCode !== 0) {
+      throw new Error(
+        `stat ${resolved} in ${sandboxId} failed (exit ${run.exitCode}): ${run.stderr.text().trim()}`,
+      );
+    }
+    return entryFromStatLine(resolved, run.stdout.text());
+  }
+
+  async makeDir(sandboxId: string, path: string): Promise<boolean> {
+    const resolved = resolveSandboxPath(path);
+    const containerId = await this.expectState(sandboxId, 'running');
+    const container = this.docker.getContainer(containerId);
+    const run = await this.runInContainer(container, sandboxId, {
+      cmd: [
+        'timeout',
+        '--signal=KILL',
+        String(FILE_OP_TIMEOUT_SECONDS),
+        'bash',
+        '-c',
+        MAKE_DIR_SCRIPT,
+        'bash',
+        resolved,
+      ],
+      outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+    });
+    if (run.exitCode === ALREADY_EXISTS_EXIT) {
+      return false;
+    }
+    if (run.exitCode !== 0) {
+      throw new Error(
+        `mkdir ${resolved} in ${sandboxId} failed (exit ${run.exitCode}): ${run.stderr.text().trim()}`,
+      );
+    }
+    return true;
+  }
+
+  async move(
+    sandboxId: string,
+    from: string,
+    to: string,
+  ): Promise<SandboxEntry> {
+    const source = resolveSandboxPath(from);
+    const destination = resolveSandboxPath(to);
+    const containerId = await this.expectState(sandboxId, 'running');
+    const container = this.docker.getContainer(containerId);
+    const run = await this.runInContainer(container, sandboxId, {
+      cmd: [
+        'timeout',
+        '--signal=KILL',
+        String(FILE_OP_TIMEOUT_SECONDS),
+        'bash',
+        '-c',
+        MOVE_SCRIPT,
+        'bash',
+        source,
+        destination,
+      ],
+      outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+    });
+    if (run.exitCode === NO_SUCH_FILE_EXIT) {
+      throw new FileNotFoundError(`no such file: ${source}`);
+    }
+    if (run.exitCode !== 0) {
+      throw new Error(
+        `moving ${source} to ${destination} in ${sandboxId} failed (exit ${run.exitCode}): ${run.stderr.text().trim()}`,
+      );
+    }
+    return this.statEntry(sandboxId, destination);
+  }
+
+  async remove(sandboxId: string, path: string): Promise<void> {
+    const resolved = resolveSandboxPath(path);
+    const containerId = await this.expectState(sandboxId, 'running');
+    const container = this.docker.getContainer(containerId);
+    const run = await this.runInContainer(container, sandboxId, {
+      cmd: [
+        'timeout',
+        '--signal=KILL',
+        String(FILE_OP_TIMEOUT_SECONDS),
+        'bash',
+        '-c',
+        REMOVE_SCRIPT,
+        'bash',
+        resolved,
+      ],
+      outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+    });
+    if (run.exitCode === NO_SUCH_FILE_EXIT) {
+      throw new FileNotFoundError(`no such file: ${resolved}`);
+    }
+    if (run.exitCode !== 0) {
+      throw new Error(
+        `removing ${resolved} in ${sandboxId} failed (exit ${run.exitCode}): ${run.stderr.text().trim()}`,
+      );
+    }
+  }
+
+  /** The buffered face of the exec pipeline: capped sinks, awaited to the end. */
   private async runInContainer(
     container: Docker.Container,
     sandboxId: string,
     spec: {
       cmd: string[];
       outputCap: number;
-      stdin?: Buffer;
+      stdin?: Buffer | NodeJS.ReadableStream;
       workingDir?: string;
       env?: Record<string, string>;
     },
   ): Promise<{ exitCode: number; stdout: CappedBuffer; stderr: CappedBuffer }> {
+    const stdout = new CappedBuffer(spec.outputCap);
+    const stderr = new CappedBuffer(spec.outputCap);
+    const wait = await this.startInContainer(container, sandboxId, {
+      cmd: spec.cmd,
+      stdout,
+      stderr,
+      stdin: spec.stdin,
+      workingDir: spec.workingDir,
+      env: spec.env,
+    });
+    return { exitCode: await wait(), stdout, stderr };
+  }
+
+  /**
+   * The one exec pipeline: start, demux into the caller's sinks, optionally
+   * feed stdin (ending the stream is what delivers EOF to the in-container
+   * reader), then — inside the returned wait — wait for the stream and poll
+   * for the exit code: the engine records it a beat after the stream ends,
+   * the same measured lag as kill vs exited in stop(). Tty stays off: the
+   * multiplexed stream is what demuxStream can split back into distinct
+   * stdout and stderr. Resolving means the command has started; everything
+   * after start is the wait's business.
+   */
+  private async startInContainer(
+    container: Docker.Container,
+    sandboxId: string,
+    spec: {
+      cmd: string[];
+      stdout: Writable;
+      stderr: Writable;
+      stdin?: Buffer | NodeJS.ReadableStream;
+      workingDir?: string;
+      env?: Record<string, string>;
+    },
+  ): Promise<() => Promise<number>> {
     const exec = await container.exec({
       Cmd: spec.cmd,
       AttachStdin: spec.stdin !== undefined,
@@ -452,28 +867,41 @@ export class DockerExecutor implements Executor {
     const stream = await exec.start(
       spec.stdin !== undefined ? { hijack: true, stdin: true } : {},
     );
-    const stdout = new CappedBuffer(spec.outputCap);
-    const stderr = new CappedBuffer(spec.outputCap);
-    this.docker.modem.demuxStream(stream, stdout, stderr);
+    this.docker.modem.demuxStream(stream, spec.stdout, spec.stderr);
     if (spec.stdin !== undefined) {
-      stream.end(spec.stdin);
-    }
-    await new Promise<void>((resolve, reject) => {
-      stream.on('end', resolve);
-      stream.on('close', resolve);
-      stream.on('error', reject);
-    });
-    let info = await exec.inspect();
-    for (let i = 0; info.Running || info.ExitCode === null; i++) {
-      if (i >= 20) {
-        throw new Error(
-          `exec on ${sandboxId} ended but no exit code was recorded`,
-        );
+      if (Buffer.isBuffer(spec.stdin)) {
+        stream.end(spec.stdin);
+      } else {
+        // pipe() forwards the source's end as the exec's stdin EOF. A source
+        // error would otherwise leave the in-container reader waiting for
+        // the timeout wrapper to kill it — destroying the stream surfaces
+        // the failure now instead.
+        spec.stdin.on('error', (err) => stream.destroy(err));
+        spec.stdin.pipe(stream);
       }
-      await new Promise((resolve) => setTimeout(resolve, 50));
-      info = await exec.inspect();
     }
-    return { exitCode: info.ExitCode, stdout, stderr };
+    const finished = (async () => {
+      await new Promise<void>((resolve, reject) => {
+        stream.on('end', resolve);
+        stream.on('close', resolve);
+        stream.on('error', reject);
+      });
+      let info = await exec.inspect();
+      for (let i = 0; info.Running || info.ExitCode === null; i++) {
+        if (i >= 20) {
+          throw new Error(
+            `exec on ${sandboxId} ended but no exit code was recorded`,
+          );
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        info = await exec.inspect();
+      }
+      return info.ExitCode;
+    })();
+    // A failure before anyone calls wait must not crash the daemon as an
+    // unhandled rejection; wait() still observes it through the same promise.
+    finished.catch(() => {});
+    return () => finished;
   }
 
   private imagePath(sandboxId: string): string {
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index b85dd98..7130a33 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -28,20 +28,79 @@ export interface ExecResult {
   stderrTruncated: boolean;
 }
 
+export interface ExecStreamOptions {
+  /** A shell string, executed as `bash -c <command>` inside the sandbox. */
+  command: string;
+  /** Same in-container deadline as ExecOptions; on expiry exit 137. */
+  timeoutSeconds: number;
+  cwd?: string;
+  env?: Record<string, string>;
+  /**
+   * Run under a login shell (`bash -l -c`), which loads the image's profile
+   * — the E2B surface's habit. The native API keeps plain `bash -c`; each
+   * protocol stays true to its own contract.
+   */
+  loginShell?: boolean;
+  /**
+   * Called with each output chunk as it arrives. No cap: nothing accumulates
+   * server-side. A returned promise MAY be awaited before the next chunk
+   * (the real executor does — backpressure travels to the container; the
+   * fake's in-memory source has nothing to press back on).
+   */
+  onStdout: (chunk: Buffer) => void | Promise<void>;
+  onStderr: (chunk: Buffer) => void | Promise<void>;
+}
+
+/**
+ * A started command. Obtaining the handle means the exec is running; wait()
+ * is its result. Deliberately handle-shaped (not a plain promise): process
+ * management verbs — kill, stdin, reconnect — will grow here later without
+ * reshaping every caller.
+ */
+export interface ExecStreamHandle {
+  wait(): Promise<{ exitCode: number }>;
+}
+
 export interface FileToWrite {
   /** Absolute, or relative to /home/user — resolveSandboxPath's rules. */
   path: string;
   content: Buffer;
 }
 
+/** What the filesystem says about one path — the shape stat and listDir speak. */
+export interface SandboxEntry {
+  /** Basename; '/' for the root itself. */
+  name: string;
+  /** Absolute resolved path. */
+  path: string;
+  /** 'other' covers symlinks, FIFOs and friends — observed, not modeled. */
+  type: 'file' | 'dir' | 'other';
+  /** Bytes for files; whatever the filesystem reports for directories. */
+  sizeBytes: number;
+  /** ISO 8601 UTC. */
+  modifiedTime: string;
+  /** Permission bits, e.g. 0o644. */
+  mode: number;
+  owner: string;
+  group: string;
+}
+
 /**
  * The file-op error taxonomy, shared by both executors down to the message
  * (the contract exam holds them to it) and mapped to HTTP statuses by the
- * route: not found -> 404, not a regular file -> 400, too large -> 413.
+ * routes: not found -> 404, not a regular file / not a directory -> 400,
+ * too large -> 413, disk full -> 507.
  */
 export class FileNotFoundError extends Error {}
 export class NotAFileError extends Error {}
+export class NotADirectoryError extends Error {}
 export class FileTooLargeError extends Error {}
+/**
+ * The sandbox disk ran out of room mid-write. Only the real executor can
+ * produce it (the fake's memory disk has no edge), so unlike the rest of the
+ * taxonomy its message is not contract-pinned.
+ */
+export class DiskFullError extends Error {}
 
 /**
  * The executor is where lifecycle decisions become physical reality:
@@ -101,6 +160,17 @@ export interface Executor {
    * drained and dropped, and the truncation reported.
    */
   exec(sandboxId: string, opts: ExecOptions): Promise<ExecResult>;
+  /**
+   * Runs a shell command, delivering output live through the callbacks
+   * instead of buffering — chunk boundaries follow the command's own writes.
+   * The returned promise resolves once the command has started (a start
+   * failure rejects here); handle.wait() resolves with the honest exit code.
+   * Same running-state requirement and in-container deadline as exec.
+   */
+  execStream(
+    sandboxId: string,
+    opts: ExecStreamOptions,
+  ): Promise<ExecStreamHandle>;
   /**
    * Writes every file in the batch, in order, failing fast — earlier files
    * stay written (a batch saves round-trips, it is not a transaction).
@@ -119,4 +189,58 @@ export interface Executor {
    * and not in the schema because only the executor can observe the size.
    */
   readFile(sandboxId: string, path: string): Promise<Buffer>;
+  /**
+   * Streams one file's bytes through the callback, uncapped — nothing
+   * accumulates server-side, so the disk quota is the only ceiling (the E2B
+   * surface's contract; the native API's 16 MiB cap is the base64-JSON
+   * shape's own rule and does not reach here). A returned promise from the
+   * callback is awaited before the next chunk: backpressure travels through
+   * to the in-container reader. Errors as readFile, minus the size gate.
+   */
+  readFileStream(
+    sandboxId: string,
+    path: string,
+    onChunk: (chunk: Buffer) => void | Promise<void>,
+  ): Promise<void>;
+  /**
+   * Streams content into one file, uncapped, parents created, overwriting —
+   * writeFiles' semantics without materializing the bytes. A full disk
+   * throws DiskFullError.
+   */
+  writeFileStream(
+    sandboxId: string,
+    path: string,
+    content: NodeJS.ReadableStream,
+  ): Promise<void>;
+  /**
+   * Entries under a directory, depth ≥ 1 levels down, sorted by path.
+   * Throws FileNotFoundError for a missing path, NotADirectoryError for a
+   * file. Requires state `running`, like every file verb.
+   */
+  listDir(
+    sandboxId: string,
+    path: string,
+    depth: number,
+  ): Promise<SandboxEntry[]>;
+  /** One path's entry. FileNotFoundError when nothing is there. */
+  statEntry(sandboxId: string, path: string): Promise<SandboxEntry>;
+  /**
+   * mkdir -p. True when created; false when the path already exists —
+   * whatever it is: claiming "created" over an existing file would be a lie,
+   * and the caller's next stat tells the truth either way.
+   */
+  makeDir(sandboxId: string, path: string): Promise<boolean>;
+  /**
+   * rename(2) semantics (`mv -T`): an existing destination file is
+   * replaced, a destination directory is not merged into. The source must
+   * exist (FileNotFoundError); parents of the destination are not created.
+   * Returns the destination's entry.
+   */
+  move(sandboxId: string, from: string, to: string): Promise<SandboxEntry>;
+  /**
+   * rm -rf: file or directory tree. FileNotFoundError when nothing is there
+   * — removing nothing is a caller's confusion worth reporting, not a goal
+   * state (unlike removeDisk, whose caller is reconciliation).
+   */
+  remove(sandboxId: string, path: string): Promise<void>;
 }
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index 4f54d93..a93df0e 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -7,19 +7,73 @@ import {
   type ContainerState,
   type ExecOptions,
   type ExecResult,
+  type ExecStreamHandle,
+  type ExecStreamOptions,
   type Executor,
   FileNotFoundError,
   FileTooLargeError,
   type FileToWrite,
+  NotADirectoryError,
   NotAFileError,
+  type SandboxEntry,
 } from './executor';
 
 /**
- * Directories the base image guarantees in every sandbox. The fake's
- * filesystem is otherwise implicit — a directory exists exactly when some
- * file lives under it, which is all mkdir -p semantics leave observable.
+ * Directories every real sandbox is born with, with the owner and mode
+ * reality gives them: the image's skeleton plus lost+found — the mkfs.ext4
+ * artifact every disk carries in its root (/home/user), which a directory
+ * listing must therefore show on the fake too.
  */
-const BUILTIN_DIRS = new Set(['/', '/home', '/home/user', '/tmp']);
+const BUILTIN_DIRS: Record<string, { owner: string; mode: number }> = {
+  '/': { owner: 'root', mode: 0o755 },
+  '/home': { owner: 'root', mode: 0o755 },
+  '/home/user': { owner: 'user', mode: 0o755 },
+  '/home/user/lost+found': { owner: 'root', mode: 0o700 },
+  '/tmp': { owner: 'root', mode: 0o1777 },
+};
+
+/**
+ * The fake disk's content: one node per path, directories materialized —
+ * mkdir -p on a real disk leaves real directories behind, so the model
+ * does too (an earlier implicit-directory model could not answer makeDir
+ * on an empty directory or list one).
+ */
+type FakeNode =
+  | { type: 'file'; content: Buffer; modifiedTime: string }
+  | { type: 'dir'; modifiedTime: string };
+
+function seededDisk(): Map<string, FakeNode> {
+  const now = new Date().toISOString();
+  return new Map(
+    Object.keys(BUILTIN_DIRS).map((path) => [
+      path,
+      { type: 'dir' as const, modifiedTime: now },
+    ]),
+  );
+}
+
+/**
+ * Node -> entry, with the metadata reality would report: files land as
+ * uid 1000 with the default umask (644), created directories as 755, and
+ * the built-in skeleton keeps the image's own owners and modes.
+ */
+function entryFor(path: string, node: FakeNode): SandboxEntry {
+  const meta =
+    node.type === 'dir'
+      ? (BUILTIN_DIRS[path] ?? { owner: 'user', mode: 0o755 })
+      : { owner: 'user', mode: 0o644 };
+  return {
+    name: path.slice(path.lastIndexOf('/') + 1) || '/',
+    path,
+    type: node.type,
+    // 4096 = one ext4 block, what a real directory stats as.
+    sizeBytes: node.type === 'file' ? node.content.length : 4096,
+    modifiedTime: node.modifiedTime,
+    mode: meta.mode,
+    owner: meta.owner,
+    group: meta.owner,
+  };
+}
 
 /**
  * In-memory stand-in for the Docker+gVisor executor. Not a throwaway: it is
@@ -39,7 +93,7 @@ export class FakeExecutor implements Executor {
    * the disk does. That is the "the disk is the sandbox's body" invariant,
    * modeled where it physically lives.
    */
-  private readonly files = new Map<string, Map<string, Buffer>>();
+  private readonly fs = new Map<string, Map<string, FakeNode>>();
 
   /** Test hook: what does "reality" say about this sandbox? */
   stateOf(sandboxId: string): ContainerState | undefined {
@@ -70,7 +124,7 @@ export class FakeExecutor implements Executor {
       throw new Error(`container ${sandboxId} already exists`);
     }
     this.disks.add(sandboxId);
-    this.files.set(sandboxId, new Map());
+    this.fs.set(sandboxId, seededDisk());
     this.containers.set(sandboxId, 'running');
   }
 
@@ -113,7 +167,7 @@ export class FakeExecutor implements Executor {
     // hearing.
     const hadContainer = this.containers.delete(sandboxId);
     const hadDisk = this.disks.delete(sandboxId);
-    this.files.delete(sandboxId);
+    this.fs.delete(sandboxId);
     if (!hadContainer && !hadDisk) {
       throw new Error(`container ${sandboxId} is absent, cannot destroy`);
     }
@@ -131,71 +185,276 @@ export class FakeExecutor implements Executor {
   async removeDisk(sandboxId: string): Promise<void> {
     // Idempotent by contract: an absent disk already is the goal state.
     this.disks.delete(sandboxId);
-    this.files.delete(sandboxId);
+    this.fs.delete(sandboxId);
   }
 
   async exec(sandboxId: string, opts: ExecOptions): Promise<ExecResult> {
-    this.expect(sandboxId, 'running');
-    // The timeout races the command, same outcome as the real executor's
-    // in-container `timeout --signal=KILL`: exit 137, partial output dropped.
-    let timer: NodeJS.Timeout | undefined;
-    const deadline = new Promise<ExecResult>((resolve) => {
-      timer = setTimeout(
-        () => resolve(fakeResult(137)),
-        opts.timeoutSeconds * 1000,
-      );
+    const stdout = new CappedText(EXEC_OUTPUT_LIMIT_BYTES);
+    const stderr = new CappedText(EXEC_OUTPUT_LIMIT_BYTES);
+    const handle = await this.execStream(sandboxId, {
+      command: opts.command,
+      timeoutSeconds: opts.timeoutSeconds,
+      cwd: opts.cwd,
+      env: opts.env,
+      onStdout: (chunk) => stdout.push(chunk),
+      onStderr: (chunk) => stderr.push(chunk),
     });
-    try {
-      return await Promise.race([interpret(opts), deadline]);
-    } finally {
-      clearTimeout(timer);
-    }
+    const { exitCode } = await handle.wait();
+    return {
+      exitCode,
+      stdout: stdout.text,
+      stderr: stderr.text,
+      stdoutTruncated: stdout.truncated,
+      stderrTruncated: stderr.truncated,
+    };
+  }
+
+  async execStream(
+    sandboxId: string,
+    opts: ExecStreamOptions,
+  ): Promise<ExecStreamHandle> {
+    this.expect(sandboxId, 'running');
+    // The timeout races the interpreter, same outcome as the real executor's
+    // in-container `timeout --signal=KILL`: exit 137. Chunks delivered before
+    // the kill stay delivered — an emitted chunk cannot be unsent — and the
+    // flag silences anything the losing interpreter emits afterwards.
+    let timedOut = false;
+    const emit = {
+      stdout: (text: string) => {
+        if (!timedOut) opts.onStdout(Buffer.from(text, 'utf8'));
+      },
+      stderr: (text: string) => {
+        if (!timedOut) opts.onStderr(Buffer.from(text, 'utf8'));
+      },
+    };
+    const done = (async () => {
+      let timer: NodeJS.Timeout | undefined;
+      const deadline = new Promise<number>((resolve) => {
+        timer = setTimeout(() => {
+          timedOut = true;
+          resolve(137);
+        }, opts.timeoutSeconds * 1000);
+      });
+      try {
+        return {
+          exitCode: await Promise.race([interpret(opts, emit), deadline]),
+        };
+      } finally {
+        clearTimeout(timer);
+      }
+    })();
+    // A failure before anyone calls wait must not become an unhandled
+    // rejection; wait() still observes it through the same promise.
+    done.catch(() => {});
+    return { wait: () => done };
   }
 
   async writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void> {
     this.expect(sandboxId, 'running');
-    const disk = this.files.get(sandboxId) ?? new Map<string, Buffer>();
-    this.files.set(sandboxId, disk);
+    const disk = this.disk(sandboxId);
     for (const file of files) {
-      const path = resolveSandboxPath(file.path);
-      if (this.isDirectory(disk, path)) {
-        throw new NotAFileError(`not a regular file: ${path}`);
-      }
       // Copy on the way in: the caller's buffer is theirs to reuse.
-      disk.set(path, Buffer.from(file.content));
+      this.writeNode(
+        sandboxId,
+        disk,
+        resolveSandboxPath(file.path),
+        Buffer.from(file.content),
+      );
     }
   }
 
   async readFile(sandboxId: string, path: string): Promise<Buffer> {
+    const node = this.fileNode(sandboxId, resolveSandboxPath(path));
+    if (node.content.length > FILE_SIZE_LIMIT_BYTES) {
+      throw new FileTooLargeError(
+        `file too large: ${resolveSandboxPath(path)} is ${node.content.length} bytes, limit ${FILE_SIZE_LIMIT_BYTES}`,
+      );
+    }
+    return Buffer.from(node.content);
+  }
+
+  async readFileStream(
+    sandboxId: string,
+    path: string,
+    onChunk: (chunk: Buffer) => void | Promise<void>,
+  ): Promise<void> {
+    // The uncapped path: no size gate, one chunk (the fake has no reason to
+    // slice; chunking is the real pipe's business, not the contract's).
+    const node = this.fileNode(sandboxId, resolveSandboxPath(path));
+    await onChunk(Buffer.from(node.content));
+  }
+
+  async writeFileStream(
+    sandboxId: string,
+    path: string,
+    content: NodeJS.ReadableStream,
+  ): Promise<void> {
     this.expect(sandboxId, 'running');
-    const disk = this.files.get(sandboxId) ?? new Map<string, Buffer>();
+    const disk = this.disk(sandboxId);
     const resolved = resolveSandboxPath(path);
-    const content = disk.get(resolved);
-    if (content !== undefined) {
-      if (content.length > FILE_SIZE_LIMIT_BYTES) {
-        throw new FileTooLargeError(
-          `file too large: ${resolved} is ${content.length} bytes, limit ${FILE_SIZE_LIMIT_BYTES}`,
-        );
-      }
-      return Buffer.from(content);
+    const chunks: Buffer[] = [];
+    for await (const chunk of content) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    this.writeNode(sandboxId, disk, resolved, Buffer.concat(chunks));
+  }
+
+  async listDir(
+    sandboxId: string,
+    path: string,
+    depth: number,
+  ): Promise<SandboxEntry[]> {
+    this.expect(sandboxId, 'running');
+    const disk = this.disk(sandboxId);
+    const base = resolveSandboxPath(path);
+    const node = disk.get(base);
+    if (!node) throw new FileNotFoundError(`no such file: ${base}`);
+    if (node.type !== 'dir') {
+      throw new NotADirectoryError(`not a directory: ${base}`);
+    }
+    const prefix = base === '/' ? '/' : `${base}/`;
+    const entries: SandboxEntry[] = [];
+    for (const [p, n] of disk) {
+      if (p === base || !p.startsWith(prefix)) continue;
+      if (p.slice(prefix.length).split('/').length > depth) continue;
+      entries.push(entryFor(p, n));
+    }
+    return entries.sort((a, b) =>
+      a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
+    );
+  }
+
+  async statEntry(sandboxId: string, path: string): Promise<SandboxEntry> {
+    this.expect(sandboxId, 'running');
+    const resolved = resolveSandboxPath(path);
+    const node = this.disk(sandboxId).get(resolved);
+    if (!node) throw new FileNotFoundError(`no such file: ${resolved}`);
+    return entryFor(resolved, node);
+  }
+
+  async makeDir(sandboxId: string, path: string): Promise<boolean> {
+    this.expect(sandboxId, 'running');
+    const disk = this.disk(sandboxId);
+    const resolved = resolveSandboxPath(path);
+    if (disk.has(resolved)) return false;
+    const now = new Date().toISOString();
+    this.ensureParents(sandboxId, disk, resolved);
+    disk.set(resolved, { type: 'dir', modifiedTime: now });
+    return true;
+  }
+
+  async move(
+    sandboxId: string,
+    from: string,
+    to: string,
+  ): Promise<SandboxEntry> {
+    this.expect(sandboxId, 'running');
+    const disk = this.disk(sandboxId);
+    const source = resolveSandboxPath(from);
+    const destination = resolveSandboxPath(to);
+    const node = disk.get(source);
+    if (!node) throw new FileNotFoundError(`no such file: ${source}`);
+    if (BUILTIN_DIRS[source]) {
+      // Reality refuses too (mount points, root-owned); wording untested.
+      throw new Error(`moving ${source} failed: built-in directory`);
     }
-    if (this.isDirectory(disk, resolved)) {
+    const destNode = disk.get(destination);
+    if (destNode && (node.type === 'dir' || destNode.type === 'dir')) {
+      // rename(2) only replaces a file with a file; everything else errors
+      // on the real executor too (mv wording differs, untested by contract).
+      throw new Error(
+        `moving ${source} to ${destination} failed: destination exists`,
+      );
+    }
+    const oldPrefix = `${source}/`;
+    for (const [p, n] of [...disk]) {
+      if (p !== source && !p.startsWith(oldPrefix)) continue;
+      disk.delete(p);
+      disk.set(destination + p.slice(source.length), n);
+    }
+    return entryFor(destination, node);
+  }
+
+  async remove(sandboxId: string, path: string): Promise<void> {
+    this.expect(sandboxId, 'running');
+    const disk = this.disk(sandboxId);
+    const resolved = resolveSandboxPath(path);
+    const node = disk.get(resolved);
+    if (!node) throw new FileNotFoundError(`no such file: ${resolved}`);
+    if (BUILTIN_DIRS[resolved]) {
+      // rm refuses / outright and cannot rmdir root-owned mount points;
+      // wording differs from the real stderr, untested by contract.
+      throw new Error(`removing ${resolved} failed: built-in directory`);
+    }
+    const prefix = `${resolved}/`;
+    for (const p of [...disk.keys()]) {
+      if (p === resolved || p.startsWith(prefix)) disk.delete(p);
+    }
+  }
+
+  private disk(sandboxId: string): Map<string, FakeNode> {
+    const disk = this.fs.get(sandboxId) ?? seededDisk();
+    this.fs.set(sandboxId, disk);
+    return disk;
+  }
+
+  /** The write path shared by buffered and streaming writes. */
+  private writeNode(
+    sandboxId: string,
+    disk: Map<string, FakeNode>,
+    resolved: string,
+    content: Buffer,
+  ): void {
+    const existing = disk.get(resolved);
+    if (existing?.type === 'dir') {
       throw new NotAFileError(`not a regular file: ${resolved}`);
     }
-    throw new FileNotFoundError(`no such file: ${resolved}`);
+    this.ensureParents(sandboxId, disk, resolved);
+    disk.set(resolved, {
+      type: 'file',
+      content,
+      modifiedTime: new Date().toISOString(),
+    });
   }
 
-  /**
-   * A path is a directory when the image ships it or some file lives under
-   * it — the same observable truth mkdir -p leaves behind on a real disk.
-   */
-  private isDirectory(disk: Map<string, Buffer>, path: string): boolean {
-    if (BUILTIN_DIRS.has(path)) return true;
-    const prefix = path === '/' ? '/' : `${path}/`;
-    for (const existing of disk.keys()) {
-      if (existing.startsWith(prefix)) return true;
+  /** mkdir -p leaves real directories behind; so does the fake. */
+  private ensureParents(
+    sandboxId: string,
+    disk: Map<string, FakeNode>,
+    resolved: string,
+  ): void {
+    const segments = resolved.split('/').filter((s) => s !== '');
+    let parent = '';
+    for (const segment of segments.slice(0, -1)) {
+      parent += `/${segment}`;
+      const node = disk.get(parent);
+      if (node === undefined) {
+        disk.set(parent, {
+          type: 'dir',
+          modifiedTime: new Date().toISOString(),
+        });
+      } else if (node.type !== 'dir') {
+        // mkdir -p over a file fails on the real executor too (its stderr
+        // wording differs; the contract does not pin this path).
+        throw new Error(
+          `cannot create parent directory ${parent} in ${sandboxId}: not a directory`,
+        );
+      }
+    }
+  }
+
+  /** Node with the running-state and is-a-file checks every read shares. */
+  private fileNode(
+    sandboxId: string,
+    resolved: string,
+  ): Extract<FakeNode, { type: 'file' }> {
+    this.expect(sandboxId, 'running');
+    const node = this.disk(sandboxId).get(resolved);
+    if (!node) throw new FileNotFoundError(`no such file: ${resolved}`);
+    if (node.type !== 'file') {
+      throw new NotAFileError(`not a regular file: ${resolved}`);
     }
-    return false;
+    return node;
   }
 
   private expect(sandboxId: string, wanted: ContainerState): void {
@@ -209,54 +468,93 @@ export class FakeExecutor implements Executor {
 }
 
 /**
- * Truncation lives in this single exit so every interpreted command obeys
- * the protocol cap. The interpreter only ever emits ASCII, so string length
- * equals byte length and slice() is an honest byte cap.
+ * Truncation lives in this single sink so the buffered exec obeys the
+ * protocol cap however the interpreter chunks its output. The interpreter
+ * only ever emits ASCII, so string length equals byte length and slice()
+ * is an honest byte cap.
  */
-function fakeResult(exitCode: number, stdout = '', stderr = ''): ExecResult {
-  return {
-    exitCode,
-    stdout: stdout.slice(0, EXEC_OUTPUT_LIMIT_BYTES),
-    stderr: stderr.slice(0, EXEC_OUTPUT_LIMIT_BYTES),
-    stdoutTruncated: stdout.length > EXEC_OUTPUT_LIMIT_BYTES,
-    stderrTruncated: stderr.length > EXEC_OUTPUT_LIMIT_BYTES,
-  };
+class CappedText {
+  text = '';
+  truncated = false;
+
+  constructor(private readonly cap: number) {}
+
+  push(chunk: Buffer): void {
+    const s = chunk.toString('utf8');
+    const room = this.cap - this.text.length;
+    if (room > 0) this.text += s.slice(0, room);
+    if (s.length > room) this.truncated = true;
+  }
+}
+
+interface Emit {
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
 }
 
 /**
- * A six-verb pocket bash: exactly what the contract exam and the e2e suite
- * need to exercise exec through the same questions the real executor
- * answers, nothing more. Not a shell — an unknown verb gets bash's honest
- * 127. If the real bash's wording ever proves different on the test
- * machine, this string yields: reality wins.
+ * A pocket bash: the six verbs plus `;` sequencing — exactly what the
+ * contract exam and the e2e suite need to exercise exec through the same
+ * questions the real executor answers, nothing more. Each verb's output is
+ * its own live chunk (the contract's streaming questions time the gaps).
+ * Not a shell — an unknown verb gets bash's honest 127 and, like bash, the
+ * sequence carries on; `exit` ends it. If the real bash's wording ever
+ * proves different on the test machine, this string yields: reality wins.
  */
-async function interpret(opts: ExecOptions): Promise<ExecResult> {
-  const command = opts.command.trim();
+async function interpret(
+  opts: { command: string; cwd?: string; env?: Record<string, string> },
+  emit: Emit,
+): Promise<number> {
+  let exitCode = 0;
+  for (const segment of opts.command.split(';')) {
+    const command = segment.trim();
+    if (command === '') continue;
+    const exited = command.match(/^exit (\d+)$/)?.[1];
+    if (exited !== undefined) return Number(exited);
+    exitCode = await interpretVerb(command, opts, emit);
+  }
+  return exitCode;
+}
+
+async function interpretVerb(
+  command: string,
+  opts: { cwd?: string; env?: Record<string, string> },
+  emit: Emit,
+): Promise<number> {
   const echoed = command.match(/^echo (.*)$/s)?.[1];
-  if (echoed !== undefined) return fakeResult(0, `${echoed}\n`);
-  const exitCode = command.match(/^exit (\d+)$/)?.[1];
-  if (exitCode !== undefined) return fakeResult(Number(exitCode));
+  if (echoed !== undefined) {
+    emit.stdout(`${echoed}\n`);
+    return 0;
+  }
   const napSeconds = command.match(/^sleep (\d+(?:\.\d+)?)$/)?.[1];
   if (napSeconds !== undefined) {
     // A real timer on purpose: e2e races this against the daemon's
-    // wall-clock idle scanner to prove the exec heartbeat works.
+    // wall-clock idle scanner to prove the exec heartbeat works, and the
+    // contract's streaming questions time the chunk gap it creates.
     await new Promise((resolve) =>
       setTimeout(resolve, Number(napSeconds) * 1000),
     );
-    return fakeResult(0);
+    return 0;
+  }
+  if (command === 'pwd') {
+    emit.stdout(`${opts.cwd ?? '/home/user'}\n`);
+    return 0;
   }
-  if (command === 'pwd') return fakeResult(0, `${opts.cwd ?? '/home/user'}\n`);
   const envKey = command.match(/^printenv (\w+)$/)?.[1];
   if (envKey !== undefined) {
     const value = opts.env?.[envKey];
-    return value === undefined ? fakeResult(1) : fakeResult(0, `${value}\n`);
+    if (value === undefined) return 1;
+    emit.stdout(`${value}\n`);
+    return 0;
   }
   const seqEnd = command.match(/^seq 1 (\d+)$/)?.[1];
   if (seqEnd !== undefined) {
     let out = '';
     for (let i = 1; i <= Number(seqEnd); i++) out += `${i}\n`;
-    return fakeResult(0, out);
+    emit.stdout(out);
+    return 0;
   }
   const verb = command.split(/\s/)[0];
-  return fakeResult(127, '', `bash: line 1: ${verb}: command not found\n`);
+  emit.stderr(`bash: line 1: ${verb}: command not found\n`);
+  return 127;
 }

From b57606266ab529cee51e71f1fd5407ec4e84a2e1 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 18:53:15 +0800
Subject: [PATCH 006/133] The ledger learns E2B deadlines: an absolute clock
 beside the idle rules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five columns, all inert for natively-acquired sandboxes: metadata and
envs (persisted for list filtering and command env merging), deadlineAt
plus onDeadline (the E2B timeout), and pausedByUser (explicit pause,
cleared by every wake — an awake sandbox is not paused).

The scanner enforces deadlines before idle cooling: kill destroys from
any state, pause freezes once and leaves the row parked. Unlike the idle
rules this clock is absolute — activity never extends it, only
create/connect/setTimeout do, which is exactly E2B's semantics.

e2bView() is the single arbiter of what the E2B surface reports: the
LOGICAL state, never the physical one. A sandbox the idle scanner froze
still reads running (passive freezing is an implementation detail, 50ms
wake); paused is reserved for explicit pauses and expired pause-deadlines;
an expired kill-deadline is protocol-dead immediately, physical teardown
follows on the scanner's beat.

The exec heartbeat moves to its own module: the compat layer's streaming
exec and file transfers need the same scanner-repellent as native exec.
---
 packages/server/drizzle/0002_e2b-columns.sql  |   5 +
 .../server/drizzle/meta/0002_snapshot.json    | 135 ++++++++++++++
 packages/server/drizzle/meta/_journal.json    |   7 +
 packages/server/src/db/ledger.ts              |  43 +++++
 packages/server/src/db/schema.ts              |  19 ++
 packages/server/src/e2b/view.test.ts          |  68 +++++++
 packages/server/src/e2b/view.ts               |  23 +++
 packages/server/src/exec-heartbeat.ts         |  27 +++
 packages/server/src/lifecycle.ts              |  18 +-
 packages/server/src/routes/sandboxes.ts       |  26 +--
 packages/server/src/scanner.test.ts           | 173 +++++++++++++++++-
 packages/server/src/scanner.ts                |  42 ++++-
 12 files changed, 546 insertions(+), 40 deletions(-)
 create mode 100644 packages/server/drizzle/0002_e2b-columns.sql
 create mode 100644 packages/server/drizzle/meta/0002_snapshot.json
 create mode 100644 packages/server/src/e2b/view.test.ts
 create mode 100644 packages/server/src/e2b/view.ts
 create mode 100644 packages/server/src/exec-heartbeat.ts

diff --git a/packages/server/drizzle/0002_e2b-columns.sql b/packages/server/drizzle/0002_e2b-columns.sql
new file mode 100644
index 0000000..e2cf669
--- /dev/null
+++ b/packages/server/drizzle/0002_e2b-columns.sql
@@ -0,0 +1,5 @@
+ALTER TABLE `sandboxes` ADD `metadata` text;--> statement-breakpoint
+ALTER TABLE `sandboxes` ADD `envs` text;--> statement-breakpoint
+ALTER TABLE `sandboxes` ADD `deadline_at` text;--> statement-breakpoint
+ALTER TABLE `sandboxes` ADD `on_deadline` text;--> statement-breakpoint
+ALTER TABLE `sandboxes` ADD `paused_by_user` integer DEFAULT false NOT NULL;
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/0002_snapshot.json b/packages/server/drizzle/meta/0002_snapshot.json
new file mode 100644
index 0000000..31f5472
--- /dev/null
+++ b/packages/server/drizzle/meta/0002_snapshot.json
@@ -0,0 +1,135 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "f741bfad-03cf-4605-a353-c4b409ddc2a0",
+  "prevId": "1aef50f2-e7f6-46b3-b2f6-7ce50166defc",
+  "tables": {
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "user_key": {
+          "name": "user_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_user_key_unique": {
+          "name": "sandboxes_user_key_unique",
+          "columns": [
+            "user_key"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index c774636..624a755 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -15,6 +15,13 @@
       "when": 1783538558684,
       "tag": "0001_stop-after-nullable",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1783592514453,
+      "tag": "0002_e2b-columns",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/db/ledger.ts b/packages/server/src/db/ledger.ts
index 3559322..af12a2a 100644
--- a/packages/server/src/db/ledger.ts
+++ b/packages/server/src/db/ledger.ts
@@ -29,6 +29,14 @@ export interface CreateSandboxInput {
   userKey: string;
   nodeId: string;
   policy: LifecyclePolicy;
+  /** E2B-surface extras; native acquire never sets them. */
+  e2b?: {
+    /** JSON-serialized objects, stored verbatim. */
+    metadata: string | null;
+    envs: string | null;
+    deadlineAt: string;
+    onDeadline: 'kill' | 'pause';
+  };
 }
 
 /** Inserts a new sandbox row in `active` state. Throws if the user key is taken. */
@@ -44,6 +52,11 @@ export function createSandbox(db: Db, input: CreateSandboxInput): SandboxRow {
     archiveAfterSeconds: input.policy.archiveAfterSeconds,
     createdAt: now,
     lastActiveAt: now,
+    metadata: input.e2b?.metadata ?? null,
+    envs: input.e2b?.envs ?? null,
+    deadlineAt: input.e2b?.deadlineAt ?? null,
+    onDeadline: input.e2b?.onDeadline ?? null,
+    pausedByUser: false,
   };
   db.insert(sandboxes).values(row).run();
   return row;
@@ -110,6 +123,36 @@ export function overwriteState(
     .run();
 }
 
+/**
+ * Sets or clears the E2B deadline. Both travel together: a deadline without
+ * an action (or the reverse) would be a row the scanner cannot interpret.
+ */
+export function setDeadline(
+  db: Db,
+  sandboxId: string,
+  deadline: { deadlineAt: string; onDeadline: 'kill' | 'pause' } | null,
+): void {
+  db.update(sandboxes)
+    .set({
+      deadlineAt: deadline?.deadlineAt ?? null,
+      onDeadline: deadline?.onDeadline ?? null,
+    })
+    .where(eq(sandboxes.sandboxId, sandboxId))
+    .run();
+}
+
+/** Marks an explicit E2B pause; wakes clear it (an awake sandbox is not paused). */
+export function setPausedByUser(
+  db: Db,
+  sandboxId: string,
+  paused: boolean,
+): void {
+  db.update(sandboxes)
+    .set({ pausedByUser: paused })
+    .where(eq(sandboxes.sandboxId, sandboxId))
+    .run();
+}
+
 export function findByUserKey(db: Db, userKey: string): SandboxRow | undefined {
   return db
     .select()
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index f875db7..f61a6cc 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -23,6 +23,25 @@ export const sandboxes = sqliteTable('sandboxes', {
   archiveAfterSeconds: integer('archive_after_seconds'),
   createdAt: text('created_at').notNull(),
   lastActiveAt: text('last_active_at').notNull(),
+  /**
+   * The E2B surface's columns. All NULL / defaulted for natively-acquired
+   * sandboxes — the native lifecycle never reads them.
+   */
+  /** JSON object; E2B metadata, persisted for list filtering and echo. */
+  metadata: text('metadata'),
+  /** JSON object; sandbox-level default envs, merged under per-command envs. */
+  envs: text('envs'),
+  /** ISO 8601; the E2B timeout's absolute deadline. NULL = no deadline. */
+  deadlineAt: text('deadline_at'),
+  /** What the scanner does when deadlineAt passes. Non-null iff deadlineAt is. */
+  onDeadline: text('on_deadline', { enum: ['kill', 'pause'] }),
+  /**
+   * Explicitly paused through the E2B surface and not woken since. Only
+   * consulted by the logical-state view; every wake back to active clears it.
+   */
+  pausedByUser: integer('paused_by_user', { mode: 'boolean' })
+    .notNull()
+    .default(false),
 });
 
 export type SandboxRow = typeof sandboxes.$inferSelect;
diff --git a/packages/server/src/e2b/view.test.ts b/packages/server/src/e2b/view.test.ts
new file mode 100644
index 0000000..22cf17b
--- /dev/null
+++ b/packages/server/src/e2b/view.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import type { SandboxRow } from '../db/schema';
+import { e2bView } from './view';
+
+function row(overrides: Partial<SandboxRow>): SandboxRow {
+  return {
+    sandboxId: 'sbx-1',
+    userKey: 'alice',
+    state: 'active',
+    nodeId: 'node-test',
+    freezeAfterSeconds: 60,
+    stopAfterSeconds: null,
+    archiveAfterSeconds: null,
+    createdAt: '2026-07-09T00:00:00.000Z',
+    lastActiveAt: '2026-07-09T00:00:00.000Z',
+    metadata: null,
+    envs: null,
+    deadlineAt: null,
+    onDeadline: null,
+    pausedByUser: false,
+    ...overrides,
+  };
+}
+
+const NOW = new Date('2026-07-09T12:00:00.000Z');
+
+describe('e2bView', () => {
+  it('reports the logical state, not the physical one: frozen and stopped still read running', () => {
+    // Passive cooling is Dormice's implementation detail — until a deadline
+    // or an explicit pause says otherwise, the sandbox is protocol-alive.
+    expect(e2bView(row({ state: 'active' }), NOW)).toBe('running');
+    expect(e2bView(row({ state: 'frozen' }), NOW)).toBe('running');
+    expect(e2bView(row({ state: 'stopped' }), NOW)).toBe('running');
+  });
+
+  it('a future deadline is still running; an expired one acts', () => {
+    const future = new Date(NOW.getTime() + 60_000).toISOString();
+    const past = new Date(NOW.getTime() - 1).toISOString();
+    expect(e2bView(row({ deadlineAt: future, onDeadline: 'kill' }), NOW)).toBe(
+      'running',
+    );
+    expect(e2bView(row({ deadlineAt: past, onDeadline: 'kill' }), NOW)).toBe(
+      'dead',
+    );
+    expect(e2bView(row({ deadlineAt: past, onDeadline: 'pause' }), NOW)).toBe(
+      'paused',
+    );
+  });
+
+  it('an explicit pause reads paused whatever the physical state', () => {
+    expect(e2bView(row({ pausedByUser: true, state: 'active' }), NOW)).toBe(
+      'paused',
+    );
+    expect(e2bView(row({ pausedByUser: true, state: 'frozen' }), NOW)).toBe(
+      'paused',
+    );
+  });
+
+  it('an expired kill deadline outranks an explicit pause: dead is dead', () => {
+    const past = new Date(NOW.getTime() - 1).toISOString();
+    expect(
+      e2bView(
+        row({ deadlineAt: past, onDeadline: 'kill', pausedByUser: true }),
+        NOW,
+      ),
+    ).toBe('dead');
+  });
+});
diff --git a/packages/server/src/e2b/view.ts b/packages/server/src/e2b/view.ts
new file mode 100644
index 0000000..63ed292
--- /dev/null
+++ b/packages/server/src/e2b/view.ts
@@ -0,0 +1,23 @@
+import type { SandboxRow } from '../db/schema';
+
+export type E2bState = 'running' | 'paused' | 'dead';
+
+/**
+ * The single arbiter of what the E2B surface says about a sandbox.
+ *
+ * It reports the LOGICAL state, never the physical one: a sandbox the idle
+ * scanner froze behind the caller's back is still `running` here — passive
+ * freezing is Dormice's implementation detail (50ms wake, invisible to the
+ * caller), and protocol-wise the sandbox is alive until its deadline says
+ * otherwise. `paused` is reserved for what E2B means by it: an explicit
+ * pause, or an expired deadline whose action is pause. An expired kill-type
+ * deadline reports `dead` — the sandbox is protocol-gone the moment the
+ * deadline passes; the scanner's physical teardown follows on its own beat.
+ */
+export function e2bView(row: SandboxRow, now: Date): E2bState {
+  if (row.deadlineAt !== null && Date.parse(row.deadlineAt) <= now.getTime()) {
+    return row.onDeadline === 'pause' ? 'paused' : 'dead';
+  }
+  if (row.pausedByUser) return 'paused';
+  return 'running';
+}
diff --git a/packages/server/src/exec-heartbeat.ts b/packages/server/src/exec-heartbeat.ts
new file mode 100644
index 0000000..4fc82a9
--- /dev/null
+++ b/packages/server/src/exec-heartbeat.ts
@@ -0,0 +1,27 @@
+import type { Db } from './db/db';
+import { touch } from './db/ledger';
+
+/**
+ * Keeps a sandbox's idle clock fresh while an exec (or a long file stream)
+ * is in flight, so the scanner never freezes a container that is
+ * mid-command. Half the freeze threshold (never above 10s) lands at least
+ * one touch inside every scan window, down to the schema's minimum
+ * freezeAfterSeconds of 1. A vanished row (released mid-exec) stops the
+ * timer — the exec itself will fail with its own honest error; an unhandled
+ * throw inside setInterval would take the daemon down instead.
+ */
+export function startExecHeartbeat(
+  db: Db,
+  sandboxId: string,
+  freezeAfterSeconds: number,
+): () => void {
+  const intervalMs = Math.min((freezeAfterSeconds * 1000) / 2, 10_000);
+  const timer = setInterval(() => {
+    try {
+      touch(db, sandboxId);
+    } catch {
+      clearInterval(timer);
+    }
+  }, intervalMs);
+  return () => clearInterval(timer);
+}
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index e5f5c65..419da29 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -1,5 +1,5 @@
 import type { Db } from './db/db';
-import { deleteSandbox, transition } from './db/ledger';
+import { deleteSandbox, setPausedByUser, transition } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import type { Executor } from './executor/executor';
 
@@ -58,10 +58,10 @@ export async function wakeSandbox(
       return row;
     case 'frozen':
       await executor.unfreeze(row.sandboxId);
-      return transition(db, row.sandboxId, 'active');
+      return awaken(db, row);
     case 'stopped':
       await executor.start(row.sandboxId);
-      return transition(db, row.sandboxId, 'active');
+      return awaken(db, row);
     case 'archived':
     case 'restoring':
       // Unreachable today — nothing archives until the S3 archiver lands.
@@ -71,3 +71,15 @@ export async function wakeSandbox(
       );
   }
 }
+
+/**
+ * The ledger side of a wake. An awake sandbox is by definition not paused,
+ * so any explicit E2B pause mark is cleared along with the transition —
+ * ledger honesty, not an E2B-surface concern leaking in.
+ */
+function awaken(db: Db, row: SandboxRow): SandboxRow {
+  if (row.pausedByUser) {
+    setPausedByUser(db, row.sandboxId, false);
+  }
+  return { ...transition(db, row.sandboxId, 'active'), pausedByUser: false };
+}
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index ba346df..25fea15 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -28,6 +28,7 @@ import {
   touch,
 } from '../db/ledger';
 import type { SandboxRow } from '../db/schema';
+import { startExecHeartbeat } from '../exec-heartbeat';
 import {
   type Executor,
   FileNotFoundError,
@@ -46,31 +47,6 @@ export interface SandboxRoutesOptions {
   locks: KeyedQueue;
 }
 
-/**
- * Keeps a sandbox's idle clock fresh while an exec is in flight, so the
- * scanner never freezes a container that is mid-command. Half the freeze
- * threshold (never above 10s) lands at least one touch inside every scan
- * window, down to the schema's minimum freezeAfterSeconds of 1. A vanished
- * row (released mid-exec) stops the timer — the exec itself will fail with
- * its own honest error; an unhandled throw inside setInterval would take
- * the daemon down instead.
- */
-function startExecHeartbeat(
-  db: Db,
-  sandboxId: string,
-  freezeAfterSeconds: number,
-): () => void {
-  const intervalMs = Math.min((freezeAfterSeconds * 1000) / 2, 10_000);
-  const timer = setInterval(() => {
-    try {
-      touch(db, sandboxId);
-    } catch {
-      clearInterval(timer);
-    }
-  }, intervalMs);
-  return () => clearInterval(timer);
-}
-
 /** Ledger row -> wire shape: nest the flat policy columns, attach the endpoint. */
 function toSandbox(row: SandboxRow, endpoint: string): Sandbox {
   return {
diff --git a/packages/server/src/scanner.test.ts b/packages/server/src/scanner.test.ts
index bf58bc1..1f41050 100644
--- a/packages/server/src/scanner.test.ts
+++ b/packages/server/src/scanner.test.ts
@@ -6,7 +6,7 @@ import {
 } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { type Db, migrateDb, openDb } from './db/db';
-import { createSandbox, findByUserKey } from './db/ledger';
+import { createSandbox, findByUserKey, setDeadline, touch } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
@@ -42,7 +42,12 @@ describe('idle scanner', () => {
     const { db, executor, locks } = setup();
     const row = await seed(db, executor, 'alice');
     const result = await scanOnce(db, executor, locks, after(row, 1));
-    expect(result).toEqual({ frozen: 0, stopped: 0, failures: [] });
+    expect(result).toEqual({
+      frozen: 0,
+      stopped: 0,
+      expiredKilled: 0,
+      failures: [],
+    });
     expect(findByUserKey(db, 'alice')?.state).toBe('active');
     expect(executor.stateOf(row.sandboxId)).toBe('running');
   });
@@ -56,7 +61,12 @@ describe('idle scanner', () => {
       locks,
       after(row, row.freezeAfterSeconds),
     );
-    expect(result).toEqual({ frozen: 1, stopped: 0, failures: [] });
+    expect(result).toEqual({
+      frozen: 1,
+      stopped: 0,
+      expiredKilled: 0,
+      failures: [],
+    });
     expect(findByUserKey(db, 'alice')?.state).toBe('frozen');
     expect(executor.stateOf(row.sandboxId)).toBe('paused');
   });
@@ -71,7 +81,12 @@ describe('idle scanner', () => {
     });
     await scanOnce(db, executor, locks, after(row, 60));
     const result = await scanOnce(db, executor, locks, after(row, 120));
-    expect(result).toEqual({ frozen: 0, stopped: 1, failures: [] });
+    expect(result).toEqual({
+      frozen: 0,
+      stopped: 1,
+      expiredKilled: 0,
+      failures: [],
+    });
     expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
     expect(executor.stateOf(row.sandboxId)).toBe('stopped');
   });
@@ -83,12 +98,14 @@ describe('idle scanner', () => {
     expect(await scanOnce(db, executor, locks, yearLater)).toEqual({
       frozen: 1,
       stopped: 0,
+      expiredKilled: 0,
       failures: [],
     });
     expect(findByUserKey(db, 'alice')?.state).toBe('frozen');
     expect(await scanOnce(db, executor, locks, yearLater)).toEqual({
       frozen: 0,
       stopped: 1,
+      expiredKilled: 0,
       failures: [],
     });
     expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
@@ -102,7 +119,12 @@ describe('idle scanner', () => {
     });
     const slow = await seed(db, executor, 'slow');
     const result = await scanOnce(db, executor, locks, after(quick, 100));
-    expect(result).toEqual({ frozen: 1, stopped: 0, failures: [] });
+    expect(result).toEqual({
+      frozen: 1,
+      stopped: 0,
+      expiredKilled: 0,
+      failures: [],
+    });
     expect(findByUserKey(db, 'quick')?.state).toBe('frozen');
     expect(findByUserKey(db, 'slow')?.state).toBe('active');
     expect(executor.stateOf(slow.sandboxId)).toBe('running');
@@ -125,7 +147,12 @@ describe('idle scanner', () => {
       locks,
       after(row, 365 * 24 * 60 * 60),
     );
-    expect(yearLater).toEqual({ frozen: 0, stopped: 0, failures: [] });
+    expect(yearLater).toEqual({
+      frozen: 0,
+      stopped: 0,
+      expiredKilled: 0,
+      failures: [],
+    });
     expect(findByUserKey(db, 'resident')?.state).toBe('frozen');
   });
 
@@ -182,7 +209,12 @@ describe('idle scanner vs the per-key queue', () => {
       locks,
       after(row, row.freezeAfterSeconds),
     );
-    expect(result).toEqual({ frozen: 0, stopped: 0, failures: [] });
+    expect(result).toEqual({
+      frozen: 0,
+      stopped: 0,
+      expiredKilled: 0,
+      failures: [],
+    });
     expect(findByUserKey(db, 'alice')?.state).toBe('active');
 
     release();
@@ -194,7 +226,12 @@ describe('idle scanner vs the per-key queue', () => {
       locks,
       after(row, row.freezeAfterSeconds),
     );
-    expect(next).toEqual({ frozen: 1, stopped: 0, failures: [] });
+    expect(next).toEqual({
+      frozen: 1,
+      stopped: 0,
+      expiredKilled: 0,
+      failures: [],
+    });
   });
 
   it('re-reads under the lock: a sandbox released mid-sweep is skipped, not failed', async () => {
@@ -226,7 +263,125 @@ describe('idle scanner vs the per-key queue', () => {
     );
     const [result] = await Promise.all([sweep, released]);
 
-    expect(result).toEqual({ frozen: 1, stopped: 0, failures: [] });
+    expect(result).toEqual({
+      frozen: 1,
+      stopped: 0,
+      expiredKilled: 0,
+      failures: [],
+    });
+    expect(findByUserKey(db, 'doomed')).toBeUndefined();
+  });
+});
+
+describe('E2B deadline rule', () => {
+  async function seedWithDeadline(
+    db: Db,
+    executor: FakeExecutor,
+    userKey: string,
+    row: SandboxRow | null,
+    afterSeconds: number,
+    onDeadline: 'kill' | 'pause',
+  ): Promise<SandboxRow> {
+    const seeded = row ?? (await seed(db, executor, userKey));
+    setDeadline(db, seeded.sandboxId, {
+      deadlineAt: after(seeded, afterSeconds).toISOString(),
+      onDeadline,
+    });
+    return seeded;
+  }
+
+  it('kills an expired kill-deadline sandbox: container, disk and row gone', async () => {
+    const { db, executor, locks } = setup();
+    const row = await seedWithDeadline(
+      db,
+      executor,
+      'doomed',
+      null,
+      100,
+      'kill',
+    );
+
+    // Before the deadline nothing happens (idle is far below freeze too).
+    const early = await scanOnce(db, executor, locks, after(row, 50));
+    expect(early).toEqual({
+      frozen: 0,
+      stopped: 0,
+      expiredKilled: 0,
+      failures: [],
+    });
+
+    const late = await scanOnce(db, executor, locks, after(row, 100));
+    expect(late).toEqual({
+      frozen: 0,
+      stopped: 0,
+      expiredKilled: 1,
+      failures: [],
+    });
     expect(findByUserKey(db, 'doomed')).toBeUndefined();
+    expect(executor.stateOf(row.sandboxId)).toBeUndefined();
+    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+  });
+
+  it('the deadline outranks idle cooling: due for both means dead, not frozen', async () => {
+    const { db, executor, locks } = setup();
+    const row = await seedWithDeadline(db, executor, 'both', null, 10, 'kill');
+    // Way past freezeAfterSeconds AND past the deadline.
+    const result = await scanOnce(
+      db,
+      executor,
+      locks,
+      after(row, row.freezeAfterSeconds + 1000),
+    );
+    expect(result).toEqual({
+      frozen: 0,
+      stopped: 0,
+      expiredKilled: 1,
+      failures: [],
+    });
+    expect(findByUserKey(db, 'both')).toBeUndefined();
+  });
+
+  it('activity does not extend a deadline — it is an absolute clock', async () => {
+    const { db, executor, locks } = setup();
+    const row = await seedWithDeadline(db, executor, 'busy', null, 100, 'kill');
+    // The sandbox stays busy right up to the deadline; E2B kills anyway —
+    // only create/connect/setTimeout move a deadline, never activity.
+    touch(db, row.sandboxId, after(row, 99).toISOString());
+    const result = await scanOnce(db, executor, locks, after(row, 101));
+    expect(result.expiredKilled).toBe(1);
+    expect(findByUserKey(db, 'busy')).toBeUndefined();
+  });
+
+  it('parks an expired pause-deadline sandbox frozen, once, and keeps the row', async () => {
+    const { db, executor, locks } = setup();
+    const row = await seedWithDeadline(
+      db,
+      executor,
+      'parked',
+      null,
+      100,
+      'pause',
+    );
+
+    const late = await scanOnce(db, executor, locks, after(row, 100));
+    expect(late).toEqual({
+      frozen: 1,
+      stopped: 0,
+      expiredKilled: 0,
+      failures: [],
+    });
+    expect(findByUserKey(db, 'parked')?.state).toBe('frozen');
+    expect(executor.stateOf(row.sandboxId)).toBe('paused');
+
+    // A second sweep finds no physical work left: frozen already satisfies
+    // the pause action, and the logical view reads the deadline directly.
+    const again = await scanOnce(db, executor, locks, after(row, 200));
+    expect(again).toEqual({
+      frozen: 0,
+      stopped: 0,
+      expiredKilled: 0,
+      failures: [],
+    });
+    expect(findByUserKey(db, 'parked')?.state).toBe('frozen');
   });
 });
diff --git a/packages/server/src/scanner.ts b/packages/server/src/scanner.ts
index ac7546b..6c82fd5 100644
--- a/packages/server/src/scanner.ts
+++ b/packages/server/src/scanner.ts
@@ -3,15 +3,33 @@ import { findBySandboxId, listSandboxes } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
-import { freezeSandbox, stopSandbox } from './lifecycle';
+import { freezeSandbox, releaseSandbox, stopSandbox } from './lifecycle';
 
 export interface ScanResult {
   frozen: number;
   stopped: number;
+  /** E2B deadlines whose action was kill, enforced this sweep: sandbox destroyed. */
+  expiredKilled: number;
   /** Sandboxes whose transition failed this sweep; the caller logs them. */
   failures: Array<{ sandboxId: string; message: string }>;
 }
 
+/**
+ * The E2B deadline rule. Unlike the idle rules it is an absolute clock —
+ * E2B kills a sandbox at its deadline even mid-command; activity does not
+ * extend it, only create/connect/setTimeout do. `kill` applies from any
+ * state (release handles them all); `pause` only has physical work while
+ * the sandbox is still active — colder states already satisfy it, and the
+ * logical view reads the expired deadline directly.
+ */
+function dueDeadline(row: SandboxRow, now: Date): 'kill' | 'pause' | null {
+  if (row.deadlineAt === null || Date.parse(row.deadlineAt) > now.getTime()) {
+    return null;
+  }
+  if (row.onDeadline !== 'pause') return 'kill';
+  return row.state === 'active' ? 'pause' : null;
+}
+
 /**
  * Which one-rung-colder move a row is due for, if any. One rung per sweep,
  * mirroring ALLOWED_TRANSITIONS — a long-dead sandbox freezes on this sweep
@@ -65,9 +83,14 @@ export async function scanOnce(
   locks: KeyedQueue,
   now: Date,
 ): Promise<ScanResult> {
-  const result: ScanResult = { frozen: 0, stopped: 0, failures: [] };
+  const result: ScanResult = {
+    frozen: 0,
+    stopped: 0,
+    expiredKilled: 0,
+    failures: [],
+  };
   for (const row of listSandboxes(db)) {
-    if (dueTransition(row, now) === null) {
+    if (dueDeadline(row, now) === null && dueTransition(row, now) === null) {
       continue;
     }
     try {
@@ -76,6 +99,19 @@ export async function scanOnce(
         if (!fresh) {
           return; // Released since the sweep's snapshot.
         }
+        // The deadline outranks idle cooling: a row due for both dies (or
+        // parks) by its deadline, not one rung colder.
+        const deadline = dueDeadline(fresh, now);
+        if (deadline === 'kill') {
+          await releaseSandbox(db, executor, fresh.sandboxId);
+          result.expiredKilled += 1;
+          return;
+        }
+        if (deadline === 'pause') {
+          await freezeSandbox(db, executor, fresh.sandboxId);
+          result.frozen += 1;
+          return;
+        }
         const due = dueTransition(fresh, now);
         if (due === 'freeze') {
           await freezeSandbox(db, executor, fresh.sandboxId);

From 58db3ac6715d08cd22722fd4f266f39fd2018798 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 18:53:38 +0800
Subject: [PATCH 007/133] E2B compatibility layer: control plane and envd on
 one origin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The official e2b package connects with two URLs — apiUrl -> /e2b/api,
sandboxUrl -> /e2b/envd — plus e2b_<token> as its API key; it names the
target sandbox in an E2b-Sandbox-Id header on every envd request, so a
single origin serves every sandbox with no wildcard DNS.

Faithful by default: create is fresh each call, the timeout kills at its
deadline (autoPause parks instead), kill destroys container, disk and
row. Dormice's immortality is opt-in — metadata.userKey makes create
idempotent (an acquire in E2B clothes), and lifecycle verbs never impose
a deadline on natively-acquired sandboxes.

envd speaks Connect RPC in the JSON codec: unary filesystem verbs
(Stat/ListDir/MakeDir/Move/Remove) run in the key's slot; Process/Start
streams enveloped start/data/end events with keepalives, the daemon's own
timer answering a blown connect-timeout-ms with deadline_exceeded — the
in-container kill is just cleanup, never a 137 guessing game. /files
uploads stream through multipart (preservePath: the filename IS the
destination path) or octet-stream, downloads stream out with an exact
content-length; no artificial size cap — the disk quota is the ceiling.

Two error dialects, both verified against the SDK: the control plane's
{code, message} carries the NUMERIC status (openapi-fetch checks
error.code === 404 for kill-already-gone and 409 for pause-already-
paused); Connect errors carry the protocol's string codes. What v1 does
not support answers unimplemented with a hint: stdin, signals, process
reconnect, PTY, watch.
---
 packages/server/package.json           |   1 +
 packages/server/src/app.ts             |   7 +
 packages/server/src/e2b/compat.test.ts | 615 ++++++++++++++++++++++
 packages/server/src/e2b/control.ts     | 377 ++++++++++++++
 packages/server/src/e2b/deps.ts        |  12 +
 packages/server/src/e2b/envd.ts        | 686 +++++++++++++++++++++++++
 packages/server/src/e2b/index.ts       |  19 +
 packages/server/src/e2b/protocol.ts    | 127 +++++
 pnpm-lock.yaml                         | 247 +++++++++
 9 files changed, 2091 insertions(+)
 create mode 100644 packages/server/src/e2b/compat.test.ts
 create mode 100644 packages/server/src/e2b/control.ts
 create mode 100644 packages/server/src/e2b/deps.ts
 create mode 100644 packages/server/src/e2b/envd.ts
 create mode 100644 packages/server/src/e2b/index.ts
 create mode 100644 packages/server/src/e2b/protocol.ts

diff --git a/packages/server/package.json b/packages/server/package.json
index 6cade4d..5369c16 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -21,6 +21,7 @@
   },
   "dependencies": {
     "@dormice/shared": "workspace:*",
+    "@fastify/multipart": "^10.0.0",
     "better-sqlite3": "^12.11.1",
     "dockerode": "^5.0.1",
     "drizzle-orm": "^0.45.2",
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index c6fba1a..2f6f10a 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -9,6 +9,7 @@ import { z } from 'zod';
 import { requireApiToken } from './auth';
 import type { Config } from './config';
 import type { Db } from './db/db';
+import { registerE2bCompat } from './e2b';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
 import { sandboxRoutes } from './routes/sandboxes';
@@ -92,5 +93,11 @@ export function buildApp({
     await api.register(sandboxRoutes, { config, db, executor, locks });
   });
 
+  // The E2B compatibility surface lives beside the native API with its own
+  // auth (X-API-KEY / X-Access-Token) and its own error dialect.
+  app.register(async (compat) => {
+    await registerE2bCompat(compat, { config, db, executor, locks });
+  });
+
   return app;
 }
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
new file mode 100644
index 0000000..d6f141a
--- /dev/null
+++ b/packages/server/src/e2b/compat.test.ts
@@ -0,0 +1,615 @@
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { buildApp } from '../app';
+import { loadConfig } from '../config';
+import { migrateDb, openDb } from '../db/db';
+import { findBySandboxId, setDeadline } from '../db/ledger';
+import { FakeExecutor } from '../executor/fake';
+import { KeyedQueue } from '../keyed-queue';
+import { scanOnce } from '../scanner';
+import { mintEnvdToken } from './protocol';
+
+const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
+const TOKEN = 'test-token-test-token-test-token';
+
+function testApp(executor: FakeExecutor = new FakeExecutor()) {
+  const db = openDb(':memory:');
+  migrateDb(db, MIGRATIONS);
+  const config = loadConfig({
+    DORMICE_DB_PATH: ':memory:',
+    DORMICE_NODE_ID: 'node-test',
+    DORMICE_API_TOKEN: TOKEN,
+  });
+  const locks = new KeyedQueue();
+  const app = buildApp({ config, db, executor, locks, logger: false });
+  return { app, db, executor, locks };
+}
+
+type TestApp = ReturnType<typeof testApp>;
+
+const apiKey = { 'x-api-key': `e2b_${TOKEN}` };
+
+function control(
+  t: TestApp,
+  method: 'POST' | 'GET' | 'DELETE',
+  url: string,
+  payload?: Record<string, unknown>,
+) {
+  return t.app.inject({
+    method,
+    url: `/e2b/api${url}`,
+    headers: apiKey,
+    ...(payload === undefined ? {} : { payload }),
+  });
+}
+
+async function createSandbox(
+  t: TestApp,
+  payload: Record<string, unknown> = {},
+): Promise<{ sandboxID: string; envdAccessToken: string }> {
+  const res = await control(t, 'POST', '/sandboxes', payload);
+  expect(res.statusCode).toBe(201);
+  return res.json();
+}
+
+function envdHeaders(sandboxID: string) {
+  return {
+    'e2b-sandbox-id': sandboxID,
+    'x-access-token': mintEnvdToken(TOKEN, sandboxID),
+  };
+}
+
+function envdRpc(
+  t: TestApp,
+  sandboxID: string,
+  url: string,
+  payload: Record<string, unknown>,
+) {
+  return t.app.inject({
+    method: 'POST',
+    url: `/e2b/envd${url}`,
+    headers: envdHeaders(sandboxID),
+    payload,
+  });
+}
+
+/** 1 flag byte + 4-byte BE length + JSON, repeated — the Connect stream shape. */
+function parseEnvelopes(
+  payload: Buffer,
+): Array<{ flags: number; json: Record<string, unknown> }> {
+  const frames: Array<{ flags: number; json: Record<string, unknown> }> = [];
+  let offset = 0;
+  while (offset + 5 <= payload.length) {
+    const flags = payload.readUInt8(offset);
+    const length = payload.readUInt32BE(offset + 1);
+    const body = payload.subarray(offset + 5, offset + 5 + length);
+    frames.push({
+      flags,
+      json: body.length > 0 ? JSON.parse(body.toString('utf8')) : {},
+    });
+    offset += 5 + length;
+  }
+  return frames;
+}
+
+function startCommand(
+  t: TestApp,
+  sandboxID: string,
+  command: string,
+  opts: {
+    envs?: Record<string, string>;
+    headers?: Record<string, string>;
+  } = {},
+) {
+  const message = {
+    process: {
+      cmd: '/bin/bash',
+      args: ['-l', '-c', command],
+      envs: opts.envs ?? {},
+    },
+  };
+  const json = Buffer.from(JSON.stringify(message), 'utf8');
+  const head = Buffer.alloc(5);
+  head.writeUInt8(0, 0);
+  head.writeUInt32BE(json.length, 1);
+  return t.app.inject({
+    method: 'POST',
+    url: '/e2b/envd/process.Process/Start',
+    headers: {
+      ...envdHeaders(sandboxID),
+      'content-type': 'application/connect+json',
+      ...opts.headers,
+    },
+    payload: Buffer.concat([head, json]),
+  });
+}
+
+describe('E2B control plane', () => {
+  it('guards with X-API-KEY: e2b_-prefixed and bare tokens pass, others do not', async () => {
+    const t = testApp();
+    const denied = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/api/sandboxes',
+      headers: { 'x-api-key': 'e2b_wrong' },
+      payload: {},
+    });
+    expect(denied.statusCode).toBe(401);
+    expect(denied.json()).toEqual({ code: 401, message: 'invalid API key' });
+
+    const bare = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/api/sandboxes',
+      headers: { 'x-api-key': TOKEN },
+      payload: {},
+    });
+    expect(bare.statusCode).toBe(201);
+  });
+
+  it('creates a fresh sandbox per call — E2B semantics, no key given', async () => {
+    const t = testApp();
+    const first = await createSandbox(t);
+    const second = await createSandbox(t);
+    expect(first.sandboxID).not.toBe(second.sandboxID);
+    expect(first.envdAccessToken).toBe(mintEnvdToken(TOKEN, first.sandboxID));
+    expect(t.executor.stateOf(first.sandboxID)).toBe('running');
+  });
+
+  it('metadata.userKey is the Dormice extension: same key, same sandbox', async () => {
+    const t = testApp();
+    const first = await createSandbox(t, { metadata: { userKey: 'agent-7' } });
+    const second = await createSandbox(t, { metadata: { userKey: 'agent-7' } });
+    expect(second.sandboxID).toBe(first.sandboxID);
+  });
+
+  it('getInfo echoes metadata and reports the deadline as endAt', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t, {
+      timeout: 600,
+      metadata: { userKey: 'meta-echo', team: 'blue' },
+    });
+    const res = await control(t, 'GET', `/sandboxes/${sandboxID}`);
+    expect(res.statusCode).toBe(200);
+    const info = res.json();
+    expect(info.state).toBe('running');
+    expect(info.metadata).toEqual({ userKey: 'meta-echo', team: 'blue' });
+    const endInMs = Date.parse(info.endAt) - Date.now();
+    expect(endInMs).toBeGreaterThan(590_000);
+    expect(endInMs).toBeLessThan(610_000);
+  });
+
+  it('kill destroys for real: container, disk, row — and 404s after', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const killed = await control(t, 'DELETE', `/sandboxes/${sandboxID}`);
+    expect(killed.statusCode).toBe(204);
+    expect(t.executor.stateOf(sandboxID)).toBeUndefined();
+    expect(await t.executor.listDisks()).not.toContain(sandboxID);
+    expect(findBySandboxId(t.db, sandboxID)).toBeUndefined();
+
+    const again = await control(t, 'DELETE', `/sandboxes/${sandboxID}`);
+    expect(again.statusCode).toBe(404);
+    // The SDK's kill() keys "already gone -> false" off this numeric code.
+    expect(again.json().code).toBe(404);
+  });
+
+  it('an expired kill-deadline is protocol-dead immediately, reaped by the scanner after', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t, { timeout: 300 });
+    const row = findBySandboxId(t.db, sandboxID);
+    expect(row?.onDeadline).toBe('kill');
+    // Time-travel the deadline into the past instead of sleeping.
+    setDeadline(t.db, sandboxID, {
+      deadlineAt: new Date(Date.now() - 1000).toISOString(),
+      onDeadline: 'kill',
+    });
+
+    // The view answers dead before any physical teardown happened.
+    expect(
+      (await control(t, 'GET', `/sandboxes/${sandboxID}`)).statusCode,
+    ).toBe(404);
+    const connect = await control(
+      t,
+      'POST',
+      `/sandboxes/${sandboxID}/connect`,
+      {
+        timeout: 300,
+      },
+    );
+    expect(connect.statusCode).toBe(404);
+
+    // The scanner's sweep makes it physical.
+    const result = await scanOnce(t.db, t.executor, t.locks, new Date());
+    expect(result.expiredKilled).toBe(1);
+    expect(t.executor.stateOf(sandboxID)).toBeUndefined();
+  });
+
+  it('autoPause parks at the deadline and connect revives with a fresh TTL', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t, {
+      timeout: 300,
+      autoPause: true,
+    });
+    setDeadline(t.db, sandboxID, {
+      deadlineAt: new Date(Date.now() - 1000).toISOString(),
+      onDeadline: 'pause',
+    });
+
+    const paused = await control(t, 'GET', `/sandboxes/${sandboxID}`);
+    expect(paused.json().state).toBe('paused');
+
+    const connect = await control(
+      t,
+      'POST',
+      `/sandboxes/${sandboxID}/connect`,
+      {
+        timeout: 300,
+      },
+    );
+    expect(connect.statusCode).toBe(201); // 201 = this connect resumed it
+
+    const info = await control(t, 'GET', `/sandboxes/${sandboxID}`);
+    expect(info.json().state).toBe('running');
+    const fresh = findBySandboxId(t.db, sandboxID);
+    expect(Date.parse(fresh?.deadlineAt ?? '')).toBeGreaterThan(Date.now());
+  });
+
+  it('pause parks (frozen), reports paused, 409s a second pause, connect resumes', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const paused = await control(
+      t,
+      'POST',
+      `/sandboxes/${sandboxID}/pause`,
+      {},
+    );
+    expect(paused.statusCode).toBe(204);
+    expect(t.executor.stateOf(sandboxID)).toBe('paused');
+    expect(
+      (await control(t, 'GET', `/sandboxes/${sandboxID}`)).json().state,
+    ).toBe('paused');
+
+    const again = await control(t, 'POST', `/sandboxes/${sandboxID}/pause`, {});
+    expect(again.statusCode).toBe(409);
+
+    const connect = await control(
+      t,
+      'POST',
+      `/sandboxes/${sandboxID}/connect`,
+      {
+        timeout: 300,
+      },
+    );
+    expect(connect.statusCode).toBe(201);
+    expect(t.executor.stateOf(sandboxID)).toBe('running');
+  });
+
+  it('pause with memory:false maps to stopped — filesystem only, cold boot on resume', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const res = await control(t, 'POST', `/sandboxes/${sandboxID}/pause`, {
+      memory: false,
+    });
+    expect(res.statusCode).toBe(204);
+    expect(t.executor.stateOf(sandboxID)).toBe('stopped');
+    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('stopped');
+  });
+
+  it('lists with metadata and state filters, paginating via x-next-token', async () => {
+    const t = testApp();
+    const blue1 = await createSandbox(t, { metadata: { team: 'blue' } });
+    const blue2 = await createSandbox(t, { metadata: { team: 'blue' } });
+    await createSandbox(t, { metadata: { team: 'red' } });
+
+    const blues = await control(t, 'GET', '/v2/sandboxes?metadata=team%3Dblue');
+    expect(blues.statusCode).toBe(200);
+    expect(
+      blues
+        .json()
+        .map((s: { sandboxID: string }) => s.sandboxID)
+        .sort(),
+    ).toEqual([blue1.sandboxID, blue2.sandboxID].sort());
+
+    await control(t, 'POST', `/sandboxes/${blue1.sandboxID}/pause`, {});
+    const pausedOnly = await control(t, 'GET', '/v2/sandboxes?state=paused');
+    expect(
+      pausedOnly.json().map((s: { sandboxID: string }) => s.sandboxID),
+    ).toEqual([blue1.sandboxID]);
+
+    const pageOne = await control(t, 'GET', '/v2/sandboxes?limit=2');
+    expect(pageOne.json()).toHaveLength(2);
+    const token = pageOne.headers['x-next-token'];
+    expect(token).toBe('2');
+    const pageTwo = await control(
+      t,
+      'GET',
+      `/v2/sandboxes?limit=2&nextToken=${token}`,
+    );
+    expect(pageTwo.json()).toHaveLength(1);
+    expect(pageTwo.headers['x-next-token']).toBeUndefined();
+  });
+
+  it('never imposes a deadline on a natively-acquired sandbox', async () => {
+    const t = testApp();
+    const native = await t.app.inject({
+      method: 'POST',
+      url: '/acquireSandbox',
+      headers: { authorization: `Bearer ${TOKEN}` },
+      payload: { userKey: 'native-immortal' },
+    });
+    const sandboxId = native.json().sandbox.sandboxId;
+
+    const res = await control(t, 'POST', `/sandboxes/${sandboxId}/timeout`, {
+      timeout: 60,
+    });
+    expect(res.statusCode).toBe(204);
+    // Accepted but not applied: immortality is the owner's choice.
+    expect(findBySandboxId(t.db, sandboxId)?.deadlineAt).toBeNull();
+  });
+});
+
+describe('E2B envd surface', () => {
+  it('health probes the logical state: running 204, paused 502, unknown 502', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const probe = (id: string) =>
+      t.app.inject({
+        method: 'GET',
+        url: '/e2b/envd/health',
+        headers: { 'e2b-sandbox-id': id },
+      });
+
+    expect((await probe(sandboxID)).statusCode).toBe(204);
+    await control(t, 'POST', `/sandboxes/${sandboxID}/pause`, {});
+    expect((await probe(sandboxID)).statusCode).toBe(502);
+    expect((await probe('no-such-sandbox')).statusCode).toBe(502);
+  });
+
+  it('rejects a wrong or missing envd access token', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const res = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/filesystem.Filesystem/Stat',
+      headers: { 'e2b-sandbox-id': sandboxID, 'x-access-token': 'wrong' },
+      payload: { path: '/home/user' },
+    });
+    expect(res.statusCode).toBe(401);
+    expect(res.json().code).toBe('unauthenticated');
+  });
+
+  it('files round-trip over plain HTTP: multipart up, raw bytes down, content-length exact', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const content = 'streamed through multipart\n';
+    const boundary = 'dormice-test-boundary';
+    const body = [
+      `--${boundary}`,
+      // A nested filename on purpose: busboy's default strips directories
+      // (preservePath pins the fix — a bare basename would pass by luck).
+      'Content-Disposition: form-data; name="file"; filename="/home/user/nested/up.txt"',
+      'Content-Type: application/octet-stream',
+      '',
+      content,
+      `--${boundary}--`,
+      '',
+    ].join('\r\n');
+    const up = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/files?username=user',
+      headers: {
+        ...envdHeaders(sandboxID),
+        'content-type': `multipart/form-data; boundary=${boundary}`,
+      },
+      payload: body,
+    });
+    expect(up.statusCode).toBe(200);
+    expect(up.json()).toEqual([
+      { name: 'up.txt', type: 'file', path: '/home/user/nested/up.txt' },
+    ]);
+
+    const down = await t.app.inject({
+      method: 'GET',
+      url: '/e2b/envd/files?path=/home/user/nested/up.txt&username=user',
+      headers: envdHeaders(sandboxID),
+    });
+    expect(down.statusCode).toBe(200);
+    expect(down.headers['content-length']).toBe(String(content.length));
+    expect(down.body).toBe(content);
+
+    const missing = await t.app.inject({
+      method: 'GET',
+      url: '/e2b/envd/files?path=/home/user/void.txt',
+      headers: envdHeaders(sandboxID),
+    });
+    expect(missing.statusCode).toBe(404);
+    expect(missing.json().code).toBe('not_found');
+  });
+
+  it('accepts octet-stream uploads with the path in the query', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const res = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/files?path=raw.bin&username=user',
+      headers: {
+        ...envdHeaders(sandboxID),
+        'content-type': 'application/octet-stream',
+      },
+      payload: Buffer.from([1, 2, 3, 250]),
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual([
+      { name: 'raw.bin', type: 'file', path: '/home/user/raw.bin' },
+    ]);
+  });
+
+  it('speaks the filesystem service: Stat, ListDir, MakeDir, Move, Remove', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    await envdRpc(t, sandboxID, '/filesystem.Filesystem/MakeDir', {
+      path: '/home/user/dir',
+    });
+    // MakeDir again: already_exists — the SDK reads it as false.
+    const dup = await envdRpc(t, sandboxID, '/filesystem.Filesystem/MakeDir', {
+      path: '/home/user/dir',
+    });
+    expect(dup.statusCode).toBe(409);
+    expect(dup.json().code).toBe('already_exists');
+
+    await t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/files?path=/home/user/dir/f.txt',
+      headers: {
+        ...envdHeaders(sandboxID),
+        'content-type': 'application/octet-stream',
+      },
+      payload: 'content!',
+    });
+
+    const stat = await envdRpc(t, sandboxID, '/filesystem.Filesystem/Stat', {
+      path: '/home/user/dir/f.txt',
+    });
+    expect(stat.statusCode).toBe(200);
+    expect(stat.json().entry).toMatchObject({
+      name: 'f.txt',
+      type: 'FILE_TYPE_FILE',
+      path: '/home/user/dir/f.txt',
+      size: '8', // proto int64 travels as a string
+      permissions: '-rw-r--r--',
+      owner: 'user',
+    });
+
+    const list = await envdRpc(t, sandboxID, '/filesystem.Filesystem/ListDir', {
+      path: '/home/user/dir',
+      depth: 1,
+    });
+    expect(list.json().entries.map((e: { path: string }) => e.path)).toEqual([
+      '/home/user/dir/f.txt',
+    ]);
+
+    const moved = await envdRpc(t, sandboxID, '/filesystem.Filesystem/Move', {
+      source: '/home/user/dir/f.txt',
+      destination: '/home/user/dir/g.txt',
+    });
+    expect(moved.json().entry.path).toBe('/home/user/dir/g.txt');
+
+    const removed = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/Remove',
+      {
+        path: '/home/user/dir',
+      },
+    );
+    expect(removed.statusCode).toBe(200);
+    const gone = await envdRpc(t, sandboxID, '/filesystem.Filesystem/Stat', {
+      path: '/home/user/dir',
+    });
+    expect(gone.statusCode).toBe(404);
+    expect(gone.json().code).toBe('not_found');
+  });
+
+  it('streams Process/Start: start, live data, end with the honest exit code', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const res = await startCommand(t, sandboxID, 'echo hi');
+    expect(res.statusCode).toBe(200);
+    expect(res.headers['content-type']).toBe('application/connect+json');
+
+    const frames = parseEnvelopes(res.rawPayload);
+    const events = frames
+      .filter((f) => f.flags === 0)
+      .map((f) => f.json.event as Record<string, unknown>);
+    expect(events[0]).toHaveProperty('start');
+    const data = events.find((e) => 'data' in e) as {
+      data: { stdout: string };
+    };
+    expect(Buffer.from(data.data.stdout, 'base64').toString('utf8')).toBe(
+      'hi\n',
+    );
+    const end = events.at(-1) as { end: { exitCode: number; exited: boolean } };
+    expect(end.end).toMatchObject({ exitCode: 0, exited: true });
+    // The closing frame: flags 0x02, empty object — a clean end of stream.
+    expect(frames.at(-1)).toEqual({ flags: 2, json: {} });
+  });
+
+  it('a nonzero exit is a result on the wire, never an error frame', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const frames = parseEnvelopes(
+      (await startCommand(t, sandboxID, 'exit 7')).rawPayload,
+    );
+    const end = frames
+      .filter((f) => f.flags === 0)
+      .map((f) => f.json.event as Record<string, unknown>)
+      .find((e) => 'end' in e) as { end: { exitCode: number } };
+    expect(end.end.exitCode).toBe(7);
+    expect(frames.at(-1)).toEqual({ flags: 2, json: {} });
+  });
+
+  it('sandbox-level envs sit under per-command envs', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t, {
+      envVars: { FROM_SANDBOX: 'base', SHADOWED: 'under' },
+    });
+    const one = parseEnvelopes(
+      (await startCommand(t, sandboxID, 'printenv FROM_SANDBOX')).rawPayload,
+    )
+      .filter((f) => f.flags === 0)
+      .map((f) => f.json.event as { data?: { stdout?: string } })
+      .find((e) => e.data?.stdout);
+    expect(
+      Buffer.from(one?.data?.stdout ?? '', 'base64').toString('utf8'),
+    ).toBe('base\n');
+
+    const two = parseEnvelopes(
+      (
+        await startCommand(t, sandboxID, 'printenv SHADOWED', {
+          envs: { SHADOWED: 'over' },
+        })
+      ).rawPayload,
+    )
+      .filter((f) => f.flags === 0)
+      .map((f) => f.json.event as { data?: { stdout?: string } })
+      .find((e) => e.data?.stdout);
+    expect(
+      Buffer.from(two?.data?.stdout ?? '', 'base64').toString('utf8'),
+    ).toBe('over\n');
+  });
+
+  it('answers a blown connect-timeout-ms deadline with deadline_exceeded, not an end event', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const res = await startCommand(t, sandboxID, 'sleep 2', {
+      headers: { 'connect-timeout-ms': '300' },
+    });
+    const last = parseEnvelopes(res.rawPayload).at(-1);
+    expect(last?.flags).toBe(2);
+    expect((last?.json.error as { code: string }).code).toBe(
+      'deadline_exceeded',
+    );
+  });
+
+  it('names what it does not support yet: unimplemented, with a hint', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const res = await envdRpc(t, sandboxID, '/process.Process/SendInput', {});
+    expect(res.statusCode).toBe(501);
+    expect(res.json().code).toBe('unimplemented');
+    expect(res.json().message).toContain('stdin');
+  });
+
+  it('exec on a paused sandbox answers unavailable inside the stream — like a dead E2B box', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    await control(t, 'POST', `/sandboxes/${sandboxID}/pause`, {});
+    const res = await startCommand(t, sandboxID, 'echo hi');
+    expect(res.statusCode).toBe(200);
+    const frames = parseEnvelopes(res.rawPayload);
+    expect(frames).toHaveLength(1);
+    expect(frames[0]?.flags).toBe(2);
+    expect((frames[0]?.json.error as { code: string }).code).toBe(
+      'unavailable',
+    );
+  });
+});
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
new file mode 100644
index 0000000..a2a3d88
--- /dev/null
+++ b/packages/server/src/e2b/control.ts
@@ -0,0 +1,377 @@
+import { randomUUID } from 'node:crypto';
+import type { FastifyError } from 'fastify';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import { z } from 'zod';
+import {
+  countSandboxes,
+  createSandbox,
+  findBySandboxId,
+  findByUserKey,
+  listSandboxes,
+  setDeadline,
+  setPausedByUser,
+  touch,
+} from '../db/ledger';
+import type { SandboxRow } from '../db/schema';
+import {
+  freezeSandbox,
+  releaseSandbox,
+  stopSandbox,
+  wakeSandbox,
+} from '../lifecycle';
+import { resolvePolicy } from '../policy';
+import type { E2bDeps } from './deps';
+import {
+  apiError,
+  E2bError,
+  ENVD_VERSION,
+  mintEnvdToken,
+  verifyApiKey,
+} from './protocol';
+import { e2bView } from './view';
+
+/**
+ * The E2B control plane: what the official SDK calls api.e2b.app for.
+ * Mounted under /e2b/api; the SDK reaches it through its `apiUrl` option.
+ * Faithful by default — timeouts kill, kill destroys; Dormice's immortality
+ * is opt-in via metadata.userKey (idempotent create) or autoPause.
+ */
+
+/** The Dormice extension key: metadata.userKey makes create idempotent. */
+const USER_KEY_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/;
+
+/** Seconds; E2B's default sandbox TTL. */
+const DEFAULT_TIMEOUT_SECONDS = 300;
+
+const timeoutSchema = z
+  .number()
+  .int()
+  .positive()
+  .max(30 * 24 * 60 * 60);
+
+// .loose(): the v2 SDK sends fields we deliberately ignore (secure,
+// autoResume, network, ...) — tolerating them is what "two URLs and it
+// works" requires; acting on them is tracked feature by feature.
+const createBodySchema = z
+  .object({
+    templateID: z.string().optional(),
+    timeout: timeoutSchema.optional(),
+    metadata: z.record(z.string(), z.string()).optional(),
+    envVars: z.record(z.string(), z.string()).optional(),
+    autoPause: z.boolean().optional(),
+  })
+  .loose();
+
+const timeoutBodySchema = z.object({ timeout: timeoutSchema }).loose();
+
+const connectBodySchema = z
+  .object({ timeout: timeoutSchema.optional() })
+  .loose();
+
+const pauseBodySchema = z
+  .object({ memory: z.boolean().optional() })
+  .loose()
+  .optional();
+
+const listQuerySchema = z.object({
+  metadata: z.string().optional(),
+  state: z.string().optional(),
+  limit: z.coerce.number().int().positive().max(1000).default(100),
+  nextToken: z.string().optional(),
+});
+
+const notFound = (sandboxId: string) =>
+  apiError(404, `sandbox "${sandboxId}" not found`);
+
+export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
+  app,
+  { config, db, executor, locks },
+) => {
+  app.addHook('onRequest', async (request, reply) => {
+    const presented = request.headers['x-api-key'];
+    const key = Array.isArray(presented) ? presented[0] : presented;
+    if (!verifyApiKey(config.DORMICE_API_TOKEN, key)) {
+      await reply.code(401).send({ code: 401, message: 'invalid API key' });
+    }
+  });
+
+  // The E2B error dialect: every non-2xx body is { code, message } — the
+  // SDK's handleApiError reads both. Scoped here; the native { message }
+  // dialect stays untouched outside /e2b.
+  app.setErrorHandler((error: FastifyError | E2bError, request, reply) => {
+    if (error instanceof E2bError) {
+      return reply
+        .code(error.statusCode)
+        .send({ code: error.code, message: error.message });
+    }
+    const status = error.statusCode ?? 500;
+    if (status >= 500) {
+      request.log.error(error, 'e2b control request failed');
+    }
+    // openapi shape: the body's code mirrors the numeric status.
+    return reply.code(status).send({ code: status, message: error.message });
+  });
+  app.setNotFoundHandler((request, reply) => {
+    reply.code(404).send({
+      code: 404,
+      message: `route ${request.method} ${request.url} not found`,
+    });
+  });
+
+  /** What create and connect answer with. */
+  function sessionView(row: SandboxRow) {
+    return {
+      sandboxID: row.sandboxId,
+      templateID: config.DORMICE_BASE_IMAGE ?? 'base',
+      alias: row.userKey,
+      envdVersion: ENVD_VERSION,
+      envdAccessToken: mintEnvdToken(config.DORMICE_API_TOKEN, row.sandboxId),
+    };
+  }
+
+  /** What getInfo and list answer with. */
+  function infoView(row: SandboxRow, state: 'running' | 'paused') {
+    return {
+      sandboxID: row.sandboxId,
+      templateID: config.DORMICE_BASE_IMAGE ?? 'base',
+      alias: row.userKey,
+      metadata: row.metadata ? JSON.parse(row.metadata) : {},
+      state,
+      startedAt: row.createdAt,
+      // No deadline (a natively-acquired immortal sandbox) reports a year
+      // out, so SDK-side "expired?" arithmetic never trips.
+      endAt:
+        row.deadlineAt ??
+        new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString(),
+      cpuCount: config.DORMICE_SANDBOX_CPUS,
+      memoryMB: Math.round(config.DORMICE_SANDBOX_MEMORY_GB * 1024),
+      envdVersion: ENVD_VERSION,
+    };
+  }
+
+  /**
+   * Looks a sandbox up as the protocol sees it. A row whose kill-deadline
+   * has passed is protocol-dead — 404, exactly what the SDK expects of a
+   * timed-out sandbox — even while the scanner's physical teardown is still
+   * a sweep away.
+   */
+  function findLive(sandboxId: string): {
+    row: SandboxRow;
+    state: 'running' | 'paused';
+  } {
+    const row = findBySandboxId(db, sandboxId);
+    if (!row) throw notFound(sandboxId);
+    const state = e2bView(row, new Date());
+    if (state === 'dead') throw notFound(sandboxId);
+    return { row, state };
+  }
+
+  /**
+   * connect's TTL rule: only ever extended, never shortened. And only for
+   * sandboxes the E2B surface created (they always carry onDeadline):
+   * a natively-acquired sandbox is immortal by its owner's choice, and the
+   * compat surface must not quietly impose a deadline on it.
+   */
+  function extendDeadline(row: SandboxRow, timeoutSeconds: number): void {
+    if (row.onDeadline === null) return;
+    const candidate = Date.now() + timeoutSeconds * 1000;
+    const current = row.deadlineAt ? Date.parse(row.deadlineAt) : 0;
+    if (candidate > current) {
+      setDeadline(db, row.sandboxId, {
+        deadlineAt: new Date(candidate).toISOString(),
+        onDeadline: row.onDeadline,
+      });
+    }
+  }
+
+  app.post(
+    '/sandboxes',
+    { schema: { body: createBodySchema } },
+    async (request, reply) => {
+      const body = request.body;
+      const timeoutSeconds = body.timeout ?? DEFAULT_TIMEOUT_SECONDS;
+      const requestedKey = body.metadata?.userKey;
+      if (requestedKey !== undefined && !USER_KEY_PATTERN.test(requestedKey)) {
+        throw apiError(
+          400,
+          `invalid metadata.userKey "${requestedKey}": expected 1-64 chars of [a-zA-Z0-9._-]`,
+        );
+      }
+      const userKey = requestedKey ?? `e2b-${randomUUID()}`;
+
+      const row = await locks.run(userKey, async () => {
+        const existing = findByUserKey(db, userKey);
+        if (existing && e2bView(existing, new Date()) !== 'dead') {
+          // The Dormice extension: same key, same sandbox — an acquire in
+          // E2B clothes. Stored metadata/envs stay (same principle as the
+          // native policy's "override applies at creation only"); the
+          // deadline is extended like a connect.
+          const awake = await wakeSandbox(db, executor, existing);
+          extendDeadline(awake, timeoutSeconds);
+          return touch(db, awake.sandboxId);
+        }
+        if (existing) {
+          // Protocol-dead but not yet reaped: E2B semantics say it is gone,
+          // so finish the job and build fresh under the same key.
+          await releaseSandbox(db, executor, existing.sandboxId);
+        }
+
+        if (countSandboxes(db) >= config.DORMICE_MAX_SANDBOXES) {
+          throw apiError(
+            429,
+            `sandbox limit reached (DORMICE_MAX_SANDBOXES=${config.DORMICE_MAX_SANDBOXES}) — release a sandbox or raise the limit`,
+          );
+        }
+        const sandboxId = randomUUID();
+        await executor.create(sandboxId);
+        return createSandbox(db, {
+          sandboxId,
+          userKey,
+          nodeId: config.DORMICE_NODE_ID,
+          policy: resolvePolicy(undefined),
+          e2b: {
+            metadata: body.metadata ? JSON.stringify(body.metadata) : null,
+            envs:
+              body.envVars && Object.keys(body.envVars).length > 0
+                ? JSON.stringify(body.envVars)
+                : null,
+            deadlineAt: new Date(
+              Date.now() + timeoutSeconds * 1000,
+            ).toISOString(),
+            // Faithful default: E2B kills at the deadline unless the caller
+            // opted into pause (lifecycle.onTimeout='pause' on the wire).
+            onDeadline: body.autoPause ? 'pause' : 'kill',
+          },
+        });
+      });
+      return reply.code(201).send(sessionView(row));
+    },
+  );
+
+  app.post(
+    '/sandboxes/:id/connect',
+    { schema: { body: connectBodySchema } },
+    async (request, reply) => {
+      const { id } = request.params as { id: string };
+      const before = findLive(id);
+      const row = await locks.run(before.row.userKey, async () => {
+        const fresh = findBySandboxId(db, id);
+        if (!fresh || e2bView(fresh, new Date()) === 'dead') {
+          throw notFound(id);
+        }
+        const awake = await wakeSandbox(db, executor, fresh);
+        extendDeadline(awake, request.body.timeout ?? DEFAULT_TIMEOUT_SECONDS);
+        return touch(db, awake.sandboxId);
+      });
+      // 200 = it was already running, 201 = this connect resumed it.
+      return reply
+        .code(before.state === 'running' ? 200 : 201)
+        .send(sessionView(row));
+    },
+  );
+
+  app.get('/sandboxes/:id', async (request) => {
+    const { id } = request.params as { id: string };
+    const { row, state } = findLive(id);
+    return infoView(row, state);
+  });
+
+  app.delete('/sandboxes/:id', async (request, reply) => {
+    const { id } = request.params as { id: string };
+    // kill = release, for real: container, disk and row gone. Persistence
+    // on the E2B surface is "don't kill" (autoPause / userKey), never a
+    // kill that secretly keeps data.
+    const { row } = findLive(id);
+    await locks.run(row.userKey, async () => {
+      const fresh = findBySandboxId(db, id);
+      if (!fresh) throw notFound(id);
+      await releaseSandbox(db, executor, fresh.sandboxId);
+    });
+    return reply.code(204).send();
+  });
+
+  app.post(
+    '/sandboxes/:id/timeout',
+    { schema: { body: timeoutBodySchema } },
+    async (request, reply) => {
+      const { id } = request.params as { id: string };
+      const { row } = findLive(id);
+      // setTimeout overwrites in both directions, measured from now — but
+      // only for E2B-created sandboxes; native ones stay immortal.
+      if (row.onDeadline !== null) {
+        setDeadline(db, row.sandboxId, {
+          deadlineAt: new Date(
+            Date.now() + request.body.timeout * 1000,
+          ).toISOString(),
+          onDeadline: row.onDeadline,
+        });
+      }
+      return reply.code(204).send();
+    },
+  );
+
+  app.post(
+    '/sandboxes/:id/pause',
+    { schema: { body: pauseBodySchema } },
+    async (request, reply) => {
+      const { id } = request.params as { id: string };
+      const before = findLive(id);
+      if (before.state === 'paused') {
+        // The SDK reads a 409 as "already paused" and answers false.
+        throw apiError(409, 'sandbox is already paused');
+      }
+      await locks.run(before.row.userKey, async () => {
+        const fresh = findBySandboxId(db, id);
+        if (!fresh) throw notFound(id);
+        let current = fresh;
+        if (current.state === 'active') {
+          current = await freezeSandbox(db, executor, current.sandboxId);
+        }
+        // keepMemory:false maps to stopped: filesystem only, cold boot on
+        // resume — physically exactly what E2B promises for it.
+        if (request.body?.memory === false && current.state === 'frozen') {
+          await stopSandbox(db, executor, current.sandboxId);
+        }
+        setPausedByUser(db, fresh.sandboxId, true);
+      });
+      return reply.code(204).send();
+    },
+  );
+
+  app.get(
+    '/v2/sandboxes',
+    { schema: { querystring: listQuerySchema } },
+    async (request, reply) => {
+      const { metadata, state, limit, nextToken } = request.query;
+      const wanted = new Set(
+        (state ? state.split(',') : ['running', 'paused']).map((s) => s.trim()),
+      );
+      const filters = [...new URLSearchParams(metadata ?? '')];
+
+      const now = new Date();
+      const all = listSandboxes(db)
+        .map((row) => ({ row, state: e2bView(row, now) }))
+        .filter(
+          (item): item is { row: SandboxRow; state: 'running' | 'paused' } => {
+            if (item.state === 'dead' || !wanted.has(item.state)) return false;
+            if (filters.length === 0) return true;
+            const meta: Record<string, string> = item.row.metadata
+              ? JSON.parse(item.row.metadata)
+              : {};
+            return filters.every(([key, value]) => meta[key] === value);
+          },
+        )
+        // Newest first, like the E2B dashboard; stable under pagination.
+        .sort((a, b) => (a.row.createdAt < b.row.createdAt ? 1 : -1));
+
+      const offset = Number(nextToken ?? '0') || 0;
+      const page = all.slice(offset, offset + limit);
+      if (offset + limit < all.length) {
+        // The v2 pagination protocol: the cursor lives in this header; its
+        // absence is what means "no next page".
+        reply.header('x-next-token', String(offset + limit));
+      }
+      return page.map((item) => infoView(item.row, item.state));
+    },
+  );
+};
diff --git a/packages/server/src/e2b/deps.ts b/packages/server/src/e2b/deps.ts
new file mode 100644
index 0000000..d24f52a
--- /dev/null
+++ b/packages/server/src/e2b/deps.ts
@@ -0,0 +1,12 @@
+import type { Config } from '../config';
+import type { Db } from '../db/db';
+import type { Executor } from '../executor/executor';
+import type { KeyedQueue } from '../keyed-queue';
+
+/** What every compat plugin needs — the same four the native routes get. */
+export interface E2bDeps {
+  config: Config;
+  db: Db;
+  executor: Executor;
+  locks: KeyedQueue;
+}
diff --git a/packages/server/src/e2b/envd.ts b/packages/server/src/e2b/envd.ts
new file mode 100644
index 0000000..50b86a4
--- /dev/null
+++ b/packages/server/src/e2b/envd.ts
@@ -0,0 +1,686 @@
+import type { Buffer } from 'node:buffer';
+import { resolveSandboxPath } from '@dormice/shared';
+import multipart from '@fastify/multipart';
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import { findBySandboxId, touch } from '../db/ledger';
+import type { SandboxRow } from '../db/schema';
+import { startExecHeartbeat } from '../exec-heartbeat';
+import {
+  DiskFullError,
+  FileNotFoundError,
+  NotADirectoryError,
+  NotAFileError,
+  type SandboxEntry,
+} from '../executor/executor';
+import { wakeSandbox } from '../lifecycle';
+import type { E2bDeps } from './deps';
+import {
+  connectError,
+  E2bError,
+  envelope,
+  FLAG_END_STREAM,
+  FLAG_MESSAGE,
+  readFirstMessage,
+  verifyEnvdToken,
+} from './protocol';
+import { e2bView } from './view';
+
+/**
+ * The envd surface: what the official SDK reaches through its `sandboxUrl`
+ * option. One origin serves every sandbox — the SDK attaches an
+ * E2b-Sandbox-Id header to every request, so no wildcard DNS is needed.
+ * Connect RPC rides the JSON codec (the SDK sets useBinaryFormat: false);
+ * files ride plain HTTP. The daemon itself plays the role of envd — there
+ * is no agent inside the container.
+ */
+
+/** In-flight command deadline backstop when the SDK sends no deadline header. */
+const MAX_EXEC_SECONDS = 24 * 60 * 60;
+
+/** The SDK asks for keepalives via this header; we honor it, capped. */
+const MAX_KEEPALIVE_SECONDS = 30;
+
+/** Effectively unbounded route body: the disk quota is the real gate. */
+const UNLIMITED_BODY_BYTES = Number.MAX_SAFE_INTEGER;
+
+/** Synthetic PIDs — the SDK only ever uses them as opaque handles. */
+let nextPid = 1000;
+
+interface StartRequest {
+  process?: {
+    cmd?: string;
+    args?: string[];
+    envs?: Record<string, string>;
+    cwd?: string;
+  };
+  pty?: unknown;
+}
+
+/** SandboxEntry -> proto3-JSON EntryInfo (int64 size travels as a string). */
+function entryInfoJson(entry: SandboxEntry) {
+  return {
+    name: entry.name,
+    type:
+      entry.type === 'file'
+        ? 'FILE_TYPE_FILE'
+        : entry.type === 'dir'
+          ? 'FILE_TYPE_DIRECTORY'
+          : 'FILE_TYPE_UNSPECIFIED',
+    path: entry.path,
+    size: String(entry.sizeBytes),
+    mode: entry.mode,
+    permissions: permissionString(entry),
+    owner: entry.owner,
+    group: entry.group,
+    modifiedTime: entry.modifiedTime,
+  };
+}
+
+/** Go fs.FileMode style: type char + rwx triplets, display only. */
+function permissionString(entry: SandboxEntry): string {
+  const chars =
+    entry.type === 'dir' ? ['d'] : entry.type === 'file' ? ['-'] : ['?'];
+  for (let shift = 6; shift >= 0; shift -= 3) {
+    const bits = (entry.mode >> shift) & 0o7;
+    chars.push(
+      bits & 4 ? 'r' : '-',
+      bits & 2 ? 'w' : '-',
+      bits & 1 ? 'x' : '-',
+    );
+  }
+  return chars.join('');
+}
+
+/** Executor file errors -> the Connect codes the SDK maps back to its own taxonomy. */
+function toConnectError(error: unknown): unknown {
+  if (error instanceof FileNotFoundError) {
+    return connectError('not_found', error.message);
+  }
+  if (error instanceof NotAFileError || error instanceof NotADirectoryError) {
+    return connectError('invalid_argument', error.message);
+  }
+  if (error instanceof DiskFullError) {
+    return connectError('resource_exhausted', error.message);
+  }
+  return error;
+}
+
+export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
+  app,
+  { config, db, executor, locks },
+) => {
+  await app.register(multipart, {
+    limits: {
+      // The disk quota is the ceiling; a route-level cap would just be a
+      // second, dishonest one. parts/files stay bounded so a hostile form
+      // cannot spray unlimited entries.
+      fileSize: UNLIMITED_BODY_BYTES,
+      files: 1000,
+      parts: 2000,
+      fieldSize: 1024 * 1024,
+    },
+    // busboy strips filenames to their basename by default (a browser-form
+    // safety net); here the filename IS the destination path — 'notes/x.txt'
+    // must keep its directory. Traversal is not a concern this opens:
+    // resolveSandboxPath clamps '..' at the container's own root anyway.
+    preservePath: true,
+  });
+
+  // Connect streaming requests arrive enveloped; keep the raw bytes.
+  app.addContentTypeParser(
+    'application/connect+json',
+    { parseAs: 'buffer' },
+    (_request, payload, done) => done(null, payload),
+  );
+  // Octet-stream uploads pass through as a stream: nothing materializes.
+  app.addContentTypeParser(
+    'application/octet-stream',
+    (_request, payload, done) => done(null, payload),
+  );
+
+  app.setErrorHandler((error, request, reply) => {
+    if (error instanceof E2bError) {
+      return reply
+        .code(error.statusCode)
+        .send({ code: error.code, message: error.message });
+    }
+    const status = (error as { statusCode?: number }).statusCode ?? 500;
+    if (status >= 500) {
+      request.log.error(error, 'e2b envd request failed');
+    }
+    return reply.code(status).send({
+      code: status === 400 ? 'invalid_argument' : 'internal',
+      message: (error as Error).message,
+    });
+  });
+  app.setNotFoundHandler((request, reply) => {
+    reply.code(404).send({
+      code: 'not_found',
+      message: `route ${request.method} ${request.url} not found`,
+    });
+  });
+
+  /** Every envd request names its sandbox in this header. */
+  function sandboxIdOf(request: FastifyRequest): string {
+    const header = request.headers['e2b-sandbox-id'];
+    const id = Array.isArray(header) ? header[0] : header;
+    if (!id) {
+      throw new E2bError(
+        401,
+        'unauthenticated',
+        'missing E2b-Sandbox-Id header',
+      );
+    }
+    return id;
+  }
+
+  // Auth: X-Access-Token must be the HMAC minted for exactly this sandbox.
+  // /health stays open like real envd's — it is how isRunning() probes.
+  app.addHook('onRequest', async (request) => {
+    if (request.method === 'GET' && request.url.endsWith('/health')) return;
+    const sandboxId = sandboxIdOf(request);
+    const header = request.headers['x-access-token'];
+    const token = Array.isArray(header) ? header[0] : header;
+    if (
+      !token ||
+      !verifyEnvdToken(config.DORMICE_API_TOKEN, sandboxId, token)
+    ) {
+      throw new E2bError(401, 'unauthenticated', 'invalid envd access token');
+    }
+  });
+
+  /**
+   * The protocol-liveness gate. Only a logically-running sandbox serves
+   * envd traffic: paused and dead answer 502, which the SDK triages into
+   * its "sandbox timed out / not running" errors — exactly what talking to
+   * a paused or killed E2B sandbox feels like.
+   */
+  function requireRunningRow(sandboxId: string): SandboxRow {
+    const row = findBySandboxId(db, sandboxId);
+    if (!row) {
+      throw new E2bError(502, 'unavailable', 'sandbox not found');
+    }
+    const state = e2bView(row, new Date());
+    if (state !== 'running') {
+      throw new E2bError(
+        502,
+        'unavailable',
+        state === 'paused' ? 'sandbox is paused' : 'sandbox not found',
+      );
+    }
+    return row;
+  }
+
+  /**
+   * Wake under the key's slot, like every native verb: physical wake-ups
+   * take seconds and must not race the scanner or a release.
+   */
+  async function wakeForUse(sandboxId: string): Promise<SandboxRow> {
+    const before = requireRunningRow(sandboxId);
+    return locks.run(before.userKey, async () => {
+      const fresh = requireRunningRow(sandboxId);
+      const awake = await wakeSandbox(db, executor, fresh);
+      return touch(db, awake.sandboxId);
+    });
+  }
+
+  app.get('/health', async (request, reply) => {
+    // No auth, no wake — a probe must stay cheap and honest. 502 = not
+    // running, the exact signal isRunning() keys on.
+    const header = request.headers['e2b-sandbox-id'];
+    const id = Array.isArray(header) ? header[0] : header;
+    const row = id ? findBySandboxId(db, id) : undefined;
+    if (!row || e2bView(row, new Date()) !== 'running') {
+      return reply
+        .code(502)
+        .send({ code: 'unavailable', message: 'sandbox is not running' });
+    }
+    return reply.code(204).send();
+  });
+
+  // ---- files over plain HTTP ------------------------------------------
+
+  app.get('/files', async (request, reply) => {
+    const query = request.query as { path?: string };
+    if (!query.path) {
+      throw new E2bError(400, 'invalid_argument', 'missing path query');
+    }
+    const row = await wakeForUse(sandboxIdOf(request));
+    const stopHeartbeat = startExecHeartbeat(
+      db,
+      row.sandboxId,
+      row.freezeAfterSeconds,
+    );
+    try {
+      let entry: SandboxEntry;
+      try {
+        entry = await executor.statEntry(row.sandboxId, query.path);
+        if (entry.type !== 'file') {
+          throw new NotAFileError(`not a regular file: ${entry.path}`);
+        }
+      } catch (error) {
+        if (error instanceof FileNotFoundError) {
+          throw new E2bError(404, 'not_found', error.message);
+        }
+        if (error instanceof NotAFileError) {
+          throw new E2bError(400, 'invalid_argument', error.message);
+        }
+        throw error;
+      }
+      // Size first, then stream: the SDK needs content-length (an empty
+      // file is detected by `content-length: 0`), and nothing buffers here.
+      reply.hijack();
+      reply.raw.writeHead(200, {
+        'content-type': 'application/octet-stream',
+        'content-length': String(entry.sizeBytes),
+      });
+      await executor.readFileStream(row.sandboxId, query.path, (chunk) => {
+        if (!reply.raw.write(chunk)) {
+          // Backpressure: the promise pauses the pipe all the way into the
+          // container until the client drains.
+          return new Promise<void>((resolve) =>
+            reply.raw.once('drain', resolve),
+          );
+        }
+      });
+      reply.raw.end();
+    } catch (error) {
+      if (reply.raw.headersSent) {
+        // Mid-stream failure: the body length will not match the announced
+        // content-length — the client sees a broken transfer, honestly.
+        request.log.error(error, 'file download broke mid-stream');
+        reply.raw.destroy();
+        return;
+      }
+      throw error;
+    } finally {
+      stopHeartbeat();
+      try {
+        touch(db, row.sandboxId);
+      } catch {
+        // Released mid-transfer; the transfer's own error tells the story.
+      }
+    }
+  });
+
+  app.post(
+    '/files',
+    { bodyLimit: UNLIMITED_BODY_BYTES },
+    async (request, reply) => {
+      const query = request.query as { path?: string };
+      const row = await wakeForUse(sandboxIdOf(request));
+      const stopHeartbeat = startExecHeartbeat(
+        db,
+        row.sandboxId,
+        row.freezeAfterSeconds,
+      );
+      try {
+        const written: Array<{ name: string; type: 'file'; path: string }> = [];
+        const writeOne = async (
+          path: string,
+          content: NodeJS.ReadableStream,
+        ) => {
+          try {
+            await executor.writeFileStream(row.sandboxId, path, content);
+          } catch (error) {
+            if (error instanceof NotAFileError) {
+              throw new E2bError(400, 'invalid_argument', error.message);
+            }
+            if (error instanceof DiskFullError) {
+              throw new E2bError(507, 'not_enough_space', error.message);
+            }
+            throw error;
+          }
+          const resolved = resolveSandboxPath(path);
+          written.push({
+            name: resolved.slice(resolved.lastIndexOf('/') + 1),
+            type: 'file',
+            path: resolved,
+          });
+        };
+
+        if (request.isMultipart()) {
+          // The SDK's default upload shape: one part per file, field name
+          // `file`, the part's filename carrying the destination path.
+          for await (const part of request.parts()) {
+            if (part.type !== 'file') continue;
+            const destination = part.filename || query.path;
+            if (!destination) {
+              throw new E2bError(
+                400,
+                'invalid_argument',
+                'multipart file part has no filename and no ?path= fallback',
+              );
+            }
+            await writeOne(destination, part.file);
+          }
+        } else {
+          // Octet-stream (the SDK's streaming/gzip shape): path in the query.
+          if (!query.path) {
+            throw new E2bError(400, 'invalid_argument', 'missing path query');
+          }
+          await writeOne(query.path, request.body as NodeJS.ReadableStream);
+        }
+        return await reply.code(200).send(written);
+      } finally {
+        stopHeartbeat();
+        try {
+          touch(db, row.sandboxId);
+        } catch {
+          // Released mid-upload; the upload's own result tells the story.
+        }
+      }
+    },
+  );
+
+  // ---- filesystem service (Connect RPC, unary, JSON codec) ------------
+
+  /** Unary filesystem RPCs run entirely in the key's slot, like native file verbs. */
+  async function inSlot<T>(
+    sandboxId: string,
+    work: (row: SandboxRow) => Promise<T>,
+  ): Promise<T> {
+    const before = requireRunningRow(sandboxId);
+    return locks.run(before.userKey, async () => {
+      const fresh = requireRunningRow(sandboxId);
+      const awake = await wakeSandbox(db, executor, fresh);
+      const row = touch(db, awake.sandboxId);
+      try {
+        return await work(row);
+      } catch (error) {
+        throw toConnectError(error);
+      }
+    });
+  }
+
+  app.post('/filesystem.Filesystem/Stat', async (request) => {
+    const body = request.body as { path?: string };
+    if (!body.path) throw connectError('invalid_argument', 'missing path');
+    const entry = await inSlot(sandboxIdOf(request), (row) =>
+      executor.statEntry(row.sandboxId, body.path as string),
+    );
+    return { entry: entryInfoJson(entry) };
+  });
+
+  app.post('/filesystem.Filesystem/ListDir', async (request) => {
+    const body = request.body as { path?: string; depth?: number };
+    if (!body.path) throw connectError('invalid_argument', 'missing path');
+    const depth = body.depth ?? 1;
+    if (depth < 1) {
+      throw connectError('invalid_argument', 'depth should be at least one');
+    }
+    const entries = await inSlot(sandboxIdOf(request), (row) =>
+      executor.listDir(row.sandboxId, body.path as string, depth),
+    );
+    return { entries: entries.map(entryInfoJson) };
+  });
+
+  app.post('/filesystem.Filesystem/MakeDir', async (request) => {
+    const body = request.body as { path?: string };
+    if (!body.path) throw connectError('invalid_argument', 'missing path');
+    const entry = await inSlot(sandboxIdOf(request), async (row) => {
+      const created = await executor.makeDir(
+        row.sandboxId,
+        body.path as string,
+      );
+      if (!created) {
+        // The SDK reads already_exists as makeDir() === false.
+        throw connectError(
+          'already_exists',
+          `already exists: ${resolveSandboxPath(body.path as string)}`,
+        );
+      }
+      return executor.statEntry(row.sandboxId, body.path as string);
+    });
+    return { entry: entryInfoJson(entry) };
+  });
+
+  app.post('/filesystem.Filesystem/Move', async (request) => {
+    const body = request.body as { source?: string; destination?: string };
+    if (!body.source || !body.destination) {
+      throw connectError('invalid_argument', 'missing source or destination');
+    }
+    const entry = await inSlot(sandboxIdOf(request), (row) =>
+      executor.move(
+        row.sandboxId,
+        body.source as string,
+        body.destination as string,
+      ),
+    );
+    return { entry: entryInfoJson(entry) };
+  });
+
+  app.post('/filesystem.Filesystem/Remove', async (request) => {
+    const body = request.body as { path?: string };
+    if (!body.path) throw connectError('invalid_argument', 'missing path');
+    await inSlot(sandboxIdOf(request), (row) =>
+      executor.remove(row.sandboxId, body.path as string),
+    );
+    return {};
+  });
+
+  // ---- process service -------------------------------------------------
+
+  app.post('/process.Process/List', async () => {
+    // No process table yet: honest empty, matching v1's supported surface.
+    return { processes: [] };
+  });
+
+  app.post('/process.Process/Start', async (request, reply) => {
+    const message = readFirstMessage(request.body as Buffer) as StartRequest;
+    if (message.pty) {
+      return streamError(
+        reply,
+        'unimplemented',
+        'PTY is not supported yet — run plain commands via commands.run',
+      );
+    }
+    const proc = message.process ?? {};
+    const args = proc.args ?? [];
+    // The SDK always sends /bin/bash [-l] -c <command>; anything else is a
+    // shape this layer does not speak yet.
+    let command: string | undefined;
+    let loginShell = false;
+    if (args.length === 3 && args[0] === '-l' && args[1] === '-c') {
+      command = args[2];
+      loginShell = true;
+    } else if (args.length === 2 && args[0] === '-c') {
+      command = args[1];
+    }
+    if (!proc.cmd?.endsWith('bash') || command === undefined) {
+      return streamError(
+        reply,
+        'invalid_argument',
+        'only shell commands are supported: expected /bin/bash [-l] -c <command>',
+      );
+    }
+
+    let row: SandboxRow;
+    try {
+      row = await wakeForUse(sandboxIdOf(request));
+    } catch (error) {
+      if (error instanceof E2bError) {
+        // Everything this surface throws carries a Connect string code; a
+        // numeric one would be a control-plane error that leaked — treat it
+        // as the sandbox being unreachable.
+        return streamError(
+          reply,
+          typeof error.code === 'string' ? error.code : 'unavailable',
+          error.message,
+        );
+      }
+      throw error;
+    }
+
+    // The wire deadline: the SDK's connect-timeout-ms header. The daemon's
+    // timer adjudicates the wire (deadline_exceeded, like real envd); the
+    // in-container `timeout` merely cleans up the process a beat later —
+    // no guessing whether a 137 "was" a timeout.
+    const headerMs = Number(request.headers['connect-timeout-ms']);
+    const deadlineMs =
+      Number.isFinite(headerMs) && headerMs > 0
+        ? headerMs
+        : MAX_EXEC_SECONDS * 1000;
+    const timeoutSeconds = Math.min(
+      Math.ceil(deadlineMs / 1000),
+      MAX_EXEC_SECONDS,
+    );
+
+    reply.hijack();
+    reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
+    const write = (buf: Buffer) =>
+      new Promise<void>((resolve) => {
+        if (!reply.raw.write(buf)) reply.raw.once('drain', resolve);
+        else resolve();
+      });
+
+    await write(
+      envelope(FLAG_MESSAGE, { event: { start: { pid: nextPid++ } } }),
+    );
+
+    const stopHeartbeat = startExecHeartbeat(
+      db,
+      row.sandboxId,
+      row.freezeAfterSeconds,
+    );
+    // Keepalive events on the interval the SDK asked for — what keeps
+    // proxies from cutting a silent long command.
+    const keepaliveSeconds = Math.min(
+      Number(request.headers['keepalive-ping-interval']) ||
+        MAX_KEEPALIVE_SECONDS,
+      MAX_KEEPALIVE_SECONDS,
+    );
+    const keepalive = setInterval(() => {
+      reply.raw.write(envelope(FLAG_MESSAGE, { event: { keepalive: {} } }));
+    }, keepaliveSeconds * 1000);
+
+    let deadlineTimer: NodeJS.Timeout | undefined;
+    const deadline = new Promise<'deadline'>((resolve) => {
+      deadlineTimer = setTimeout(() => resolve('deadline'), deadlineMs);
+    });
+
+    try {
+      const sandboxEnvs: Record<string, string> = row.envs
+        ? JSON.parse(row.envs)
+        : {};
+      const handle = await executor.execStream(row.sandboxId, {
+        command,
+        loginShell,
+        timeoutSeconds,
+        cwd: proc.cwd,
+        // Sandbox-level envs underneath, per-command envs on top.
+        env: { ...sandboxEnvs, ...(proc.envs ?? {}) },
+        onStdout: (chunk) =>
+          write(
+            envelope(FLAG_MESSAGE, {
+              event: { data: { stdout: chunk.toString('base64') } },
+            }),
+          ),
+        onStderr: (chunk) =>
+          write(
+            envelope(FLAG_MESSAGE, {
+              event: { data: { stderr: chunk.toString('base64') } },
+            }),
+          ),
+      });
+      const outcome = await Promise.race([handle.wait(), deadline]);
+      if (outcome === 'deadline') {
+        // Real envd answers a blown deadline with the Connect error, not an
+        // end event; the SDK turns it into its TimeoutError.
+        await write(
+          envelope(FLAG_END_STREAM, {
+            error: {
+              code: 'deadline_exceeded',
+              message: `command timed out after ${deadlineMs}ms`,
+            },
+          }),
+        );
+        return;
+      }
+      const { exitCode } = outcome;
+      await write(
+        envelope(FLAG_MESSAGE, {
+          event: {
+            end: {
+              exitCode,
+              exited: true,
+              status: exitCode === 137 ? 'killed' : 'exited',
+              ...(exitCode === 137
+                ? { error: 'command killed (exit 137)' }
+                : {}),
+            },
+          },
+        }),
+      );
+      await write(envelope(FLAG_END_STREAM, {}));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      reply.raw.write(
+        envelope(FLAG_END_STREAM, { error: { code: 'internal', message } }),
+      );
+    } finally {
+      clearInterval(keepalive);
+      clearTimeout(deadlineTimer);
+      stopHeartbeat();
+      try {
+        // The command itself was the activity: the idle countdown starts
+        // when it ends, not when it started.
+        touch(db, row.sandboxId);
+      } catch {
+        // Released mid-exec; the stream's own ending tells the story.
+      }
+      reply.raw.end();
+    }
+  });
+
+  /** Streaming endpoints answer errors inside the stream: 200 + end-stream frame. */
+  function streamError(
+    reply: FastifyReply,
+    code: string,
+    message: string,
+  ): void {
+    reply.hijack();
+    reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
+    reply.raw.write(envelope(FLAG_END_STREAM, { error: { code, message } }));
+    reply.raw.end();
+  }
+
+  // ---- honest unimplemented stubs --------------------------------------
+
+  const unimplemented: Array<[string, string]> = [
+    [
+      '/process.Process/SendInput',
+      'stdin is not supported yet — pass data via files.write and read it from your command',
+    ],
+    ['/process.Process/SendSignal', 'signaling a process is not supported yet'],
+    ['/process.Process/CloseStdin', 'stdin is not supported yet'],
+    [
+      '/process.Process/Connect',
+      'reconnecting to a running command is not supported yet',
+    ],
+    ['/process.Process/Update', 'PTY is not supported yet'],
+    ['/process.Process/StreamInput', 'stdin is not supported yet'],
+    [
+      '/filesystem.Filesystem/WatchDir',
+      'directory watching is not supported yet — poll files.list instead',
+    ],
+    [
+      '/filesystem.Filesystem/CreateWatcher',
+      'directory watching is not supported yet — poll files.list instead',
+    ],
+    [
+      '/filesystem.Filesystem/GetWatcherEvents',
+      'directory watching is not supported yet',
+    ],
+    [
+      '/filesystem.Filesystem/RemoveWatcher',
+      'directory watching is not supported yet',
+    ],
+  ];
+  for (const [path, hint] of unimplemented) {
+    app.post(path, async () => {
+      throw connectError('unimplemented', hint);
+    });
+  }
+};
diff --git a/packages/server/src/e2b/index.ts b/packages/server/src/e2b/index.ts
new file mode 100644
index 0000000..24ae927
--- /dev/null
+++ b/packages/server/src/e2b/index.ts
@@ -0,0 +1,19 @@
+import type { FastifyInstance } from 'fastify';
+import { e2bControlRoutes } from './control';
+import type { E2bDeps } from './deps';
+import { e2bEnvdRoutes } from './envd';
+
+/**
+ * The E2B compatibility layer: the official `e2b` package connects with two
+ * URLs — apiUrl -> <daemon>/e2b/api, sandboxUrl -> <daemon>/e2b/envd — plus
+ * `e2b_<DORMICE_API_TOKEN>` as its API key. Both scopes carry their own
+ * auth and their own { code, message } error dialect; the native API's
+ * Bearer auth and { message } dialect stay outside, untouched.
+ */
+export async function registerE2bCompat(
+  app: FastifyInstance,
+  deps: E2bDeps,
+): Promise<void> {
+  await app.register(e2bControlRoutes, { ...deps, prefix: '/e2b/api' });
+  await app.register(e2bEnvdRoutes, { ...deps, prefix: '/e2b/envd' });
+}
diff --git a/packages/server/src/e2b/protocol.ts b/packages/server/src/e2b/protocol.ts
new file mode 100644
index 0000000..b2b4a0d
--- /dev/null
+++ b/packages/server/src/e2b/protocol.ts
@@ -0,0 +1,127 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+
+/**
+ * The envd version this compat layer claims. Deliberately 0.6.1: at or
+ * above 0.5.7 the SDK is willing to upload via octet-stream (we support
+ * it), below 0.6.2 it refuses file-metadata options client-side (we do not
+ * support xattr metadata) — the SDK blocks what we cannot do instead of us
+ * accepting data and silently dropping it. Raise only together with the
+ * features a higher number promises.
+ */
+export const ENVD_VERSION = '0.6.1';
+
+/**
+ * Errors on the E2B surface carry the E2B wire shape `{ code, message }` —
+ * a different dialect from the native `{ message }`, adjudicated per scope
+ * by each compat plugin's own error handler. Two sub-dialects, both
+ * verified against the official SDK: the control plane's `code` is the
+ * NUMERIC status (openapi-fetch literally checks `error.code === 404`),
+ * Connect RPC's `code` is the protocol's string ('not_found', ...).
+ */
+export class E2bError extends Error {
+  constructor(
+    readonly statusCode: number,
+    readonly code: string | number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** A control-plane error: numeric code mirroring the status, per E2B's openapi. */
+export function apiError(status: number, message: string): E2bError {
+  return new E2bError(status, status, message);
+}
+
+/**
+ * Connect RPC error codes -> HTTP status, per the Connect protocol's unary
+ * mapping. Only the codes this layer actually emits.
+ */
+const CONNECT_STATUS: Record<string, number> = {
+  invalid_argument: 400,
+  unauthenticated: 401,
+  not_found: 404,
+  already_exists: 409,
+  resource_exhausted: 429,
+  internal: 500,
+  unimplemented: 501,
+  unavailable: 502,
+};
+
+export function connectError(code: string, message: string): E2bError {
+  return new E2bError(CONNECT_STATUS[code] ?? 500, code, message);
+}
+
+const sha256 = (value: string) => createHash('sha256').update(value).digest();
+
+/**
+ * The per-sandbox envd access token: HMAC(API token, sandbox id). Stateless
+ * — any daemon holding the API token can verify it without a lookup, and
+ * the SDK treats the value as opaque (it just echoes what create returned).
+ */
+export function mintEnvdToken(apiToken: string, sandboxId: string): string {
+  return createHmac('sha256', apiToken)
+    .update(`envd:${sandboxId}`)
+    .digest('hex');
+}
+
+export function verifyEnvdToken(
+  apiToken: string,
+  sandboxId: string,
+  presented: string,
+): boolean {
+  // Hash both sides so timingSafeEqual gets equal lengths, constant-time.
+  return timingSafeEqual(
+    sha256(presented),
+    sha256(mintEnvdToken(apiToken, sandboxId)),
+  );
+}
+
+/**
+ * X-API-KEY check. The official SDK formats keys as `e2b_<hex>` and our
+ * hex API token is compliant as `e2b_<token>`; the bare token is accepted
+ * too — the prefix is the SDK's convention, not a secret.
+ */
+export function verifyApiKey(
+  apiToken: string,
+  presented: string | undefined,
+): boolean {
+  const bare = presented?.startsWith('e2b_') ? presented.slice(4) : presented;
+  return timingSafeEqual(sha256(bare ?? ''), sha256(apiToken));
+}
+
+/** Connect streaming envelope flags: 0x00 = message, 0x02 = end of stream. */
+export const FLAG_MESSAGE = 0x00;
+export const FLAG_END_STREAM = 0x02;
+
+/**
+ * Connect streaming envelope: 1 flag byte + 4-byte big-endian payload
+ * length + JSON payload. The JSON codec because the SDK is configured with
+ * useBinaryFormat: false — no protobuf wire format anywhere.
+ */
+export function envelope(flags: number, json: unknown): Buffer {
+  const payload = Buffer.from(JSON.stringify(json), 'utf8');
+  const head = Buffer.alloc(5);
+  head.writeUInt8(flags, 0);
+  head.writeUInt32BE(payload.length, 1);
+  return Buffer.concat([head, payload]);
+}
+
+/**
+ * Extracts the first enveloped message of a streaming request body — a
+ * Start request carries exactly one.
+ */
+export function readFirstMessage(body: Buffer): unknown {
+  if (body.length < 5) {
+    throw connectError('invalid_argument', 'truncated connect envelope');
+  }
+  const length = body.readUInt32BE(1);
+  if (body.length < 5 + length) {
+    throw connectError('invalid_argument', 'truncated connect envelope');
+  }
+  try {
+    return JSON.parse(body.subarray(5, 5 + length).toString('utf8'));
+  } catch {
+    throw connectError('invalid_argument', 'connect envelope is not JSON');
+  }
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c95d79d..755f11f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -29,6 +29,9 @@ importers:
       '@dormice/sdk':
         specifier: workspace:*
         version: link:../packages/sdk
+      e2b:
+        specifier: ^2.31.0
+        version: 2.31.0
 
   packages/cli:
     dependencies:
@@ -61,6 +64,9 @@ importers:
       '@dormice/shared':
         specifier: workspace:*
         version: link:../shared
+      '@fastify/multipart':
+        specifier: ^10.0.0
+        version: 10.0.0
       better-sqlite3:
         specifier: ^12.11.1
         version: 12.11.1
@@ -166,6 +172,20 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@bufbuild/protobuf@2.12.1':
+    resolution: {integrity: sha512-BvAMfS6LrgZiryOAZ4pBYucu4wG/Ei/9o9DZ9akbREnMLbPJiom2i8b9C8IsKErQoiKqVhrerzt3kOT/RrzLHg==}
+
+  '@connectrpc/connect-web@2.0.0-rc.3':
+    resolution: {integrity: sha512-w88P8Lsn5CCsA7MFRl2e6oLY4J/5toiNtJns/YJrlyQaWOy3RO8pDgkz+iIkG98RPMhj2thuBvsd3Cn4DKKCkw==}
+    peerDependencies:
+      '@bufbuild/protobuf': ^2.2.0
+      '@connectrpc/connect': 2.0.0-rc.3
+
+  '@connectrpc/connect@2.0.0-rc.3':
+    resolution: {integrity: sha512-ARBt64yEyKbanyRETTjcjJuHr2YXorzQo0etyS5+P6oSeW8xEuzajA9g+zDnMcj1hlX2dQE93foIWQGfpru7gQ==}
+    peerDependencies:
+      '@bufbuild/protobuf': ^2.2.0
+
   '@drizzle-team/brocli@0.10.2':
     resolution: {integrity: sha512-z33Il7l5dKjUgGULTqBsQBQwckHh5AbIuxhdsIxDDiZAzBOrZO6q9ogcWC65kU382AfynTfgNumVcNIjuIua6w==}
 
@@ -789,6 +809,12 @@ packages:
   '@fastify/ajv-compiler@4.0.5':
     resolution: {integrity: sha512-KoWKW+MhvfTRWL4qrhUwAAZoaChluo0m0vbiJlGMt2GXvL4LVPQEjt8kSpHI3IBq5Rez8fg+XeH3cneztq+C7A==}
 
+  '@fastify/busboy@3.2.0':
+    resolution: {integrity: sha512-m9FVDXU3GT2ITSe0UaMA5rU3QkfC/UXtCU8y0gSN/GugTqtVldOBWIB5V6V3sbmenVZUIpU6f+mPEO2+m5iTaA==}
+
+  '@fastify/deepmerge@3.2.1':
+    resolution: {integrity: sha512-N5Oqvltoa2r9z1tbx4xjky0oRR60v+T47Ic4J1ukoVQcptLOrIdRnCSdTGmOmajZuHVKlTnfcmrjyqsGEW1ztA==}
+
   '@fastify/error@4.2.0':
     resolution: {integrity: sha512-RSo3sVDXfHskiBZKBPRgnQTtIqpi/7zhJOEmAxCiBcM7d0uwdGdxLlsCaLzGs8v8NnxIRlfG0N51p5yFaOentQ==}
 
@@ -801,6 +827,9 @@ packages:
   '@fastify/merge-json-schemas@0.2.1':
     resolution: {integrity: sha512-OA3KGBCy6KtIvLf8DINC5880o5iBlDX4SxzLQS8HorJAbqluzLRn80UXU0bxZn7UOFhFgpRJDasfwn9nG4FG4A==}
 
+  '@fastify/multipart@10.0.0':
+    resolution: {integrity: sha512-pUx3Z1QStY7E7kwvDTIvB6P+rF5lzP+iqPgZyJyG3yBJVPvQaZxzDHYbQD89rbY0ciXrMOyGi8ezHDVexLvJDA==}
+
   '@fastify/proxy-addr@5.1.0':
     resolution: {integrity: sha512-INS+6gh91cLUjB+PVHfu1UqcB76Sqtpyp7bnL+FYojhjygvOPA9ctiD/JDKsyD9Xgu4hUhCSJBPig/w7duNajw==}
 
@@ -821,6 +850,14 @@ packages:
     engines: {node: '>=6'}
     hasBin: true
 
+  '@isaacs/cliui@9.0.0':
+    resolution: {integrity: sha512-AokJm4tuBHillT+FpMtxQ60n8ObyXBatq7jD2/JA9dxbDDokKQm8KMht5ibGzLVU9IJDIKK4TPKgMHEYMn3lMg==}
+    engines: {node: '>=18'}
+
+  '@isaacs/fs-minipass@4.0.1':
+    resolution: {integrity: sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==}
+    engines: {node: '>=18.0.0'}
+
   '@jridgewell/gen-mapping@0.3.13':
     resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
 
@@ -1225,6 +1262,10 @@ packages:
   avvio@9.2.0:
     resolution: {integrity: sha512-2t/sy01ArdHHE0vRH5Hsay+RtCZt3dLPji7W7/MMOCEgze5b7SNDC4j5H6FnVgPkI1MTNFGzHdHrVXDDl7QSSQ==}
 
+  balanced-match@4.0.4:
+    resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
+    engines: {node: 18 || 20 || >=22}
+
   base64-js@1.5.1:
     resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
 
@@ -1241,6 +1282,10 @@ packages:
   bl@4.1.0:
     resolution: {integrity: sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==}
 
+  brace-expansion@5.0.7:
+    resolution: {integrity: sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA==}
+    engines: {node: 18 || 20 || >=22}
+
   buffer-from@1.1.2:
     resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==}
 
@@ -1265,6 +1310,10 @@ packages:
     resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
     engines: {node: '>=18'}
 
+  chalk@5.6.2:
+    resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
+    engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+
   chokidar@4.0.3:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
@@ -1272,6 +1321,10 @@ packages:
   chownr@1.1.4:
     resolution: {integrity: sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==}
 
+  chownr@3.0.0:
+    resolution: {integrity: sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==}
+    engines: {node: '>=18'}
+
   cliui@8.0.1:
     resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==}
     engines: {node: '>=12'}
@@ -1291,6 +1344,9 @@ packages:
     resolution: {integrity: sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==}
     engines: {node: '>= 6'}
 
+  compare-versions@6.1.1:
+    resolution: {integrity: sha512-4hm4VPpIecmlg59CHXnRDnqGplJFrbLG4aFEl5vl6cK1u76ws3LLvX7ikFnTDl5vo39sjWD6AaDPYodJp/NNHg==}
+
   confbox@0.1.8:
     resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==}
 
@@ -1342,6 +1398,9 @@ packages:
     resolution: {integrity: sha512-XJgGhoR/CLpqshm4d3L7rzH6t8NgDFUIIpztYlLHIApeJjMZKYJMz2zxPsYxnejq5h3ELYSw/RBsi3t5h7gNTA==}
     engines: {node: '>= 8.0'}
 
+  dockerfile-ast@0.7.1:
+    resolution: {integrity: sha512-oX/A4I0EhSkGqrFv0YuvPkBUSYp1XiY8O8zAKc8Djglx8ocz+JfOr8gP0ryRMC2myqvDLagmnZaU9ot1vG2ijw==}
+
   dockerode@5.0.1:
     resolution: {integrity: sha512-avsq/xk4YPIrn0CgleX5bjT9Y8IT1p9PxrNQ++RBQ2WEyFfHCTDsT9kmyxz+H/axnjAwg8wJWEIuPGOUuNupiA==}
     engines: {node: '>= 14.17'}
@@ -1442,6 +1501,10 @@ packages:
       sqlite3:
         optional: true
 
+  e2b@2.31.0:
+    resolution: {integrity: sha512-vXQomb16mOk+ufi3YFfN6eURm6eC0NZGMK49PXibfpsmy0azcvLbQuHxCkhgyAk5z5GVfrEUwc08QKVtt6KNFg==}
+    engines: {node: '>=20.18.1'}
+
   emoji-regex@8.0.0:
     resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
 
@@ -1545,6 +1608,10 @@ packages:
   fix-dts-default-cjs-exports@1.0.1:
     resolution: {integrity: sha512-pVIECanWFC61Hzl2+oOCtoJ3F17kglZC/6N94eRWycFgBH35hHx0Li604ZIzhseh97mf2p0cv7vVrOZGoqhlEg==}
 
+  foreground-child@3.3.1:
+    resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==}
+    engines: {node: '>=14'}
+
   fs-constants@1.0.0:
     resolution: {integrity: sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==}
 
@@ -1567,6 +1634,11 @@ packages:
   github-from-package@0.0.0:
     resolution: {integrity: sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==}
 
+  glob@11.1.0:
+    resolution: {integrity: sha512-vuNwKSaKiqm7g0THUBu2x7ckSs3XJLXE+2ssL7/MfTGPLLcrJQ/4Uq1CjPTtO5cCIiRxqvN6Twy1qOwhL0Xjcw==}
+    engines: {node: 20 || >=22}
+    hasBin: true
+
   human-signals@8.0.1:
     resolution: {integrity: sha512-eKCa6bwnJhvxj14kZk5NCPc6Hb6BdsU9DZcOnmQKSnO1VKrfV0zCvtttPZUsBvjmNDn8rpcJfpwSYnHBjc95MQ==}
     engines: {node: '>=18.18.0'}
@@ -1603,6 +1675,10 @@ packages:
   isexe@2.0.0:
     resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
 
+  jackspeak@4.2.3:
+    resolution: {integrity: sha512-ykkVRwrYvFm1nb2AJfKKYPr0emF6IiXDYUaFx4Zn9ZuIH7MrzEZ3sD5RlqGXNRpHtvUHJyOnCEFxOlNDtGo7wg==}
+    engines: {node: 20 || >=22}
+
   joycon@3.1.1:
     resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==}
     engines: {node: '>=10'}
@@ -1711,6 +1787,10 @@ packages:
   long@5.3.2:
     resolution: {integrity: sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==}
 
+  lru-cache@11.5.2:
+    resolution: {integrity: sha512-4pfM1Ff0x50o0tQwb5ucw/RzNyD0/YJME6IVcStalZuMWxdt3sR3huStTtxz4PUmvZfRguvDejasvQ2kifR11g==}
+    engines: {node: 20 || >=22}
+
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
@@ -1718,9 +1798,21 @@ packages:
     resolution: {integrity: sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ==}
     engines: {node: '>=10'}
 
+  minimatch@10.2.5:
+    resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==}
+    engines: {node: 18 || 20 || >=22}
+
   minimist@1.2.8:
     resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
 
+  minipass@7.1.3:
+    resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==}
+    engines: {node: '>=16 || 14 >=14.17'}
+
+  minizlib@3.1.0:
+    resolution: {integrity: sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==}
+    engines: {node: '>= 18'}
+
   mkdirp-classic@0.5.3:
     resolution: {integrity: sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==}
 
@@ -1767,9 +1859,18 @@ packages:
   once@1.4.0:
     resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==}
 
+  openapi-fetch@0.14.1:
+    resolution: {integrity: sha512-l7RarRHxlEZYjMLd/PR0slfMVse2/vvIAGm75/F7J6MlQ8/b9uUQmUF2kCPrQhJqMXSxmYWObVgeYXbFYzZR+A==}
+
   openapi-types@12.1.3:
     resolution: {integrity: sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw==}
 
+  openapi-typescript-helpers@0.0.15:
+    resolution: {integrity: sha512-opyTPaunsklCBpTK8JGef6mfPhLSnyy5a0IN9vKtx3+4aExf+KxEqYwIy3hqkedXIB97u357uLMJsOnm3GVjsw==}
+
+  package-json-from-dist@1.0.1:
+    resolution: {integrity: sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==}
+
   parse-ms@4.0.0:
     resolution: {integrity: sha512-TXfryirbmq34y8QBwgqCVLi+8oA3oWx2eAnSn62ITyEhEYaWRlVZ2DvMM9eZbMs/RfxPu/PK/aBLyGj4IrqMHw==}
     engines: {node: '>=18'}
@@ -1782,6 +1883,10 @@ packages:
     resolution: {integrity: sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ==}
     engines: {node: '>=12'}
 
+  path-scurry@2.0.2:
+    resolution: {integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==}
+    engines: {node: 18 || 20 || >=22}
+
   pathe@2.0.3:
     resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
 
@@ -1809,6 +1914,9 @@ packages:
   pkg-types@1.3.1:
     resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
 
+  platform@1.3.6:
+    resolution: {integrity: sha512-fnWVljUchTro6RiCFvCXBbNhJc2NijN7oIQxbwsyL0buWJPG85v81ehlHI9fXrJsMNgTofEoWIQeClKpgxFLrg==}
+
   postcss-load-config@6.0.1:
     resolution: {integrity: sha512-oPtTM4oerL+UXmx+93ytZVN82RrlY/wPUV8IeDxFrzIjXOLF1pN+EmKPLbubvKHT2HC20xXsCAH2Z+CKV6Oz/g==}
     engines: {node: '>= 18'}
@@ -2024,6 +2132,10 @@ packages:
     resolution: {integrity: sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==}
     engines: {node: '>=6'}
 
+  tar@7.5.19:
+    resolution: {integrity: sha512-4LeEWl96twnS2Q7Bz4MGqgazLqO+hJN63GZxXoIqh1T3VweYD997gbU1ItNsQafqqXTXd5WFyFdReLtwvRBNiw==}
+    engines: {node: '>=18'}
+
   thenify-all@1.6.0:
     resolution: {integrity: sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==}
     engines: {node: '>=0.8'}
@@ -2111,6 +2223,10 @@ packages:
   undici-types@8.3.0:
     resolution: {integrity: sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==}
 
+  undici@7.28.0:
+    resolution: {integrity: sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==}
+    engines: {node: '>=20.18.1'}
+
   undici@8.7.0:
     resolution: {integrity: sha512-N7iQtfyLhIMOFgQubvmLV26svHpO0bqKnAiWotTQCVKCmWrcGbBotPuW1x+xwYZ2VHdSTVUfPQQnlEt1/LouTQ==}
     engines: {node: '>=22.19.0'}
@@ -2206,6 +2322,12 @@ packages:
       jsdom:
         optional: true
 
+  vscode-languageserver-textdocument@1.0.12:
+    resolution: {integrity: sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==}
+
+  vscode-languageserver-types@3.18.0:
+    resolution: {integrity: sha512-8TsGPNMIMiiBdkORgRSvLjuiEIiAFtO+KssmYWxQ+uSVvlf7RjK8YKCOjPzZ+YA04jXEV7+7LvkSmHkhpNS99g==}
+
   which@2.0.2:
     resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
     engines: {node: '>= 8'}
@@ -2227,6 +2349,10 @@ packages:
     resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
     engines: {node: '>=10'}
 
+  yallist@5.0.0:
+    resolution: {integrity: sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==}
+    engines: {node: '>=18'}
+
   yaml@2.9.0:
     resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
     engines: {node: '>= 14.6'}
@@ -2286,6 +2412,17 @@ snapshots:
   '@biomejs/cli-win32-x64@2.5.2':
     optional: true
 
+  '@bufbuild/protobuf@2.12.1': {}
+
+  '@connectrpc/connect-web@2.0.0-rc.3(@bufbuild/protobuf@2.12.1)(@connectrpc/connect@2.0.0-rc.3(@bufbuild/protobuf@2.12.1))':
+    dependencies:
+      '@bufbuild/protobuf': 2.12.1
+      '@connectrpc/connect': 2.0.0-rc.3(@bufbuild/protobuf@2.12.1)
+
+  '@connectrpc/connect@2.0.0-rc.3(@bufbuild/protobuf@2.12.1)':
+    dependencies:
+      '@bufbuild/protobuf': 2.12.1
+
   '@drizzle-team/brocli@0.10.2': {}
 
   '@emnapi/core@1.11.1':
@@ -2620,6 +2757,10 @@ snapshots:
       ajv-formats: 3.0.1(ajv@8.20.0)
       fast-uri: 3.1.3
 
+  '@fastify/busboy@3.2.0': {}
+
+  '@fastify/deepmerge@3.2.1': {}
+
   '@fastify/error@4.2.0': {}
 
   '@fastify/fast-json-stringify-compiler@5.1.0':
@@ -2632,6 +2773,14 @@ snapshots:
     dependencies:
       dequal: 2.0.3
 
+  '@fastify/multipart@10.0.0':
+    dependencies:
+      '@fastify/busboy': 3.2.0
+      '@fastify/deepmerge': 3.2.1
+      '@fastify/error': 4.2.0
+      fastify-plugin: 5.1.0
+      secure-json-parse: 4.1.0
+
   '@fastify/proxy-addr@5.1.0':
     dependencies:
       '@fastify/forwarded': 3.0.1
@@ -2666,6 +2815,12 @@ snapshots:
       protobufjs: 7.6.5
       yargs: 17.7.3
 
+  '@isaacs/cliui@9.0.0': {}
+
+  '@isaacs/fs-minipass@4.0.1':
+    dependencies:
+      minipass: 7.1.3
+
   '@jridgewell/gen-mapping@0.3.13':
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
@@ -2963,6 +3118,8 @@ snapshots:
       '@fastify/error': 4.2.0
       fastq: 1.20.1
 
+  balanced-match@4.0.4: {}
+
   base64-js@1.5.1: {}
 
   bcrypt-pbkdf@1.0.2:
@@ -2984,6 +3141,10 @@ snapshots:
       inherits: 2.0.4
       readable-stream: 3.6.2
 
+  brace-expansion@5.0.7:
+    dependencies:
+      balanced-match: 4.0.4
+
   buffer-from@1.1.2: {}
 
   buffer@5.7.1:
@@ -3003,12 +3164,16 @@ snapshots:
 
   chai@6.2.2: {}
 
+  chalk@5.6.2: {}
+
   chokidar@4.0.3:
     dependencies:
       readdirp: 4.1.2
 
   chownr@1.1.4: {}
 
+  chownr@3.0.0: {}
+
   cliui@8.0.1:
     dependencies:
       string-width: 4.2.3
@@ -3025,6 +3190,8 @@ snapshots:
 
   commander@4.1.1: {}
 
+  compare-versions@6.1.1: {}
+
   confbox@0.1.8: {}
 
   consola@3.4.2: {}
@@ -3068,6 +3235,11 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  dockerfile-ast@0.7.1:
+    dependencies:
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-languageserver-types: 3.18.0
+
   dockerode@5.0.1:
     dependencies:
       '@balena/dockerignore': 1.0.2
@@ -3091,6 +3263,20 @@ snapshots:
       '@types/better-sqlite3': 7.6.13
       better-sqlite3: 12.11.1
 
+  e2b@2.31.0:
+    dependencies:
+      '@bufbuild/protobuf': 2.12.1
+      '@connectrpc/connect': 2.0.0-rc.3(@bufbuild/protobuf@2.12.1)
+      '@connectrpc/connect-web': 2.0.0-rc.3(@bufbuild/protobuf@2.12.1)(@connectrpc/connect@2.0.0-rc.3(@bufbuild/protobuf@2.12.1))
+      chalk: 5.6.2
+      compare-versions: 6.1.1
+      dockerfile-ast: 0.7.1
+      glob: 11.1.0
+      openapi-fetch: 0.14.1
+      platform: 1.3.6
+      tar: 7.5.19
+      undici: 7.28.0
+
   emoji-regex@8.0.0: {}
 
   end-of-stream@1.4.5:
@@ -3309,6 +3495,11 @@ snapshots:
       mlly: 1.8.2
       rollup: 4.62.2
 
+  foreground-child@3.3.1:
+    dependencies:
+      cross-spawn: 7.0.6
+      signal-exit: 4.1.0
+
   fs-constants@1.0.0: {}
 
   fsevents@2.3.3:
@@ -3327,6 +3518,15 @@ snapshots:
 
   github-from-package@0.0.0: {}
 
+  glob@11.1.0:
+    dependencies:
+      foreground-child: 3.3.1
+      jackspeak: 4.2.3
+      minimatch: 10.2.5
+      minipass: 7.1.3
+      package-json-from-dist: 1.0.1
+      path-scurry: 2.0.2
+
   human-signals@8.0.1: {}
 
   ieee754@1.2.1: {}
@@ -3347,6 +3547,10 @@ snapshots:
 
   isexe@2.0.0: {}
 
+  jackspeak@4.2.3:
+    dependencies:
+      '@isaacs/cliui': 9.0.0
+
   joycon@3.1.1: {}
 
   json-schema-ref-resolver@3.0.0:
@@ -3428,14 +3632,26 @@ snapshots:
 
   long@5.3.2: {}
 
+  lru-cache@11.5.2: {}
+
   magic-string@0.30.21:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
 
   mimic-response@3.1.0: {}
 
+  minimatch@10.2.5:
+    dependencies:
+      brace-expansion: 5.0.7
+
   minimist@1.2.8: {}
 
+  minipass@7.1.3: {}
+
+  minizlib@3.1.0:
+    dependencies:
+      minipass: 7.1.3
+
   mkdirp-classic@0.5.3: {}
 
   mlly@1.8.2:
@@ -3479,14 +3695,27 @@ snapshots:
     dependencies:
       wrappy: 1.0.2
 
+  openapi-fetch@0.14.1:
+    dependencies:
+      openapi-typescript-helpers: 0.0.15
+
   openapi-types@12.1.3: {}
 
+  openapi-typescript-helpers@0.0.15: {}
+
+  package-json-from-dist@1.0.1: {}
+
   parse-ms@4.0.0: {}
 
   path-key@3.1.1: {}
 
   path-key@4.0.0: {}
 
+  path-scurry@2.0.2:
+    dependencies:
+      lru-cache: 11.5.2
+      minipass: 7.1.3
+
   pathe@2.0.3: {}
 
   picocolors@1.1.1: {}
@@ -3521,6 +3750,8 @@ snapshots:
       mlly: 1.8.2
       pathe: 2.0.3
 
+  platform@1.3.6: {}
+
   postcss-load-config@6.0.1(postcss@8.5.16)(tsx@4.23.0)(yaml@2.9.0):
     dependencies:
       lilconfig: 3.1.3
@@ -3772,6 +4003,14 @@ snapshots:
       inherits: 2.0.4
       readable-stream: 3.6.2
 
+  tar@7.5.19:
+    dependencies:
+      '@isaacs/fs-minipass': 4.0.1
+      chownr: 3.0.0
+      minipass: 7.1.3
+      minizlib: 3.1.0
+      yallist: 5.0.0
+
   thenify-all@1.6.0:
     dependencies:
       thenify: 3.3.1
@@ -3854,6 +4093,8 @@ snapshots:
 
   undici-types@8.3.0: {}
 
+  undici@7.28.0: {}
+
   undici@8.7.0: {}
 
   unicorn-magic@0.3.0: {}
@@ -3901,6 +4142,10 @@ snapshots:
     transitivePeerDependencies:
       - msw
 
+  vscode-languageserver-textdocument@1.0.12: {}
+
+  vscode-languageserver-types@3.18.0: {}
+
   which@2.0.2:
     dependencies:
       isexe: 2.0.0
@@ -3920,6 +4165,8 @@ snapshots:
 
   y18n@5.0.8: {}
 
+  yallist@5.0.0: {}
+
   yaml@2.9.0: {}
 
   yargs-parser@21.1.1: {}

From 062f2cba57149100d78c21f0e45b47d641758133 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 18:53:58 +0800
Subject: [PATCH 008/133] e2e drives the official e2b SDK against the daemon:
 13 items green on the fake
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The compatibility promise verified with the promise's own artifact: the
official e2b package (2.31.0 — the supply-chain gate held back 2.32.0,
released yesterday), pointed at the daemon by exactly two URLs. Commands
with live streaming (timed chunk gap), CommandExitError on nonzero exits,
files write/read/list/stat/rename/remove, byte-exact round-trips,
metadata lookup through Sandbox.list, real timeout death, onTimeout:
pause parking with connect revival, explicit pause/resume, setTimeout
extension, and the idempotent-create extension.

Two more items run only on the docker executor (whoami/uid 1000, login
shell) — the pocket interpreter has no users; the real-machine exam
covers them.
---
 e2e/package.json    |   3 +-
 e2e/src/e2b.test.ts | 277 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 279 insertions(+), 1 deletion(-)
 create mode 100644 e2e/src/e2b.test.ts

diff --git a/e2e/package.json b/e2e/package.json
index 84c43f8..4f97a8c 100644
--- a/e2e/package.json
+++ b/e2e/package.json
@@ -10,6 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@dormice/sdk": "workspace:*"
+    "@dormice/sdk": "workspace:*",
+    "e2b": "^2.31.0"
   }
 }
diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
new file mode 100644
index 0000000..a246b55
--- /dev/null
+++ b/e2e/src/e2b.test.ts
@@ -0,0 +1,277 @@
+import { CommandExitError, Sandbox } from 'e2b';
+import { describe, expect, inject, it } from 'vitest';
+
+// The compatibility promise, verified with the promise's own artifact: the
+// OFFICIAL e2b package, pointed at the daemon by exactly two URLs (plus its
+// API key). Nothing in here imports Dormice code — if these tests pass, a
+// real E2B application migrates by changing configuration, not code.
+const connection = () => ({
+  apiKey: `e2b_${inject('dormiceToken')}`,
+  apiUrl: `${inject('dormiceEndpoint')}/e2b/api`,
+  sandboxUrl: `${inject('dormiceEndpoint')}/e2b/envd`,
+});
+
+function sleep(seconds: number) {
+  return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+}
+
+describe('official e2b SDK against the daemon', () => {
+  it('creates a sandbox and runs a command', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      expect(sbx.sandboxId).toBeTruthy();
+      const result = await sbx.commands.run('echo hello-dormice');
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toBe('hello-dormice\n');
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('throws CommandExitError on a nonzero exit — the SDK’s own contract', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      const error = await sbx.commands.run('exit 3').catch((e) => e);
+      expect(error).toBeInstanceOf(CommandExitError);
+      expect(error.exitCode).toBe(3);
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('streams output live through onStdout, not buffered', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      const chunks: Array<{ text: string; at: number }> = [];
+      const result = await sbx.commands.run(
+        'echo first; sleep 1; echo second',
+        {
+          onStdout: (text) => {
+            chunks.push({ text, at: Date.now() });
+          },
+        },
+      );
+      expect(result.stdout).toBe('first\nsecond\n');
+      const at = chunks.map((c) => c.at);
+      // A real gap between chunks is what "streaming" means; a buffered
+      // implementation delivers everything at once.
+      expect(Math.max(...at) - Math.min(...at)).toBeGreaterThanOrEqual(500);
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('honors cwd and envs per command, with sandbox envs underneath', async () => {
+    const sbx = await Sandbox.create({
+      ...connection(),
+      envs: { FROM_SANDBOX: 'base-value' },
+    });
+    try {
+      const cwd = await sbx.commands.run('pwd', { cwd: '/tmp' });
+      expect(cwd.stdout).toBe('/tmp\n');
+      const fromSandbox = await sbx.commands.run('printenv FROM_SANDBOX');
+      expect(fromSandbox.stdout).toBe('base-value\n');
+      const shadowed = await sbx.commands.run('printenv FROM_SANDBOX', {
+        envs: { FROM_SANDBOX: 'per-command' },
+      });
+      expect(shadowed.stdout).toBe('per-command\n');
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('writes, reads, lists, stats, renames and removes files', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      const entry = await sbx.files.write(
+        'notes/hello.txt',
+        '你好,Dormice ✓\n',
+      );
+      expect(entry.path).toBe('/home/user/notes/hello.txt');
+      expect(await sbx.files.read('notes/hello.txt')).toBe('你好,Dormice ✓\n');
+
+      // The array form writes a batch.
+      await sbx.files.write([
+        { path: 'notes/a.txt', data: 'a' },
+        { path: 'notes/b.txt', data: 'b' },
+      ]);
+      const names = (await sbx.files.list('notes')).map((e) => e.name).sort();
+      expect(names).toEqual(['a.txt', 'b.txt', 'hello.txt']);
+
+      expect(await sbx.files.exists('notes/a.txt')).toBe(true);
+      expect(await sbx.files.exists('notes/void.txt')).toBe(false);
+
+      const info = await sbx.files.getInfo('notes/a.txt');
+      expect(info.type).toBe('file');
+      expect(Number(info.size)).toBe(1);
+
+      const renamed = await sbx.files.rename('notes/a.txt', 'notes/z.txt');
+      expect(renamed.path).toBe('/home/user/notes/z.txt');
+
+      expect(await sbx.files.makeDir('notes/deep/er')).toBe(true);
+      expect(await sbx.files.makeDir('notes/deep/er')).toBe(false);
+
+      await sbx.files.remove('notes');
+      expect(await sbx.files.exists('notes')).toBe(false);
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('round-trips bytes exactly', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      const bytes = new Uint8Array(512).map((_, i) => i % 256);
+      await sbx.files.write('blob.bin', bytes.buffer);
+      const back = await sbx.files.read('blob.bin', { format: 'bytes' });
+      expect(Buffer.from(back).equals(Buffer.from(bytes))).toBe(true);
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('reports info, appears in list, and can be found by metadata', async () => {
+    const sbx = await Sandbox.create({
+      ...connection(),
+      metadata: { suite: 'e2b-e2e', run: 'metadata-lookup' },
+    });
+    try {
+      expect(await sbx.isRunning()).toBe(true);
+      const info = await sbx.getInfo();
+      expect(info.state).toBe('running');
+      expect(info.metadata).toMatchObject({ run: 'metadata-lookup' });
+
+      const found = await Sandbox.list({
+        ...connection(),
+        query: { metadata: { run: 'metadata-lookup' } },
+      }).nextItems();
+      expect(found.map((s) => s.sandboxId)).toContain(sbx.sandboxId);
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('kill destroys for real: gone from list, connect refuses, second kill is false', async () => {
+    const sbx = await Sandbox.create(connection());
+    await sbx.files.write('doomed.txt', 'will not survive');
+    expect(await sbx.kill()).toBe(true);
+
+    expect(await sbx.isRunning()).toBe(false);
+    await expect(Sandbox.connect(sbx.sandboxId, connection())).rejects.toThrow(
+      /not found/i,
+    );
+    expect(await Sandbox.kill(sbx.sandboxId, connection())).toBe(false);
+  });
+
+  it('a sandbox dies at its timeout — E2B semantics, honored for real', async () => {
+    const sbx = await Sandbox.create({ ...connection(), timeoutMs: 2_000 });
+    expect(await sbx.isRunning()).toBe(true);
+    // Past the deadline plus a scanner sweep (the e2e daemon sweeps every
+    // second): the sandbox must be protocol-dead and physically reaped.
+    await sleep(3.5);
+    expect(await sbx.isRunning()).toBe(false);
+    await expect(Sandbox.connect(sbx.sandboxId, connection())).rejects.toThrow(
+      /not found/i,
+    );
+  });
+
+  it('onTimeout pause parks the sandbox instead; connect revives it, files intact', async () => {
+    const sbx = await Sandbox.create({
+      ...connection(),
+      timeoutMs: 2_000,
+      lifecycle: { onTimeout: 'pause' },
+    });
+    try {
+      await sbx.files.write('keep.txt', 'still here');
+      await sleep(3.5);
+      expect(await sbx.isRunning()).toBe(false);
+      const info = await sbx.getInfo();
+      expect(info.state).toBe('paused');
+
+      const revived = await Sandbox.connect(sbx.sandboxId, connection());
+      expect(await revived.isRunning()).toBe(true);
+      expect(await revived.files.read('keep.txt')).toBe('still here');
+    } finally {
+      await Sandbox.kill(sbx.sandboxId, connection()).catch(() => {});
+    }
+  }, 20_000);
+
+  it('pause and connect: explicit pause parks, connect resumes, files intact', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      await sbx.files.write('nap.txt', 'through the nap');
+      expect(await sbx.pause()).toBe(true);
+      expect(await sbx.isRunning()).toBe(false);
+      expect((await sbx.getInfo()).state).toBe('paused');
+      // Pausing an already-paused sandbox reports false, not an error.
+      expect(await sbx.pause()).toBe(false);
+
+      const revived = await Sandbox.connect(sbx.sandboxId, connection());
+      expect((await revived.getInfo()).state).toBe('running');
+      expect(await revived.files.read('nap.txt')).toBe('through the nap');
+    } finally {
+      await Sandbox.kill(sbx.sandboxId, connection()).catch(() => {});
+    }
+  });
+
+  it('setTimeout extends the lease', async () => {
+    const sbx = await Sandbox.create({ ...connection(), timeoutMs: 2_000 });
+    try {
+      await sbx.setTimeout(600_000);
+      await sleep(3.5);
+      // Without the extension this sandbox would be dead by now.
+      expect(await sbx.isRunning()).toBe(true);
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('the Dormice extension: metadata.userKey makes create idempotent, data persists', async () => {
+    const first = await Sandbox.create({
+      ...connection(),
+      metadata: { userKey: 'e2e-agent-key' },
+    });
+    try {
+      await first.files.write('persistent.txt', 'same sandbox every time');
+      const second = await Sandbox.create({
+        ...connection(),
+        metadata: { userKey: 'e2e-agent-key' },
+      });
+      expect(second.sandboxId).toBe(first.sandboxId);
+      expect(await second.files.read('persistent.txt')).toBe(
+        'same sandbox every time',
+      );
+    } finally {
+      await first.kill();
+    }
+  });
+});
+
+// Identity and real-shell behavior only a real container can answer; the
+// pocket interpreter has no users or profiles. The docker-mode e2e run on
+// the test machine covers these.
+describe.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
+  'official e2b SDK, docker executor only',
+  () => {
+    it('commands run as user (uid 1000), never root', async () => {
+      const sbx = await Sandbox.create(connection());
+      try {
+        const result = await sbx.commands.run('whoami && id -u');
+        expect(result.stdout).toBe('user\n1000\n');
+      } finally {
+        await sbx.kill();
+      }
+    });
+
+    it('runs a login shell: the image profile is loaded', async () => {
+      const sbx = await Sandbox.create(connection());
+      try {
+        // `bash -l -c` sources the profile; $HOME comes from the user entry.
+        const result = await sbx.commands.run('echo $HOME');
+        expect(result.stdout).toBe('/home/user\n');
+      } finally {
+        await sbx.kill();
+      }
+    });
+  },
+);

From ad7f7e69623cd877d99dfe441b96c9e7c29d8216 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 19:14:03 +0800
Subject: [PATCH 009/133] The disk is born fully owned: mkfs's root-owned
 lost+found blocked uid-1000 find

---
 packages/server/src/executor/docker.ts | 7 ++++++-
 packages/server/src/executor/fake.ts   | 5 +++--
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index de87865..77e3c2a 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -981,8 +981,13 @@ export class DockerExecutor implements Executor {
     // interactive "proceed anyway?" prompt no one is there to answer.
     await execa('mkfs.ext4', ['-q', '-F', img]);
     await execa('mount', ['-o', 'loop,discard', img, mnt]);
-    // The mounted fs root must belong to the in-container user (uid 1000).
+    // Born fully owned by the in-container user (uid 1000): the fs root and
+    // mkfs's lost+found — root:0700 otherwise, which uid-1000 file plumbing
+    // cannot descend into (find at depth ≥ 2 exits 1). Only safe at birth;
+    // once a sandbox has run, disk content is sandbox-controlled and the
+    // host must not touch it (ensureMounted deliberately never chowns).
     await chown(mnt, 1000, 1000);
+    await chown(path.join(mnt, 'lost+found'), 1000, 1000);
   }
 
   /** Idempotent: mounts the sandbox disk unless it already is mounted. */
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index a93df0e..1ba1d4d 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -22,13 +22,14 @@ import {
  * Directories every real sandbox is born with, with the owner and mode
  * reality gives them: the image's skeleton plus lost+found — the mkfs.ext4
  * artifact every disk carries in its root (/home/user), which a directory
- * listing must therefore show on the fake too.
+ * listing must therefore show on the fake too. lost+found belongs to the
+ * user because provisionDisk chowns it at disk birth.
  */
 const BUILTIN_DIRS: Record<string, { owner: string; mode: number }> = {
   '/': { owner: 'root', mode: 0o755 },
   '/home': { owner: 'root', mode: 0o755 },
   '/home/user': { owner: 'user', mode: 0o755 },
-  '/home/user/lost+found': { owner: 'root', mode: 0o700 },
+  '/home/user/lost+found': { owner: 'user', mode: 0o700 },
   '/tmp': { owner: 'root', mode: 0o1777 },
 };
 

From ad20a92e8d3e775c46c95ed2473d7b4ca140ae19 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 20:44:21 +0800
Subject: [PATCH 010/133] dor doctor: 19 read-only host checks, every rule a
 measured fact
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Answers one question: can this host run the Dormice daemon? Checks gate
on each other (non-Linux skips everything, no root skips iptables), read
effective values over config files (the swappiness=0 factory-default
lesson), and name fixes without ever applying them — fixing is
install.sh's job. Three probes start a real runsc container by default
(fake kernel, metadata BLOCKED, uid 1000); --quick skips them; doctor
never pulls images. Any failure exits 1.
---
 packages/cli/src/doctor.test.ts | 331 ++++++++++++++++++
 packages/cli/src/doctor.ts      | 576 ++++++++++++++++++++++++++++++++
 packages/cli/src/main.ts        |  13 +
 3 files changed, 920 insertions(+)
 create mode 100644 packages/cli/src/doctor.test.ts
 create mode 100644 packages/cli/src/doctor.ts

diff --git a/packages/cli/src/doctor.test.ts b/packages/cli/src/doctor.test.ts
new file mode 100644
index 0000000..87a3274
--- /dev/null
+++ b/packages/cli/src/doctor.test.ts
@@ -0,0 +1,331 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type CheckResult,
+  type DoctorContext,
+  type RunResult,
+  runDoctor,
+} from './doctor';
+
+const IMAGE = 'dormice-base:20260708';
+const TOKEN = 'a'.repeat(64);
+
+const ok = (stdout: string): RunResult => ({ ok: true, stdout, stderr: '' });
+const boom = (stderr: string): RunResult => ({ ok: false, stdout: '', stderr });
+
+const GOOD_DAEMON_JSON = JSON.stringify({
+  'registry-mirrors': [],
+  'log-driver': 'json-file',
+  'log-opts': { 'max-size': '10m', 'max-file': '3' },
+  icc: false,
+});
+
+const IPTABLES_GOOD = [
+  '-N DOCKER-USER',
+  '-A DOCKER-USER -d 100.100.100.200/32 -j DROP',
+  '-A DOCKER-USER -d 169.254.0.0/16 -j DROP',
+  '-A DOCKER-USER -j RETURN',
+].join('\n');
+
+const DF_ROOMY =
+  'Filesystem 1024-blocks Used Available Capacity Mounted on\n' +
+  '/dev/vda3 200000000 50000000 150000000 25% /';
+
+/**
+ * A whole healthy host, faked. Tests override single facts to break one
+ * check at a time — the doctor equivalent of the contract suite's "one
+ * behavior per question".
+ */
+function fakeHost(
+  overrides: {
+    platform?: string;
+    nodeVersion?: string;
+    uid?: number;
+    env?: Record<string, string | undefined>;
+    files?: Record<string, string | undefined>;
+    commands?: Record<string, RunResult>;
+  } = {},
+): DoctorContext & { calls: string[] } {
+  const files: Record<string, string | undefined> = {
+    '/sys/fs/cgroup/cgroup.controllers': 'cpuset cpu io memory pids',
+    '/etc/docker/daemon.json': GOOD_DAEMON_JSON,
+    '/proc/meminfo': 'MemTotal: 30000000 kB\nSwapTotal: 16777212 kB',
+    '/proc/sys/vm/swappiness': '100\n',
+    '/etc/iptables/rules.v4': IPTABLES_GOOD,
+    ...overrides.files,
+  };
+  const commands: Record<string, RunResult> = {
+    'docker version --format {{.Server.Version}}': ok('29.6.1\n'),
+    'docker info --format {{json .Runtimes}}': ok(
+      '{"runc":{"path":"runc"},"runsc":{"path":"/usr/local/bin/runsc"}}',
+    ),
+    'iptables -S DOCKER-USER': ok(IPTABLES_GOOD),
+    [`docker image inspect ${IMAGE}`]: ok('[{}]'),
+    'df -Pk /var/lib/dormice': ok(DF_ROOMY),
+    [`docker run --rm --runtime=runsc ${IMAGE} uname -r`]:
+      ok('4.19.0-gvisor\n'),
+    [`docker run --rm --runtime=runsc ${IMAGE} bash -c timeout 3 bash -c "</dev/tcp/100.100.100.200/80" && echo LEAK || echo BLOCKED`]:
+      ok('BLOCKED\n'),
+    [`docker run --rm --runtime=runsc ${IMAGE} id -u`]: ok('1000\n'),
+    ...overrides.commands,
+  };
+  const calls: string[] = [];
+  return {
+    platform: overrides.platform ?? 'linux',
+    nodeVersion: overrides.nodeVersion ?? 'v24.18.0',
+    uid: overrides.uid ?? 0,
+    env: overrides.env ?? {
+      DORMICE_API_TOKEN: TOKEN,
+      DORMICE_EXECUTOR: 'docker',
+      DORMICE_BASE_IMAGE: IMAGE,
+      DORMICE_DB_PATH: '/var/lib/dormice/dormice.db',
+      DORMICE_DATA_DIR: '/var/lib/dormice',
+    },
+    calls,
+    run: async (cmd, args) => {
+      const key = [cmd, ...args].join(' ');
+      calls.push(key);
+      return commands[key] ?? boom(`fake host: no answer for "${key}"`);
+    },
+    readTextFile: async (path) => files[path],
+  };
+}
+
+const statusOf = (results: Record<string, CheckResult>, id: string) =>
+  results[id]?.status;
+
+describe('runDoctor on a healthy host', () => {
+  it('passes everything and declares the host ready', async () => {
+    const { results, report, failed } = await runDoctor(fakeHost());
+    expect(failed).toBe(false);
+    const statuses = new Set(
+      Object.values(results).map((result) => result.status),
+    );
+    expect(statuses).toEqual(new Set(['pass']));
+    expect(report).toContain('This host looks ready');
+  });
+
+  it('--quick skips the probes without starting any container', async () => {
+    const ctx = fakeHost();
+    const { results, failed } = await runDoctor(ctx, { quick: true });
+    expect(failed).toBe(false);
+    expect(statusOf(results, 'probe-gvisor')).toBe('skip');
+    expect(statusOf(results, 'probe-metadata')).toBe('skip');
+    expect(statusOf(results, 'probe-image-user')).toBe('skip');
+    expect(ctx.calls.filter((call) => call.includes('docker run'))).toEqual([]);
+  });
+});
+
+describe('platform gating', () => {
+  it('on macOS only the platform-independent checks run', async () => {
+    const { results, failed } = await runDoctor(
+      fakeHost({ platform: 'darwin' }),
+    );
+    expect(failed).toBe(true);
+    expect(statusOf(results, 'os-linux')).toBe('fail');
+    expect(statusOf(results, 'node-version')).toBe('pass');
+    expect(statusOf(results, 'api-token')).toBe('pass');
+    expect(statusOf(results, 'docker-daemon')).toBe('skip');
+    expect(statusOf(results, 'probe-gvisor')).toBe('skip');
+  });
+
+  it('without root, the iptables checks are skipped, not falsely red', async () => {
+    const { results } = await runDoctor(fakeHost({ uid: 1000 }));
+    expect(statusOf(results, 'root')).toBe('fail');
+    expect(statusOf(results, 'metadata-firewall')).toBe('skip');
+    expect(statusOf(results, 'metadata-persisted')).toBe('skip');
+  });
+});
+
+describe('freezing prerequisites', () => {
+  it('flags a wrong effective swappiness with the sysctl.d fix', async () => {
+    // The Alibaba Cloud factory setting: their own sysctl.d file ships 0.
+    const { results, report, failed } = await runDoctor(
+      fakeHost({ files: { '/proc/sys/vm/swappiness': '0\n' } }),
+    );
+    expect(failed).toBe(true);
+    expect(results.swappiness).toMatchObject({
+      status: 'fail',
+      fix: expect.stringContaining('99-dormice.conf'),
+    });
+    expect(report).toContain('effective value is 0');
+  });
+
+  it('flags a swapless host as a freezing failure', async () => {
+    const { results } = await runDoctor(
+      fakeHost({ files: { '/proc/meminfo': 'SwapTotal: 0 kB' } }),
+    );
+    expect(results.swap).toMatchObject({
+      status: 'fail',
+      detail: expect.stringContaining('nowhere to push'),
+    });
+  });
+});
+
+describe('docker configuration', () => {
+  it('a missing daemon.json fails both icc and log rotation', async () => {
+    const { results } = await runDoctor(
+      fakeHost({ files: { '/etc/docker/daemon.json': undefined } }),
+    );
+    expect(statusOf(results, 'icc-disabled')).toBe('fail');
+    expect(statusOf(results, 'log-rotation')).toBe('fail');
+  });
+
+  it('accepts the "local" log driver, which rotates by default', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        files: {
+          '/etc/docker/daemon.json': JSON.stringify({
+            icc: false,
+            'log-driver': 'local',
+          }),
+        },
+      }),
+    );
+    expect(statusOf(results, 'log-rotation')).toBe('pass');
+  });
+});
+
+describe('metadata firewall', () => {
+  it('names the exact missing DROP rule', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        commands: {
+          'iptables -S DOCKER-USER': ok(
+            '-N DOCKER-USER\n-A DOCKER-USER -d 169.254.0.0/16 -j DROP',
+          ),
+        },
+      }),
+    );
+    expect(results['metadata-firewall']).toMatchObject({
+      status: 'fail',
+      detail: expect.stringContaining('100.100.100.200'),
+    });
+  });
+
+  it('rules present but not persisted is a warning, not a failure', async () => {
+    const { results, failed } = await runDoctor(
+      fakeHost({ files: { '/etc/iptables/rules.v4': undefined } }),
+    );
+    expect(results['metadata-persisted']).toMatchObject({
+      status: 'warn',
+      fix: expect.stringContaining('iptables-persistent'),
+    });
+    // Warnings alone never flip the exit code.
+    expect(failed).toBe(false);
+  });
+});
+
+describe('daemon configuration', () => {
+  it('a missing token warns, a short token fails', async () => {
+    const unset = await runDoctor(
+      fakeHost({ env: { DORMICE_EXECUTOR: 'fake' } }),
+    );
+    expect(statusOf(unset.results, 'api-token')).toBe('warn');
+
+    const short = await runDoctor(
+      fakeHost({
+        env: { DORMICE_API_TOKEN: 'too-short', DORMICE_EXECUTOR: 'fake' },
+      }),
+    );
+    expect(short.results['api-token']).toMatchObject({
+      status: 'fail',
+      detail: expect.stringContaining('9 characters'),
+    });
+  });
+
+  it('docker mode with the default relative DB path fails ahead of the daemon', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        env: {
+          DORMICE_API_TOKEN: TOKEN,
+          DORMICE_EXECUTOR: 'docker',
+          DORMICE_BASE_IMAGE: IMAGE,
+          DORMICE_DATA_DIR: '/var/lib/dormice',
+          // DORMICE_DB_PATH unset: the default is relative.
+        },
+      }),
+    );
+    expect(results['absolute-paths']).toMatchObject({
+      status: 'fail',
+      detail: expect.stringContaining('DORMICE_DB_PATH=data/dormice.db'),
+    });
+  });
+
+  it('without a base image, image check and probes skip with directions', async () => {
+    const { results, failed } = await runDoctor(
+      fakeHost({ env: { DORMICE_API_TOKEN: TOKEN } }),
+    );
+    expect(results['base-image']).toMatchObject({
+      status: 'skip',
+      detail: expect.stringContaining('DORMICE_BASE_IMAGE'),
+    });
+    expect(statusOf(results, 'probe-gvisor')).toBe('skip');
+    expect(statusOf(results, 'absolute-paths')).toBe('skip');
+    expect(failed).toBe(false);
+  });
+
+  it('scarce disk space warns with the measured number', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        commands: {
+          'df -Pk /var/lib/dormice': ok(
+            'Filesystem 1024-blocks Used Available Capacity Mounted on\n' +
+              '/dev/vda3 200000000 195000000 5242880 98% /',
+          ),
+        },
+      }),
+    );
+    expect(results['disk-space']).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('5.0 GiB'),
+    });
+  });
+});
+
+describe('container probes', () => {
+  it('a real host kernel in the probe means gVisor is not isolating', async () => {
+    const { results, failed } = await runDoctor(
+      fakeHost({
+        commands: {
+          [`docker run --rm --runtime=runsc ${IMAGE} uname -r`]: ok(
+            '6.8.0-124-generic\n',
+          ),
+        },
+      }),
+    );
+    expect(failed).toBe(true);
+    expect(results['probe-gvisor']).toMatchObject({
+      status: 'fail',
+      detail: expect.stringContaining('6.8.0-124-generic'),
+    });
+  });
+
+  it('LEAK from the metadata probe is a hard failure with the iptables fix', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        commands: {
+          [`docker run --rm --runtime=runsc ${IMAGE} bash -c timeout 3 bash -c "</dev/tcp/100.100.100.200/80" && echo LEAK || echo BLOCKED`]:
+            ok('LEAK\n'),
+        },
+      }),
+    );
+    expect(results['probe-metadata']).toMatchObject({
+      status: 'fail',
+      fix: expect.stringContaining('DOCKER-USER'),
+    });
+  });
+
+  it('a root image fails the uid probe', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        commands: {
+          [`docker run --rm --runtime=runsc ${IMAGE} id -u`]: ok('0\n'),
+        },
+      }),
+    );
+    expect(results['probe-image-user']).toMatchObject({
+      status: 'fail',
+      detail: expect.stringContaining('uid 0'),
+    });
+  });
+});
diff --git a/packages/cli/src/doctor.ts b/packages/cli/src/doctor.ts
new file mode 100644
index 0000000..8f2d6a0
--- /dev/null
+++ b/packages/cli/src/doctor.ts
@@ -0,0 +1,576 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+
+/**
+ * `dor doctor` answers one question: can this host run the Dormice daemon?
+ *
+ * Every check below encodes a fact measured on a real machine (the pit
+ * list), not a hypothesis. Two disciplines:
+ *
+ * - Read-only. Doctor names the fix but never applies it — a checker that
+ *   quietly mutates the system is the "silent self-healing" the design
+ *   rules forbid. Fixing is install.sh's job.
+ * - Effective values over config files. The lesson: some clouds ship
+ *   vm.swappiness=0 in their own sysctl.d file, so "our config file
+ *   exists" proves nothing. Wherever the live value is readable, read it.
+ */
+
+export interface RunResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Everything a check may touch, injected so tests can fake a whole host.
+ * Same discipline as FakeExecutor: the fake is the permanent test double,
+ * the real machine is the final judge.
+ */
+export interface DoctorContext {
+  platform: string;
+  nodeVersion: string;
+  uid: number | undefined;
+  env: Record<string, string | undefined>;
+  run(
+    cmd: string,
+    args: string[],
+    opts?: { timeoutMs?: number },
+  ): Promise<RunResult>;
+  /** undefined when the file is missing or unreadable. */
+  readTextFile(path: string): Promise<string | undefined>;
+}
+
+export function realDoctorContext(): DoctorContext {
+  return {
+    platform: process.platform,
+    nodeVersion: process.version,
+    uid: process.getuid?.(),
+    env: process.env,
+    run: (cmd, args, opts) =>
+      new Promise((resolve) => {
+        execFile(
+          cmd,
+          args,
+          // SIGKILL on timeout: a hung dockerd must not hang doctor too.
+          {
+            timeout: opts?.timeoutMs ?? 10_000,
+            killSignal: 'SIGKILL',
+            maxBuffer: 1024 * 1024,
+          },
+          (error, stdout, stderr) => {
+            resolve({
+              ok: error === null,
+              stdout,
+              stderr: stderr || (error ? error.message : ''),
+            });
+          },
+        );
+      }),
+    readTextFile: async (path) => {
+      try {
+        return await readFile(path, 'utf8');
+      } catch {
+        return undefined;
+      }
+    },
+  };
+}
+
+export type CheckStatus = 'pass' | 'fail' | 'warn' | 'skip';
+
+export interface CheckResult {
+  status: CheckStatus;
+  detail: string;
+  fix?: string;
+}
+
+interface DoctorCheck {
+  id: string;
+  title: string;
+  /** Checks that must pass first; otherwise this one is skipped. */
+  needs?: string[];
+  /** Starts a real container — skipped by --quick. */
+  probe?: boolean;
+  run(ctx: DoctorContext): Promise<CheckResult>;
+}
+
+const pass = (detail: string): CheckResult => ({ status: 'pass', detail });
+const fail = (detail: string, fix?: string): CheckResult => ({
+  status: 'fail',
+  detail,
+  fix,
+});
+const warn = (detail: string, fix?: string): CheckResult => ({
+  status: 'warn',
+  detail,
+  fix,
+});
+const skip = (detail: string): CheckResult => ({ status: 'skip', detail });
+
+const DAEMON_JSON = '/etc/docker/daemon.json';
+const RULES_V4 = '/etc/iptables/rules.v4';
+const METADATA_IP = '100.100.100.200';
+const METADATA_RANGE = '169.254.0.0/16';
+
+async function daemonJson(
+  ctx: DoctorContext,
+): Promise<Record<string, unknown> | undefined> {
+  const text = await ctx.readTextFile(DAEMON_JSON);
+  if (text === undefined) return undefined;
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+const baseImage = (ctx: DoctorContext) => ctx.env.DORMICE_BASE_IMAGE;
+
+const CHECKS: DoctorCheck[] = [
+  {
+    id: 'os-linux',
+    title: 'operating system',
+    run: async (ctx) =>
+      ctx.platform === 'linux'
+        ? pass('Linux')
+        : fail(
+            `the daemon needs Linux (loop mounts, cgroups, gVisor) — found "${ctx.platform}"`,
+          ),
+  },
+  {
+    id: 'node-version',
+    title: 'Node.js version',
+    run: async (ctx) => {
+      const major = Number(ctx.nodeVersion.replace(/^v/, '').split('.')[0]);
+      return major >= 22
+        ? pass(`${ctx.nodeVersion} (>= 22)`)
+        : fail(`${ctx.nodeVersion} is below the required Node 22`);
+    },
+  },
+  {
+    id: 'root',
+    title: 'running as root',
+    needs: ['os-linux'],
+    run: async (ctx) =>
+      ctx.uid === 0
+        ? pass('uid 0')
+        : fail(
+            `running as uid ${ctx.uid ?? 'unknown'} — loop mounts, mkfs and cgroup writes need root`,
+            'run doctor and the daemon as root',
+          ),
+  },
+  {
+    id: 'cgroup-v2',
+    title: 'cgroup v2 memory controller',
+    needs: ['os-linux'],
+    run: async (ctx) => {
+      const controllers = await ctx.readTextFile(
+        '/sys/fs/cgroup/cgroup.controllers',
+      );
+      if (controllers === undefined) {
+        return fail(
+          'cgroup v2 unified hierarchy is not mounted — freezing needs memory.reclaim, a cgroup v2 file',
+          'boot with systemd.unified_cgroup_hierarchy=1 (default on Ubuntu 22.04+)',
+        );
+      }
+      return controllers.includes('memory')
+        ? pass('memory controller available')
+        : fail('cgroup v2 is mounted but the memory controller is missing');
+    },
+  },
+  {
+    id: 'docker-daemon',
+    title: 'Docker daemon',
+    needs: ['os-linux'],
+    run: async (ctx) => {
+      const res = await ctx.run('docker', [
+        'version',
+        '--format',
+        '{{.Server.Version}}',
+      ]);
+      return res.ok
+        ? pass(`server ${res.stdout.trim()}`)
+        : fail(
+            `dockerd is unreachable: ${res.stderr.trim()}`,
+            'install Docker and start dockerd (https://docs.docker.com/engine/install/)',
+          );
+    },
+  },
+  {
+    id: 'gvisor-runtime',
+    title: 'gVisor runtime (runsc)',
+    needs: ['docker-daemon'],
+    run: async (ctx) => {
+      const res = await ctx.run('docker', [
+        'info',
+        '--format',
+        '{{json .Runtimes}}',
+      ]);
+      if (!res.ok) return fail(`docker info failed: ${res.stderr.trim()}`);
+      return res.stdout.includes('"runsc"')
+        ? pass('runsc registered as a Docker runtime')
+        : fail(
+            'runsc is not a registered Docker runtime — sandboxes would share the host kernel',
+            'install gVisor, then `runsc install` and restart docker (https://gvisor.dev/docs/user_guide/install/)',
+          );
+    },
+  },
+  {
+    id: 'icc-disabled',
+    title: 'inter-container traffic off',
+    needs: ['os-linux'],
+    run: async (ctx) => {
+      const config = await daemonJson(ctx);
+      if (config === undefined) {
+        return fail(
+          `${DAEMON_JSON} is missing or not valid JSON — Docker defaults to icc: true, so one sandbox can scan another`,
+          `set "icc": false in ${DAEMON_JSON} and restart docker`,
+        );
+      }
+      return config.icc === false
+        ? pass(`"icc": false in ${DAEMON_JSON}`)
+        : fail(
+            `"icc" is not false in ${DAEMON_JSON} — one sandbox can scan another`,
+            `set "icc": false in ${DAEMON_JSON} and restart docker`,
+          );
+    },
+  },
+  {
+    id: 'log-rotation',
+    title: 'container log rotation',
+    needs: ['os-linux'],
+    run: async (ctx) => {
+      const config = await daemonJson(ctx);
+      const logOpts = config?.['log-opts'] as
+        | Record<string, unknown>
+        | undefined;
+      // The "local" driver rotates by default; json-file needs max-size.
+      if (config?.['log-driver'] === 'local' || logOpts?.['max-size']) {
+        return pass(
+          logOpts?.['max-size']
+            ? `max-size ${logOpts['max-size']}`
+            : 'log-driver "local" rotates by default',
+        );
+      }
+      return fail(
+        'container stdout logs grow without bound — a long-lived sandbox fills the disk over months',
+        `set "log-driver": "json-file", "log-opts": {"max-size": "10m", "max-file": "3"} in ${DAEMON_JSON} and restart docker`,
+      );
+    },
+  },
+  {
+    id: 'swap',
+    title: 'swap present',
+    needs: ['os-linux'],
+    run: async (ctx) => {
+      const meminfo = (await ctx.readTextFile('/proc/meminfo')) ?? '';
+      const kb = Number(/^SwapTotal:\s*(\d+) kB/m.exec(meminfo)?.[1] ?? 0);
+      return kb > 0
+        ? pass(`${(kb / 1024 / 1024).toFixed(1)} GiB`)
+        : fail(
+            'no swap — freezing has nowhere to push sandbox memory (measured: 0 bytes reclaimed without it)',
+            "fallocate -l 16G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile, then add '/swapfile none swap sw 0 0' to /etc/fstab",
+          );
+    },
+  },
+  {
+    id: 'swappiness',
+    title: 'vm.swappiness = 100',
+    needs: ['os-linux'],
+    run: async (ctx) => {
+      // The live value, on purpose: some clouds ship swappiness=0 in their
+      // own sysctl.d file, so a config file existing proves nothing.
+      const raw = await ctx.readTextFile('/proc/sys/vm/swappiness');
+      const value = raw?.trim();
+      if (value === undefined)
+        return fail('cannot read /proc/sys/vm/swappiness');
+      return value === '100'
+        ? pass('100 (effective value)')
+        : fail(
+            `effective value is ${value} — below 100 the kernel refuses to swap gVisor's shmem-held sandbox memory (measured at 60: 0 bytes reclaimed)`,
+            "echo 'vm.swappiness=100' > /etc/sysctl.d/99-dormice.conf && sysctl --system",
+          );
+    },
+  },
+  {
+    id: 'metadata-firewall',
+    title: 'cloud metadata firewall',
+    needs: ['root', 'docker-daemon'],
+    run: async (ctx) => {
+      const res = await ctx.run('iptables', ['-S', 'DOCKER-USER']);
+      if (!res.ok) {
+        return fail(`cannot read the DOCKER-USER chain: ${res.stderr.trim()}`);
+      }
+      const dropped = (needle: string) =>
+        res.stdout
+          .split('\n')
+          .some(
+            (line) => line.includes(`-d ${needle}`) && line.includes('-j DROP'),
+          );
+      const missing = [
+        !dropped(METADATA_RANGE) && METADATA_RANGE,
+        !dropped(METADATA_IP) && !dropped(`${METADATA_IP}/32`) && METADATA_IP,
+      ].filter(Boolean);
+      return missing.length === 0
+        ? pass(`DROP rules for ${METADATA_RANGE} and ${METADATA_IP}`)
+        : fail(
+            `no DROP rule for ${missing.join(' or ')} — a sandbox can steal cloud credentials from the metadata service`,
+            `iptables -I DOCKER-USER -d ${METADATA_RANGE} -j DROP && iptables -I DOCKER-USER -d ${METADATA_IP} -j DROP`,
+          );
+    },
+  },
+  {
+    id: 'metadata-persisted',
+    title: 'firewall rules persisted',
+    needs: ['metadata-firewall'],
+    run: async (ctx) => {
+      const rules = await ctx.readTextFile(RULES_V4);
+      return rules?.includes(METADATA_IP) && rules.includes('169.254')
+        ? pass(`both rules in ${RULES_V4}`)
+        : warn(
+            'the DROP rules live only in memory — a reboot silently drops them',
+            'apt-get install -y iptables-persistent && netfilter-persistent save',
+          );
+    },
+  },
+  {
+    id: 'api-token',
+    title: 'DORMICE_API_TOKEN',
+    run: async (ctx) => {
+      const token = ctx.env.DORMICE_API_TOKEN;
+      if (token === undefined || token === '') {
+        return warn(
+          'not set in this shell — the daemon refuses to start without it',
+          'export DORMICE_API_TOKEN=$(openssl rand -hex 32)',
+        );
+      }
+      return token.length >= 32
+        ? pass(`set (${token.length} characters)`)
+        : fail(
+            `set but only ${token.length} characters — the daemon requires at least 32`,
+            'export DORMICE_API_TOKEN=$(openssl rand -hex 32)',
+          );
+    },
+  },
+  {
+    id: 'base-image',
+    title: 'base image available',
+    needs: ['docker-daemon'],
+    run: async (ctx) => {
+      const image = baseImage(ctx);
+      if (!image) {
+        return skip(
+          'DORMICE_BASE_IMAGE is not set — set it to check the image and enable the container probes',
+        );
+      }
+      const res = await ctx.run('docker', ['image', 'inspect', image]);
+      return res.ok
+        ? pass(`${image} is present locally`)
+        : fail(
+            `${image} is not present locally`,
+            'build it from images/Dockerfile — doctor never pulls images itself',
+          );
+    },
+  },
+  {
+    id: 'absolute-paths',
+    title: 'docker-mode paths absolute',
+    run: async (ctx) => {
+      if (ctx.env.DORMICE_EXECUTOR !== 'docker') {
+        return skip('DORMICE_EXECUTOR is not "docker"');
+      }
+      // Same resolution the daemon does: unset falls back to the default,
+      // and the default DB path is relative — which docker mode refuses.
+      const paths = {
+        DORMICE_DB_PATH: ctx.env.DORMICE_DB_PATH ?? 'data/dormice.db',
+        DORMICE_DATA_DIR: ctx.env.DORMICE_DATA_DIR ?? '/var/lib/dormice',
+      };
+      const relative = Object.entries(paths)
+        .filter(([, value]) => !isAbsolute(value))
+        .map(([name, value]) => `${name}=${value}`);
+      return relative.length === 0
+        ? pass('DORMICE_DB_PATH and DORMICE_DATA_DIR are absolute')
+        : fail(
+            `${relative.join(', ')} — a relative path depends on the start directory, and a wrong start directory opens an empty ledger next to real sandboxes`,
+            'export DORMICE_DB_PATH=/var/lib/dormice/dormice.db (or another absolute path)',
+          );
+    },
+  },
+  {
+    id: 'disk-space',
+    title: 'free disk space',
+    needs: ['os-linux'],
+    run: async (ctx) => {
+      const dir = ctx.env.DORMICE_DATA_DIR ?? '/var/lib/dormice';
+      let res = await ctx.run('df', ['-Pk', dir]);
+      let note = '';
+      if (!res.ok) {
+        // The data dir may not exist before the first daemon start; the
+        // root filesystem is the honest stand-in.
+        res = await ctx.run('df', ['-Pk', '/']);
+        note = ` (${dir} does not exist yet; measured /)`;
+      }
+      const kb = Number(res.stdout.trim().split('\n').at(-1)?.split(/\s+/)[3]);
+      if (!res.ok || Number.isNaN(kb)) {
+        return warn(`cannot measure free space: ${res.stderr.trim()}`);
+      }
+      const gib = kb / 1024 / 1024;
+      return gib >= 10
+        ? pass(`${gib.toFixed(1)} GiB free for ${dir}${note}`)
+        : warn(
+            `only ${gib.toFixed(1)} GiB free for ${dir}${note} — a full disk means even the ledger cannot write`,
+          );
+    },
+  },
+  {
+    id: 'probe-gvisor',
+    title: 'probe: gVisor fake kernel',
+    needs: ['gvisor-runtime', 'base-image'],
+    probe: true,
+    run: async (ctx) => {
+      const image = baseImage(ctx) as string;
+      const res = await ctx.run(
+        'docker',
+        ['run', '--rm', '--runtime=runsc', image, 'uname', '-r'],
+        { timeoutMs: 60_000 },
+      );
+      if (!res.ok)
+        return fail(`the probe container failed: ${res.stderr.trim()}`);
+      const kernel = res.stdout.trim();
+      return kernel.includes('gvisor')
+        ? pass(`sandbox kernel: ${kernel}`)
+        : fail(
+            `sandbox reports kernel "${kernel}" — that is a real kernel, gVisor is not isolating`,
+            'reinstall gVisor (`runsc install`) and restart docker',
+          );
+    },
+  },
+  {
+    id: 'probe-metadata',
+    title: 'probe: metadata blocked inside',
+    needs: ['gvisor-runtime', 'base-image'],
+    probe: true,
+    run: async (ctx) => {
+      const res = await ctx.run(
+        'docker',
+        [
+          'run',
+          '--rm',
+          '--runtime=runsc',
+          baseImage(ctx) as string,
+          'bash',
+          '-c',
+          `timeout 3 bash -c "</dev/tcp/${METADATA_IP}/80" && echo LEAK || echo BLOCKED`,
+        ],
+        { timeoutMs: 60_000 },
+      );
+      if (res.stdout.includes('BLOCKED')) {
+        return pass('metadata service unreachable from inside a sandbox');
+      }
+      if (res.stdout.includes('LEAK')) {
+        return fail(
+          `a sandbox reached ${METADATA_IP} — cloud credentials are stealable`,
+          `iptables -I DOCKER-USER -d ${METADATA_RANGE} -j DROP && iptables -I DOCKER-USER -d ${METADATA_IP} -j DROP`,
+        );
+      }
+      return fail(`the probe container failed: ${res.stderr.trim()}`);
+    },
+  },
+  {
+    id: 'probe-image-user',
+    title: 'probe: image runs as uid 1000',
+    needs: ['gvisor-runtime', 'base-image'],
+    probe: true,
+    run: async (ctx) => {
+      const res = await ctx.run(
+        'docker',
+        [
+          'run',
+          '--rm',
+          '--runtime=runsc',
+          baseImage(ctx) as string,
+          'id',
+          '-u',
+        ],
+        { timeoutMs: 60_000 },
+      );
+      if (!res.ok)
+        return fail(`the probe container failed: ${res.stderr.trim()}`);
+      const uid = res.stdout.trim();
+      return uid === '1000'
+        ? pass('uid 1000 (non-root)')
+        : fail(
+            `the image runs as uid ${uid} — sandboxes must run as a non-root uid-1000 user`,
+            'rebuild the image with a uid-1000 user (see images/Dockerfile)',
+          );
+    },
+  },
+];
+
+const ICONS: Record<CheckStatus, string> = {
+  pass: '✔',
+  fail: '✖',
+  warn: '⚠',
+  skip: '·',
+};
+
+export interface DoctorReport {
+  results: Record<string, CheckResult>;
+  report: string;
+  failed: boolean;
+}
+
+export async function runDoctor(
+  ctx: DoctorContext,
+  opts: { quick?: boolean } = {},
+): Promise<DoctorReport> {
+  const results: Record<string, CheckResult> = {};
+  const titles: Record<string, string> = {};
+  for (const check of CHECKS) titles[check.id] = check.title;
+
+  for (const check of CHECKS) {
+    if (opts.quick && check.probe) {
+      results[check.id] = skip('container probes skipped (--quick)');
+      continue;
+    }
+    const blocker = check.needs?.find((id) => results[id]?.status !== 'pass');
+    if (blocker !== undefined) {
+      results[check.id] = skip(`needs "${titles[blocker]}" to pass first`);
+      continue;
+    }
+    results[check.id] = await check.run(ctx);
+  }
+
+  const width = Math.max(...CHECKS.map((check) => check.title.length));
+  const lines = [
+    'Dormice doctor — can this host run the daemon? (read-only, fixes are named, never applied)',
+    '',
+  ];
+  for (const check of CHECKS) {
+    const result = results[check.id] as CheckResult;
+    lines.push(
+      `${ICONS[result.status]} ${check.title.padEnd(width)}  ${result.detail}`,
+    );
+    if (result.fix && result.status !== 'pass') {
+      lines.push(`  ${' '.repeat(width)}  fix: ${result.fix}`);
+    }
+  }
+
+  const count = (status: CheckStatus) =>
+    Object.values(results).filter((result) => result.status === status).length;
+  const failed = count('fail') > 0;
+  lines.push(
+    '',
+    `${count('pass')} passed, ${count('fail')} failed, ${count('warn')} warnings, ${count('skip')} skipped.`,
+  );
+  lines.push(
+    failed
+      ? 'Not ready — fix the ✖ items above and run doctor again.'
+      : count('warn') > 0
+        ? 'No failures — review the ⚠ items above.'
+        : 'This host looks ready to run the Dormice daemon.',
+  );
+
+  return { results, report: lines.join('\n'), failed };
+}
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index be41fd0..6375798 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -15,11 +15,24 @@ import {
   sandboxPush,
   sandboxRelease,
 } from './commands';
+import { realDoctorContext, runDoctor } from './doctor';
 
 const program = new Command('dor').description(
   'Command-line tool for a Dormice daemon (also installed as `dormice`)',
 );
 
+program
+  .command('doctor')
+  .description('Check whether this host can run the Dormice daemon (read-only)')
+  .option('--quick', 'skip the probes that start a real sandbox container')
+  .action(async (opts: { quick?: boolean }) => {
+    const { report, failed } = await runDoctor(realDoctorContext(), {
+      quick: opts.quick,
+    });
+    console.log(report);
+    if (failed) process.exitCode = 1;
+  });
+
 const sandbox = program
   .command('sandbox')
   .description('Inspect and manage sandboxes');

From 21105f78e7bbf90084b8489ede399c9828da9d28 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 21:22:16 +0800
Subject: [PATCH 011/133] install.sh turns a bare host into a running daemon,
 doctor has the last word

deploy/install.sh automates every fix doctor names: pinned Node and
gVisor (sha512 of the binaries, not the sidecar files), Docker with
daemon.json merged key by key, swap and swappiness=100, the metadata
DROP rules persisted, code cloned to /opt/dormice and built, the base
image, /etc/dormice/env with a generated token that re-runs never
rotate, and a crash-only systemd unit. Every step checks before it
acts, so a re-run is an upgrade. The install only succeeds if the
daemon answers /healthz and dor doctor exits green. CI now shellchecks
the one script users pipe into bash.
---
 .github/workflows/ci.yml |   3 +
 README.md                |  23 ++-
 deploy/dormice.service   |  21 +++
 deploy/install.sh        | 355 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 398 insertions(+), 4 deletions(-)
 create mode 100644 deploy/dormice.service
 create mode 100644 deploy/install.sh

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 50f83dc..6c01dfc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -45,6 +45,9 @@ jobs:
       - run: pnpm build
       - run: pnpm typecheck
       - run: pnpm lint
+      # The installer is the one shell script users pipe into bash — it gets
+      # the same static gate the TypeScript gets from Biome.
+      - run: shellcheck deploy/install.sh
       - run: pnpm test
 
   # This is a public repository: a leaked credential anywhere in git history
diff --git a/README.md b/README.md
index b09cc13..059f5b5 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 **The SQLite of agent sandboxes** — a self-hosted sandbox platform for AI agents. One machine, sandboxes that live forever, idle costs nothing.
 
-> **Status: early development.** The daemon, its lifecycle engine, the SDK, and the real Docker + gVisor executor work end to end — the full create → freeze → stop → wake cycle passes on real infrastructure. Running code inside a sandbox and the E2B-compatible API are the next milestones. Nothing here is ready for production yet.
+> **Status: early development.** The daemon, its lifecycle engine, the SDK, the CLI, the real Docker + gVisor executor, and the E2B-compatible API work end to end — the full create → freeze → stop → wake cycle, command execution, file I/O, and the official `e2b` SDK against real infrastructure. Nothing here is ready for production yet.
 
 ## The idea
 
@@ -11,14 +11,29 @@ Cloud sandbox platforms charge for every second a sandbox exists, so their sandb
 - **`acquireSandbox(userKey)` is the entire mental model.** Idempotent: the same key always comes back to the same sandbox, whatever state it was in. No sandbox → create; frozen → wake; stopped → start; archived → restore.
 - **Idle is free.** Sandboxes cool down on their own — `active → frozen → stopped → archived` — one rung at a time, and any acquire brings them back.
 - **Deploys like a single binary.** One daemon, one SQLite ledger, one port. No Kubernetes, no external database.
-- **E2B compatibility is on the roadmap**: the goal is that the official `e2b` SDK works against Dormice by changing two URLs.
+- **E2B compatible**: the official `e2b` SDK works against Dormice by changing two URLs (`apiUrl`, `sandboxUrl`).
+
+## Install
+
+One command on a bare Ubuntu/Debian x86_64 host (as root):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash
+```
+
+Behind a slow connection to the usual sources, add `-s -- --mirror cn`.
+The installer is idempotent — re-running it upgrades the code and repairs
+drift, and never rotates your API token. It ends by running `dor doctor`,
+19 read-only checks (including three that boot a real gVisor container)
+that decide whether the install actually succeeded; `dor doctor` can be
+re-run on its own at any time.
 
 ## Host prerequisites (docker executor)
 
 The daemon itself runs anywhere Node 22+ runs, with an in-memory fake
 executor for development. Running **real** sandboxes needs a Linux host
-prepared ahead of time — an `install.sh` and a `dor doctor` will automate
-these checks later, but today they are the operator's job:
+prepared as above — `install.sh` automates all of it and `dor doctor`
+verifies it, but these are the facts underneath:
 
 - **Docker + gVisor (`runsc`)**, and root (loop mounts, cgroup writes).
 - **Swap, and `vm.swappiness=100`.** Freezing squeezes an idle sandbox's
diff --git a/deploy/dormice.service b/deploy/dormice.service
new file mode 100644
index 0000000..5dd8225
--- /dev/null
+++ b/deploy/dormice.service
@@ -0,0 +1,21 @@
+# Dormice daemon. Installed by deploy/install.sh; configuration lives in
+# /etc/dormice/env (full-line comments only there — systemd's EnvironmentFile
+# treats an inline comment as part of the value).
+[Unit]
+Description=Dormice daemon (agent sandbox control plane)
+Wants=network-online.target
+After=network-online.target docker.service
+Requires=docker.service
+
+[Service]
+ExecStart=/usr/local/bin/node /opt/dormice/packages/server/dist/main.js
+EnvironmentFile=/etc/dormice/env
+# Crash-only: the daemon reconciles its ledger against Docker on every start,
+# so restarting it is always safe — and always the right move.
+Restart=always
+RestartSec=3
+# One process, one writer. The SQLite ledger's exclusive lock enforces this;
+# never wrap the daemon in a process manager that forks workers.
+
+[Install]
+WantedBy=multi-user.target
diff --git a/deploy/install.sh b/deploy/install.sh
new file mode 100644
index 0000000..ebfa3d3
--- /dev/null
+++ b/deploy/install.sh
@@ -0,0 +1,355 @@
+#!/usr/bin/env bash
+# Dormice installer: turns a bare Ubuntu/Debian x86_64 host into a running
+# Dormice daemon, then proves it by running `dor doctor`.
+#
+#   curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash
+#
+# Flags (pass after `bash -s --` when piping):
+#   --mirror cn     use mainland-China mirrors for every download
+#   --swap-gb N     size of the swapfile to create when the host has no swap
+#                   (default 16 — the configuration freezing was measured on)
+#
+# Three promises, mirroring `dor doctor`:
+#   - Idempotent. Every step checks before it acts; a step whose outcome is
+#     already in place says [skip] and touches nothing. Re-running upgrades
+#     the code and repairs drift, and never rotates your API token.
+#   - Loud. Every step prints what it found and what it did.
+#   - Verified. The install has not succeeded until `dor doctor` says so —
+#     the same 19 checks, including the three real-container probes.
+set -euo pipefail
+export DEBIAN_FRONTEND=noninteractive
+
+# ---- pinned versions -------------------------------------------------------
+# The Node version and checksum must match images/Dockerfile: the host and
+# the sandboxes run the same interpreter, verified against the same official
+# SHASUMS256.txt, so a poisoned mirror cannot slip a different tarball in.
+NODE_VERSION=v24.18.0
+NODE_SHA256=55aa7153f9d88f28d765fcdad5ae6945b5c0f98a36881703817e4c450fa76742
+# gVisor is pinned to the release proven on real hardware, with checksums of
+# the binaries themselves — the .sha512 files published next to the binaries
+# only guard transit, not a poisoned origin.
+GVISOR_RELEASE=release-20260622.0
+RUNSC_SHA512=6df95d09363dbd9ee5d5c889c1549b457e1783b039ff60a8f9f16f8c94c774a2ca2eef5b1c370e36b863f6b0407b53ba3c69051c6ef051253843dabf89a6de4e
+SHIM_SHA512=87c63197836574b7a2c057d2c0647d2badb679187f0b9175ecf78ac52207cdaa3f101629d3e5d165c95930ca35fe81bc26bb90fcf08e09b99c2ee047b6235ce2
+
+REPO_URL=https://github.com/BitMiracle-AI/Dormice.git
+INSTALL_DIR=/opt/dormice
+ENV_FILE=/etc/dormice/env
+DATA_DIR=/var/lib/dormice
+DAEMON_JSON=/etc/docker/daemon.json
+PORT=3676
+
+# ---- flags -----------------------------------------------------------------
+MIRROR=''
+SWAP_GB=16
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --mirror) MIRROR="${2:?--mirror needs a value}"; shift 2 ;;
+    --mirror=*) MIRROR="${1#*=}"; shift ;;
+    --swap-gb) SWAP_GB="${2:?--swap-gb needs a value}"; shift 2 ;;
+    --swap-gb=*) SWAP_GB="${1#*=}"; shift ;;
+    *) echo "install.sh: unknown flag $1 (known: --mirror cn, --swap-gb N)" >&2; exit 1 ;;
+  esac
+done
+if [ -n "$MIRROR" ] && [ "$MIRROR" != cn ]; then
+  echo "install.sh: --mirror only knows \"cn\", got \"$MIRROR\"" >&2
+  exit 1
+fi
+
+log()  { printf '\n==> %s\n' "$*"; }
+note() { printf '    %s\n' "$*"; }
+die()  { printf '\ninstall.sh: %s\n' "$*" >&2; exit 1; }
+
+# ---- preflight: the facts install.sh cannot fix ----------------------------
+log 'preflight'
+[ "$(uname -s)" = Linux ] || die "the daemon needs Linux (loop mounts, cgroups, gVisor) — found $(uname -s)"
+[ "$(uname -m)" = x86_64 ] || die "the pinned Node and gVisor binaries are x86_64 — found $(uname -m)"
+[ "$(id -u)" = 0 ] || die 'run as root — loop mounts, mkfs and cgroup writes need it'
+command -v apt-get >/dev/null || die 'this installer knows apt-based distros (Ubuntu/Debian) only'
+grep -qw memory /sys/fs/cgroup/cgroup.controllers 2>/dev/null \
+  || die 'cgroup v2 with the memory controller is required (default on Ubuntu 22.04+) — freezing writes memory.reclaim'
+note "Linux x86_64, root, cgroup v2 — ok"
+
+# ---- base packages ---------------------------------------------------------
+log 'base packages (git, curl, openssl)'
+missing=''
+for tool in git curl openssl; do
+  command -v "$tool" >/dev/null || missing="$missing $tool"
+done
+if [ -n "$missing" ]; then
+  apt-get update -q
+  # shellcheck disable=SC2086 # word splitting is the point
+  apt-get install -qy ca-certificates $missing
+  note "installed:$missing"
+else
+  note '[skip] all present'
+fi
+
+# ---- Node ------------------------------------------------------------------
+log "Node.js $NODE_VERSION"
+if command -v node >/dev/null && [ "$(node -p 'process.version.slice(1).split(".")[0]')" -ge 22 ]; then
+  note "[skip] $(node --version) already satisfies >= 22"
+else
+  node_dist=https://nodejs.org/dist
+  [ "$MIRROR" = cn ] && node_dist=https://npmmirror.com/mirrors/node
+  tarball="node-$NODE_VERSION-linux-x64.tar.xz"
+  curl -fsSL -o "/tmp/$tarball" "$node_dist/$NODE_VERSION/$tarball"
+  echo "$NODE_SHA256  /tmp/$tarball" | sha256sum -c - >/dev/null
+  tar -xJf "/tmp/$tarball" -C /opt && rm "/tmp/$tarball"
+  for b in node npm npx corepack; do
+    ln -sf "/opt/node-$NODE_VERSION-linux-x64/bin/$b" "/usr/local/bin/$b"
+  done
+  note "installed $(node --version) to /opt, linked into /usr/local/bin"
+fi
+
+# ---- Docker ----------------------------------------------------------------
+log 'Docker'
+if docker version --format '{{.Server.Version}}' >/dev/null 2>&1; then
+  note "[skip] dockerd $(docker version --format '{{.Server.Version}}') is running"
+else
+  curl -fsSL -o /tmp/get-docker.sh https://get.docker.com
+  if [ "$MIRROR" = cn ]; then
+    sh /tmp/get-docker.sh --mirror Aliyun
+  else
+    sh /tmp/get-docker.sh
+  fi
+  rm /tmp/get-docker.sh
+  systemctl enable --now docker
+  note "installed dockerd $(docker version --format '{{.Server.Version}}')"
+fi
+
+# ---- daemon.json: icc off + log rotation -----------------------------------
+# Merged key by key, never overwritten: the operator's registry mirrors and
+# whatever `runsc install` wrote must survive. A daemon.json that exists but
+# is not valid JSON is the operator's to fix — guessing would destroy it.
+log 'Docker daemon.json (icc: false, log rotation)'
+if [ -f "$DAEMON_JSON" ] && ! node -e "JSON.parse(require('fs').readFileSync('$DAEMON_JSON','utf8'))" 2>/dev/null; then
+  die "$DAEMON_JSON exists but is not valid JSON — fix it by hand, then re-run"
+fi
+mkdir -p /etc/docker
+daemon_json_result=$(node - "$DAEMON_JSON" <<'EOF'
+const fs = require('fs');
+const path = process.argv[2];
+let config = {};
+try { config = JSON.parse(fs.readFileSync(path, 'utf8')); } catch {}
+const before = JSON.stringify(config);
+config.icc = false;
+const rotates = config['log-driver'] === 'local' || config['log-opts']?.['max-size'];
+if (!rotates) {
+  config['log-driver'] = 'json-file';
+  config['log-opts'] = { ...config['log-opts'], 'max-size': '10m', 'max-file': '3' };
+}
+if (JSON.stringify(config) === before) { console.log('unchanged'); process.exit(0); }
+fs.writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
+console.log('changed');
+EOF
+)
+if [ "$daemon_json_result" = changed ]; then
+  note "updated $DAEMON_JSON — restarting docker (this stops running containers)"
+  systemctl restart docker
+else
+  note '[skip] already configured'
+fi
+
+# ---- gVisor ----------------------------------------------------------------
+log "gVisor ($GVISOR_RELEASE)"
+if docker info --format '{{json .Runtimes}}' | grep -q '"runsc"'; then
+  note "[skip] runsc is a registered Docker runtime ($(runsc --version | head -1))"
+else
+  if [ ! -x /usr/local/bin/runsc ]; then
+    gvisor_url="https://storage.googleapis.com/gvisor/releases/release/$GVISOR_RELEASE/x86_64"
+    for bin in runsc containerd-shim-runsc-v1; do
+      curl -fsSL -o "/tmp/$bin" "$gvisor_url/$bin" || die "cannot download $bin from $gvisor_url —
+    if this host cannot reach storage.googleapis.com, download runsc and
+    containerd-shim-runsc-v1 ($GVISOR_RELEASE, x86_64) on a machine that can,
+    copy them to /usr/local/bin/ here, then re-run this script: it verifies
+    their checksums and continues from where it left off"
+    done
+    echo "$RUNSC_SHA512  /tmp/runsc" | sha512sum -c - >/dev/null
+    echo "$SHIM_SHA512  /tmp/containerd-shim-runsc-v1" | sha512sum -c - >/dev/null
+    chmod a+rx /tmp/runsc /tmp/containerd-shim-runsc-v1
+    mv /tmp/runsc /tmp/containerd-shim-runsc-v1 /usr/local/bin/
+  fi
+  echo "$RUNSC_SHA512  /usr/local/bin/runsc" | sha512sum -c - >/dev/null \
+    || die "/usr/local/bin/runsc does not match the pinned $GVISOR_RELEASE checksum"
+  /usr/local/bin/runsc install
+  systemctl restart docker
+  note "installed $(runsc --version | head -1), registered with Docker"
+fi
+
+# ---- swap ------------------------------------------------------------------
+# Freezing squeezes sandbox memory out to swap; without swap the measured
+# result is 0 bytes reclaimed. The swapfile goes on the root filesystem.
+log 'swap'
+swap_kb=$(awk '/^SwapTotal:/ {print $2}' /proc/meminfo)
+if [ "$swap_kb" -gt 0 ]; then
+  note "[skip] $((swap_kb / 1024 / 1024)) GiB of swap already present"
+else
+  fallocate -l "${SWAP_GB}G" /swapfile
+  chmod 600 /swapfile
+  mkswap /swapfile >/dev/null
+  swapon /swapfile
+  echo '/swapfile none swap sw 0 0' >>/etc/fstab
+  note "created a ${SWAP_GB} GiB /swapfile, persisted in /etc/fstab"
+fi
+
+# ---- vm.swappiness = 100 ----------------------------------------------------
+# gVisor holds sandbox memory as shared memory, which the kernel refuses to
+# swap below swappiness 100 (measured at 60: 0 bytes reclaimed). The file is
+# named to sort after cloud-vendor sysctl.d files that ship swappiness=0.
+log 'vm.swappiness = 100'
+if [ "$(cat /proc/sys/vm/swappiness)" = 100 ]; then
+  note '[skip] effective value is already 100'
+else
+  echo 'vm.swappiness=100' >/etc/sysctl.d/99-dormice.conf
+  sysctl --system >/dev/null
+  [ "$(cat /proc/sys/vm/swappiness)" = 100 ] \
+    || die 'wrote /etc/sysctl.d/99-dormice.conf but the effective value still is not 100 — something later in sysctl order overrides it'
+  note 'set via /etc/sysctl.d/99-dormice.conf (survives reboot)'
+fi
+
+# ---- cloud metadata firewall -------------------------------------------------
+# Sandboxes run untrusted code; on a cloud host with an attached role, one
+# curl to the metadata service steals live credentials. gVisor blocks kernel
+# attack surface, not network reachability — this must be firewalled.
+log 'cloud metadata firewall (DOCKER-USER chain)'
+docker_user=$(iptables -S DOCKER-USER 2>/dev/null) \
+  || die 'the DOCKER-USER chain is missing — is dockerd running?'
+added=''
+for target in 169.254.0.0/16 100.100.100.200; do
+  if ! printf '%s\n' "$docker_user" | grep -q -- "-d ${target%/*}\(/[0-9]*\)\? .*-j DROP"; then
+    iptables -I DOCKER-USER -d "$target" -j DROP
+    added="$added $target"
+  fi
+done
+if [ -n "$added" ]; then note "added DROP rules:$added"; else note '[skip] both DROP rules present'; fi
+if ! grep -qs 100.100.100.200 /etc/iptables/rules.v4; then
+  # Preseeded so apt never prompts; the explicit save below is what persists.
+  echo 'iptables-persistent iptables-persistent/autosave_v4 boolean true' | debconf-set-selections
+  echo 'iptables-persistent iptables-persistent/autosave_v6 boolean true' | debconf-set-selections
+  command -v netfilter-persistent >/dev/null || { apt-get update -q; apt-get install -qy iptables-persistent; }
+  netfilter-persistent save >/dev/null 2>&1
+  note 'persisted to /etc/iptables/rules.v4 (survives reboot)'
+else
+  note '[skip] rules already persisted'
+fi
+
+# ---- Dormice code -----------------------------------------------------------
+log "Dormice code ($INSTALL_DIR)"
+clone_url=$REPO_URL
+[ "$MIRROR" = cn ] && clone_url="https://ghfast.top/$REPO_URL"
+if [ -d "$INSTALL_DIR/.git" ]; then
+  git -C "$INSTALL_DIR" pull --ff-only -q
+  note "updated to $(git -C "$INSTALL_DIR" log --oneline -1)"
+else
+  git clone -q "$clone_url" "$INSTALL_DIR"
+  note "cloned $(git -C "$INSTALL_DIR" log --oneline -1)"
+fi
+
+log 'build'
+pnpm_version=$(node -p "require('$INSTALL_DIR/package.json').packageManager.split('@')[1]")
+if ! command -v pnpm >/dev/null || [ "$(pnpm --version)" != "$pnpm_version" ]; then
+  if [ "$MIRROR" = cn ]; then
+    npm install -g "pnpm@$pnpm_version" --registry=https://registry.npmmirror.com >/dev/null
+  else
+    npm install -g "pnpm@$pnpm_version" >/dev/null
+  fi
+  # npm -g installs into the active Node's prefix; when that is our /opt
+  # Node, the binary needs a link onto PATH.
+  if [ -x "/opt/node-$NODE_VERSION-linux-x64/bin/pnpm" ]; then
+    ln -sf "/opt/node-$NODE_VERSION-linux-x64/bin/pnpm" /usr/local/bin/pnpm
+  fi
+fi
+cd "$INSTALL_DIR"
+if [ "$MIRROR" = cn ]; then
+  npm_config_registry=https://registry.npmmirror.com pnpm install --frozen-lockfile
+else
+  pnpm install --frozen-lockfile
+fi
+pnpm build
+ln -sf "$INSTALL_DIR/packages/cli/dist/main.js" /usr/local/bin/dormice
+ln -sf "$INSTALL_DIR/packages/cli/dist/main.js" /usr/local/bin/dor
+note "built; \`dormice\` and \`dor\` linked into /usr/local/bin"
+
+# ---- sandbox base image ------------------------------------------------------
+log 'sandbox base image'
+existing_image=''
+[ -f "$ENV_FILE" ] && existing_image=$(sed -n 's/^DORMICE_BASE_IMAGE=//p' "$ENV_FILE")
+if [ -n "$existing_image" ] && docker image inspect "$existing_image" >/dev/null 2>&1; then
+  base_image=$existing_image
+  note "[skip] $base_image (from $ENV_FILE) is present"
+else
+  base_image="dormice-base:$(date +%Y%m%d)"
+  if [ "$MIRROR" = cn ] && ! docker image inspect ubuntu:24.04 >/dev/null 2>&1; then
+    # Personal registry mirrors in mainland China often proxy only an image
+    # whitelist; daocloud + retag is the measured workaround.
+    docker pull -q docker.m.daocloud.io/library/ubuntu:24.04
+    docker tag docker.m.daocloud.io/library/ubuntu:24.04 ubuntu:24.04
+    docker rmi -f docker.m.daocloud.io/library/ubuntu:24.04 >/dev/null
+  fi
+  if [ "$MIRROR" = cn ]; then
+    docker build -t "$base_image" \
+      --build-arg UBUNTU_MIRROR=https://mirrors.aliyun.com/ubuntu/ \
+      --build-arg NODE_DIST=https://npmmirror.com/mirrors/node \
+      --build-arg PIP_INDEX=https://mirrors.aliyun.com/pypi/simple/ \
+      --build-arg NPM_REGISTRY=https://registry.npmmirror.com \
+      "$INSTALL_DIR/images"
+  else
+    docker build -t "$base_image" "$INSTALL_DIR/images"
+  fi
+  note "built $base_image from images/Dockerfile"
+fi
+
+# ---- daemon configuration ----------------------------------------------------
+log "daemon configuration ($ENV_FILE)"
+install -d -m 700 "$DATA_DIR"
+if [ -f "$ENV_FILE" ]; then
+  note "[skip] exists — kept as is (your API token is never rotated); delete it to regenerate"
+else
+  install -d -m 755 /etc/dormice
+  # No inline comments below: systemd's EnvironmentFile takes the whole line
+  # as the value. Full-line comments are fine.
+  cat >"$ENV_FILE" <<EOF
+# Dormice daemon configuration, read by systemd (EnvironmentFile).
+# Full-line comments only — an inline comment becomes part of the value.
+# All knobs and defaults: packages/server/src/config.ts
+DORMICE_API_TOKEN=$(openssl rand -hex 32)
+DORMICE_EXECUTOR=docker
+DORMICE_BASE_IMAGE=$base_image
+DORMICE_DB_PATH=$DATA_DIR/dormice.db
+DORMICE_DATA_DIR=$DATA_DIR
+EOF
+  chmod 600 "$ENV_FILE"
+  note "wrote $ENV_FILE (mode 600) with a fresh API token"
+fi
+
+# ---- systemd service ---------------------------------------------------------
+log 'systemd service'
+cp "$INSTALL_DIR/deploy/dormice.service" /etc/systemd/system/dormice.service
+systemctl daemon-reload
+systemctl enable dormice >/dev/null 2>&1
+# Restart, not start: a re-run just built fresh code, and the daemon is
+# crash-only by design — restarting it is always safe.
+systemctl restart dormice
+note 'enabled and (re)started'
+
+# ---- verification: the install has not succeeded until doctor says so --------
+log 'verification'
+for _ in $(seq 1 20); do
+  curl -fsS "http://127.0.0.1:$PORT/healthz" >/dev/null 2>&1 && break
+  sleep 0.5
+done
+curl -fsS "http://127.0.0.1:$PORT/healthz" >/dev/null 2>&1 \
+  || die "the daemon did not answer /healthz on 127.0.0.1:$PORT — check: journalctl -u dormice -n 50"
+note "daemon is answering on 127.0.0.1:$PORT"
+set -a
+# shellcheck source=/dev/null
+. "$ENV_FILE"
+set +a
+dor doctor
+
+printf '\nDormice is installed.\n'
+printf '  API token:   grep ^DORMICE_API_TOKEN %s\n' "$ENV_FILE"
+printf '  daemon logs: journalctl -u dormice -f\n'
+printf '  CLI:         export DORMICE_ENDPOINT=http://127.0.0.1:%s DORMICE_API_TOKEN=<token>; dor sandbox ls\n' "$PORT"
+printf '  The daemon listens on 127.0.0.1 only, by design — exposing it is a reverse proxy'"'"'s job.\n'

From adf455d14b0a78cff4f023a86b1f2b8ea3b92a93 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 21:29:11 +0800
Subject: [PATCH 012/133] The cn Ubuntu mirror must be http: the base image has
 no CA certs yet

First real run caught it: layer 1 of images/Dockerfile is what installs
ca-certificates, so an https apt mirror cannot handshake inside the bare
ubuntu:24.04 image. apt integrity comes from GPG signatures, not TLS.
---
 deploy/install.sh | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/deploy/install.sh b/deploy/install.sh
index ebfa3d3..0c252aa 100644
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -288,8 +288,12 @@ else
     docker rmi -f docker.m.daocloud.io/library/ubuntu:24.04 >/dev/null
   fi
   if [ "$MIRROR" = cn ]; then
+    # http on purpose: the base image has no CA certificates until this very
+    # layer installs them, so an https mirror cannot even handshake. apt's
+    # integrity comes from GPG signatures, not TLS (the default
+    # archive.ubuntu.com is http too).
     docker build -t "$base_image" \
-      --build-arg UBUNTU_MIRROR=https://mirrors.aliyun.com/ubuntu/ \
+      --build-arg UBUNTU_MIRROR=http://mirrors.aliyun.com/ubuntu/ \
       --build-arg NODE_DIST=https://npmmirror.com/mirrors/node \
       --build-arg PIP_INDEX=https://mirrors.aliyun.com/pypi/simple/ \
       --build-arg NPM_REGISTRY=https://registry.npmmirror.com \

From 2e6e93258f85bb43f3309b9f46a07ce0ab345fc6 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 21:57:45 +0800
Subject: [PATCH 013/133] Web console at /ui: a stateless session cookie opens
 the same native routes

---
 README.md                             |  14 +-
 e2e/src/ui.test.ts                    |  78 ++++
 packages/server/package.json          |   2 +
 packages/server/src/app.ts            |  22 +-
 packages/server/src/auth.ts           |  76 +++-
 packages/server/src/main.ts           |  19 +-
 packages/server/src/routes/ui.test.ts | 199 ++++++++++
 packages/server/src/routes/ui.ts      | 102 +++++
 packages/web/index.html               |  12 +
 packages/web/package.json             |  17 +
 packages/web/src/api.ts               |  43 ++
 packages/web/src/index.ts             |   2 -
 packages/web/src/main.tsx             |  51 +++
 packages/web/src/pages/login.tsx      |  53 +++
 packages/web/src/pages/sandboxes.tsx  | 204 ++++++++++
 packages/web/src/styles.css           |   1 +
 packages/web/tsconfig.json            |   7 +-
 packages/web/vite.config.ts           |  19 +
 pnpm-lock.yaml                        | 550 +++++++++++++++++++++++++-
 19 files changed, 1441 insertions(+), 30 deletions(-)
 create mode 100644 e2e/src/ui.test.ts
 create mode 100644 packages/server/src/routes/ui.test.ts
 create mode 100644 packages/server/src/routes/ui.ts
 create mode 100644 packages/web/index.html
 create mode 100644 packages/web/src/api.ts
 delete mode 100644 packages/web/src/index.ts
 create mode 100644 packages/web/src/main.tsx
 create mode 100644 packages/web/src/pages/login.tsx
 create mode 100644 packages/web/src/pages/sandboxes.tsx
 create mode 100644 packages/web/src/styles.css
 create mode 100644 packages/web/vite.config.ts

diff --git a/README.md b/README.md
index 059f5b5..b7d3270 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 **The SQLite of agent sandboxes** — a self-hosted sandbox platform for AI agents. One machine, sandboxes that live forever, idle costs nothing.
 
-> **Status: early development.** The daemon, its lifecycle engine, the SDK, the CLI, the real Docker + gVisor executor, and the E2B-compatible API work end to end — the full create → freeze → stop → wake cycle, command execution, file I/O, and the official `e2b` SDK against real infrastructure. Nothing here is ready for production yet.
+> **Status: early development.** The daemon, its lifecycle engine, the SDK, the CLI, the web console, the real Docker + gVisor executor, and the E2B-compatible API work end to end — the full create → freeze → stop → wake cycle, command execution, file I/O, and the official `e2b` SDK against real infrastructure. Nothing here is ready for production yet.
 
 ## The idea
 
@@ -28,6 +28,16 @@ drift, and never rotates your API token. It ends by running `dor doctor`,
 that decide whether the install actually succeeded; `dor doctor` can be
 re-run on its own at any time.
 
+## Web console
+
+The daemon serves a small web console at `http://127.0.0.1:3676/ui` —
+sign in with the API token once and it becomes an httpOnly session cookie;
+the token itself is never stored anywhere the page can read. The console
+shows every sandbox with its live lifecycle state (the same
+`/listSandboxes` the SDK sees) and can release sandboxes. Since the daemon
+listens on 127.0.0.1 only, reach a remote host's console through an SSH
+tunnel: `ssh -L 3676:127.0.0.1:3676 root@host`.
+
 ## Host prerequisites (docker executor)
 
 The daemon itself runs anywhere Node 22+ runs, with an in-memory fake
@@ -63,7 +73,7 @@ pnpm monorepo:
 | `packages/server` | The daemon: Fastify + SQLite ledger + lifecycle engine |
 | `packages/sdk` | `@dormice/sdk` — TypeScript client for the native API |
 | `packages/cli` | `dormice` command-line tool (`dor` for short) |
-| `packages/web` | Web console (skeleton) |
+| `packages/web` | Web console: React SPA, served by the daemon at `/ui` |
 | `e2e` | Black-box suite: boots the built daemon, drives it over the wire |
 
 ## Development
diff --git a/e2e/src/ui.test.ts b/e2e/src/ui.test.ts
new file mode 100644
index 0000000..f28a3ec
--- /dev/null
+++ b/e2e/src/ui.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, inject, it } from 'vitest';
+
+// The web console, black-box: plain fetch against the built daemon, the
+// same requests a browser would make. The daemon serves packages/web/dist
+// (pnpm build ran before this suite), so this also proves the monorepo
+// path hop in main.ts survives the dist layout.
+
+const endpoint = () => inject('dormiceEndpoint');
+
+async function loginCookie(token: string): Promise<string> {
+  const res = await fetch(`${endpoint()}/ui/auth/login`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ token }),
+  });
+  expect(res.status).toBe(200);
+  const setCookie = res.headers.getSetCookie();
+  expect(setCookie).toHaveLength(1);
+  // "name=value; Path=/; ..." -> "name=value", what a browser would send back.
+  const cookie = setCookie[0]?.split(';')[0];
+  if (!cookie) throw new Error('no session cookie in login response');
+  return cookie;
+}
+
+describe('web console over a real daemon', () => {
+  it('serves the built SPA at /ui/, with assets under /ui/', async () => {
+    const res = await fetch(`${endpoint()}/ui/`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toContain('text/html');
+    const html = await res.text();
+    expect(html).toContain('<title>Dormice</title>');
+    // The base path is baked in at build time — a bare /assets reference
+    // would 404 behind the daemon's /ui prefix.
+    expect(html).toContain('/ui/assets/');
+  });
+
+  it('falls back to the SPA for client-side routes', async () => {
+    const res = await fetch(`${endpoint()}/ui/login`);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain('<title>Dormice</title>');
+  });
+
+  it('rejects a login with the wrong token', async () => {
+    const res = await fetch(`${endpoint()}/ui/auth/login`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ token: 'w'.repeat(64) }),
+    });
+    expect(res.status).toBe(401);
+    expect(res.headers.getSetCookie()).toHaveLength(0);
+  });
+
+  it('login yields a session cookie that opens the native API', async () => {
+    const cookie = await loginCookie(inject('dormiceToken'));
+    const res = await fetch(`${endpoint()}/listSandboxes`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        cookie,
+        'x-dormice-console': '1',
+      },
+      body: '{}',
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { sandboxes: unknown[] };
+    expect(Array.isArray(body.sandboxes)).toBe(true);
+  });
+
+  it('the cookie without the console header stays locked out', async () => {
+    const cookie = await loginCookie(inject('dormiceToken'));
+    const res = await fetch(`${endpoint()}/listSandboxes`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', cookie },
+      body: '{}',
+    });
+    expect(res.status).toBe(401);
+  });
+});
diff --git a/packages/server/package.json b/packages/server/package.json
index 5369c16..c3b9594 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -21,7 +21,9 @@
   },
   "dependencies": {
     "@dormice/shared": "workspace:*",
+    "@fastify/cookie": "^11.0.2",
     "@fastify/multipart": "^10.0.0",
+    "@fastify/static": "^9.1.3",
     "better-sqlite3": "^12.11.1",
     "dockerode": "^5.0.1",
     "drizzle-orm": "^0.45.2",
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 2f6f10a..758e0ae 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -1,3 +1,4 @@
+import fastifyCookie from '@fastify/cookie';
 import fastify, { type FastifyError } from 'fastify';
 import {
   serializerCompiler,
@@ -6,13 +7,14 @@ import {
 } from 'fastify-type-provider-zod';
 import { type Logger, pino } from 'pino';
 import { z } from 'zod';
-import { requireApiToken } from './auth';
+import { requireApiAuth } from './auth';
 import type { Config } from './config';
 import type { Db } from './db/db';
 import { registerE2bCompat } from './e2b';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
 import { sandboxRoutes } from './routes/sandboxes';
+import { uiRoutes } from './routes/ui';
 
 export interface AppDeps {
   config: Config;
@@ -30,6 +32,11 @@ export interface AppDeps {
    * before anything that needs it.
    */
   logger?: boolean | Logger;
+  /**
+   * Where the built web console lives; main.ts resolves the monorepo
+   * layout, tests inject a fixture. Absent means /ui answers an honest 404.
+   */
+  webDistDir?: string;
 }
 
 /**
@@ -47,6 +54,7 @@ export function buildApp({
   executor,
   locks,
   logger = true,
+  webDistDir,
 }: AppDeps) {
   // Always a pino instance (booleans are normalized into one): two fastify()
   // call shapes would give the instance two different types.
@@ -88,11 +96,21 @@ export function buildApp({
     async () => ({ status: 'ok' as const }),
   );
 
+  // Cookie parsing app-wide: the auth arbiter reads the console's session
+  // cookie on the native routes, the /ui surface mints and clears it.
+  app.register(fastifyCookie);
+
   app.register(async (api) => {
-    api.addHook('onRequest', requireApiToken(config.DORMICE_API_TOKEN));
+    api.addHook('onRequest', requireApiAuth(config.DORMICE_API_TOKEN));
     await api.register(sandboxRoutes, { config, db, executor, locks });
   });
 
+  // The web console: session endpoints (open — login carries the token
+  // itself) and the static SPA. Its API calls go through the routes above.
+  app.register(async (ui) => {
+    await ui.register(uiRoutes, { config, webDistDir });
+  });
+
   // The E2B compatibility surface lives beside the native API with its own
   // auth (X-API-KEY / X-Access-Token) and its own error dialect.
   app.register(async (compat) => {
diff --git a/packages/server/src/auth.ts b/packages/server/src/auth.ts
index 5b62b9a..8f5579d 100644
--- a/packages/server/src/auth.ts
+++ b/packages/server/src/auth.ts
@@ -1,20 +1,76 @@
-import { createHash, timingSafeEqual } from 'node:crypto';
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
 import type { onRequestAsyncHookHandler } from 'fastify';
 
 const sha256 = (value: string) => createHash('sha256').update(value).digest();
 
+/** Constant-time string comparison; both sides hashed so lengths never leak. */
+export function tokensEqual(presented: string, expected: string): boolean {
+  return timingSafeEqual(sha256(presented), sha256(expected));
+}
+
+/**
+ * The web console's session cookie. Stateless on purpose: the daemon is
+ * crash-only, and an in-memory session table would log every operator out
+ * on each restart. The value carries its own expiry and an HMAC over it —
+ * the same pattern as the envd access token — so a restart changes nothing
+ * and rotating the API token invalidates every session at once.
+ */
+export const SESSION_COOKIE = 'dormice_session';
+export const SESSION_TTL_SECONDS = 7 * 24 * 60 * 60;
+
 /**
- * Bearer-token check for all API routes (/healthz stays open — liveness
- * probes have no secrets). Both sides are hashed before comparison so
- * timingSafeEqual gets equal-length inputs and the comparison stays
- * constant-time regardless of what the client sent.
+ * Cookie-authenticated requests must also carry this header. A cross-origin
+ * page cannot send a custom header without a CORS preflight, and the daemon
+ * answers no preflights — this closes the hole SameSite leaves open
+ * (SameSite ignores the port, so another local web app counts as same-site).
  */
-export function requireApiToken(token: string): onRequestAsyncHookHandler {
-  const expected = sha256(`Bearer ${token}`);
+export const CONSOLE_HEADER = 'x-dormice-console';
+
+function sessionHmac(apiToken: string, expiresAtSeconds: number): string {
+  return createHmac('sha256', apiToken)
+    .update(`ui-session:${expiresAtSeconds}`)
+    .digest('hex');
+}
+
+export function mintSession(apiToken: string, nowMs = Date.now()): string {
+  const expiresAt = Math.floor(nowMs / 1000) + SESSION_TTL_SECONDS;
+  return `${expiresAt}.${sessionHmac(apiToken, expiresAt)}`;
+}
+
+export function verifySession(
+  apiToken: string,
+  value: string,
+  nowMs = Date.now(),
+): boolean {
+  const dot = value.indexOf('.');
+  if (dot < 0) return false;
+  const expiresAt = Number(value.slice(0, dot));
+  // The expiry is plaintext in the cookie — nothing secret to compare in
+  // constant time. The HMAC comparison below is the constant-time one.
+  if (!Number.isInteger(expiresAt) || expiresAt * 1000 <= nowMs) return false;
+  return tokensEqual(value.slice(dot + 1), sessionHmac(apiToken, expiresAt));
+}
+
+/**
+ * The single arbiter of who may call the API (/healthz stays open —
+ * liveness probes have no secrets). Two credentials open the same door:
+ * the Bearer token (SDK, CLI, curl) and the web console's session cookie
+ * (which additionally requires the console header, see above). A second
+ * route surface with its own auth would be a second truth.
+ */
+export function requireApiAuth(token: string): onRequestAsyncHookHandler {
   return async (request, reply) => {
-    const presented = sha256(request.headers.authorization ?? '');
-    if (!timingSafeEqual(presented, expected)) {
-      await reply.code(401).send({ message: 'missing or invalid API token' });
+    if (tokensEqual(request.headers.authorization ?? '', `Bearer ${token}`)) {
+      return;
+    }
+    const cookie = request.cookies?.[SESSION_COOKIE];
+    if (
+      cookie &&
+      request.headers[CONSOLE_HEADER] !== undefined &&
+      verifySession(token, cookie)
+    ) {
+      return;
     }
+    await reply.code(401).send({ message: 'missing or invalid API token' });
   };
 }
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 5a66b6e..08c9bca 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { pino } from 'pino';
 import { buildApp } from './app';
@@ -66,7 +67,23 @@ const executor = buildExecutor(config, (msg) => log.info(msg));
 // must share the same per-sandbox slots or the serialization means nothing.
 const locks = new KeyedQueue();
 
-const app = buildApp({ config, db, executor, locks, logger: log });
+// The web console ships beside the server in the monorepo; this file sits
+// one level under packages/server both as src/main.ts and as dist/main.js,
+// so the relative hop to packages/web/dist is the same either way. A
+// missing dist is loud but not fatal: the API works without the console.
+const webDistDir = fileURLToPath(new URL('../../web/dist', import.meta.url));
+if (!existsSync(webDistDir)) {
+  log.warn(`web console not found at ${webDistDir} — /ui disabled`);
+}
+
+const app = buildApp({
+  config,
+  db,
+  executor,
+  locks,
+  logger: log,
+  webDistDir: existsSync(webDistDir) ? webDistDir : undefined,
+});
 
 // Before trusting the pairing of this ledger and this reality, check it:
 // reconciliation destroys whatever the ledger disowns, so a daemon booted
diff --git a/packages/server/src/routes/ui.test.ts b/packages/server/src/routes/ui.test.ts
new file mode 100644
index 0000000..c99d36d
--- /dev/null
+++ b/packages/server/src/routes/ui.test.ts
@@ -0,0 +1,199 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { buildApp } from '../app';
+import {
+  CONSOLE_HEADER,
+  mintSession,
+  SESSION_COOKIE,
+  SESSION_TTL_SECONDS,
+  verifySession,
+} from '../auth';
+import { loadConfig } from '../config';
+import { migrateDb, openDb } from '../db/db';
+import { FakeExecutor } from '../executor/fake';
+import { KeyedQueue } from '../keyed-queue';
+
+const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
+const TOKEN = 'test-token-test-token-test-token';
+
+function testApp(webDistDir?: string) {
+  const db = openDb(':memory:');
+  migrateDb(db, MIGRATIONS);
+  const config = loadConfig({
+    DORMICE_DB_PATH: ':memory:',
+    DORMICE_API_TOKEN: TOKEN,
+  });
+  return buildApp({
+    config,
+    db,
+    executor: new FakeExecutor(),
+    locks: new KeyedQueue(),
+    logger: false,
+    webDistDir,
+  });
+}
+
+/** A minimal built console: an index.html and one hashed asset. */
+function fixtureDist(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'dormice-webdist-'));
+  writeFileSync(join(dir, 'index.html'), '<html>dormice console</html>');
+  mkdirSync(join(dir, 'assets'));
+  writeFileSync(join(dir, 'assets', 'app-abc123.js'), 'console.log("ui")');
+  return dir;
+}
+
+async function login(app: ReturnType<typeof testApp>, token = TOKEN) {
+  return app.inject({
+    method: 'POST',
+    url: '/ui/auth/login',
+    payload: { token },
+  });
+}
+
+/** The Set-Cookie value for the session cookie, parsed by fastify's helper. */
+function sessionCookie(res: { cookies: Array<Record<string, unknown>> }) {
+  const cookie = res.cookies.find((c) => c.name === SESSION_COOKIE);
+  expect(cookie).toBeDefined();
+  return cookie as { value: string } & Record<string, unknown>;
+}
+
+describe('session mint/verify', () => {
+  it('round-trips a fresh session', () => {
+    expect(verifySession(TOKEN, mintSession(TOKEN))).toBe(true);
+  });
+
+  it('rejects an expired session', () => {
+    const past = Date.now() - (SESSION_TTL_SECONDS + 10) * 1000;
+    expect(verifySession(TOKEN, mintSession(TOKEN, past))).toBe(false);
+  });
+
+  it('rejects a tampered expiry: the HMAC covers it', () => {
+    const value = mintSession(TOKEN);
+    const [exp, mac] = value.split('.');
+    const later = `${Number(exp) + 3600}.${mac}`;
+    expect(verifySession(TOKEN, later)).toBe(false);
+  });
+
+  it('rejects garbage and sessions minted under another token', () => {
+    expect(verifySession(TOKEN, 'not-a-session')).toBe(false);
+    expect(verifySession(TOKEN, '')).toBe(false);
+    expect(
+      verifySession(TOKEN, mintSession('other-token-other-token-other-tk')),
+    ).toBe(false);
+  });
+});
+
+describe('POST /ui/auth/login', () => {
+  it('rejects a wrong token without setting a cookie', async () => {
+    const res = await login(testApp(), 'wrong-token-wrong-token-wrong-tk');
+    expect(res.statusCode).toBe(401);
+    expect(res.cookies).toHaveLength(0);
+  });
+
+  it('sets an httpOnly strict session cookie for the right token', async () => {
+    const res = await login(testApp());
+    expect(res.statusCode).toBe(200);
+    const cookie = sessionCookie(res);
+    expect(cookie.httpOnly).toBe(true);
+    expect(cookie.sameSite).toBe('Strict');
+    expect(cookie.path).toBe('/');
+    expect(cookie.maxAge).toBe(SESSION_TTL_SECONDS);
+    expect(verifySession(TOKEN, cookie.value)).toBe(true);
+  });
+});
+
+describe('cookie-authenticated API access', () => {
+  async function list(
+    app: ReturnType<typeof testApp>,
+    cookieValue: string,
+    headers: Record<string, string> = { [CONSOLE_HEADER]: '1' },
+  ) {
+    return app.inject({
+      method: 'POST',
+      url: '/listSandboxes',
+      cookies: { [SESSION_COOKIE]: cookieValue },
+      headers,
+      payload: {},
+    });
+  }
+
+  it('a fresh session cookie opens the native API', async () => {
+    const app = testApp();
+    const cookie = sessionCookie(await login(app));
+    const res = await list(app, cookie.value);
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ sandboxes: [] });
+  });
+
+  it('the cookie alone is not enough: the console header is required', async () => {
+    const app = testApp();
+    const cookie = sessionCookie(await login(app));
+    const res = await list(app, cookie.value, {});
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('rejects a tampered cookie', async () => {
+    const res = await list(testApp(), `${mintSession(TOKEN)}ff`);
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('rejects an expired cookie', async () => {
+    const past = Date.now() - (SESSION_TTL_SECONDS + 10) * 1000;
+    const res = await list(testApp(), mintSession(TOKEN, past));
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('does not open the E2B surface: that has its own auth', async () => {
+    const app = testApp();
+    const cookie = sessionCookie(await login(app));
+    const res = await app.inject({
+      method: 'GET',
+      url: '/e2b/api/v2/sandboxes',
+      cookies: { [SESSION_COOKIE]: cookie.value },
+      headers: { [CONSOLE_HEADER]: '1' },
+    });
+    expect(res.statusCode).toBe(401);
+  });
+});
+
+describe('POST /ui/auth/logout', () => {
+  it('clears the session cookie', async () => {
+    const res = await testApp().inject({
+      method: 'POST',
+      url: '/ui/auth/logout',
+    });
+    expect(res.statusCode).toBe(200);
+    const cookie = sessionCookie(res);
+    expect(cookie.value).toBe('');
+  });
+});
+
+describe('static console at /ui', () => {
+  it('serves index.html and assets from the injected dist', async () => {
+    const app = testApp(fixtureDist());
+    const index = await app.inject({ method: 'GET', url: '/ui/' });
+    expect(index.statusCode).toBe(200);
+    expect(index.body).toContain('dormice console');
+    const asset = await app.inject({
+      method: 'GET',
+      url: '/ui/assets/app-abc123.js',
+    });
+    expect(asset.statusCode).toBe(200);
+  });
+
+  it('falls back to index.html for client-side routes (SPA)', async () => {
+    const app = testApp(fixtureDist());
+    const res = await app.inject({ method: 'GET', url: '/ui/sandboxes/deep' });
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toContain('dormice console');
+  });
+
+  it('answers an honest 404 when the console is not built', async () => {
+    const res = await testApp().inject({ method: 'GET', url: '/ui' });
+    expect(res.statusCode).toBe(404);
+    expect(res.json().message).toContain('pnpm build');
+  });
+});
diff --git a/packages/server/src/routes/ui.ts b/packages/server/src/routes/ui.ts
new file mode 100644
index 0000000..34a2157
--- /dev/null
+++ b/packages/server/src/routes/ui.ts
@@ -0,0 +1,102 @@
+import fastifyStatic from '@fastify/static';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import { z } from 'zod';
+import {
+  mintSession,
+  SESSION_COOKIE,
+  SESSION_TTL_SECONDS,
+  tokensEqual,
+} from '../auth';
+import type { Config } from '../config';
+
+export interface UiRoutesOptions {
+  config: Config;
+  /**
+   * Where the built web console lives (packages/web/dist). Injected so
+   * tests point it at a fixture and embedders can omit it; absent means
+   * /ui answers an honest 404 instead of guessing at paths.
+   */
+  webDistDir?: string;
+}
+
+// No Secure flag: the daemon speaks plain http on 127.0.0.1 by design, and
+// behind a TLS reverse proxy the browser-facing side is the proxy's job.
+const COOKIE_OPTIONS = {
+  httpOnly: true,
+  sameSite: 'strict',
+  path: '/',
+} as const;
+
+/**
+ * The web console's own surface: session endpoints and the static SPA.
+ * Everything else the console does goes through the native RPC routes with
+ * the session cookie — same routes, same truth as the SDK and CLI.
+ */
+export const uiRoutes: FastifyPluginAsyncZod<UiRoutesOptions> = async (
+  app,
+  { config, webDistDir },
+) => {
+  app.post(
+    '/ui/auth/login',
+    {
+      schema: {
+        body: z.object({ token: z.string() }),
+        response: {
+          200: z.object({ loggedIn: z.literal(true) }),
+          401: z.object({ message: z.string() }),
+        },
+      },
+    },
+    async (request, reply) => {
+      if (!tokensEqual(request.body.token, config.DORMICE_API_TOKEN)) {
+        return reply.code(401).send({ message: 'invalid API token' });
+      }
+      reply.setCookie(SESSION_COOKIE, mintSession(config.DORMICE_API_TOKEN), {
+        ...COOKIE_OPTIONS,
+        // The cookie lives exactly as long as the HMAC inside it is valid.
+        maxAge: SESSION_TTL_SECONDS,
+      });
+      return { loggedIn: true as const };
+    },
+  );
+
+  app.post(
+    '/ui/auth/logout',
+    {
+      schema: {
+        response: { 200: z.object({ loggedIn: z.literal(false) }) },
+      },
+    },
+    async (_request, reply) => {
+      reply.clearCookie(SESSION_COOKIE, COOKIE_OPTIONS);
+      return { loggedIn: false as const };
+    },
+  );
+
+  if (webDistDir) {
+    await app.register(
+      async (ui) => {
+        await ui.register(fastifyStatic, { root: webDistDir });
+        // SPA fallback: the router owns paths under /ui, so any GET that
+        // matches no file is a client-side route — serve the app and let
+        // it resolve. Everything else keeps the honest 404.
+        ui.setNotFoundHandler((request, reply) => {
+          if (request.method === 'GET') {
+            return reply.sendFile('index.html');
+          }
+          reply.code(404).send({
+            message: `route ${request.method} ${request.url} not found`,
+          });
+        });
+      },
+      { prefix: '/ui' },
+    );
+  } else {
+    app.get('/ui', async (_request, reply) =>
+      reply.code(404).send({
+        message:
+          'web console not available: packages/web/dist was not found at startup — run `pnpm build` first',
+      }),
+    );
+  }
+};
diff --git a/packages/web/index.html b/packages/web/index.html
new file mode 100644
index 0000000..7918003
--- /dev/null
+++ b/packages/web/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Dormice</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/packages/web/package.json b/packages/web/package.json
index 4f7c7d6..6a31fe6 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -6,6 +6,23 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "build": "vite build",
+    "dev": "vite",
     "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.101.2",
+    "@tanstack/react-router": "^1.170.17",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "devDependencies": {
+    "@dormice/shared": "workspace:*",
+    "@tailwindcss/vite": "^4.3.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "tailwindcss": "^4.3.2",
+    "vite": "^8.1.3"
   }
 }
diff --git a/packages/web/src/api.ts b/packages/web/src/api.ts
new file mode 100644
index 0000000..6258c26
--- /dev/null
+++ b/packages/web/src/api.ts
@@ -0,0 +1,43 @@
+import type { Sandbox } from '@dormice/shared';
+
+/**
+ * The console talks to the daemon's native RPC routes — the same routes,
+ * same truth as the SDK and CLI — authenticated by the httpOnly session
+ * cookie the browser attaches on its own. The custom header is the second
+ * half of the CSRF defense: a cross-origin page cannot send it without a
+ * CORS preflight, and the daemon answers no preflights.
+ */
+export class UnauthorizedError extends Error {}
+
+async function rpc<T>(path: string, body: unknown = {}): Promise<T> {
+  const res = await fetch(path, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'x-dormice-console': '1',
+    },
+    body: JSON.stringify(body),
+  });
+  if (res.status === 401) {
+    throw new UnauthorizedError('not logged in');
+  }
+  if (!res.ok) {
+    const message = await res
+      .json()
+      .then((data: { message?: string }) => data.message)
+      .catch(() => undefined);
+    throw new Error(message ?? `${path} failed with ${res.status}`);
+  }
+  return res.json() as Promise<T>;
+}
+
+export const login = (token: string) =>
+  rpc<{ loggedIn: true }>('/ui/auth/login', { token });
+
+export const logout = () => rpc<{ loggedIn: false }>('/ui/auth/logout');
+
+export const listSandboxes = () =>
+  rpc<{ sandboxes: Sandbox[] }>('/listSandboxes');
+
+export const releaseSandbox = (userKey: string) =>
+  rpc<{ released: boolean }>('/releaseSandbox', { userKey });
diff --git a/packages/web/src/index.ts b/packages/web/src/index.ts
deleted file mode 100644
index 4d2be72..0000000
--- a/packages/web/src/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-// Web console placeholder. Replaced by the Vite + React SPA scaffold in later steps.
-export {};
diff --git a/packages/web/src/main.tsx b/packages/web/src/main.tsx
new file mode 100644
index 0000000..f9f9ee9
--- /dev/null
+++ b/packages/web/src/main.tsx
@@ -0,0 +1,51 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import {
+  createRootRoute,
+  createRoute,
+  createRouter,
+  Outlet,
+  RouterProvider,
+} from '@tanstack/react-router';
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { LoginPage } from './pages/login';
+import { SandboxesPage } from './pages/sandboxes';
+import './styles.css';
+
+const rootRoute = createRootRoute({ component: Outlet });
+
+const sandboxesRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/',
+  component: SandboxesPage,
+});
+
+const loginRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/login',
+  component: LoginPage,
+});
+
+// The daemon serves the console under /ui; the router lives there too so
+// server paths and client paths are the same strings everywhere.
+const router = createRouter({
+  routeTree: rootRoute.addChildren([sandboxesRoute, loginRoute]),
+  basepath: '/ui',
+});
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router;
+  }
+}
+
+const queryClient = new QueryClient();
+
+// biome-ignore lint/style/noNonNullAssertion: index.html always has #root
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <RouterProvider router={router} />
+    </QueryClientProvider>
+  </StrictMode>,
+);
diff --git a/packages/web/src/pages/login.tsx b/packages/web/src/pages/login.tsx
new file mode 100644
index 0000000..436bb9f
--- /dev/null
+++ b/packages/web/src/pages/login.tsx
@@ -0,0 +1,53 @@
+import { useMutation } from '@tanstack/react-query';
+import { useNavigate } from '@tanstack/react-router';
+import { useState } from 'react';
+import { login } from '../api';
+
+/**
+ * One field, one button. The token is posted once and comes back as an
+ * httpOnly session cookie — it is never stored anywhere the page can read.
+ */
+export function LoginPage() {
+  const navigate = useNavigate();
+  const [token, setToken] = useState('');
+  const mutation = useMutation({
+    mutationFn: login,
+    onSuccess: () => navigate({ to: '/' }),
+  });
+
+  return (
+    <main className="flex min-h-screen items-center justify-center bg-slate-950 text-slate-100">
+      <form
+        className="w-full max-w-sm rounded-xl border border-slate-800 bg-slate-900 p-8 shadow-lg"
+        onSubmit={(event) => {
+          event.preventDefault();
+          mutation.mutate(token);
+        }}
+      >
+        <h1 className="text-2xl font-semibold">Dormice</h1>
+        <p className="mt-1 text-sm text-slate-400">
+          Paste the daemon's API token to open the console.
+        </p>
+        <input
+          type="password"
+          // biome-ignore lint/a11y/noAutofocus: the page has exactly one input and exists only to receive it
+          autoFocus
+          value={token}
+          onChange={(event) => setToken(event.target.value)}
+          placeholder="DORMICE_API_TOKEN"
+          className="mt-6 w-full rounded-md border border-slate-700 bg-slate-950 px-3 py-2 font-mono text-sm placeholder:text-slate-600 focus:border-sky-500 focus:outline-none"
+        />
+        {mutation.isError && (
+          <p className="mt-3 text-sm text-red-400">{mutation.error.message}</p>
+        )}
+        <button
+          type="submit"
+          disabled={token.length === 0 || mutation.isPending}
+          className="mt-6 w-full rounded-md bg-sky-600 py-2 font-medium text-white hover:bg-sky-500 disabled:opacity-50"
+        >
+          {mutation.isPending ? 'Signing in…' : 'Sign in'}
+        </button>
+      </form>
+    </main>
+  );
+}
diff --git a/packages/web/src/pages/sandboxes.tsx b/packages/web/src/pages/sandboxes.tsx
new file mode 100644
index 0000000..2077dcb
--- /dev/null
+++ b/packages/web/src/pages/sandboxes.tsx
@@ -0,0 +1,204 @@
+import type { Sandbox, SandboxState } from '@dormice/shared';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useNavigate } from '@tanstack/react-router';
+import { useEffect, useState } from 'react';
+import {
+  listSandboxes,
+  logout,
+  releaseSandbox,
+  UnauthorizedError,
+} from '../api';
+
+const STATE_STYLES: Record<SandboxState, string> = {
+  active: 'bg-emerald-500/15 text-emerald-400 border-emerald-500/30',
+  frozen: 'bg-sky-500/15 text-sky-400 border-sky-500/30',
+  stopped: 'bg-slate-500/15 text-slate-400 border-slate-500/30',
+  archived: 'bg-violet-500/15 text-violet-400 border-violet-500/30',
+  restoring: 'bg-amber-500/15 text-amber-400 border-amber-500/30',
+};
+
+function formatDuration(totalSeconds: number): string {
+  const s = Math.max(0, Math.floor(totalSeconds));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
+  if (s < 86400)
+    return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+  return `${Math.floor(s / 86400)}d ${Math.floor((s % 86400) / 3600)}h`;
+}
+
+function since(iso: string): string {
+  return formatDuration((Date.now() - Date.parse(iso)) / 1000);
+}
+
+/** The three knobs in one line: how this sandbox cools down when idle. */
+function policyLine(policy: Sandbox['policy']): string {
+  const step = (label: string, seconds: number | null) =>
+    seconds === null ? `${label} never` : `${label} ${formatDuration(seconds)}`;
+  return [
+    step('freeze', policy.freezeAfterSeconds),
+    step('stop', policy.stopAfterSeconds),
+    step('archive', policy.archiveAfterSeconds),
+  ].join(' · ');
+}
+
+function ReleaseButton({ userKey }: { userKey: string }) {
+  const queryClient = useQueryClient();
+  const [armed, setArmed] = useState(false);
+  const mutation = useMutation({
+    mutationFn: releaseSandbox,
+    onSettled: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
+  });
+
+  // Two clicks on purpose: release destroys the sandbox and its disk, and a
+  // modal library is more machinery than one armed state.
+  if (!armed) {
+    return (
+      <button
+        type="button"
+        onClick={() => setArmed(true)}
+        className="rounded-md border border-slate-700 px-3 py-1 text-xs text-slate-300 hover:border-red-500/50 hover:text-red-400"
+      >
+        Release
+      </button>
+    );
+  }
+  return (
+    <span className="flex items-center justify-end gap-2">
+      <button
+        type="button"
+        onClick={() => mutation.mutate(userKey)}
+        disabled={mutation.isPending}
+        className="rounded-md bg-red-600 px-3 py-1 text-xs font-medium text-white hover:bg-red-500 disabled:opacity-50"
+      >
+        {mutation.isPending ? 'Releasing…' : 'Destroy it'}
+      </button>
+      <button
+        type="button"
+        onClick={() => setArmed(false)}
+        className="rounded-md border border-slate-700 px-3 py-1 text-xs text-slate-400"
+      >
+        Keep
+      </button>
+    </span>
+  );
+}
+
+export function SandboxesPage() {
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+  const query = useQuery({
+    queryKey: ['sandboxes'],
+    queryFn: listSandboxes,
+    // The observation window observes: a short poll against a local SQLite
+    // read is effectively free, and 2s is faster than the human eye needs.
+    refetchInterval: 2000,
+    retry: false,
+  });
+
+  useEffect(() => {
+    if (query.error instanceof UnauthorizedError) {
+      navigate({ to: '/login' });
+    }
+  }, [query.error, navigate]);
+
+  const logoutMutation = useMutation({
+    mutationFn: logout,
+    onSuccess: () => {
+      queryClient.clear();
+      navigate({ to: '/login' });
+    },
+  });
+
+  const sandboxes = query.data?.sandboxes ?? [];
+
+  return (
+    <main className="min-h-screen bg-slate-950 text-slate-100">
+      <header className="flex items-center justify-between border-b border-slate-800 px-6 py-4">
+        <div className="flex items-baseline gap-3">
+          <h1 className="text-lg font-semibold">Dormice</h1>
+          <span className="text-sm text-slate-400">
+            {sandboxes.length} sandbox{sandboxes.length === 1 ? '' : 'es'}
+          </span>
+        </div>
+        <button
+          type="button"
+          onClick={() => logoutMutation.mutate()}
+          className="rounded-md border border-slate-700 px-3 py-1 text-sm text-slate-300 hover:border-slate-500"
+        >
+          Sign out
+        </button>
+      </header>
+
+      <section className="px-6 py-6">
+        {query.isError && !(query.error instanceof UnauthorizedError) && (
+          <p className="mb-4 rounded-md border border-red-500/30 bg-red-500/10 px-4 py-2 text-sm text-red-400">
+            {query.error.message}
+          </p>
+        )}
+
+        {query.isSuccess && sandboxes.length === 0 && (
+          <div className="rounded-xl border border-slate-800 bg-slate-900 px-6 py-12 text-center text-slate-400">
+            <p className="font-medium text-slate-300">No sandboxes yet</p>
+            <p className="mt-2 text-sm">
+              Acquire one via the SDK or{' '}
+              <code className="rounded bg-slate-800 px-1.5 py-0.5 font-mono text-xs">
+                POST /acquireSandbox
+              </code>{' '}
+              — it will appear here within two seconds.
+            </p>
+          </div>
+        )}
+
+        {sandboxes.length > 0 && (
+          <div className="overflow-x-auto rounded-xl border border-slate-800">
+            <table className="w-full text-left text-sm">
+              <thead className="border-b border-slate-800 bg-slate-900 text-xs uppercase tracking-wide text-slate-500">
+                <tr>
+                  <th className="px-4 py-3">User key</th>
+                  <th className="px-4 py-3">State</th>
+                  <th className="px-4 py-3">Idle</th>
+                  <th className="px-4 py-3">Lifecycle policy</th>
+                  <th className="px-4 py-3">Sandbox ID</th>
+                  <th className="px-4 py-3">Age</th>
+                  <th className="px-4 py-3 text-right">Actions</th>
+                </tr>
+              </thead>
+              <tbody className="divide-y divide-slate-800/70">
+                {sandboxes.map((sandbox) => (
+                  <tr key={sandbox.sandboxId} className="hover:bg-slate-900/60">
+                    <td className="px-4 py-3 font-mono">{sandbox.userKey}</td>
+                    <td className="px-4 py-3">
+                      <span
+                        className={`inline-block rounded-full border px-2.5 py-0.5 text-xs font-medium ${STATE_STYLES[sandbox.state]}`}
+                      >
+                        {sandbox.state}
+                      </span>
+                    </td>
+                    <td className="px-4 py-3 tabular-nums text-slate-400">
+                      {since(sandbox.lastActiveAt)}
+                    </td>
+                    <td className="px-4 py-3 text-xs text-slate-400">
+                      {policyLine(sandbox.policy)}
+                    </td>
+                    <td
+                      className="max-w-40 truncate px-4 py-3 font-mono text-xs text-slate-500"
+                      title={sandbox.sandboxId}
+                    >
+                      {sandbox.sandboxId}
+                    </td>
+                    <td className="px-4 py-3 tabular-nums text-slate-400">
+                      {since(sandbox.createdAt)}
+                    </td>
+                    <td className="px-4 py-3 text-right">
+                      <ReleaseButton userKey={sandbox.userKey} />
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+      </section>
+    </main>
+  );
+}
diff --git a/packages/web/src/styles.css b/packages/web/src/styles.css
new file mode 100644
index 0000000..f1d8c73
--- /dev/null
+++ b/packages/web/src/styles.css
@@ -0,0 +1 @@
+@import "tailwindcss";
diff --git a/packages/web/tsconfig.json b/packages/web/tsconfig.json
index 564a599..2cf299c 100644
--- a/packages/web/tsconfig.json
+++ b/packages/web/tsconfig.json
@@ -1,4 +1,9 @@
 {
   "extends": "../../tsconfig.base.json",
-  "include": ["src"]
+  "compilerOptions": {
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "jsx": "react-jsx"
+  },
+  "include": ["src", "vite.config.ts"]
 }
diff --git a/packages/web/vite.config.ts b/packages/web/vite.config.ts
new file mode 100644
index 0000000..a0346ba
--- /dev/null
+++ b/packages/web/vite.config.ts
@@ -0,0 +1,19 @@
+import tailwindcss from '@tailwindcss/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  // The daemon serves the built console under /ui — assets must resolve there.
+  base: '/ui/',
+  plugins: [react(), tailwindcss()],
+  server: {
+    // Dev mode: Vite owns /ui, the daemon (fake executor is fine) owns the
+    // API — same paths the browser uses in production, so no API base knob.
+    proxy: {
+      '/ui/auth': 'http://127.0.0.1:3676',
+      '/listSandboxes': 'http://127.0.0.1:3676',
+      '/releaseSandbox': 'http://127.0.0.1:3676',
+      '/acquireSandbox': 'http://127.0.0.1:3676',
+    },
+  },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 755f11f..2fbfec5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -16,13 +16,13 @@ importers:
         version: 26.1.0
       tsup:
         specifier: ^8.5.1
-        version: 8.5.1(postcss@8.5.16)(tsx@4.23.0)(typescript@6.0.3)(yaml@2.9.0)
+        version: 8.5.1(jiti@2.7.0)(postcss@8.5.16)(tsx@4.23.0)(typescript@6.0.3)(yaml@2.9.0)
       typescript:
         specifier: ^6.0.3
         version: 6.0.3
       vitest:
         specifier: ^4.1.10
-        version: 4.1.10(@types/node@26.1.0)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(tsx@4.23.0)(yaml@2.9.0))
+        version: 4.1.10(@types/node@26.1.0)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
 
   e2e:
     dependencies:
@@ -64,9 +64,15 @@ importers:
       '@dormice/shared':
         specifier: workspace:*
         version: link:../shared
+      '@fastify/cookie':
+        specifier: ^11.0.2
+        version: 11.0.2
       '@fastify/multipart':
         specifier: ^10.0.0
         version: 10.0.0
+      '@fastify/static':
+        specifier: ^9.1.3
+        version: 9.1.3
       better-sqlite3:
         specifier: ^12.11.1
         version: 12.11.1
@@ -108,7 +114,42 @@ importers:
         specifier: ^4.4.3
         version: 4.4.3
 
-  packages/web: {}
+  packages/web:
+    dependencies:
+      '@tanstack/react-query':
+        specifier: ^5.101.2
+        version: 5.101.2(react@19.2.7)
+      '@tanstack/react-router':
+        specifier: ^1.170.17
+        version: 1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      react:
+        specifier: ^19.2.7
+        version: 19.2.7
+      react-dom:
+        specifier: ^19.2.7
+        version: 19.2.7(react@19.2.7)
+    devDependencies:
+      '@dormice/shared':
+        specifier: workspace:*
+        version: link:../shared
+      '@tailwindcss/vite':
+        specifier: ^4.3.2
+        version: 4.3.2(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
+      '@types/react':
+        specifier: ^19.2.17
+        version: 19.2.17
+      '@types/react-dom':
+        specifier: ^19.2.3
+        version: 19.2.3(@types/react@19.2.17)
+      '@vitejs/plugin-react':
+        specifier: ^6.0.3
+        version: 6.0.3(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
+      tailwindcss:
+        specifier: ^4.3.2
+        version: 4.3.2
+      vite:
+        specifier: ^8.1.3
+        version: 8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)
 
 packages:
 
@@ -806,12 +847,18 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@fastify/accept-negotiator@2.0.1':
+    resolution: {integrity: sha512-/c/TW2bO/v9JeEgoD/g1G5GxGeCF1Hafdf79WPmUlgYiBXummY0oX3VVq4yFkKKVBKDNlaDUYoab7g38RpPqCQ==}
+
   '@fastify/ajv-compiler@4.0.5':
     resolution: {integrity: sha512-KoWKW+MhvfTRWL4qrhUwAAZoaChluo0m0vbiJlGMt2GXvL4LVPQEjt8kSpHI3IBq5Rez8fg+XeH3cneztq+C7A==}
 
   '@fastify/busboy@3.2.0':
     resolution: {integrity: sha512-m9FVDXU3GT2ITSe0UaMA5rU3QkfC/UXtCU8y0gSN/GugTqtVldOBWIB5V6V3sbmenVZUIpU6f+mPEO2+m5iTaA==}
 
+  '@fastify/cookie@11.0.2':
+    resolution: {integrity: sha512-GWdwdGlgJxyvNv+QcKiGNevSspMQXncjMZ1J8IvuDQk0jvkzgWWZFNC2En3s+nHndZBGV8IbLwOI/sxCZw/mzA==}
+
   '@fastify/deepmerge@3.2.1':
     resolution: {integrity: sha512-N5Oqvltoa2r9z1tbx4xjky0oRR60v+T47Ic4J1ukoVQcptLOrIdRnCSdTGmOmajZuHVKlTnfcmrjyqsGEW1ztA==}
 
@@ -833,6 +880,12 @@ packages:
   '@fastify/proxy-addr@5.1.0':
     resolution: {integrity: sha512-INS+6gh91cLUjB+PVHfu1UqcB76Sqtpyp7bnL+FYojhjygvOPA9ctiD/JDKsyD9Xgu4hUhCSJBPig/w7duNajw==}
 
+  '@fastify/send@4.1.0':
+    resolution: {integrity: sha512-TMYeQLCBSy2TOFmV95hQWkiTYgC/SEx7vMdV+wnZVX4tt8VBLKzmH8vV9OzJehV0+XBfg+WxPMt5wp+JBUKsVw==}
+
+  '@fastify/static@9.1.3':
+    resolution: {integrity: sha512-aXrYtsiryLhRxRNaxNqsn7FUISeb7rB9q4eHUPIot5aeQBLNahnz1m6thzm7JWC1poSGXS9XrX8DvuMivp2hkQ==}
+
   '@fastify/swagger@9.7.0':
     resolution: {integrity: sha512-Vp1SC1GC2Hrkd3faFILv86BzUNyFz5N4/xdExqtCgkGASOzn/x+eMe4qXIGq7cdT6wif/P/oa6r1Ruqx19paZA==}
 
@@ -861,6 +914,9 @@ packages:
   '@jridgewell/gen-mapping@0.3.13':
     resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
 
+  '@jridgewell/remapping@2.3.5':
+    resolution: {integrity: sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==}
+
   '@jridgewell/resolve-uri@3.1.2':
     resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
     engines: {node: '>=6.0.0'}
@@ -874,6 +930,10 @@ packages:
   '@js-sdsl/ordered-map@4.4.2':
     resolution: {integrity: sha512-iUKgm52T8HOE/makSxjqoWhe95ZJA1/G1sYsGev2JDKUSS14KAgg1LHb+Ba+IPow0xflbnSkOsZcO08C7w1gYw==}
 
+  '@lukeed/ms@2.0.2':
+    resolution: {integrity: sha512-9I2Zn6+NJLfaGoz9jN3lpwDgAYvfGeNYdbAIjJOqzs4Tpc+VU3Jqq4IofSUBKajiDS8k9fZIg18/z13mpk1bsA==}
+    engines: {node: '>=8'}
+
   '@napi-rs/wasm-runtime@1.1.6':
     resolution: {integrity: sha512-ZLv/JdUfkvOy9eCnnBaGfiO+XimbjebAeO+MRQqD/B+FR1tnRN0tpKSJHRbE8sFfS6aqsXZ67TQjfwfsxULVbg==}
     peerDependencies:
@@ -1159,6 +1219,132 @@ packages:
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
+  '@tailwindcss/node@4.3.2':
+    resolution: {integrity: sha512-yWP/sqEcBLaD8JuA6zNwxoYKr75qxTioYwlRwekj5Jr/I5GXnoJfjetH/psLUIv74cYTH2lBUEzBkinthoYcBg==}
+
+  '@tailwindcss/oxide-android-arm64@4.3.2':
+    resolution: {integrity: sha512-WHxqIuHpvZ5VtdX6GTl1Ik/Vp2YuN42Et+0CdeaVd/frQ9jAvGmvR8vLT+jk3e8/Q3x8kECB9+R17pgpp2BulA==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [android]
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.2':
+    resolution: {integrity: sha512-GZypeUY/IDJW3877KeM+O67vbXr3MBnbtEL4aYhNErv/JWZhye2vGSWWG9tB6iiqR2MqRNkY8IOUy4NdSZV26w==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-darwin-x64@4.3.2':
+    resolution: {integrity: sha512-UIIzmefR6KO1sDU7MzRqAxC8iBpft/VhkGjTjnhoS6k7Z3rQ9wEgA1ODSiyH/tcSYssulNm4Ci3hOeK1jH7ccQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.2':
+    resolution: {integrity: sha512-GN+uAmcI6DNspnCDwtOAZrTz6oukJnp337qZvxqCGLd3BHBzJpO0ZbTLRvJNdztOeAmTzewewGIMPb0tk2R4WA==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.2':
+    resolution: {integrity: sha512-4ABn7qSbdHRwTiDiuWNegCyb5+2FJ4vKIKc3DmKrvAFw7MU1Lm11dIkTPwUaFdTzc7IsOpDbqBrlh0x6y36U/w==}
+    engines: {node: '>= 20'}
+    cpu: [arm]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.2':
+    resolution: {integrity: sha512-wDgEIGwoM8w8pufh9LVt1PahDgNdKXrLC2qfAnV3vAmococ9RWbxeAw4pxPttd/TsJfwjyLf90Dg1y9y8I6Emw==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.2':
+    resolution: {integrity: sha512-J5Nuk0uZQIiMTJj3LEx4sAA9tMFUoXQZFv1J6An+QGYe53HKRJuFDi0rpq/tuouCZeAbOBY3kQ6g8qeD4TUjtA==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.2':
+    resolution: {integrity: sha512-kqCZpSKOBEJO4mz7OqWoofBZeXTAwaVGPj0ErAj7CojmhKpWVWVOnrt9dE8odoIraZq4oj3ausM37kXi+Tow8w==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.2':
+    resolution: {integrity: sha512-cixpqbh2toJDmkuCRI68nXA8ZxNmdK9Y+9v5h3MC3ZQKy/0BO8AWzlkWyRM7JAFSGBlfig4YVTPsK6MVgqz1uw==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.2':
+    resolution: {integrity: sha512-4ec2Z/LOmRsAgU23CS4xeJfcJlmRg94A/XrbGRCF1gyU/zdDfRLYDVsS+ynSZCmGNxQ1jQriQOKMQeQxBA3Isw==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+    bundledDependencies:
+      - '@napi-rs/wasm-runtime'
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - '@tybys/wasm-util'
+      - '@emnapi/wasi-threads'
+      - tslib
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.2':
+    resolution: {integrity: sha512-Zyr/M0+XcYZu3bZrUytc7TXvrk0ftWfl8gN2MwekNDzhqhKRUucMPSeOzM0o0wH5AWOU49BsKRrfKxI2atCPMQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.2':
+    resolution: {integrity: sha512-QI9BO7KlNZsp2GuO0jwAAj5jCDABOKXRkCk2XuKTSaNEFSdfzqswYVTtCHBNKHLsqyjFyFkqlDiwkNbTYSssMQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [win32]
+
+  '@tailwindcss/oxide@4.3.2':
+    resolution: {integrity: sha512-z8ZgnzX8gdNoWLBLqBPoh/sjnxkwvf9ZuWjnO0l0yIzbLa5/9S+eC5QxGZKRobVHIC3/1BoMWjHblqWjcgFgag==}
+    engines: {node: '>= 20'}
+
+  '@tailwindcss/vite@4.3.2':
+    resolution: {integrity: sha512-eHpMeX4JXfVNJDEcsouTeCBubJBTcTLigeaw/NTUW6PB5ATKKXdyonnXgTBX2VuRbjz1hjfz6C5XAhr52ImQXA==}
+    peerDependencies:
+      vite: ^5.2.0 || ^6 || ^7 || ^8
+
+  '@tanstack/history@1.162.0':
+    resolution: {integrity: sha512-79pf/RkhteYZTRgcR4F9kbk84P2N8rugQJswxfIqovlbRiT3yI7eBE+5QorIrZaOKktsgzRlXh1l/du/xpl4iA==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/query-core@5.101.2':
+    resolution: {integrity: sha512-hH5MLoJhF7KaIGd7q3xTXGXvslI+GYlM1Z/35aSHHWaCJWB7XvTSHYuV3eM7tw+aE0mT/xMro4M4Q9rCGHT0lw==}
+
+  '@tanstack/react-query@5.101.2':
+    resolution: {integrity: sha512-seDkr6kzGzX1okaaTtZPtgA688CDPlXUz1C6xSg0ESqn04Vuc8tlrYms1s3de+znBqhPVxFRfpAfUf+6XvfPWg==}
+    peerDependencies:
+      react: ^18 || ^19
+
+  '@tanstack/react-router@1.170.17':
+    resolution: {integrity: sha512-ppLkjCfSMaeug9rmFRYzOd4TIqWV+yTE7tzIny7alJsSnM7w4lzEZm6eqCehG0SPetpZ0R3K+UnanSmBgOAVcQ==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      react: '>=18.0.0 || >=19.0.0'
+      react-dom: '>=18.0.0 || >=19.0.0'
+
+  '@tanstack/react-store@0.9.3':
+    resolution: {integrity: sha512-y2iHd/N9OkoQbFJLUX1T9vbc2O9tjH0pQRgTcx1/Nz4IlwLvkgpuglXUx+mXt0g5ZDFrEeDnONPqkbfxXJKwRg==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@tanstack/router-core@1.171.14':
+    resolution: {integrity: sha512-Mo3hwx0qB0cJsVYGDjG0+Ouf7VV74h/vsoDMGztdlyzDanp4gBA2s7IVvm6hFrmQM6GpD9F0Z7SqD7OldfLE7g==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/store@0.9.3':
+    resolution: {integrity: sha512-8reSzl/qGWGGVKhBoxXPMWzATSbZLZFWhwBAFO9NAyp0TxzfBP0mIrGb8CP8KrQTmvzXlR/vFPPUrHTLBGyFyw==}
+
   '@tybys/wasm-util@0.10.3':
     resolution: {integrity: sha512-F3fo1MYrRJYL3zER0OUOmkutjr1Vp23m7OsSgp7nq4SP6OqX6C/56XFIPAl5bt3zaBRjmW7SGz3u/6LwFpYcOg==}
 
@@ -1186,9 +1372,30 @@ packages:
   '@types/node@26.1.0':
     resolution: {integrity: sha512-O0A1G3xPGy4w7AgQdAQYUlQ+BKk2Oovw8eRpofyp5KdBZULnbe+WqaOVNrm705SHphCiG4XHsACrSmPu1f+Kgw==}
 
+  '@types/react-dom@19.2.3':
+    resolution: {integrity: sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==}
+    peerDependencies:
+      '@types/react': ^19.2.0
+
+  '@types/react@19.2.17':
+    resolution: {integrity: sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw==}
+
   '@types/ssh2@1.15.5':
     resolution: {integrity: sha512-N1ASjp/nXH3ovBHddRJpli4ozpk6UdDYIX4RJWFa9L1YKnzdhTlVmiGHm4DZnj/jLbqZpes4aeR30EFGQtvhQQ==}
 
+  '@vitejs/plugin-react@6.0.3':
+    resolution: {integrity: sha512-vmFvco5/QuC2f9Oj+wTk0+9XeDFkHxSamwZKYc7MxYwKICfvUvlMhqKI0VuICPltGqh1neqBKDvO4kes1ya8vg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      '@rolldown/plugin-babel': ^0.1.7 || ^0.2.0
+      babel-plugin-react-compiler: ^1.0.0
+      vite: ^8.0.0
+    peerDependenciesMeta:
+      '@rolldown/plugin-babel':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+
   '@vitest/expect@4.1.10':
     resolution: {integrity: sha512-YsCn+qAk1GWjQOWFEsEcL2gNQ0zmVmQu3T03qP6UyjhtmdtwtbuI+DASn/7iQB3HGTXkdBwGddzxPlmiql5vlA==}
 
@@ -1354,9 +1561,16 @@ packages:
     resolution: {integrity: sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==}
     engines: {node: ^14.18.0 || >=16.10.0}
 
+  content-disposition@1.1.0:
+    resolution: {integrity: sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==}
+    engines: {node: '>=18'}
+
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
 
+  cookie-es@3.1.1:
+    resolution: {integrity: sha512-UaXxwISYJPTr9hwQxMFYZ7kNhSXboMXP+Z3TRX6f1/NyaGPfuNUZOWP1pUEb75B2HjfklIYLVRfWiFZJyC6Npg==}
+
   cookie@1.1.1:
     resolution: {integrity: sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==}
     engines: {node: '>=18'}
@@ -1369,6 +1583,9 @@ packages:
     resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
     engines: {node: '>= 8'}
 
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
+
   debug@4.4.3:
     resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
     engines: {node: '>=6.0'}
@@ -1386,6 +1603,10 @@ packages:
     resolution: {integrity: sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==}
     engines: {node: '>=4.0.0'}
 
+  depd@2.0.0:
+    resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
+    engines: {node: '>= 0.8'}
+
   dequal@2.0.3:
     resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
     engines: {node: '>=6'}
@@ -1511,6 +1732,10 @@ packages:
   end-of-stream@1.4.5:
     resolution: {integrity: sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==}
 
+  enhanced-resolve@5.21.6:
+    resolution: {integrity: sha512-aNnGCvbJ/RIyWo1IuhNdVjnNF+EjH9wpzpNHt+ci/m9He9LJvUN8wrCcXjp9cWsGNAuvSpVFTx/vraAFQ8qGjQ==}
+    engines: {node: '>=10.13.0'}
+
   es-module-lexer@2.3.0:
     resolution: {integrity: sha512-KLdwQm2NvGLDkQDCGvmiQrhkd0JbMzXthwQAUgWjQuQdBLFa3eiBP5arXZyA+f8x+x7OXgud6bq2rxjGtHV2tw==}
 
@@ -1538,6 +1763,9 @@ packages:
     resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
     engines: {node: '>=6'}
 
+  escape-html@1.0.3:
+    resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
+
   estree-walker@3.0.3:
     resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
 
@@ -1639,6 +1867,17 @@ packages:
     engines: {node: 20 || >=22}
     hasBin: true
 
+  glob@13.0.6:
+    resolution: {integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==}
+    engines: {node: 18 || 20 || >=22}
+
+  graceful-fs@4.2.11:
+    resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
+
+  http-errors@2.0.1:
+    resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
+    engines: {node: '>= 0.8'}
+
   human-signals@8.0.1:
     resolution: {integrity: sha512-eKCa6bwnJhvxj14kZk5NCPc6Hb6BdsU9DZcOnmQKSnO1VKrfV0zCvtttPZUsBvjmNDn8rpcJfpwSYnHBjc95MQ==}
     engines: {node: '>=18.18.0'}
@@ -1672,6 +1911,10 @@ packages:
     resolution: {integrity: sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ==}
     engines: {node: '>=18'}
 
+  isbot@5.2.0:
+    resolution: {integrity: sha512-gbZiGCb4B5xaoxg9mS7koAyRdvJnArk10VLSHOgz6rtBG93/pi1xOFaVvXMKZ7JXgyZ8zAbNRK5uIBdIUTFSqw==}
+    engines: {node: '>=18'}
+
   isexe@2.0.0:
     resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
 
@@ -1679,6 +1922,10 @@ packages:
     resolution: {integrity: sha512-ykkVRwrYvFm1nb2AJfKKYPr0emF6IiXDYUaFx4Zn9ZuIH7MrzEZ3sD5RlqGXNRpHtvUHJyOnCEFxOlNDtGo7wg==}
     engines: {node: 20 || >=22}
 
+  jiti@2.7.0:
+    resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}
+    hasBin: true
+
   joycon@3.1.1:
     resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==}
     engines: {node: '>=10'}
@@ -1794,6 +2041,11 @@ packages:
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
+  mime@3.0.0:
+    resolution: {integrity: sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A==}
+    engines: {node: '>=10.0.0'}
+    hasBin: true
+
   mimic-response@3.1.0:
     resolution: {integrity: sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ==}
     engines: {node: '>=10'}
@@ -1969,6 +2221,15 @@ packages:
     resolution: {integrity: sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw==}
     hasBin: true
 
+  react-dom@19.2.7:
+    resolution: {integrity: sha512-t0BRVXvbiE/o20Hfw669rLbMCDWtYZLvmJigy2f0MxsXF+71pxhR3xOkspmsO8h3ZlNzyibAmtCa3l4lYKk6gQ==}
+    peerDependencies:
+      react: ^19.2.7
+
+  react@19.2.7:
+    resolution: {integrity: sha512-HNe9WslTbXmFK8o8cmwgAeJFSBvt1bPdHCVKtaaV+WlAN36mpT4hcRpwbf3fY56ar2oIXzsBpOAiIRHAdY0OlQ==}
+    engines: {node: '>=0.10.0'}
+
   readable-stream@3.6.2:
     resolution: {integrity: sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==}
     engines: {node: '>= 6'}
@@ -2034,6 +2295,9 @@ packages:
   safer-buffer@2.1.2:
     resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
 
+  scheduler@0.27.0:
+    resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
+
   secure-json-parse@4.1.0:
     resolution: {integrity: sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA==}
 
@@ -2042,9 +2306,22 @@ packages:
     engines: {node: '>=10'}
     hasBin: true
 
+  seroval-plugins@1.5.4:
+    resolution: {integrity: sha512-S0xQPhUTefAhNvNWFg0c1J8qJArHt5KdtJ/cFAofo06KD1MVSeFWyl4iiu+ApDIuw0WhjpOfCdgConOfAnLgkw==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      seroval: ^1.0
+
+  seroval@1.5.4:
+    resolution: {integrity: sha512-46uFvgrXTVxZcUorgSSRZ4y+ieqLLQRMlG4bnCZKW3qI6BZm7Rg4ntMW4p1mILEEBZWrFlcpp0AyIIlM6jD9iw==}
+    engines: {node: '>=10'}
+
   set-cookie-parser@2.7.2:
     resolution: {integrity: sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==}
 
+  setprototypeof@1.2.0:
+    resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
+
   shebang-command@2.0.0:
     resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
     engines: {node: '>=8'}
@@ -2098,6 +2375,10 @@ packages:
   stackback@0.0.2:
     resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
 
+  statuses@2.0.2:
+    resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==}
+    engines: {node: '>= 0.8'}
+
   std-env@4.1.0:
     resolution: {integrity: sha512-Rq7ybcX2RuC55r9oaPVEW7/xu3tj8u4GeBYHBWCychFtzMIr86A7e3PPEBPT37sHStKX3+TiX/Fr/ACmJLVlLQ==}
 
@@ -2125,6 +2406,13 @@ packages:
     engines: {node: '>=16 || 14 >=14.17'}
     hasBin: true
 
+  tailwindcss@4.3.2:
+    resolution: {integrity: sha512-WtctNNSH8A9jlMIqxzuYumOHU5uGZyRv0Q5svQl+oEPy5w84YpBxdb7MdqyiSPQge5jTJ6zFQLq0PFygdccSBA==}
+
+  tapable@2.3.3:
+    resolution: {integrity: sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==}
+    engines: {node: '>=6'}
+
   tar-fs@2.1.5:
     resolution: {integrity: sha512-OboTd8mmMhZDNPV+UjQcK9yKAatXu2aJ+r1w4im1Otd4M4fl2hwvdoXUxIYHFTHWK/3y3FarBP70v3vwmGlOxw==}
 
@@ -2169,6 +2457,10 @@ packages:
     resolution: {integrity: sha512-m1TdR/rvT7kgGJZhspNtXdsdYk0fddFpJJFlG5s+UkPFo6lkLoZ3YLOaovPYjq1R75NP5JfeTlSHaOsE09peCg==}
     engines: {node: '>=20'}
 
+  toidentifier@1.0.1:
+    resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==}
+    engines: {node: '>=0.6'}
+
   tree-kill@1.2.2:
     resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==}
     hasBin: true
@@ -2235,6 +2527,11 @@ packages:
     resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
     engines: {node: '>=18'}
 
+  use-sync-external-store@1.6.0:
+    resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   util-deprecate@1.0.2:
     resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
 
@@ -2751,6 +3048,8 @@ snapshots:
   '@esbuild/win32-x64@0.28.1':
     optional: true
 
+  '@fastify/accept-negotiator@2.0.1': {}
+
   '@fastify/ajv-compiler@4.0.5':
     dependencies:
       ajv: 8.20.0
@@ -2759,6 +3058,11 @@ snapshots:
 
   '@fastify/busboy@3.2.0': {}
 
+  '@fastify/cookie@11.0.2':
+    dependencies:
+      cookie: 1.1.1
+      fastify-plugin: 5.1.0
+
   '@fastify/deepmerge@3.2.1': {}
 
   '@fastify/error@4.2.0': {}
@@ -2786,6 +3090,23 @@ snapshots:
       '@fastify/forwarded': 3.0.1
       ipaddr.js: 2.4.0
 
+  '@fastify/send@4.1.0':
+    dependencies:
+      '@lukeed/ms': 2.0.2
+      escape-html: 1.0.3
+      fast-decode-uri-component: 1.0.1
+      http-errors: 2.0.1
+      mime: 3.0.0
+
+  '@fastify/static@9.1.3':
+    dependencies:
+      '@fastify/accept-negotiator': 2.0.1
+      '@fastify/send': 4.1.0
+      content-disposition: 1.1.0
+      fastify-plugin: 5.1.0
+      fastq: 1.20.1
+      glob: 13.0.6
+
   '@fastify/swagger@9.7.0':
     dependencies:
       fastify-plugin: 5.1.0
@@ -2826,6 +3147,11 @@ snapshots:
       '@jridgewell/sourcemap-codec': 1.5.5
       '@jridgewell/trace-mapping': 0.3.31
 
+  '@jridgewell/remapping@2.3.5':
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+
   '@jridgewell/resolve-uri@3.1.2': {}
 
   '@jridgewell/sourcemap-codec@1.5.5': {}
@@ -2837,6 +3163,8 @@ snapshots:
 
   '@js-sdsl/ordered-map@4.4.2': {}
 
+  '@lukeed/ms@2.0.2': {}
+
   '@napi-rs/wasm-runtime@1.1.6(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
     dependencies:
       '@emnapi/core': 1.11.1
@@ -3000,6 +3328,108 @@ snapshots:
 
   '@standard-schema/spec@1.1.0': {}
 
+  '@tailwindcss/node@4.3.2':
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      enhanced-resolve: 5.21.6
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      magic-string: 0.30.21
+      source-map-js: 1.2.1
+      tailwindcss: 4.3.2
+
+  '@tailwindcss/oxide-android-arm64@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-x64@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.2':
+    optional: true
+
+  '@tailwindcss/oxide@4.3.2':
+    optionalDependencies:
+      '@tailwindcss/oxide-android-arm64': 4.3.2
+      '@tailwindcss/oxide-darwin-arm64': 4.3.2
+      '@tailwindcss/oxide-darwin-x64': 4.3.2
+      '@tailwindcss/oxide-freebsd-x64': 4.3.2
+      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.3.2
+      '@tailwindcss/oxide-linux-arm64-gnu': 4.3.2
+      '@tailwindcss/oxide-linux-arm64-musl': 4.3.2
+      '@tailwindcss/oxide-linux-x64-gnu': 4.3.2
+      '@tailwindcss/oxide-linux-x64-musl': 4.3.2
+      '@tailwindcss/oxide-wasm32-wasi': 4.3.2
+      '@tailwindcss/oxide-win32-arm64-msvc': 4.3.2
+      '@tailwindcss/oxide-win32-x64-msvc': 4.3.2
+
+  '@tailwindcss/vite@4.3.2(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))':
+    dependencies:
+      '@tailwindcss/node': 4.3.2
+      '@tailwindcss/oxide': 4.3.2
+      tailwindcss: 4.3.2
+      vite: 8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)
+
+  '@tanstack/history@1.162.0': {}
+
+  '@tanstack/query-core@5.101.2': {}
+
+  '@tanstack/react-query@5.101.2(react@19.2.7)':
+    dependencies:
+      '@tanstack/query-core': 5.101.2
+      react: 19.2.7
+
+  '@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@tanstack/history': 1.162.0
+      '@tanstack/react-store': 0.9.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@tanstack/router-core': 1.171.14
+      isbot: 5.2.0
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
+  '@tanstack/react-store@0.9.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@tanstack/store': 0.9.3
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      use-sync-external-store: 1.6.0(react@19.2.7)
+
+  '@tanstack/router-core@1.171.14':
+    dependencies:
+      '@tanstack/history': 1.162.0
+      cookie-es: 3.1.1
+      seroval: 1.5.4
+      seroval-plugins: 1.5.4(seroval@1.5.4)
+
+  '@tanstack/store@0.9.3': {}
+
   '@tybys/wasm-util@0.10.3':
     dependencies:
       tslib: 2.8.1
@@ -3037,10 +3467,23 @@ snapshots:
     dependencies:
       undici-types: 8.3.0
 
+  '@types/react-dom@19.2.3(@types/react@19.2.17)':
+    dependencies:
+      '@types/react': 19.2.17
+
+  '@types/react@19.2.17':
+    dependencies:
+      csstype: 3.2.3
+
   '@types/ssh2@1.15.5':
     dependencies:
       '@types/node': 18.19.130
 
+  '@vitejs/plugin-react@6.0.3(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))':
+    dependencies:
+      '@rolldown/pluginutils': 1.0.1
+      vite: 8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)
+
   '@vitest/expect@4.1.10':
     dependencies:
       '@standard-schema/spec': 1.1.0
@@ -3050,13 +3493,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.0
 
-  '@vitest/mocker@4.1.10(vite@8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(tsx@4.23.0)(yaml@2.9.0))':
+  '@vitest/mocker@4.1.10(vite@8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))':
     dependencies:
       '@vitest/spy': 4.1.10
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(tsx@4.23.0)(yaml@2.9.0)
+      vite: 8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)
 
   '@vitest/pretty-format@4.1.10':
     dependencies:
@@ -3196,8 +3639,12 @@ snapshots:
 
   consola@3.4.2: {}
 
+  content-disposition@1.1.0: {}
+
   convert-source-map@2.0.0: {}
 
+  cookie-es@3.1.1: {}
+
   cookie@1.1.1: {}
 
   cpu-features@0.0.10:
@@ -3212,6 +3659,8 @@ snapshots:
       shebang-command: 2.0.0
       which: 2.0.2
 
+  csstype@3.2.3: {}
+
   debug@4.4.3:
     dependencies:
       ms: 2.1.3
@@ -3222,6 +3671,8 @@ snapshots:
 
   deep-extend@0.6.0: {}
 
+  depd@2.0.0: {}
+
   dequal@2.0.3: {}
 
   detect-libc@2.1.2: {}
@@ -3283,6 +3734,11 @@ snapshots:
     dependencies:
       once: 1.4.0
 
+  enhanced-resolve@5.21.6:
+    dependencies:
+      graceful-fs: 4.2.11
+      tapable: 2.3.3
+
   es-module-lexer@2.3.0: {}
 
   esbuild@0.18.20:
@@ -3399,6 +3855,8 @@ snapshots:
 
   escalade@3.2.0: {}
 
+  escape-html@1.0.3: {}
+
   estree-walker@3.0.3:
     dependencies:
       '@types/estree': 1.0.9
@@ -3527,6 +3985,22 @@ snapshots:
       package-json-from-dist: 1.0.1
       path-scurry: 2.0.2
 
+  glob@13.0.6:
+    dependencies:
+      minimatch: 10.2.5
+      minipass: 7.1.3
+      path-scurry: 2.0.2
+
+  graceful-fs@4.2.11: {}
+
+  http-errors@2.0.1:
+    dependencies:
+      depd: 2.0.0
+      inherits: 2.0.4
+      setprototypeof: 1.2.0
+      statuses: 2.0.2
+      toidentifier: 1.0.1
+
   human-signals@8.0.1: {}
 
   ieee754@1.2.1: {}
@@ -3545,12 +4019,16 @@ snapshots:
 
   is-unicode-supported@2.1.0: {}
 
+  isbot@5.2.0: {}
+
   isexe@2.0.0: {}
 
   jackspeak@4.2.3:
     dependencies:
       '@isaacs/cliui': 9.0.0
 
+  jiti@2.7.0: {}
+
   joycon@3.1.1: {}
 
   json-schema-ref-resolver@3.0.0:
@@ -3638,6 +4116,8 @@ snapshots:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  mime@3.0.0: {}
+
   mimic-response@3.1.0: {}
 
   minimatch@10.2.5:
@@ -3752,10 +4232,11 @@ snapshots:
 
   platform@1.3.6: {}
 
-  postcss-load-config@6.0.1(postcss@8.5.16)(tsx@4.23.0)(yaml@2.9.0):
+  postcss-load-config@6.0.1(jiti@2.7.0)(postcss@8.5.16)(tsx@4.23.0)(yaml@2.9.0):
     dependencies:
       lilconfig: 3.1.3
     optionalDependencies:
+      jiti: 2.7.0
       postcss: 8.5.16
       tsx: 4.23.0
       yaml: 2.9.0
@@ -3817,6 +4298,13 @@ snapshots:
       minimist: 1.2.8
       strip-json-comments: 2.0.1
 
+  react-dom@19.2.7(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+      scheduler: 0.27.0
+
+  react@19.2.7: {}
+
   readable-stream@3.6.2:
     dependencies:
       inherits: 2.0.4
@@ -3905,12 +4393,22 @@ snapshots:
 
   safer-buffer@2.1.2: {}
 
+  scheduler@0.27.0: {}
+
   secure-json-parse@4.1.0: {}
 
   semver@7.8.5: {}
 
+  seroval-plugins@1.5.4(seroval@1.5.4):
+    dependencies:
+      seroval: 1.5.4
+
+  seroval@1.5.4: {}
+
   set-cookie-parser@2.7.2: {}
 
+  setprototypeof@1.2.0: {}
+
   shebang-command@2.0.0:
     dependencies:
       shebang-regex: 3.0.0
@@ -3958,6 +4456,8 @@ snapshots:
 
   stackback@0.0.2: {}
 
+  statuses@2.0.2: {}
+
   std-env@4.1.0: {}
 
   string-width@4.2.3:
@@ -3988,6 +4488,10 @@ snapshots:
       tinyglobby: 0.2.17
       ts-interface-checker: 0.1.13
 
+  tailwindcss@4.3.2: {}
+
+  tapable@2.3.3: {}
+
   tar-fs@2.1.5:
     dependencies:
       chownr: 1.1.4
@@ -4038,6 +4542,8 @@ snapshots:
 
   toad-cache@3.7.4: {}
 
+  toidentifier@1.0.1: {}
+
   tree-kill@1.2.2: {}
 
   ts-interface-checker@0.1.13: {}
@@ -4045,7 +4551,7 @@ snapshots:
   tslib@2.8.1:
     optional: true
 
-  tsup@8.5.1(postcss@8.5.16)(tsx@4.23.0)(typescript@6.0.3)(yaml@2.9.0):
+  tsup@8.5.1(jiti@2.7.0)(postcss@8.5.16)(tsx@4.23.0)(typescript@6.0.3)(yaml@2.9.0):
     dependencies:
       bundle-require: 5.1.0(esbuild@0.27.7)
       cac: 6.7.14
@@ -4056,7 +4562,7 @@ snapshots:
       fix-dts-default-cjs-exports: 1.0.1
       joycon: 3.1.1
       picocolors: 1.1.1
-      postcss-load-config: 6.0.1(postcss@8.5.16)(tsx@4.23.0)(yaml@2.9.0)
+      postcss-load-config: 6.0.1(jiti@2.7.0)(postcss@8.5.16)(tsx@4.23.0)(yaml@2.9.0)
       resolve-from: 5.0.0
       rollup: 4.62.2
       source-map: 0.7.6
@@ -4099,9 +4605,13 @@ snapshots:
 
   unicorn-magic@0.3.0: {}
 
+  use-sync-external-store@1.6.0(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+
   util-deprecate@1.0.2: {}
 
-  vite@8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(tsx@4.23.0)(yaml@2.9.0):
+  vite@8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0):
     dependencies:
       lightningcss: 1.32.0
       picomatch: 4.0.5
@@ -4112,13 +4622,29 @@ snapshots:
       '@types/node': 26.1.0
       esbuild: 0.27.7
       fsevents: 2.3.3
+      jiti: 2.7.0
+      tsx: 4.23.0
+      yaml: 2.9.0
+
+  vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0):
+    dependencies:
+      lightningcss: 1.32.0
+      picomatch: 4.0.5
+      postcss: 8.5.16
+      rolldown: 1.1.4
+      tinyglobby: 0.2.17
+    optionalDependencies:
+      '@types/node': 26.1.0
+      esbuild: 0.28.1
+      fsevents: 2.3.3
+      jiti: 2.7.0
       tsx: 4.23.0
       yaml: 2.9.0
 
-  vitest@4.1.10(@types/node@26.1.0)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(tsx@4.23.0)(yaml@2.9.0)):
+  vitest@4.1.10(@types/node@26.1.0)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)):
     dependencies:
       '@vitest/expect': 4.1.10
-      '@vitest/mocker': 4.1.10(vite@8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(tsx@4.23.0)(yaml@2.9.0))
+      '@vitest/mocker': 4.1.10(vite@8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
       '@vitest/pretty-format': 4.1.10
       '@vitest/runner': 4.1.10
       '@vitest/snapshot': 4.1.10
@@ -4135,7 +4661,7 @@ snapshots:
       tinyexec: 1.2.4
       tinyglobby: 0.2.17
       tinyrainbow: 3.1.0
-      vite: 8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(tsx@4.23.0)(yaml@2.9.0)
+      vite: 8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 26.1.0

From 7a3ef439aa1f6c2a2696310226c5976d3fa4b3a1 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 9 Jul 2026 22:56:47 +0800
Subject: [PATCH 014/133] The console rebuilt on shadcn and file routes: create
 and detail join release

---
 README.md                                     |    8 +-
 biome.json                                    |   10 +-
 packages/web/components.json                  |   25 +
 packages/web/package.json                     |   22 +-
 packages/web/src/api.ts                       |   43 -
 packages/web/src/components/ui/accordion.tsx  |   76 +
 .../web/src/components/ui/alert-dialog.tsx    |  187 +
 packages/web/src/components/ui/alert.tsx      |   76 +
 .../web/src/components/ui/aspect-ratio.tsx    |   22 +
 packages/web/src/components/ui/attachment.tsx |  207 ++
 packages/web/src/components/ui/avatar.tsx     |  107 +
 packages/web/src/components/ui/badge.tsx      |   52 +
 packages/web/src/components/ui/breadcrumb.tsx |  125 +
 packages/web/src/components/ui/bubble.tsx     |  128 +
 .../web/src/components/ui/button-group.tsx    |   87 +
 packages/web/src/components/ui/button.tsx     |   56 +
 packages/web/src/components/ui/calendar.tsx   |  220 ++
 packages/web/src/components/ui/card.tsx       |  100 +
 packages/web/src/components/ui/carousel.tsx   |  243 ++
 packages/web/src/components/ui/chart.tsx      |  373 ++
 packages/web/src/components/ui/checkbox.tsx   |   29 +
 .../web/src/components/ui/collapsible.tsx     |   19 +
 packages/web/src/components/ui/combobox.tsx   |  298 ++
 packages/web/src/components/ui/command.tsx    |  195 +
 .../web/src/components/ui/context-menu.tsx    |  270 ++
 packages/web/src/components/ui/dialog.tsx     |  158 +
 packages/web/src/components/ui/direction.tsx  |    4 +
 packages/web/src/components/ui/drawer.tsx     |  228 ++
 .../web/src/components/ui/dropdown-menu.tsx   |  265 ++
 packages/web/src/components/ui/empty.tsx      |  104 +
 packages/web/src/components/ui/field.tsx      |  238 ++
 packages/web/src/components/ui/hover-card.tsx |   51 +
 .../web/src/components/ui/input-group.tsx     |  155 +
 packages/web/src/components/ui/input-otp.tsx  |   85 +
 packages/web/src/components/ui/input.tsx      |   20 +
 packages/web/src/components/ui/item.tsx       |  201 ++
 packages/web/src/components/ui/kbd.tsx        |   26 +
 packages/web/src/components/ui/label.tsx      |   20 +
 packages/web/src/components/ui/marker.tsx     |   71 +
 packages/web/src/components/ui/menubar.tsx    |  277 ++
 .../src/components/ui/message-scroller.tsx    |  131 +
 packages/web/src/components/ui/message.tsx    |   92 +
 .../web/src/components/ui/native-select.tsx   |   62 +
 .../web/src/components/ui/navigation-menu.tsx |  169 +
 packages/web/src/components/ui/pagination.tsx |  130 +
 packages/web/src/components/ui/popover.tsx    |   88 +
 packages/web/src/components/ui/progress.tsx   |   83 +
 .../web/src/components/ui/radio-group.tsx     |   36 +
 packages/web/src/components/ui/resizable.tsx  |   50 +
 .../web/src/components/ui/scroll-area.tsx     |   53 +
 packages/web/src/components/ui/select.tsx     |  200 +
 packages/web/src/components/ui/separator.tsx  |   23 +
 packages/web/src/components/ui/sheet.tsx      |  136 +
 packages/web/src/components/ui/sidebar.tsx    |  725 ++++
 packages/web/src/components/ui/skeleton.tsx   |   13 +
 packages/web/src/components/ui/slider.tsx     |   52 +
 packages/web/src/components/ui/sonner.tsx     |   50 +
 packages/web/src/components/ui/spinner.tsx    |   14 +
 packages/web/src/components/ui/switch.tsx     |   30 +
 packages/web/src/components/ui/table.tsx      |  116 +
 packages/web/src/components/ui/tabs.tsx       |   80 +
 packages/web/src/components/ui/textarea.tsx   |   18 +
 .../web/src/components/ui/toggle-group.tsx    |   89 +
 packages/web/src/components/ui/toggle.tsx     |   45 +
 packages/web/src/components/ui/tooltip.tsx    |   64 +
 .../web/src/features/auth/pages/LoginPage.tsx |   81 +
 .../components/CreateSandboxDialog.tsx        |  183 +
 .../components/ReleaseSandboxButton.tsx       |   68 +
 .../components/SandboxStateBadge.tsx          |   24 +
 packages/web/src/features/sandboxes/format.ts |   30 +
 .../features/sandboxes/hooks/useSandboxes.ts  |   44 +
 .../sandboxes/pages/SandboxDetailPage.tsx     |  109 +
 .../sandboxes/pages/SandboxesPage.tsx         |  127 +
 packages/web/src/hooks/use-mobile.ts          |   19 +
 packages/web/src/index.css                    |    4 +
 packages/web/src/lib/api.ts                   |   79 +
 packages/web/src/lib/queryClient.ts           |    3 +
 packages/web/src/lib/session.ts               |   21 +
 packages/web/src/lib/utils.ts                 |    6 +
 packages/web/src/main.tsx                     |   46 +-
 packages/web/src/pages/login.tsx              |   53 -
 packages/web/src/pages/sandboxes.tsx          |  204 --
 packages/web/src/routeTree.gen.ts             |  118 +
 packages/web/src/routes/__root.tsx            |   11 +
 packages/web/src/routes/_app.tsx              |   18 +
 packages/web/src/routes/_app/index.tsx        |    6 +
 .../src/routes/_app/sandboxes/$userKey.tsx    |    6 +
 packages/web/src/routes/login.tsx             |   30 +
 packages/web/src/shadcn.css                   |  130 +
 packages/web/src/styles.css                   |    1 -
 packages/web/tsconfig.json                    |    4 +-
 packages/web/vite.config.ts                   |   12 +-
 pnpm-lock.yaml                                | 3205 ++++++++++++++++-
 93 files changed, 11721 insertions(+), 351 deletions(-)
 create mode 100644 packages/web/components.json
 delete mode 100644 packages/web/src/api.ts
 create mode 100644 packages/web/src/components/ui/accordion.tsx
 create mode 100644 packages/web/src/components/ui/alert-dialog.tsx
 create mode 100644 packages/web/src/components/ui/alert.tsx
 create mode 100644 packages/web/src/components/ui/aspect-ratio.tsx
 create mode 100644 packages/web/src/components/ui/attachment.tsx
 create mode 100644 packages/web/src/components/ui/avatar.tsx
 create mode 100644 packages/web/src/components/ui/badge.tsx
 create mode 100644 packages/web/src/components/ui/breadcrumb.tsx
 create mode 100644 packages/web/src/components/ui/bubble.tsx
 create mode 100644 packages/web/src/components/ui/button-group.tsx
 create mode 100644 packages/web/src/components/ui/button.tsx
 create mode 100644 packages/web/src/components/ui/calendar.tsx
 create mode 100644 packages/web/src/components/ui/card.tsx
 create mode 100644 packages/web/src/components/ui/carousel.tsx
 create mode 100644 packages/web/src/components/ui/chart.tsx
 create mode 100644 packages/web/src/components/ui/checkbox.tsx
 create mode 100644 packages/web/src/components/ui/collapsible.tsx
 create mode 100644 packages/web/src/components/ui/combobox.tsx
 create mode 100644 packages/web/src/components/ui/command.tsx
 create mode 100644 packages/web/src/components/ui/context-menu.tsx
 create mode 100644 packages/web/src/components/ui/dialog.tsx
 create mode 100644 packages/web/src/components/ui/direction.tsx
 create mode 100644 packages/web/src/components/ui/drawer.tsx
 create mode 100644 packages/web/src/components/ui/dropdown-menu.tsx
 create mode 100644 packages/web/src/components/ui/empty.tsx
 create mode 100644 packages/web/src/components/ui/field.tsx
 create mode 100644 packages/web/src/components/ui/hover-card.tsx
 create mode 100644 packages/web/src/components/ui/input-group.tsx
 create mode 100644 packages/web/src/components/ui/input-otp.tsx
 create mode 100644 packages/web/src/components/ui/input.tsx
 create mode 100644 packages/web/src/components/ui/item.tsx
 create mode 100644 packages/web/src/components/ui/kbd.tsx
 create mode 100644 packages/web/src/components/ui/label.tsx
 create mode 100644 packages/web/src/components/ui/marker.tsx
 create mode 100644 packages/web/src/components/ui/menubar.tsx
 create mode 100644 packages/web/src/components/ui/message-scroller.tsx
 create mode 100644 packages/web/src/components/ui/message.tsx
 create mode 100644 packages/web/src/components/ui/native-select.tsx
 create mode 100644 packages/web/src/components/ui/navigation-menu.tsx
 create mode 100644 packages/web/src/components/ui/pagination.tsx
 create mode 100644 packages/web/src/components/ui/popover.tsx
 create mode 100644 packages/web/src/components/ui/progress.tsx
 create mode 100644 packages/web/src/components/ui/radio-group.tsx
 create mode 100644 packages/web/src/components/ui/resizable.tsx
 create mode 100644 packages/web/src/components/ui/scroll-area.tsx
 create mode 100644 packages/web/src/components/ui/select.tsx
 create mode 100644 packages/web/src/components/ui/separator.tsx
 create mode 100644 packages/web/src/components/ui/sheet.tsx
 create mode 100644 packages/web/src/components/ui/sidebar.tsx
 create mode 100644 packages/web/src/components/ui/skeleton.tsx
 create mode 100644 packages/web/src/components/ui/slider.tsx
 create mode 100644 packages/web/src/components/ui/sonner.tsx
 create mode 100644 packages/web/src/components/ui/spinner.tsx
 create mode 100644 packages/web/src/components/ui/switch.tsx
 create mode 100644 packages/web/src/components/ui/table.tsx
 create mode 100644 packages/web/src/components/ui/tabs.tsx
 create mode 100644 packages/web/src/components/ui/textarea.tsx
 create mode 100644 packages/web/src/components/ui/toggle-group.tsx
 create mode 100644 packages/web/src/components/ui/toggle.tsx
 create mode 100644 packages/web/src/components/ui/tooltip.tsx
 create mode 100644 packages/web/src/features/auth/pages/LoginPage.tsx
 create mode 100644 packages/web/src/features/sandboxes/components/CreateSandboxDialog.tsx
 create mode 100644 packages/web/src/features/sandboxes/components/ReleaseSandboxButton.tsx
 create mode 100644 packages/web/src/features/sandboxes/components/SandboxStateBadge.tsx
 create mode 100644 packages/web/src/features/sandboxes/format.ts
 create mode 100644 packages/web/src/features/sandboxes/hooks/useSandboxes.ts
 create mode 100644 packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx
 create mode 100644 packages/web/src/features/sandboxes/pages/SandboxesPage.tsx
 create mode 100644 packages/web/src/hooks/use-mobile.ts
 create mode 100644 packages/web/src/index.css
 create mode 100644 packages/web/src/lib/api.ts
 create mode 100644 packages/web/src/lib/queryClient.ts
 create mode 100644 packages/web/src/lib/session.ts
 create mode 100644 packages/web/src/lib/utils.ts
 delete mode 100644 packages/web/src/pages/login.tsx
 delete mode 100644 packages/web/src/pages/sandboxes.tsx
 create mode 100644 packages/web/src/routeTree.gen.ts
 create mode 100644 packages/web/src/routes/__root.tsx
 create mode 100644 packages/web/src/routes/_app.tsx
 create mode 100644 packages/web/src/routes/_app/index.tsx
 create mode 100644 packages/web/src/routes/_app/sandboxes/$userKey.tsx
 create mode 100644 packages/web/src/routes/login.tsx
 create mode 100644 packages/web/src/shadcn.css
 delete mode 100644 packages/web/src/styles.css

diff --git a/README.md b/README.md
index b7d3270..0d9c7aa 100644
--- a/README.md
+++ b/README.md
@@ -34,9 +34,11 @@ The daemon serves a small web console at `http://127.0.0.1:3676/ui` —
 sign in with the API token once and it becomes an httpOnly session cookie;
 the token itself is never stored anywhere the page can read. The console
 shows every sandbox with its live lifecycle state (the same
-`/listSandboxes` the SDK sees) and can release sandboxes. Since the daemon
-listens on 127.0.0.1 only, reach a remote host's console through an SSH
-tunnel: `ssh -L 3676:127.0.0.1:3676 root@host`.
+`/listSandboxes` the SDK sees), opens a per-sandbox detail view, creates
+sandboxes (the same idempotent `acquire`, with the lifecycle knobs), and
+releases them. Since the daemon listens on 127.0.0.1 only, reach a remote
+host's console through an SSH tunnel:
+`ssh -L 3676:127.0.0.1:3676 root@host`.
 
 ## Host prerequisites (docker executor)
 
diff --git a/biome.json b/biome.json
index d2fe836..21514d9 100644
--- a/biome.json
+++ b/biome.json
@@ -1,7 +1,15 @@
 {
   "$schema": "https://biomejs.dev/schemas/2.5.2/schema.json",
   "files": {
-    "includes": ["**", "!packages/*/drizzle"]
+    "includes": [
+      "**",
+      "!packages/*/drizzle",
+      "!packages/web/src/components/ui",
+      "!packages/web/src/hooks/use-mobile.ts",
+      "!packages/web/src/lib/utils.ts",
+      "!packages/web/src/shadcn.css",
+      "!packages/web/src/routeTree.gen.ts"
+    ]
   },
   "vcs": {
     "enabled": true,
diff --git a/packages/web/components.json b/packages/web/components.json
new file mode 100644
index 0000000..f9d6812
--- /dev/null
+++ b/packages/web/components.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-rhea",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/shadcn.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "hugeicons",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default-translucent",
+  "menuAccent": "subtle",
+  "registries": {}
+}
diff --git a/packages/web/package.json b/packages/web/package.json
index 6a31fe6..ae33ed1 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -11,17 +11,37 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@base-ui/react": "^1.6.0",
+    "@fontsource-variable/inter": "^5.2.8",
+    "@hugeicons/core-free-icons": "^4.2.2",
+    "@hugeicons/react": "^1.1.9",
+    "@shadcn/react": "^0.2.1",
     "@tanstack/react-query": "^5.101.2",
     "@tanstack/react-router": "^1.170.17",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.4.0",
+    "embla-carousel-react": "^8.6.0",
+    "input-otp": "^1.4.2",
+    "next-themes": "^0.4.6",
     "react": "^19.2.7",
-    "react-dom": "^19.2.7"
+    "react-day-picker": "^10.0.1",
+    "react-dom": "^19.2.7",
+    "react-resizable-panels": "^4.12.1",
+    "recharts": "3.8.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.6.0",
+    "tw-animate-css": "^1.4.0"
   },
   "devDependencies": {
     "@dormice/shared": "workspace:*",
     "@tailwindcss/vite": "^4.3.2",
+    "@tanstack/router-plugin": "^1.168.19",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.3",
+    "shadcn": "^4.13.0",
     "tailwindcss": "^4.3.2",
     "vite": "^8.1.3"
   }
diff --git a/packages/web/src/api.ts b/packages/web/src/api.ts
deleted file mode 100644
index 6258c26..0000000
--- a/packages/web/src/api.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import type { Sandbox } from '@dormice/shared';
-
-/**
- * The console talks to the daemon's native RPC routes — the same routes,
- * same truth as the SDK and CLI — authenticated by the httpOnly session
- * cookie the browser attaches on its own. The custom header is the second
- * half of the CSRF defense: a cross-origin page cannot send it without a
- * CORS preflight, and the daemon answers no preflights.
- */
-export class UnauthorizedError extends Error {}
-
-async function rpc<T>(path: string, body: unknown = {}): Promise<T> {
-  const res = await fetch(path, {
-    method: 'POST',
-    headers: {
-      'content-type': 'application/json',
-      'x-dormice-console': '1',
-    },
-    body: JSON.stringify(body),
-  });
-  if (res.status === 401) {
-    throw new UnauthorizedError('not logged in');
-  }
-  if (!res.ok) {
-    const message = await res
-      .json()
-      .then((data: { message?: string }) => data.message)
-      .catch(() => undefined);
-    throw new Error(message ?? `${path} failed with ${res.status}`);
-  }
-  return res.json() as Promise<T>;
-}
-
-export const login = (token: string) =>
-  rpc<{ loggedIn: true }>('/ui/auth/login', { token });
-
-export const logout = () => rpc<{ loggedIn: false }>('/ui/auth/logout');
-
-export const listSandboxes = () =>
-  rpc<{ sandboxes: Sandbox[] }>('/listSandboxes');
-
-export const releaseSandbox = (userKey: string) =>
-  rpc<{ released: boolean }>('/releaseSandbox', { userKey });
diff --git a/packages/web/src/components/ui/accordion.tsx b/packages/web/src/components/ui/accordion.tsx
new file mode 100644
index 0000000..51081d0
--- /dev/null
+++ b/packages/web/src/components/ui/accordion.tsx
@@ -0,0 +1,76 @@
+import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion"
+
+import { cn } from "@/lib/utils"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { ArrowDown01Icon, ArrowUp01Icon } from "@hugeicons/core-free-icons"
+
+function Accordion({ className, ...props }: AccordionPrimitive.Root.Props) {
+  return (
+    <AccordionPrimitive.Root
+      data-slot="accordion"
+      className={cn(
+        "flex w-full flex-col overflow-hidden rounded-2xl border",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AccordionItem({ className, ...props }: AccordionPrimitive.Item.Props) {
+  return (
+    <AccordionPrimitive.Item
+      data-slot="accordion-item"
+      className={cn("not-last:border-b data-open:bg-muted/50", className)}
+      {...props}
+    />
+  )
+}
+
+function AccordionTrigger({
+  className,
+  children,
+  ...props
+}: AccordionPrimitive.Trigger.Props) {
+  return (
+    <AccordionPrimitive.Header className="flex">
+      <AccordionPrimitive.Trigger
+        data-slot="accordion-trigger"
+        className={cn(
+          "group/accordion-trigger relative flex flex-1 items-start justify-between gap-6 border border-transparent p-4 text-left text-sm font-medium transition-all outline-none hover:underline aria-disabled:pointer-events-none aria-disabled:opacity-50 **:data-[slot=accordion-trigger-icon]:ml-auto **:data-[slot=accordion-trigger-icon]:size-4 **:data-[slot=accordion-trigger-icon]:text-muted-foreground",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <HugeiconsIcon icon={ArrowDown01Icon} strokeWidth={2} data-slot="accordion-trigger-icon" className="pointer-events-none shrink-0 group-aria-expanded/accordion-trigger:hidden" />
+        <HugeiconsIcon icon={ArrowUp01Icon} strokeWidth={2} data-slot="accordion-trigger-icon" className="pointer-events-none hidden shrink-0 group-aria-expanded/accordion-trigger:inline" />
+      </AccordionPrimitive.Trigger>
+    </AccordionPrimitive.Header>
+  )
+}
+
+function AccordionContent({
+  className,
+  children,
+  ...props
+}: AccordionPrimitive.Panel.Props) {
+  return (
+    <AccordionPrimitive.Panel
+      data-slot="accordion-content"
+      className="overflow-hidden px-4 text-sm data-open:animate-accordion-down data-closed:animate-accordion-up"
+      {...props}
+    >
+      <div
+        className={cn(
+          "h-(--accordion-panel-height) pt-0 pb-4 data-ending-style:h-0 data-starting-style:h-0 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4",
+          className
+        )}
+      >
+        {children}
+      </div>
+    </AccordionPrimitive.Panel>
+  )
+}
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent }
diff --git a/packages/web/src/components/ui/alert-dialog.tsx b/packages/web/src/components/ui/alert-dialog.tsx
new file mode 100644
index 0000000..d7f9f66
--- /dev/null
+++ b/packages/web/src/components/ui/alert-dialog.tsx
@@ -0,0 +1,187 @@
+"use client"
+
+import * as React from "react"
+import { AlertDialog as AlertDialogPrimitive } from "@base-ui/react/alert-dialog"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+
+function AlertDialog({ ...props }: AlertDialogPrimitive.Root.Props) {
+  return <AlertDialogPrimitive.Root data-slot="alert-dialog" {...props} />
+}
+
+function AlertDialogTrigger({ ...props }: AlertDialogPrimitive.Trigger.Props) {
+  return (
+    <AlertDialogPrimitive.Trigger data-slot="alert-dialog-trigger" {...props} />
+  )
+}
+
+function AlertDialogPortal({ ...props }: AlertDialogPrimitive.Portal.Props) {
+  return (
+    <AlertDialogPrimitive.Portal data-slot="alert-dialog-portal" {...props} />
+  )
+}
+
+function AlertDialogOverlay({
+  className,
+  ...props
+}: AlertDialogPrimitive.Backdrop.Props) {
+  return (
+    <AlertDialogPrimitive.Backdrop
+      data-slot="alert-dialog-overlay"
+      className={cn(
+        "fixed inset-0 isolate z-50 bg-black/30 duration-100 supports-backdrop-filter:backdrop-blur-sm data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogContent({
+  className,
+  size = "default",
+  ...props
+}: AlertDialogPrimitive.Popup.Props & {
+  size?: "default" | "sm"
+}) {
+  return (
+    <AlertDialogPortal>
+      <AlertDialogOverlay />
+      <AlertDialogPrimitive.Popup
+        data-slot="alert-dialog-content"
+        data-size={size}
+        className={cn(
+          "group/alert-dialog-content fixed top-1/2 left-1/2 z-50 grid w-full -translate-x-1/2 -translate-y-1/2 gap-6 rounded-[min(var(--radius-4xl),24px)] bg-popover p-6 text-popover-foreground shadow-xl ring-1 ring-foreground/5 duration-100 outline-none data-[size=default]:max-w-xs data-[size=sm]:max-w-xs data-[size=default]:sm:max-w-md dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+          className
+        )}
+        {...props}
+      />
+    </AlertDialogPortal>
+  )
+}
+
+function AlertDialogHeader({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-dialog-header"
+      className={cn(
+        "grid grid-rows-[auto_1fr] place-items-center gap-1.5 text-center has-data-[slot=alert-dialog-media]:grid-rows-[auto_auto_1fr] has-data-[slot=alert-dialog-media]:gap-x-6 sm:group-data-[size=default]/alert-dialog-content:place-items-start sm:group-data-[size=default]/alert-dialog-content:text-left sm:group-data-[size=default]/alert-dialog-content:has-data-[slot=alert-dialog-media]:grid-rows-[auto_1fr]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogFooter({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-dialog-footer"
+      className={cn(
+        "flex flex-col-reverse gap-2 group-data-[size=sm]/alert-dialog-content:grid group-data-[size=sm]/alert-dialog-content:grid-cols-2 sm:flex-row sm:justify-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogMedia({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-dialog-media"
+      className={cn(
+        "mb-2 inline-flex size-16 items-center justify-center rounded-full bg-muted sm:group-data-[size=default]/alert-dialog-content:row-span-2 *:[svg:not([class*='size-'])]:size-8",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Title>) {
+  return (
+    <AlertDialogPrimitive.Title
+      data-slot="alert-dialog-title"
+      className={cn(
+        "font-heading text-lg font-medium sm:group-data-[size=default]/alert-dialog-content:group-has-data-[slot=alert-dialog-media]/alert-dialog-content:col-start-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Description>) {
+  return (
+    <AlertDialogPrimitive.Description
+      data-slot="alert-dialog-description"
+      className={cn(
+        "text-sm text-balance text-muted-foreground md:text-pretty *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogAction({
+  className,
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  return (
+    <Button
+      data-slot="alert-dialog-action"
+      className={cn(className)}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogCancel({
+  className,
+  variant = "outline",
+  size = "default",
+  ...props
+}: AlertDialogPrimitive.Close.Props &
+  Pick<React.ComponentProps<typeof Button>, "variant" | "size">) {
+  return (
+    <AlertDialogPrimitive.Close
+      data-slot="alert-dialog-cancel"
+      className={cn(className)}
+      render={<Button variant={variant} size={size} />}
+      {...props}
+    />
+  )
+}
+
+export {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogMedia,
+  AlertDialogOverlay,
+  AlertDialogPortal,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+}
diff --git a/packages/web/src/components/ui/alert.tsx b/packages/web/src/components/ui/alert.tsx
new file mode 100644
index 0000000..b9f98e5
--- /dev/null
+++ b/packages/web/src/components/ui/alert.tsx
@@ -0,0 +1,76 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const alertVariants = cva(
+  "group/alert relative grid w-full gap-0.5 rounded-2xl border px-4 py-3 text-left text-sm has-data-[slot=alert-action]:relative has-data-[slot=alert-action]:pr-18 has-[>svg]:grid-cols-[auto_1fr] has-[>svg]:gap-x-2.5 *:[svg]:row-span-2 *:[svg]:translate-y-0.5 *:[svg]:text-current *:[svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: "bg-card text-card-foreground",
+        destructive:
+          "bg-card text-destructive *:data-[slot=alert-description]:text-destructive/90 *:[svg]:text-current",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function Alert({
+  className,
+  variant,
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>) {
+  return (
+    <div
+      data-slot="alert"
+      role="alert"
+      className={cn(alertVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}
+
+function AlertTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-title"
+      className={cn(
+        "font-medium group-has-[>svg]/alert:col-start-2 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDescription({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-description"
+      className={cn(
+        "text-sm text-balance text-muted-foreground md:text-pretty [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertAction({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-action"
+      className={cn("absolute top-2.5 right-3", className)}
+      {...props}
+    />
+  )
+}
+
+export { Alert, AlertTitle, AlertDescription, AlertAction }
diff --git a/packages/web/src/components/ui/aspect-ratio.tsx b/packages/web/src/components/ui/aspect-ratio.tsx
new file mode 100644
index 0000000..4c0ebaa
--- /dev/null
+++ b/packages/web/src/components/ui/aspect-ratio.tsx
@@ -0,0 +1,22 @@
+import { cn } from "@/lib/utils"
+
+function AspectRatio({
+  ratio,
+  className,
+  ...props
+}: React.ComponentProps<"div"> & { ratio: number }) {
+  return (
+    <div
+      data-slot="aspect-ratio"
+      style={
+        {
+          "--ratio": ratio,
+        } as React.CSSProperties
+      }
+      className={cn("relative aspect-(--ratio)", className)}
+      {...props}
+    />
+  )
+}
+
+export { AspectRatio }
diff --git a/packages/web/src/components/ui/attachment.tsx b/packages/web/src/components/ui/attachment.tsx
new file mode 100644
index 0000000..7c44bd9
--- /dev/null
+++ b/packages/web/src/components/ui/attachment.tsx
@@ -0,0 +1,207 @@
+import * as React from "react"
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+
+const attachmentVariants = cva(
+  "group/attachment relative flex w-fit max-w-full min-w-0 shrink-0 flex-wrap rounded-2xl border bg-card text-card-foreground transition-colors focus-within:ring-1 focus-within:ring-ring/30 has-[>a,>button]:hover:bg-muted/50 data-[state=error]:border-destructive/30 data-[state=idle]:border-dashed",
+  {
+    variants: {
+      size: {
+        default:
+          "gap-2 text-sm has-data-[slot=attachment-content]:px-2.5 has-data-[slot=attachment-content]:py-2 has-data-[slot=attachment-media]:p-2",
+        sm: "gap-2.5 text-xs has-data-[slot=attachment-content]:px-2 has-data-[slot=attachment-content]:py-1.5 has-data-[slot=attachment-media]:p-1.5",
+        xs: "gap-1.5 rounded-xl text-xs has-data-[slot=attachment-content]:px-1.5 has-data-[slot=attachment-content]:py-1 has-data-[slot=attachment-media]:p-1",
+      },
+      orientation: {
+        horizontal: "min-w-40 items-center",
+        vertical: "w-24 flex-col has-data-[slot=attachment-content]:w-30",
+      },
+    },
+  }
+)
+
+function Attachment({
+  className,
+  state = "done",
+  size = "default",
+  orientation = "horizontal",
+  ...props
+}: React.ComponentProps<"div"> &
+  VariantProps<typeof attachmentVariants> & {
+    state?: "idle" | "uploading" | "processing" | "error" | "done"
+  }) {
+  return (
+    <div
+      data-slot="attachment"
+      data-state={state}
+      data-size={size}
+      data-orientation={orientation}
+      className={cn(attachmentVariants({ size, orientation }), className)}
+      {...props}
+    />
+  )
+}
+
+const attachmentMediaVariants = cva(
+  "relative flex aspect-square w-10 shrink-0 items-center justify-center overflow-hidden rounded-lg bg-muted text-foreground group-data-[orientation=vertical]/attachment:w-full group-data-[size=sm]/attachment:w-8 group-data-[size=xs]/attachment:w-7 group-data-[size=xs]/attachment:rounded-md group-data-[state=error]/attachment:bg-destructive/10 group-data-[state=error]/attachment:text-destructive group-data-[orientation=vertical]/attachment:*:data-[slot=spinner]:size-6! [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 group-data-[orientation=vertical]/attachment:[&_svg:not([class*='size-'])]:size-6 group-data-[size=xs]/attachment:[&_svg:not([class*='size-'])]:size-3.5",
+  {
+    variants: {
+      variant: {
+        icon: "",
+        image:
+          "opacity-60 group-data-[state=done]/attachment:opacity-100 group-data-[state=idle]/attachment:opacity-100 *:[img]:aspect-square *:[img]:w-full *:[img]:object-cover",
+      },
+    },
+    defaultVariants: {
+      variant: "icon",
+    },
+  }
+)
+
+function AttachmentMedia({
+  className,
+  variant = "icon",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof attachmentMediaVariants>) {
+  return (
+    <div
+      data-slot="attachment-media"
+      data-variant={variant}
+      className={cn(attachmentMediaVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}
+
+function AttachmentContent({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="attachment-content"
+      className={cn(
+        "max-w-full min-w-0 flex-1 leading-tight group-data-[orientation=vertical]/attachment:px-1",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AttachmentTitle({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="attachment-title"
+      className={cn(
+        "block max-w-full min-w-0 truncate font-medium group-data-[state=processing]/attachment:shimmer group-data-[state=uploading]/attachment:shimmer",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AttachmentDescription({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="attachment-description"
+      className={cn(
+        "mt-0.5 block min-w-0 truncate text-xs text-muted-foreground group-data-[state=error]/attachment:text-destructive/80",
+        "max-w-full",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AttachmentActions({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="attachment-actions"
+      className={cn(
+        "relative z-20 flex shrink-0 items-center group-data-[orientation=vertical]/attachment:absolute group-data-[orientation=vertical]/attachment:top-3 group-data-[orientation=vertical]/attachment:right-3 group-data-[orientation=vertical]/attachment:gap-1",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AttachmentAction({
+  className,
+  variant,
+  size = "icon-xs",
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  return (
+    <Button
+      data-slot="attachment-action"
+      variant={variant ?? "ghost"}
+      size={size}
+      className={cn(className)}
+      {...props}
+    />
+  )
+}
+
+function AttachmentTrigger({
+  className,
+  render,
+  type,
+  ...props
+}: useRender.ComponentProps<"button">) {
+  return useRender({
+    defaultTagName: "button",
+    props: mergeProps<"button">(
+      {
+        type: render ? type : (type ?? "button"),
+        className: cn("absolute inset-0 z-10 outline-none", className),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "attachment-trigger",
+    },
+  })
+}
+
+function AttachmentGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="attachment-group"
+      className={cn(
+        "flex min-w-0 scroll-fade-x snap-x snap-mandatory scroll-px-1 scrollbar-none gap-3 overflow-x-auto overscroll-x-contain py-1 *:data-[slot=attachment]:flex-none *:data-[slot=attachment]:snap-start",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Attachment,
+  AttachmentGroup,
+  AttachmentMedia,
+  AttachmentContent,
+  AttachmentTitle,
+  AttachmentDescription,
+  AttachmentActions,
+  AttachmentAction,
+  AttachmentTrigger,
+}
diff --git a/packages/web/src/components/ui/avatar.tsx b/packages/web/src/components/ui/avatar.tsx
new file mode 100644
index 0000000..e92a2f4
--- /dev/null
+++ b/packages/web/src/components/ui/avatar.tsx
@@ -0,0 +1,107 @@
+import * as React from "react"
+import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"
+
+import { cn } from "@/lib/utils"
+
+function Avatar({
+  className,
+  size = "default",
+  ...props
+}: AvatarPrimitive.Root.Props & {
+  size?: "default" | "sm" | "lg"
+}) {
+  return (
+    <AvatarPrimitive.Root
+      data-slot="avatar"
+      data-size={size}
+      className={cn(
+        "group/avatar relative flex size-8 shrink-0 rounded-full select-none after:absolute after:inset-0 after:rounded-full after:border after:border-border after:mix-blend-darken data-[size=lg]:size-10 data-[size=sm]:size-6 dark:after:mix-blend-lighten",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props) {
+  return (
+    <AvatarPrimitive.Image
+      data-slot="avatar-image"
+      className={cn(
+        "aspect-square size-full rounded-full object-cover",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarFallback({
+  className,
+  ...props
+}: AvatarPrimitive.Fallback.Props) {
+  return (
+    <AvatarPrimitive.Fallback
+      data-slot="avatar-fallback"
+      className={cn(
+        "flex size-full items-center justify-center rounded-full bg-muted text-sm text-muted-foreground group-data-[size=sm]/avatar:text-xs",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="avatar-badge"
+      className={cn(
+        "absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground bg-blend-color ring-2 ring-background select-none",
+        "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",
+        "group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2",
+        "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="avatar-group"
+      className={cn(
+        "group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarGroupCount({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="avatar-group-count"
+      className={cn(
+        "relative flex size-8 shrink-0 items-center justify-center rounded-full bg-muted text-sm text-muted-foreground ring-2 ring-background group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarBadge,
+}
diff --git a/packages/web/src/components/ui/badge.tsx b/packages/web/src/components/ui/badge.tsx
new file mode 100644
index 0000000..6d49b91
--- /dev/null
+++ b/packages/web/src/components/ui/badge.tsx
@@ -0,0 +1,52 @@
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const badgeVariants = cva(
+  "group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-2xl border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-all focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3!",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground [a]:hover:bg-primary/80",
+        secondary:
+          "bg-secondary text-secondary-foreground [a]:hover:bg-secondary/80",
+        destructive:
+          "bg-destructive/10 text-destructive focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:focus-visible:ring-destructive/40 [a]:hover:bg-destructive/20",
+        outline:
+          "border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground",
+        ghost:
+          "hover:bg-muted hover:text-muted-foreground dark:hover:bg-muted/50",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function Badge({
+  className,
+  variant = "default",
+  render,
+  ...props
+}: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>) {
+  return useRender({
+    defaultTagName: "span",
+    props: mergeProps<"span">(
+      {
+        className: cn(badgeVariants({ variant }), className),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "badge",
+      variant,
+    },
+  })
+}
+
+export { Badge, badgeVariants }
diff --git a/packages/web/src/components/ui/breadcrumb.tsx b/packages/web/src/components/ui/breadcrumb.tsx
new file mode 100644
index 0000000..4a5b3c0
--- /dev/null
+++ b/packages/web/src/components/ui/breadcrumb.tsx
@@ -0,0 +1,125 @@
+import * as React from "react"
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+
+import { cn } from "@/lib/utils"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { ArrowRight01Icon, MoreHorizontalCircle01Icon } from "@hugeicons/core-free-icons"
+
+function Breadcrumb({ className, ...props }: React.ComponentProps<"nav">) {
+  return (
+    <nav
+      aria-label="breadcrumb"
+      data-slot="breadcrumb"
+      className={cn(className)}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
+  return (
+    <ol
+      data-slot="breadcrumb-list"
+      className={cn(
+        "flex flex-wrap items-center gap-1.5 text-sm wrap-break-word text-muted-foreground sm:gap-2.5",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="breadcrumb-item"
+      className={cn("inline-flex items-center gap-1.5", className)}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbLink({
+  className,
+  render,
+  ...props
+}: useRender.ComponentProps<"a">) {
+  return useRender({
+    defaultTagName: "a",
+    props: mergeProps<"a">(
+      {
+        className: cn("transition-colors hover:text-foreground", className),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "breadcrumb-link",
+    },
+  })
+}
+
+function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="breadcrumb-page"
+      role="link"
+      aria-disabled="true"
+      aria-current="page"
+      className={cn("font-normal text-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbSeparator({
+  children,
+  className,
+  ...props
+}: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="breadcrumb-separator"
+      role="presentation"
+      aria-hidden="true"
+      className={cn("[&>svg]:size-3.5", className)}
+      {...props}
+    >
+      {children ?? (
+        <HugeiconsIcon icon={ArrowRight01Icon} strokeWidth={2} />
+      )}
+    </li>
+  )
+}
+
+function BreadcrumbEllipsis({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="breadcrumb-ellipsis"
+      role="presentation"
+      aria-hidden="true"
+      className={cn(
+        "flex size-5 items-center justify-center [&>svg]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <HugeiconsIcon icon={MoreHorizontalCircle01Icon} strokeWidth={2} />
+      <span className="sr-only">More</span>
+    </span>
+  )
+}
+
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+}
diff --git a/packages/web/src/components/ui/bubble.tsx b/packages/web/src/components/ui/bubble.tsx
new file mode 100644
index 0000000..8ac3330
--- /dev/null
+++ b/packages/web/src/components/ui/bubble.tsx
@@ -0,0 +1,128 @@
+import * as React from "react"
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+function BubbleGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="bubble-group"
+      className={cn("flex min-w-0 flex-col gap-2", className)}
+      {...props}
+    />
+  )
+}
+
+const bubbleVariants = cva(
+  "group/bubble relative flex w-fit max-w-[80%] min-w-0 flex-col gap-1 group-data-[align=end]/message:self-end data-[align=end]:self-end data-[variant=ghost]:max-w-full",
+  {
+    variants: {
+      variant: {
+        default:
+          "*:data-[slot=bubble-content]:bg-primary *:data-[slot=bubble-content]:text-primary-foreground [&>[data-slot=bubble-content]:is(button,a):hover]:bg-primary/80",
+        secondary:
+          "*:data-[slot=bubble-content]:bg-secondary *:data-[slot=bubble-content]:text-secondary-foreground [&>[data-slot=bubble-content]:is(button,a):hover]:bg-[color-mix(in_oklch,var(--secondary),var(--foreground)_5%)]",
+        muted:
+          "*:data-[slot=bubble-content]:bg-muted [&>[data-slot=bubble-content]:is(button,a):hover]:bg-[color-mix(in_oklch,var(--muted),var(--foreground)_5%)]",
+        tinted:
+          "*:data-[slot=bubble-content]:bg-[oklch(from_var(--primary)_0.93_calc(c*0.4)_h)] *:data-[slot=bubble-content]:text-foreground dark:*:data-[slot=bubble-content]:bg-[oklch(from_var(--primary)_0.3_calc(c*0.4)_h)] [&>[data-slot=bubble-content]:is(button,a):hover]:bg-[oklch(from_var(--primary)_0.88_calc(c*0.5)_h)] dark:[&>[data-slot=bubble-content]:is(button,a):hover]:bg-[oklch(from_var(--primary)_0.35_calc(c*0.5)_h)]",
+        outline:
+          "*:data-[slot=bubble-content]:border-border *:data-[slot=bubble-content]:bg-background [&>[data-slot=bubble-content]:is(button,a):hover]:bg-muted [&>[data-slot=bubble-content]:is(button,a):hover]:text-foreground dark:[&>[data-slot=bubble-content]:is(button,a):hover]:bg-input/30",
+        ghost:
+          "border-none *:data-[slot=bubble-content]:rounded-none *:data-[slot=bubble-content]:bg-transparent *:data-[slot=bubble-content]:p-0 [&>[data-slot=bubble-content]:is(button,a):hover]:bg-muted [&>[data-slot=bubble-content]:is(button,a):hover]:text-foreground dark:[&>[data-slot=bubble-content]:is(button,a):hover]:bg-muted/50",
+        destructive:
+          "*:data-[slot=bubble-content]:bg-destructive/10 *:data-[slot=bubble-content]:text-destructive dark:*:data-[slot=bubble-content]:bg-destructive/20 [&>[data-slot=bubble-content]:is(button,a):hover]:bg-destructive/20 dark:[&>[data-slot=bubble-content]:is(button,a):hover]:bg-destructive/30",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function Bubble({
+  variant = "default",
+  align = "start",
+  className,
+  ...props
+}: React.ComponentProps<"div"> &
+  VariantProps<typeof bubbleVariants> & {
+    align?: "start" | "end"
+  }) {
+  return (
+    <div
+      data-slot="bubble"
+      data-variant={variant}
+      data-align={align}
+      className={cn(bubbleVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}
+
+function BubbleContent({
+  className,
+  render,
+  ...props
+}: useRender.ComponentProps<"div">) {
+  return useRender({
+    defaultTagName: "div",
+    props: mergeProps<"div">(
+      {
+        className: cn(
+          "w-fit max-w-full min-w-0 overflow-hidden rounded-3xl border border-transparent px-3 py-2.5 text-sm leading-relaxed wrap-break-word group-data-[align=end]/bubble:self-end [button]:text-left [button,a]:transition-colors [button,a]:outline-none [button,a]:focus-visible:border-ring [button,a]:focus-visible:ring-3 [button,a]:focus-visible:ring-ring/30",
+          className
+        ),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "bubble-content",
+    },
+  })
+}
+
+const bubbleReactionsVariants = cva(
+  "absolute z-10 flex w-fit shrink-0 items-center justify-center gap-1 rounded-full bg-muted px-1.5 py-0.5 text-sm ring-3 ring-card has-[button]:p-0",
+  {
+    variants: {
+      side: {
+        top: "top-0 -translate-y-3/4",
+        bottom: "bottom-0 translate-y-3/4",
+      },
+      align: {
+        start: "left-3",
+        end: "right-3",
+      },
+    },
+    defaultVariants: {
+      side: "bottom",
+      align: "end",
+    },
+  }
+)
+
+function BubbleReactions({
+  side = "bottom",
+  align = "end",
+  className,
+  ...props
+}: React.ComponentProps<"div"> & {
+  align?: "start" | "end"
+  side?: "top" | "bottom"
+}) {
+  return (
+    <div
+      data-slot="bubble-reactions"
+      data-align={align}
+      data-side={side}
+      className={cn(bubbleReactionsVariants({ side, align }), className)}
+      {...props}
+    />
+  )
+}
+
+export { BubbleGroup, Bubble, BubbleContent, BubbleReactions }
diff --git a/packages/web/src/components/ui/button-group.tsx b/packages/web/src/components/ui/button-group.tsx
new file mode 100644
index 0000000..5298614
--- /dev/null
+++ b/packages/web/src/components/ui/button-group.tsx
@@ -0,0 +1,87 @@
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { Separator } from "@/components/ui/separator"
+
+const buttonGroupVariants = cva(
+  "flex w-fit items-stretch *:focus-visible:relative *:focus-visible:z-10 has-[>[data-slot=button-group]]:gap-2 has-[>[data-variant=outline]]:*:data-[slot=input-group]:border-border has-[>[data-variant=outline]]:*:data-[slot=select-trigger]:border-border has-[>[data-variant=outline]]:[&>[data-slot=input-group]:has(:focus-visible)]:border-ring has-[>[data-variant=outline]]:[&>[data-slot=select-trigger]:focus-visible]:border-ring has-[select[aria-hidden=true]:last-child]:[&>[data-slot=select-trigger]:last-of-type]:rounded-r-2xl [&>[data-slot=select-trigger]:not([class*='w-'])]:w-fit [&>input]:flex-1 has-[>[data-variant=outline]]:[&>input]:border-border has-[>[data-variant=outline]]:[&>input:focus-visible]:border-ring",
+  {
+    variants: {
+      orientation: {
+        horizontal:
+          "*:data-slot:rounded-r-none [&>[data-slot]:not(:has(~[data-slot]))]:rounded-r-2xl! [&>[data-slot]~[data-slot]]:rounded-l-none [&>[data-slot]~[data-slot]]:border-l-0",
+        vertical:
+          "flex-col *:data-slot:rounded-b-none [&>[data-slot]:not(:has(~[data-slot]))]:rounded-b-2xl! [&>[data-slot]~[data-slot]]:rounded-t-none [&>[data-slot]~[data-slot]]:border-t-0",
+      },
+    },
+    defaultVariants: {
+      orientation: "horizontal",
+    },
+  }
+)
+
+function ButtonGroup({
+  className,
+  orientation,
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof buttonGroupVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="button-group"
+      data-orientation={orientation}
+      className={cn(buttonGroupVariants({ orientation }), className)}
+      {...props}
+    />
+  )
+}
+
+function ButtonGroupText({
+  className,
+  render,
+  ...props
+}: useRender.ComponentProps<"div">) {
+  return useRender({
+    defaultTagName: "div",
+    props: mergeProps<"div">(
+      {
+        className: cn(
+          "flex items-center gap-2 rounded-2xl border bg-muted px-2.5 text-sm font-medium [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+          className
+        ),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "button-group-text",
+    },
+  })
+}
+
+function ButtonGroupSeparator({
+  className,
+  orientation = "vertical",
+  ...props
+}: React.ComponentProps<typeof Separator>) {
+  return (
+    <Separator
+      data-slot="button-group-separator"
+      orientation={orientation}
+      className={cn(
+        "relative self-stretch bg-input data-horizontal:mx-px data-horizontal:w-auto data-vertical:my-px data-vertical:h-auto",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  ButtonGroup,
+  ButtonGroupSeparator,
+  ButtonGroupText,
+  buttonGroupVariants,
+}
diff --git a/packages/web/src/components/ui/button.tsx b/packages/web/src/components/ui/button.tsx
new file mode 100644
index 0000000..e87e24d
--- /dev/null
+++ b/packages/web/src/components/ui/button.tsx
@@ -0,0 +1,56 @@
+import { Button as ButtonPrimitive } from "@base-ui/react/button"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva(
+  "group/button inline-flex shrink-0 items-center justify-center rounded-2xl border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/80",
+        outline:
+          "border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:bg-transparent dark:hover:bg-input/30",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-[color-mix(in_oklch,var(--secondary),var(--foreground)_5%)] aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
+        ghost:
+          "hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
+        destructive:
+          "bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default:
+          "h-8 gap-1.5 px-3 has-data-[icon=inline-end]:pr-2.5 has-data-[icon=inline-start]:pl-2.5",
+        xs: "h-6 gap-1 px-2.5 text-xs has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2 [&_svg:not([class*='size-'])]:size-3",
+        sm: "h-7 gap-1 px-3 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        lg: "h-9 gap-1.5 px-4 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3",
+        icon: "size-8",
+        "icon-xs": "size-6 [&_svg:not([class*='size-'])]:size-3",
+        "icon-sm": "size-7",
+        "icon-lg": "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function Button({
+  className,
+  variant = "default",
+  size = "default",
+  ...props
+}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>) {
+  return (
+    <ButtonPrimitive
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+}
+
+export { Button, buttonVariants }
diff --git a/packages/web/src/components/ui/calendar.tsx b/packages/web/src/components/ui/calendar.tsx
new file mode 100644
index 0000000..19f000f
--- /dev/null
+++ b/packages/web/src/components/ui/calendar.tsx
@@ -0,0 +1,220 @@
+import * as React from "react"
+import {
+  DayPicker,
+  getDefaultClassNames,
+  type DayButton,
+  type Locale,
+} from "react-day-picker"
+
+import { cn } from "@/lib/utils"
+import { Button, buttonVariants } from "@/components/ui/button"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { ArrowLeftIcon, ArrowRightIcon, ArrowDownIcon } from "@hugeicons/core-free-icons"
+
+function Calendar({
+  className,
+  classNames,
+  showOutsideDays = true,
+  captionLayout = "label",
+  buttonVariant = "ghost",
+  locale,
+  formatters,
+  components,
+  ...props
+}: React.ComponentProps<typeof DayPicker> & {
+  buttonVariant?: React.ComponentProps<typeof Button>["variant"]
+}) {
+  const defaultClassNames = getDefaultClassNames()
+
+  return (
+    <DayPicker
+      showOutsideDays={showOutsideDays}
+      className={cn(
+        "group/calendar bg-background p-3 [--cell-radius:var(--radius-2xl)] [--cell-size:--spacing(8)] in-data-[slot=card-content]:bg-transparent in-data-[slot=popover-content]:bg-transparent",
+        String.raw`rtl:**:[.rdp-button\_next>svg]:rotate-180`,
+        String.raw`rtl:**:[.rdp-button\_previous>svg]:rotate-180`,
+        className
+      )}
+      captionLayout={captionLayout}
+      locale={locale}
+      formatters={{
+        formatMonthDropdown: (date) =>
+          date.toLocaleString(locale?.code, { month: "short" }),
+        ...formatters,
+      }}
+      classNames={{
+        root: cn("w-fit", defaultClassNames.root),
+        months: cn(
+          "relative flex flex-col gap-4 md:flex-row",
+          defaultClassNames.months
+        ),
+        month: cn("flex w-full flex-col gap-4", defaultClassNames.month),
+        nav: cn(
+          "absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1",
+          defaultClassNames.nav
+        ),
+        button_previous: cn(
+          buttonVariants({ variant: buttonVariant }),
+          "size-(--cell-size) p-0 select-none aria-disabled:opacity-50",
+          defaultClassNames.button_previous
+        ),
+        button_next: cn(
+          buttonVariants({ variant: buttonVariant }),
+          "size-(--cell-size) p-0 select-none aria-disabled:opacity-50",
+          defaultClassNames.button_next
+        ),
+        month_caption: cn(
+          "flex h-(--cell-size) w-full items-center justify-center px-(--cell-size)",
+          defaultClassNames.month_caption
+        ),
+        dropdowns: cn(
+          "flex h-(--cell-size) w-full items-center justify-center gap-1.5 text-sm font-medium",
+          defaultClassNames.dropdowns
+        ),
+        dropdown_root: cn(
+          "relative rounded-(--cell-radius)",
+          defaultClassNames.dropdown_root
+        ),
+        dropdown: cn(
+          "absolute inset-0 bg-popover opacity-0",
+          defaultClassNames.dropdown
+        ),
+        caption_label: cn(
+          "font-medium select-none",
+          captionLayout === "label"
+            ? "text-sm"
+            : "flex items-center gap-1 rounded-(--cell-radius) text-sm [&>svg]:size-3.5 [&>svg]:text-muted-foreground",
+          defaultClassNames.caption_label
+        ),
+        month_grid: cn("w-full border-collapse", defaultClassNames.month_grid),
+        weekdays: cn("flex", defaultClassNames.weekdays),
+        weekday: cn(
+          "flex-1 rounded-(--cell-radius) text-[0.8rem] font-normal text-muted-foreground select-none",
+          defaultClassNames.weekday
+        ),
+        week: cn("mt-2 flex w-full", defaultClassNames.week),
+        week_number_header: cn(
+          "w-(--cell-size) select-none",
+          defaultClassNames.week_number_header
+        ),
+        week_number: cn(
+          "text-[0.8rem] text-muted-foreground select-none",
+          defaultClassNames.week_number
+        ),
+        day: cn(
+          "group/day relative aspect-square h-full w-full rounded-(--cell-radius) p-0 text-center select-none [&:last-child[data-selected=true]_button]:rounded-r-(--cell-radius)",
+          props.showWeekNumber
+            ? "[&:nth-child(2)[data-selected=true]_button]:rounded-l-(--cell-radius)"
+            : "[&:first-child[data-selected=true]_button]:rounded-l-(--cell-radius)",
+          defaultClassNames.day
+        ),
+        range_start: cn(
+          "relative isolate z-0 rounded-l-(--cell-radius) bg-muted after:absolute after:inset-y-0 after:right-0 after:w-4 after:bg-muted",
+          defaultClassNames.range_start
+        ),
+        range_middle: cn("rounded-none", defaultClassNames.range_middle),
+        range_end: cn(
+          "relative isolate z-0 rounded-r-(--cell-radius) bg-muted after:absolute after:inset-y-0 after:left-0 after:w-4 after:bg-muted",
+          defaultClassNames.range_end
+        ),
+        today: cn(
+          "rounded-(--cell-radius) bg-muted text-foreground data-[selected=true]:rounded-none",
+          defaultClassNames.today
+        ),
+        outside: cn(
+          "text-muted-foreground aria-selected:text-muted-foreground",
+          defaultClassNames.outside
+        ),
+        disabled: cn(
+          "text-muted-foreground opacity-50",
+          defaultClassNames.disabled
+        ),
+        hidden: cn("invisible", defaultClassNames.hidden),
+        ...classNames,
+      }}
+      components={{
+        Root: ({ className, rootRef, ...props }) => {
+          return (
+            <div
+              data-slot="calendar"
+              ref={rootRef}
+              className={cn(className)}
+              {...props}
+            />
+          )
+        },
+        Chevron: ({ className, orientation, ...props }) => {
+          if (orientation === "left") {
+            return (
+              <HugeiconsIcon icon={ArrowLeftIcon} strokeWidth={2} className={cn("size-4", className)} {...props} />
+            )
+          }
+
+          if (orientation === "right") {
+            return (
+              <HugeiconsIcon icon={ArrowRightIcon} strokeWidth={2} className={cn("size-4", className)} {...props} />
+            )
+          }
+
+          return (
+            <HugeiconsIcon icon={ArrowDownIcon} strokeWidth={2} className={cn("size-4", className)} {...props} />
+          )
+        },
+        DayButton: ({ ...props }) => (
+          <CalendarDayButton locale={locale} {...props} />
+        ),
+        WeekNumber: ({ children, ...props }) => {
+          return (
+            <td {...props}>
+              <div className="flex size-(--cell-size) items-center justify-center text-center">
+                {children}
+              </div>
+            </td>
+          )
+        },
+        ...components,
+      }}
+      {...props}
+    />
+  )
+}
+
+function CalendarDayButton({
+  className,
+  day,
+  modifiers,
+  locale,
+  ...props
+}: React.ComponentProps<typeof DayButton> & { locale?: Partial<Locale> }) {
+  const defaultClassNames = getDefaultClassNames()
+
+  const ref = React.useRef<HTMLButtonElement>(null)
+  React.useEffect(() => {
+    if (modifiers.focused) ref.current?.focus()
+  }, [modifiers.focused])
+
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      data-day={day.date.toLocaleDateString(locale?.code)}
+      data-selected-single={
+        modifiers.selected &&
+        !modifiers.range_start &&
+        !modifiers.range_end &&
+        !modifiers.range_middle
+      }
+      data-range-start={modifiers.range_start}
+      data-range-end={modifiers.range_end}
+      data-range-middle={modifiers.range_middle}
+      className={cn(
+        "relative isolate z-10 flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 border-0 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-ring/50 data-[range-end=true]:rounded-(--cell-radius) data-[range-end=true]:rounded-r-(--cell-radius) data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-muted data-[range-middle=true]:text-foreground data-[range-start=true]:rounded-(--cell-radius) data-[range-start=true]:rounded-l-(--cell-radius) data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-foreground [&>span]:text-xs [&>span]:opacity-70",
+        defaultClassNames.day,
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Calendar, CalendarDayButton }
diff --git a/packages/web/src/components/ui/card.tsx b/packages/web/src/components/ui/card.tsx
new file mode 100644
index 0000000..1137b40
--- /dev/null
+++ b/packages/web/src/components/ui/card.tsx
@@ -0,0 +1,100 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Card({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<"div"> & { size?: "default" | "sm" }) {
+  return (
+    <div
+      data-slot="card"
+      data-size={size}
+      className={cn(
+        "group/card flex flex-col gap-(--card-spacing) overflow-hidden rounded-[min(var(--radius-4xl),24px)] bg-card py-(--card-spacing) text-sm text-card-foreground shadow-sm ring-1 ring-foreground/5 [--card-spacing:--spacing(5)] has-[>img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(4)] dark:ring-foreground/10 *:[img:first-child]:rounded-t-[min(var(--radius-4xl),24px)] *:[img:last-child]:rounded-b-[min(var(--radius-4xl),24px)]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "group/card-header @container/card-header grid auto-rows-min items-start gap-1.5 rounded-t-[min(var(--radius-4xl),24px)] px-(--card-spacing) has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-(--card-spacing)",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn("font-heading text-base font-medium", className)}
+      {...props}
+    />
+  )
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn(
+        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-(--card-spacing)", className)}
+      {...props}
+    />
+  )
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn(
+        "flex items-center rounded-b-[min(var(--radius-4xl),24px)] px-(--card-spacing) [.border-t]:pt-(--card-spacing)",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardAction,
+  CardDescription,
+  CardContent,
+}
diff --git a/packages/web/src/components/ui/carousel.tsx b/packages/web/src/components/ui/carousel.tsx
new file mode 100644
index 0000000..139105f
--- /dev/null
+++ b/packages/web/src/components/ui/carousel.tsx
@@ -0,0 +1,243 @@
+"use client"
+
+import * as React from "react"
+import useEmblaCarousel, {
+  type UseEmblaCarouselType,
+} from "embla-carousel-react"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { ArrowLeft01Icon, ArrowRight01Icon } from "@hugeicons/core-free-icons"
+
+type CarouselApi = UseEmblaCarouselType[1]
+type UseCarouselParameters = Parameters<typeof useEmblaCarousel>
+type CarouselOptions = UseCarouselParameters[0]
+type CarouselPlugin = UseCarouselParameters[1]
+
+type CarouselProps = {
+  opts?: CarouselOptions
+  plugins?: CarouselPlugin
+  orientation?: "horizontal" | "vertical"
+  setApi?: (api: CarouselApi) => void
+}
+
+type CarouselContextProps = {
+  carouselRef: ReturnType<typeof useEmblaCarousel>[0]
+  api: ReturnType<typeof useEmblaCarousel>[1]
+  scrollPrev: () => void
+  scrollNext: () => void
+  canScrollPrev: boolean
+  canScrollNext: boolean
+} & CarouselProps
+
+const CarouselContext = React.createContext<CarouselContextProps | null>(null)
+
+function useCarousel() {
+  const context = React.useContext(CarouselContext)
+
+  if (!context) {
+    throw new Error("useCarousel must be used within a <Carousel />")
+  }
+
+  return context
+}
+
+function Carousel({
+  orientation = "horizontal",
+  opts,
+  setApi,
+  plugins,
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"div"> & CarouselProps) {
+  const [carouselRef, api] = useEmblaCarousel(
+    {
+      ...opts,
+      axis: orientation === "horizontal" ? "x" : "y",
+    },
+    plugins
+  )
+  const [canScrollPrev, setCanScrollPrev] = React.useState(false)
+  const [canScrollNext, setCanScrollNext] = React.useState(false)
+
+  const onSelect = React.useCallback((api: CarouselApi) => {
+    if (!api) return
+    setCanScrollPrev(api.canScrollPrev())
+    setCanScrollNext(api.canScrollNext())
+  }, [])
+
+  const scrollPrev = React.useCallback(() => {
+    api?.scrollPrev()
+  }, [api])
+
+  const scrollNext = React.useCallback(() => {
+    api?.scrollNext()
+  }, [api])
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key === "ArrowLeft") {
+        event.preventDefault()
+        scrollPrev()
+      } else if (event.key === "ArrowRight") {
+        event.preventDefault()
+        scrollNext()
+      }
+    },
+    [scrollPrev, scrollNext]
+  )
+
+  React.useEffect(() => {
+    if (!api || !setApi) return
+    setApi(api)
+  }, [api, setApi])
+
+  React.useEffect(() => {
+    if (!api) return
+    onSelect(api)
+    api.on("reInit", onSelect)
+    api.on("select", onSelect)
+
+    return () => {
+      api?.off("select", onSelect)
+    }
+  }, [api, onSelect])
+
+  return (
+    <CarouselContext.Provider
+      value={{
+        carouselRef,
+        api: api,
+        opts,
+        orientation:
+          orientation || (opts?.axis === "y" ? "vertical" : "horizontal"),
+        scrollPrev,
+        scrollNext,
+        canScrollPrev,
+        canScrollNext,
+      }}
+    >
+      <div
+        onKeyDownCapture={handleKeyDown}
+        className={cn("relative", className)}
+        role="region"
+        aria-roledescription="carousel"
+        data-slot="carousel"
+        {...props}
+      >
+        {children}
+      </div>
+    </CarouselContext.Provider>
+  )
+}
+
+function CarouselContent({ className, ...props }: React.ComponentProps<"div">) {
+  const { carouselRef, orientation } = useCarousel()
+
+  return (
+    <div
+      ref={carouselRef}
+      className="overflow-hidden"
+      data-slot="carousel-content"
+    >
+      <div
+        className={cn(
+          "flex",
+          orientation === "horizontal" ? "-ml-4" : "-mt-4 flex-col",
+          className
+        )}
+        {...props}
+      />
+    </div>
+  )
+}
+
+function CarouselItem({ className, ...props }: React.ComponentProps<"div">) {
+  const { orientation } = useCarousel()
+
+  return (
+    <div
+      role="group"
+      aria-roledescription="slide"
+      data-slot="carousel-item"
+      className={cn(
+        "min-w-0 shrink-0 grow-0 basis-full",
+        orientation === "horizontal" ? "pl-4" : "pt-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CarouselPrevious({
+  className,
+  variant = "outline",
+  size = "icon-sm",
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  const { orientation, scrollPrev, canScrollPrev } = useCarousel()
+
+  return (
+    <Button
+      data-slot="carousel-previous"
+      variant={variant}
+      size={size}
+      className={cn(
+        "absolute touch-manipulation rounded-2xl",
+        orientation === "horizontal"
+          ? "inset-y-0 -left-12 my-auto"
+          : "-top-12 left-1/2 -translate-x-1/2 rotate-90",
+        className
+      )}
+      disabled={!canScrollPrev}
+      onClick={scrollPrev}
+      {...props}
+    >
+      <HugeiconsIcon icon={ArrowLeft01Icon} strokeWidth={2} />
+      <span className="sr-only">Previous slide</span>
+    </Button>
+  )
+}
+
+function CarouselNext({
+  className,
+  variant = "outline",
+  size = "icon-sm",
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  const { orientation, scrollNext, canScrollNext } = useCarousel()
+
+  return (
+    <Button
+      data-slot="carousel-next"
+      variant={variant}
+      size={size}
+      className={cn(
+        "absolute touch-manipulation rounded-2xl",
+        orientation === "horizontal"
+          ? "inset-y-0 -right-12 my-auto"
+          : "-bottom-12 left-1/2 -translate-x-1/2 rotate-90",
+        className
+      )}
+      disabled={!canScrollNext}
+      onClick={scrollNext}
+      {...props}
+    >
+      <HugeiconsIcon icon={ArrowRight01Icon} strokeWidth={2} />
+      <span className="sr-only">Next slide</span>
+    </Button>
+  )
+}
+
+export {
+  type CarouselApi,
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselPrevious,
+  CarouselNext,
+  useCarousel,
+}
diff --git a/packages/web/src/components/ui/chart.tsx b/packages/web/src/components/ui/chart.tsx
new file mode 100644
index 0000000..17a5927
--- /dev/null
+++ b/packages/web/src/components/ui/chart.tsx
@@ -0,0 +1,373 @@
+"use client"
+
+import * as React from "react"
+import * as RechartsPrimitive from "recharts"
+import type { TooltipValueType } from "recharts"
+
+import { cn } from "@/lib/utils"
+
+// Format: { THEME_NAME: CSS_SELECTOR }
+const THEMES = { light: "", dark: ".dark" } as const
+
+const INITIAL_DIMENSION = { width: 320, height: 200 } as const
+type TooltipNameType = number | string
+
+export type ChartConfig = Record<
+  string,
+  {
+    label?: React.ReactNode
+    icon?: React.ComponentType
+  } & (
+    | { color?: string; theme?: never }
+    | { color?: never; theme: Record<keyof typeof THEMES, string> }
+  )
+>
+
+type ChartContextProps = {
+  config: ChartConfig
+}
+
+const ChartContext = React.createContext<ChartContextProps | null>(null)
+
+function useChart() {
+  const context = React.useContext(ChartContext)
+
+  if (!context) {
+    throw new Error("useChart must be used within a <ChartContainer />")
+  }
+
+  return context
+}
+
+function ChartContainer({
+  id,
+  className,
+  children,
+  config,
+  initialDimension = INITIAL_DIMENSION,
+  ...props
+}: React.ComponentProps<"div"> & {
+  config: ChartConfig
+  children: React.ComponentProps<
+    typeof RechartsPrimitive.ResponsiveContainer
+  >["children"]
+  initialDimension?: {
+    width: number
+    height: number
+  }
+}) {
+  const uniqueId = React.useId()
+  const chartId = `chart-${id ?? uniqueId.replace(/:/g, "")}`
+
+  return (
+    <ChartContext.Provider value={{ config }}>
+      <div
+        data-slot="chart"
+        data-chart={chartId}
+        className={cn(
+          "flex aspect-video justify-center text-xs [&_.recharts-cartesian-axis-tick_text]:fill-muted-foreground [&_.recharts-cartesian-grid_line[stroke='#ccc']]:stroke-border/50 [&_.recharts-curve.recharts-tooltip-cursor]:stroke-border [&_.recharts-dot[stroke='#fff']]:stroke-transparent [&_.recharts-layer]:outline-hidden [&_.recharts-polar-grid_[stroke='#ccc']]:stroke-border [&_.recharts-radial-bar-background-sector]:fill-muted [&_.recharts-rectangle.recharts-tooltip-cursor]:fill-muted [&_.recharts-reference-line_[stroke='#ccc']]:stroke-border [&_.recharts-sector]:outline-hidden [&_.recharts-sector[stroke='#fff']]:stroke-transparent [&_.recharts-surface]:outline-hidden",
+          className
+        )}
+        {...props}
+      >
+        <ChartStyle id={chartId} config={config} />
+        <RechartsPrimitive.ResponsiveContainer
+          initialDimension={initialDimension}
+        >
+          {children}
+        </RechartsPrimitive.ResponsiveContainer>
+      </div>
+    </ChartContext.Provider>
+  )
+}
+
+const ChartStyle = ({ id, config }: { id: string; config: ChartConfig }) => {
+  const colorConfig = Object.entries(config).filter(
+    ([, config]) => config.theme ?? config.color
+  )
+
+  if (!colorConfig.length) {
+    return null
+  }
+
+  return (
+    <style
+      dangerouslySetInnerHTML={{
+        __html: Object.entries(THEMES)
+          .map(
+            ([theme, prefix]) => `
+${prefix} [data-chart=${id}] {
+${colorConfig
+  .map(([key, itemConfig]) => {
+    const color =
+      itemConfig.theme?.[theme as keyof typeof itemConfig.theme] ??
+      itemConfig.color
+    return color ? `  --color-${key}: ${color};` : null
+  })
+  .join("\n")}
+}
+`
+          )
+          .join("\n"),
+      }}
+    />
+  )
+}
+
+const ChartTooltip = RechartsPrimitive.Tooltip
+
+function ChartTooltipContent({
+  active,
+  payload,
+  className,
+  indicator = "dot",
+  hideLabel = false,
+  hideIndicator = false,
+  label,
+  labelFormatter,
+  labelClassName,
+  formatter,
+  color,
+  nameKey,
+  labelKey,
+}: React.ComponentProps<typeof RechartsPrimitive.Tooltip> &
+  React.ComponentProps<"div"> & {
+    hideLabel?: boolean
+    hideIndicator?: boolean
+    indicator?: "line" | "dot" | "dashed"
+    nameKey?: string
+    labelKey?: string
+  } & Omit<
+    RechartsPrimitive.DefaultTooltipContentProps<
+      TooltipValueType,
+      TooltipNameType
+    >,
+    "accessibilityLayer"
+  >) {
+  const { config } = useChart()
+
+  const tooltipLabel = React.useMemo(() => {
+    if (hideLabel || !payload?.length) {
+      return null
+    }
+
+    const [item] = payload
+    const key = `${labelKey ?? item?.dataKey ?? item?.name ?? "value"}`
+    const itemConfig = getPayloadConfigFromPayload(config, item, key)
+    const value =
+      !labelKey && typeof label === "string"
+        ? (config[label]?.label ?? label)
+        : itemConfig?.label
+
+    if (labelFormatter) {
+      return (
+        <div className={cn("font-medium", labelClassName)}>
+          {labelFormatter(value, payload)}
+        </div>
+      )
+    }
+
+    if (!value) {
+      return null
+    }
+
+    return <div className={cn("font-medium", labelClassName)}>{value}</div>
+  }, [
+    label,
+    labelFormatter,
+    payload,
+    hideLabel,
+    labelClassName,
+    config,
+    labelKey,
+  ])
+
+  if (!active || !payload?.length) {
+    return null
+  }
+
+  const nestLabel = payload.length === 1 && indicator !== "dot"
+
+  return (
+    <div
+      className={cn(
+        "grid min-w-32 items-start gap-1.5 rounded-xl bg-popover px-2.5 py-1.5 text-xs text-popover-foreground shadow-lg ring-1 ring-foreground/5 dark:ring-foreground/10",
+        className
+      )}
+    >
+      {!nestLabel ? tooltipLabel : null}
+      <div className="grid gap-1.5">
+        {payload
+          .filter((item) => item.type !== "none")
+          .map((item, index) => {
+            const key = `${nameKey ?? item.name ?? item.dataKey ?? "value"}`
+            const itemConfig = getPayloadConfigFromPayload(config, item, key)
+            const indicatorColor = color ?? item.payload?.fill ?? item.color
+
+            return (
+              <div
+                key={index}
+                className={cn(
+                  "flex w-full flex-wrap items-stretch gap-2 [&>svg]:h-2.5 [&>svg]:w-2.5 [&>svg]:text-muted-foreground",
+                  indicator === "dot" && "items-center"
+                )}
+              >
+                {formatter && item?.value !== undefined && item.name ? (
+                  formatter(item.value, item.name, item, index, item.payload)
+                ) : (
+                  <>
+                    {itemConfig?.icon ? (
+                      <itemConfig.icon />
+                    ) : (
+                      !hideIndicator && (
+                        <div
+                          className={cn(
+                            "shrink-0 rounded-[2px] border-(--color-border) bg-(--color-bg)",
+                            {
+                              "h-2.5 w-2.5": indicator === "dot",
+                              "w-1": indicator === "line",
+                              "w-0 border-[1.5px] border-dashed bg-transparent":
+                                indicator === "dashed",
+                              "my-0.5": nestLabel && indicator === "dashed",
+                            }
+                          )}
+                          style={
+                            {
+                              "--color-bg": indicatorColor,
+                              "--color-border": indicatorColor,
+                            } as React.CSSProperties
+                          }
+                        />
+                      )
+                    )}
+                    <div
+                      className={cn(
+                        "flex flex-1 justify-between leading-none",
+                        nestLabel ? "items-end" : "items-center"
+                      )}
+                    >
+                      <div className="grid gap-1.5">
+                        {nestLabel ? tooltipLabel : null}
+                        <span className="text-muted-foreground">
+                          {itemConfig?.label ?? item.name}
+                        </span>
+                      </div>
+                      {item.value != null && (
+                        <span className="font-mono font-medium text-foreground tabular-nums">
+                          {typeof item.value === "number"
+                            ? item.value.toLocaleString()
+                            : String(item.value)}
+                        </span>
+                      )}
+                    </div>
+                  </>
+                )}
+              </div>
+            )
+          })}
+      </div>
+    </div>
+  )
+}
+
+const ChartLegend = RechartsPrimitive.Legend
+
+function ChartLegendContent({
+  className,
+  hideIcon = false,
+  payload,
+  verticalAlign = "bottom",
+  nameKey,
+}: React.ComponentProps<"div"> & {
+  hideIcon?: boolean
+  nameKey?: string
+} & RechartsPrimitive.DefaultLegendContentProps) {
+  const { config } = useChart()
+
+  if (!payload?.length) {
+    return null
+  }
+
+  return (
+    <div
+      className={cn(
+        "flex items-center justify-center gap-4",
+        verticalAlign === "top" ? "pb-3" : "pt-3",
+        className
+      )}
+    >
+      {payload
+        .filter((item) => item.type !== "none")
+        .map((item, index) => {
+          const key = `${nameKey ?? item.dataKey ?? "value"}`
+          const itemConfig = getPayloadConfigFromPayload(config, item, key)
+
+          return (
+            <div
+              key={index}
+              className={cn(
+                "flex items-center gap-1.5 [&>svg]:h-3 [&>svg]:w-3 [&>svg]:text-muted-foreground"
+              )}
+            >
+              {itemConfig?.icon && !hideIcon ? (
+                <itemConfig.icon />
+              ) : (
+                <div
+                  className="h-2 w-2 shrink-0 rounded-[2px]"
+                  style={{
+                    backgroundColor: item.color,
+                  }}
+                />
+              )}
+              {itemConfig?.label}
+            </div>
+          )
+        })}
+    </div>
+  )
+}
+
+function getPayloadConfigFromPayload(
+  config: ChartConfig,
+  payload: unknown,
+  key: string
+) {
+  if (typeof payload !== "object" || payload === null) {
+    return undefined
+  }
+
+  const payloadPayload =
+    "payload" in payload &&
+    typeof payload.payload === "object" &&
+    payload.payload !== null
+      ? payload.payload
+      : undefined
+
+  let configLabelKey: string = key
+
+  if (
+    key in payload &&
+    typeof payload[key as keyof typeof payload] === "string"
+  ) {
+    configLabelKey = payload[key as keyof typeof payload] as string
+  } else if (
+    payloadPayload &&
+    key in payloadPayload &&
+    typeof payloadPayload[key as keyof typeof payloadPayload] === "string"
+  ) {
+    configLabelKey = payloadPayload[
+      key as keyof typeof payloadPayload
+    ] as string
+  }
+
+  return configLabelKey in config ? config[configLabelKey] : config[key]
+}
+
+export {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  ChartLegend,
+  ChartLegendContent,
+  ChartStyle,
+}
diff --git a/packages/web/src/components/ui/checkbox.tsx b/packages/web/src/components/ui/checkbox.tsx
new file mode 100644
index 0000000..c45f73e
--- /dev/null
+++ b/packages/web/src/components/ui/checkbox.tsx
@@ -0,0 +1,29 @@
+"use client"
+
+import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox"
+
+import { cn } from "@/lib/utils"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { Tick02Icon } from "@hugeicons/core-free-icons"
+
+function Checkbox({ className, ...props }: CheckboxPrimitive.Root.Props) {
+  return (
+    <CheckboxPrimitive.Root
+      data-slot="checkbox"
+      className={cn(
+        "peer relative flex size-4 shrink-0 items-center justify-center rounded-[5px] border border-transparent bg-input/90 transition-shadow outline-none group-has-disabled/field:opacity-50 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 aria-invalid:aria-checked:border-primary dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-checked:text-primary-foreground dark:data-checked:bg-primary",
+        className
+      )}
+      {...props}
+    >
+      <CheckboxPrimitive.Indicator
+        data-slot="checkbox-indicator"
+        className="grid place-content-center text-current transition-none [&>svg]:size-3.5"
+      >
+        <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} />
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  )
+}
+
+export { Checkbox }
diff --git a/packages/web/src/components/ui/collapsible.tsx b/packages/web/src/components/ui/collapsible.tsx
new file mode 100644
index 0000000..4b242f7
--- /dev/null
+++ b/packages/web/src/components/ui/collapsible.tsx
@@ -0,0 +1,19 @@
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible"
+
+function Collapsible({ ...props }: CollapsiblePrimitive.Root.Props) {
+  return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />
+}
+
+function CollapsibleTrigger({ ...props }: CollapsiblePrimitive.Trigger.Props) {
+  return (
+    <CollapsiblePrimitive.Trigger data-slot="collapsible-trigger" {...props} />
+  )
+}
+
+function CollapsibleContent({ ...props }: CollapsiblePrimitive.Panel.Props) {
+  return (
+    <CollapsiblePrimitive.Panel data-slot="collapsible-content" {...props} />
+  )
+}
+
+export { Collapsible, CollapsibleTrigger, CollapsibleContent }
diff --git a/packages/web/src/components/ui/combobox.tsx b/packages/web/src/components/ui/combobox.tsx
new file mode 100644
index 0000000..657ffa1
--- /dev/null
+++ b/packages/web/src/components/ui/combobox.tsx
@@ -0,0 +1,298 @@
+"use client"
+
+import * as React from "react"
+import { Combobox as ComboboxPrimitive } from "@base-ui/react"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+} from "@/components/ui/input-group"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { ArrowDown01Icon, Cancel01Icon, Tick02Icon } from "@hugeicons/core-free-icons"
+
+const Combobox = ComboboxPrimitive.Root
+
+function ComboboxValue({ ...props }: ComboboxPrimitive.Value.Props) {
+  return <ComboboxPrimitive.Value data-slot="combobox-value" {...props} />
+}
+
+function ComboboxTrigger({
+  className,
+  children,
+  ...props
+}: ComboboxPrimitive.Trigger.Props) {
+  return (
+    <ComboboxPrimitive.Trigger
+      data-slot="combobox-trigger"
+      className={cn("[&_svg:not([class*='size-'])]:size-4", className)}
+      {...props}
+    >
+      {children}
+      <HugeiconsIcon icon={ArrowDown01Icon} strokeWidth={2} className="pointer-events-none size-4 text-muted-foreground" />
+    </ComboboxPrimitive.Trigger>
+  )
+}
+
+function ComboboxClear({ className, ...props }: ComboboxPrimitive.Clear.Props) {
+  return (
+    <ComboboxPrimitive.Clear
+      data-slot="combobox-clear"
+      render={<InputGroupButton variant="ghost" size="icon-xs" />}
+      className={cn(className)}
+      {...props}
+    >
+      <HugeiconsIcon icon={Cancel01Icon} strokeWidth={2} className="pointer-events-none" />
+    </ComboboxPrimitive.Clear>
+  )
+}
+
+function ComboboxInput({
+  className,
+  children,
+  disabled = false,
+  showTrigger = true,
+  showClear = false,
+  ...props
+}: ComboboxPrimitive.Input.Props & {
+  showTrigger?: boolean
+  showClear?: boolean
+}) {
+  return (
+    <InputGroup className={cn("w-auto", className)}>
+      <ComboboxPrimitive.Input
+        render={<InputGroupInput disabled={disabled} />}
+        {...props}
+      />
+      <InputGroupAddon align="inline-end">
+        {showTrigger && (
+          <InputGroupButton
+            size="icon-xs"
+            variant="ghost"
+            render={<ComboboxTrigger />}
+            data-slot="input-group-button"
+            className="group-has-data-[slot=combobox-clear]/input-group:hidden data-pressed:bg-transparent"
+            disabled={disabled}
+          />
+        )}
+        {showClear && <ComboboxClear disabled={disabled} />}
+      </InputGroupAddon>
+      {children}
+    </InputGroup>
+  )
+}
+
+function ComboboxContent({
+  className,
+  side = "bottom",
+  sideOffset = 6,
+  align = "start",
+  alignOffset = 0,
+  anchor,
+  ...props
+}: ComboboxPrimitive.Popup.Props &
+  Pick<
+    ComboboxPrimitive.Positioner.Props,
+    "side" | "align" | "sideOffset" | "alignOffset" | "anchor"
+  >) {
+  return (
+    <ComboboxPrimitive.Portal>
+      <ComboboxPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
+        anchor={anchor}
+        className="isolate z-50"
+      >
+        <ComboboxPrimitive.Popup
+          data-slot="combobox-content"
+          data-chips={!!anchor}
+          className={cn("group/combobox-content max-h-(--available-height) w-(--anchor-width) max-w-(--available-width) min-w-[calc(var(--anchor-width)+--spacing(7))] origin-(--transform-origin) overflow-hidden rounded-2xl text-popover-foreground shadow-lg ring-1 ring-foreground/5 duration-100 data-[chips=true]:min-w-(--anchor-width) data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 *:data-[slot=input-group]:m-1 *:data-[slot=input-group]:mb-0 *:data-[slot=input-group]:h-8 *:data-[slot=input-group]:border-input/30 *:data-[slot=input-group]:bg-input/50 *:data-[slot=input-group]:shadow-none dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 animate-none! relative bg-popover/70 before:pointer-events-none before:absolute before:inset-0 before:-z-1 before:rounded-[inherit] before:backdrop-blur-2xl before:backdrop-saturate-150 **:data-[slot$=-item]:focus:bg-foreground/10 **:data-[slot$=-item]:data-highlighted:bg-foreground/10 **:data-[slot$=-separator]:bg-foreground/5 **:data-[slot$=-trigger]:focus:bg-foreground/10 **:data-[slot$=-trigger]:aria-expanded:bg-foreground/10! **:data-[variant=destructive]:focus:bg-foreground/10! **:data-[variant=destructive]:text-accent-foreground! **:data-[variant=destructive]:**:text-accent-foreground!", className )}
+          {...props}
+        />
+      </ComboboxPrimitive.Positioner>
+    </ComboboxPrimitive.Portal>
+  )
+}
+
+function ComboboxList({ className, ...props }: ComboboxPrimitive.List.Props) {
+  return (
+    <ComboboxPrimitive.List
+      data-slot="combobox-list"
+      className={cn(
+        "no-scrollbar max-h-[min(calc(--spacing(72)---spacing(9)),calc(var(--available-height)---spacing(9)))] scroll-py-1 overflow-y-auto overscroll-contain p-1 data-empty:p-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ComboboxItem({
+  className,
+  children,
+  ...props
+}: ComboboxPrimitive.Item.Props) {
+  return (
+    <ComboboxPrimitive.Item
+      data-slot="combobox-item"
+      className={cn(
+        "relative flex min-h-7 w-full cursor-default items-center gap-2 rounded-xl py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground not-data-[variant=destructive]:data-highlighted:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <ComboboxPrimitive.ItemIndicator
+        render={
+          <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center" />
+        }
+      >
+        <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} className="pointer-events-none" />
+      </ComboboxPrimitive.ItemIndicator>
+    </ComboboxPrimitive.Item>
+  )
+}
+
+function ComboboxGroup({ className, ...props }: ComboboxPrimitive.Group.Props) {
+  return (
+    <ComboboxPrimitive.Group
+      data-slot="combobox-group"
+      className={cn(className)}
+      {...props}
+    />
+  )
+}
+
+function ComboboxLabel({
+  className,
+  ...props
+}: ComboboxPrimitive.GroupLabel.Props) {
+  return (
+    <ComboboxPrimitive.GroupLabel
+      data-slot="combobox-label"
+      className={cn("px-2 py-1.5 text-xs text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function ComboboxCollection({ ...props }: ComboboxPrimitive.Collection.Props) {
+  return (
+    <ComboboxPrimitive.Collection data-slot="combobox-collection" {...props} />
+  )
+}
+
+function ComboboxEmpty({ className, ...props }: ComboboxPrimitive.Empty.Props) {
+  return (
+    <ComboboxPrimitive.Empty
+      data-slot="combobox-empty"
+      className={cn(
+        "hidden w-full justify-center py-2 text-center text-sm text-muted-foreground group-data-empty/combobox-content:flex",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ComboboxSeparator({
+  className,
+  ...props
+}: ComboboxPrimitive.Separator.Props) {
+  return (
+    <ComboboxPrimitive.Separator
+      data-slot="combobox-separator"
+      className={cn("-mx-1 my-1 h-px bg-border", className)}
+      {...props}
+    />
+  )
+}
+
+function ComboboxChips({
+  className,
+  ...props
+}: React.ComponentPropsWithRef<typeof ComboboxPrimitive.Chips> &
+  ComboboxPrimitive.Chips.Props) {
+  return (
+    <ComboboxPrimitive.Chips
+      data-slot="combobox-chips"
+      className={cn(
+        "flex min-h-8 flex-wrap items-center gap-1 rounded-2xl border border-transparent bg-input/50 bg-clip-padding px-2.5 py-1 text-sm transition-[color,box-shadow] duration-200 focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/30 has-aria-invalid:border-destructive has-aria-invalid:ring-3 has-aria-invalid:ring-destructive/20 has-data-[slot=combobox-chip]:px-1 dark:has-aria-invalid:border-destructive/50 dark:has-aria-invalid:ring-destructive/40",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ComboboxChip({
+  className,
+  children,
+  showRemove = true,
+  ...props
+}: ComboboxPrimitive.Chip.Props & {
+  showRemove?: boolean
+}) {
+  return (
+    <ComboboxPrimitive.Chip
+      data-slot="combobox-chip"
+      className={cn(
+        "flex h-[calc(--spacing(5.25))] w-fit items-center justify-center gap-1 rounded-2xl bg-input px-1.5 text-xs font-medium whitespace-nowrap text-foreground has-disabled:pointer-events-none has-disabled:cursor-not-allowed has-disabled:opacity-50 has-data-[slot=combobox-chip-remove]:pr-0.5 dark:bg-input/60",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      {showRemove && (
+        <ComboboxPrimitive.ChipRemove
+          render={<Button variant="ghost" size="icon-xs" />}
+          className="-ml-0.5 size-4.5 opacity-50 hover:opacity-100 aria-disabled:pointer-events-none"
+          data-slot="combobox-chip-remove"
+        >
+          <HugeiconsIcon icon={Cancel01Icon} strokeWidth={2} className="pointer-events-none" />
+        </ComboboxPrimitive.ChipRemove>
+      )}
+    </ComboboxPrimitive.Chip>
+  )
+}
+
+function ComboboxChipsInput({
+  className,
+  ...props
+}: ComboboxPrimitive.Input.Props) {
+  return (
+    <ComboboxPrimitive.Input
+      data-slot="combobox-chip-input"
+      className={cn("min-w-16 flex-1 outline-none", className)}
+      {...props}
+    />
+  )
+}
+
+function useComboboxAnchor() {
+  return React.useRef<HTMLDivElement | null>(null)
+}
+
+export {
+  Combobox,
+  ComboboxInput,
+  ComboboxContent,
+  ComboboxList,
+  ComboboxItem,
+  ComboboxGroup,
+  ComboboxLabel,
+  ComboboxCollection,
+  ComboboxEmpty,
+  ComboboxSeparator,
+  ComboboxChips,
+  ComboboxChip,
+  ComboboxChipsInput,
+  ComboboxTrigger,
+  ComboboxValue,
+  useComboboxAnchor,
+}
diff --git a/packages/web/src/components/ui/command.tsx b/packages/web/src/components/ui/command.tsx
new file mode 100644
index 0000000..39c3426
--- /dev/null
+++ b/packages/web/src/components/ui/command.tsx
@@ -0,0 +1,195 @@
+import * as React from "react"
+import { Command as CommandPrimitive } from "cmdk"
+
+import { cn } from "@/lib/utils"
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog"
+import {
+  InputGroup,
+  InputGroupAddon,
+} from "@/components/ui/input-group"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { SearchIcon, Tick02Icon } from "@hugeicons/core-free-icons"
+
+function Command({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive>) {
+  return (
+    <CommandPrimitive
+      data-slot="command"
+      className={cn(
+        "flex size-full flex-col overflow-hidden rounded-3xl bg-popover p-1 text-popover-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CommandDialog({
+  title = "Command Palette",
+  description = "Search for a command to run...",
+  children,
+  className,
+  showCloseButton = false,
+  ...props
+}: Omit<React.ComponentProps<typeof Dialog>, "children"> & {
+  title?: string
+  description?: string
+  className?: string
+  showCloseButton?: boolean
+  children: React.ReactNode
+}) {
+  return (
+    <Dialog {...props}>
+      <DialogHeader className="sr-only">
+        <DialogTitle>{title}</DialogTitle>
+        <DialogDescription>{description}</DialogDescription>
+      </DialogHeader>
+      <DialogContent
+        className={cn(
+          "top-1/3 translate-y-0 overflow-hidden rounded-3xl! p-0",
+          className
+        )}
+        showCloseButton={showCloseButton}
+      >
+        {children}
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+function CommandInput({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Input>) {
+  return (
+    <div data-slot="command-input-wrapper" className="p-1 pb-0">
+      <InputGroup className="h-8! bg-input/50">
+        <CommandPrimitive.Input
+          data-slot="command-input"
+          className={cn(
+            "w-full text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50",
+            className
+          )}
+          {...props}
+        />
+        <InputGroupAddon>
+          <HugeiconsIcon icon={SearchIcon} strokeWidth={2} className="size-4 shrink-0 opacity-50" />
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+function CommandList({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.List>) {
+  return (
+    <CommandPrimitive.List
+      data-slot="command-list"
+      className={cn(
+        "no-scrollbar max-h-72 scroll-py-1 overflow-x-hidden overflow-y-auto outline-none",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CommandEmpty({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Empty>) {
+  return (
+    <CommandPrimitive.Empty
+      data-slot="command-empty"
+      className={cn("py-6 text-center text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function CommandGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Group>) {
+  return (
+    <CommandPrimitive.Group
+      data-slot="command-group"
+      className={cn(
+        "overflow-hidden p-1 text-foreground **:[[cmdk-group-heading]]:px-2 **:[[cmdk-group-heading]]:py-1.5 **:[[cmdk-group-heading]]:text-xs **:[[cmdk-group-heading]]:font-medium **:[[cmdk-group-heading]]:text-muted-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CommandSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Separator>) {
+  return (
+    <CommandPrimitive.Separator
+      data-slot="command-separator"
+      className={cn("my-1 h-px bg-border/50", className)}
+      {...props}
+    />
+  )
+}
+
+function CommandItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Item>) {
+  return (
+    <CommandPrimitive.Item
+      data-slot="command-item"
+      className={cn(
+        "group/command-item relative flex min-h-7 cursor-default items-center gap-2 rounded-xl px-2 py-1.5 text-sm outline-hidden select-none in-data-[slot=dialog-content]:rounded-2xl data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-selected:bg-muted data-selected:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-selected:*:[svg]:text-foreground",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} className="ml-auto opacity-0 group-has-data-[slot=command-shortcut]/command-item:hidden group-data-[checked=true]/command-item:opacity-100" />
+    </CommandPrimitive.Item>
+  )
+}
+
+function CommandShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="command-shortcut"
+      className={cn(
+        "ml-auto text-xs tracking-widest text-muted-foreground group-data-selected/command-item:text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
+  CommandSeparator,
+}
diff --git a/packages/web/src/components/ui/context-menu.tsx b/packages/web/src/components/ui/context-menu.tsx
new file mode 100644
index 0000000..e3aa862
--- /dev/null
+++ b/packages/web/src/components/ui/context-menu.tsx
@@ -0,0 +1,270 @@
+"use client"
+
+import * as React from "react"
+import { ContextMenu as ContextMenuPrimitive } from "@base-ui/react/context-menu"
+
+import { cn } from "@/lib/utils"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { ArrowRight01Icon, Tick02Icon } from "@hugeicons/core-free-icons"
+
+function ContextMenu({ ...props }: ContextMenuPrimitive.Root.Props) {
+  return <ContextMenuPrimitive.Root data-slot="context-menu" {...props} />
+}
+
+function ContextMenuPortal({ ...props }: ContextMenuPrimitive.Portal.Props) {
+  return (
+    <ContextMenuPrimitive.Portal data-slot="context-menu-portal" {...props} />
+  )
+}
+
+function ContextMenuTrigger({
+  className,
+  ...props
+}: ContextMenuPrimitive.Trigger.Props) {
+  return (
+    <ContextMenuPrimitive.Trigger
+      data-slot="context-menu-trigger"
+      className={cn("select-none", className)}
+      {...props}
+    />
+  )
+}
+
+function ContextMenuContent({
+  className,
+  align = "start",
+  alignOffset = 4,
+  side = "right",
+  sideOffset = 0,
+  ...props
+}: ContextMenuPrimitive.Popup.Props &
+  Pick<
+    ContextMenuPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset"
+  >) {
+  return (
+    <ContextMenuPrimitive.Portal>
+      <ContextMenuPrimitive.Positioner
+        className="isolate z-50 outline-none"
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+      >
+        <ContextMenuPrimitive.Popup
+          data-slot="context-menu-content"
+          className={cn("z-50 max-h-(--available-height) min-w-36 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-2xl p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/5 duration-100 outline-none data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 animate-none! relative bg-popover/70 before:pointer-events-none before:absolute before:inset-0 before:-z-1 before:rounded-[inherit] before:backdrop-blur-2xl before:backdrop-saturate-150 **:data-[slot$=-item]:focus:bg-foreground/10 **:data-[slot$=-item]:data-highlighted:bg-foreground/10 **:data-[slot$=-separator]:bg-foreground/5 **:data-[slot$=-trigger]:focus:bg-foreground/10 **:data-[slot$=-trigger]:aria-expanded:bg-foreground/10! **:data-[variant=destructive]:focus:bg-foreground/10! **:data-[variant=destructive]:text-accent-foreground! **:data-[variant=destructive]:**:text-accent-foreground!", className )}
+          {...props}
+        />
+      </ContextMenuPrimitive.Positioner>
+    </ContextMenuPrimitive.Portal>
+  )
+}
+
+function ContextMenuGroup({ ...props }: ContextMenuPrimitive.Group.Props) {
+  return (
+    <ContextMenuPrimitive.Group data-slot="context-menu-group" {...props} />
+  )
+}
+
+function ContextMenuLabel({
+  className,
+  inset,
+  ...props
+}: ContextMenuPrimitive.GroupLabel.Props & {
+  inset?: boolean
+}) {
+  return (
+    <ContextMenuPrimitive.GroupLabel
+      data-slot="context-menu-label"
+      data-inset={inset}
+      className={cn(
+        "px-2 py-1 text-xs text-muted-foreground data-inset:pl-7",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ContextMenuItem({
+  className,
+  inset,
+  variant = "default",
+  ...props
+}: ContextMenuPrimitive.Item.Props & {
+  inset?: boolean
+  variant?: "default" | "destructive"
+}) {
+  return (
+    <ContextMenuPrimitive.Item
+      data-slot="context-menu-item"
+      data-inset={inset}
+      data-variant={variant}
+      className={cn(
+        "group/context-menu-item relative flex min-h-7 cursor-default items-center gap-2 rounded-xl px-2 py-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground data-inset:pl-7 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 focus:*:[svg]:text-accent-foreground data-[variant=destructive]:*:[svg]:text-destructive",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ContextMenuSub({ ...props }: ContextMenuPrimitive.SubmenuRoot.Props) {
+  return (
+    <ContextMenuPrimitive.SubmenuRoot data-slot="context-menu-sub" {...props} />
+  )
+}
+
+function ContextMenuSubTrigger({
+  className,
+  inset,
+  children,
+  ...props
+}: ContextMenuPrimitive.SubmenuTrigger.Props & {
+  inset?: boolean
+}) {
+  return (
+    <ContextMenuPrimitive.SubmenuTrigger
+      data-slot="context-menu-sub-trigger"
+      data-inset={inset}
+      className={cn(
+        "flex min-h-7 cursor-default items-center rounded-xl px-2 py-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground data-inset:pl-7 data-open:bg-accent data-open:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <HugeiconsIcon icon={ArrowRight01Icon} strokeWidth={2} className="ml-auto" />
+    </ContextMenuPrimitive.SubmenuTrigger>
+  )
+}
+
+function ContextMenuSubContent({
+  ...props
+}: React.ComponentProps<typeof ContextMenuContent>) {
+  return (
+    <ContextMenuContent
+      data-slot="context-menu-sub-content"
+      className="shadow-lg animate-none! relative bg-popover/70 before:pointer-events-none before:absolute before:inset-0 before:-z-1 before:rounded-[inherit] before:backdrop-blur-2xl before:backdrop-saturate-150 **:data-[slot$=-item]:focus:bg-foreground/10 **:data-[slot$=-item]:data-highlighted:bg-foreground/10 **:data-[slot$=-separator]:bg-foreground/5 **:data-[slot$=-trigger]:focus:bg-foreground/10 **:data-[slot$=-trigger]:aria-expanded:bg-foreground/10! **:data-[variant=destructive]:focus:bg-foreground/10! **:data-[variant=destructive]:text-accent-foreground! **:data-[variant=destructive]:**:text-accent-foreground!"
+      side="right"
+      {...props}
+    />
+  )
+}
+
+function ContextMenuCheckboxItem({
+  className,
+  children,
+  checked,
+  inset,
+  ...props
+}: ContextMenuPrimitive.CheckboxItem.Props & {
+  inset?: boolean
+}) {
+  return (
+    <ContextMenuPrimitive.CheckboxItem
+      data-slot="context-menu-checkbox-item"
+      data-inset={inset}
+      className={cn(
+        "relative flex min-h-7 cursor-default items-center gap-2 rounded-xl py-1.5 pr-8 pl-2 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      checked={checked}
+      {...props}
+    >
+      <span className="pointer-events-none absolute right-2">
+        <ContextMenuPrimitive.CheckboxItemIndicator>
+          <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} />
+        </ContextMenuPrimitive.CheckboxItemIndicator>
+      </span>
+      {children}
+    </ContextMenuPrimitive.CheckboxItem>
+  )
+}
+
+function ContextMenuRadioGroup({
+  ...props
+}: ContextMenuPrimitive.RadioGroup.Props) {
+  return (
+    <ContextMenuPrimitive.RadioGroup
+      data-slot="context-menu-radio-group"
+      {...props}
+    />
+  )
+}
+
+function ContextMenuRadioItem({
+  className,
+  children,
+  inset,
+  ...props
+}: ContextMenuPrimitive.RadioItem.Props & {
+  inset?: boolean
+}) {
+  return (
+    <ContextMenuPrimitive.RadioItem
+      data-slot="context-menu-radio-item"
+      data-inset={inset}
+      className={cn(
+        "relative flex min-h-7 cursor-default items-center gap-2 rounded-xl py-1.5 pr-8 pl-2 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <span className="pointer-events-none absolute right-2">
+        <ContextMenuPrimitive.RadioItemIndicator>
+          <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} />
+        </ContextMenuPrimitive.RadioItemIndicator>
+      </span>
+      {children}
+    </ContextMenuPrimitive.RadioItem>
+  )
+}
+
+function ContextMenuSeparator({
+  className,
+  ...props
+}: ContextMenuPrimitive.Separator.Props) {
+  return (
+    <ContextMenuPrimitive.Separator
+      data-slot="context-menu-separator"
+      className={cn("-mx-1 my-1 h-px bg-border/50", className)}
+      {...props}
+    />
+  )
+}
+
+function ContextMenuShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="context-menu-shortcut"
+      className={cn(
+        "ml-auto text-xs tracking-widest text-muted-foreground group-focus/context-menu-item:text-accent-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  ContextMenu,
+  ContextMenuTrigger,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuCheckboxItem,
+  ContextMenuRadioItem,
+  ContextMenuLabel,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuGroup,
+  ContextMenuPortal,
+  ContextMenuSub,
+  ContextMenuSubContent,
+  ContextMenuSubTrigger,
+  ContextMenuRadioGroup,
+}
diff --git a/packages/web/src/components/ui/dialog.tsx b/packages/web/src/components/ui/dialog.tsx
new file mode 100644
index 0000000..06c19b4
--- /dev/null
+++ b/packages/web/src/components/ui/dialog.tsx
@@ -0,0 +1,158 @@
+import * as React from "react"
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { Cancel01Icon } from "@hugeicons/core-free-icons"
+
+function Dialog({ ...props }: DialogPrimitive.Root.Props) {
+  return <DialogPrimitive.Root data-slot="dialog" {...props} />
+}
+
+function DialogTrigger({ ...props }: DialogPrimitive.Trigger.Props) {
+  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />
+}
+
+function DialogPortal({ ...props }: DialogPrimitive.Portal.Props) {
+  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />
+}
+
+function DialogClose({ ...props }: DialogPrimitive.Close.Props) {
+  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />
+}
+
+function DialogOverlay({
+  className,
+  ...props
+}: DialogPrimitive.Backdrop.Props) {
+  return (
+    <DialogPrimitive.Backdrop
+      data-slot="dialog-overlay"
+      className={cn(
+        "fixed inset-0 isolate z-50 bg-black/30 duration-100 supports-backdrop-filter:backdrop-blur-sm data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogContent({
+  className,
+  children,
+  showCloseButton = true,
+  ...props
+}: DialogPrimitive.Popup.Props & {
+  showCloseButton?: boolean
+}) {
+  return (
+    <DialogPortal>
+      <DialogOverlay />
+      <DialogPrimitive.Popup
+        data-slot="dialog-content"
+        className={cn(
+          "fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-6 rounded-[min(var(--radius-4xl),24px)] bg-popover p-6 text-sm text-popover-foreground shadow-xl ring-1 ring-foreground/5 duration-100 outline-none sm:max-w-md dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <DialogPrimitive.Close
+            data-slot="dialog-close"
+            render={
+              <Button
+                variant="ghost"
+                className="absolute top-4 right-4 bg-secondary"
+                size="icon-sm"
+              />
+            }
+          >
+            <HugeiconsIcon icon={Cancel01Icon} strokeWidth={2} />
+            <span className="sr-only">Close</span>
+          </DialogPrimitive.Close>
+        )}
+      </DialogPrimitive.Popup>
+    </DialogPortal>
+  )
+}
+
+function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="dialog-header"
+      className={cn("flex flex-col gap-1.5", className)}
+      {...props}
+    />
+  )
+}
+
+function DialogFooter({
+  className,
+  showCloseButton = false,
+  children,
+  ...props
+}: React.ComponentProps<"div"> & {
+  showCloseButton?: boolean
+}) {
+  return (
+    <div
+      data-slot="dialog-footer"
+      className={cn(
+        "flex flex-col-reverse gap-2 sm:flex-row sm:justify-end",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      {showCloseButton && (
+        <DialogPrimitive.Close render={<Button variant="outline" />}>
+          Close
+        </DialogPrimitive.Close>
+      )}
+    </div>
+  )
+}
+
+function DialogTitle({ className, ...props }: DialogPrimitive.Title.Props) {
+  return (
+    <DialogPrimitive.Title
+      data-slot="dialog-title"
+      className={cn(
+        "font-heading text-base leading-none font-medium",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogDescription({
+  className,
+  ...props
+}: DialogPrimitive.Description.Props) {
+  return (
+    <DialogPrimitive.Description
+      data-slot="dialog-description"
+      className={cn(
+        "text-sm text-muted-foreground *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+}
diff --git a/packages/web/src/components/ui/direction.tsx b/packages/web/src/components/ui/direction.tsx
new file mode 100644
index 0000000..3bb2f70
--- /dev/null
+++ b/packages/web/src/components/ui/direction.tsx
@@ -0,0 +1,4 @@
+export {
+  DirectionProvider,
+  useDirection,
+} from "@base-ui/react/direction-provider"
diff --git a/packages/web/src/components/ui/drawer.tsx b/packages/web/src/components/ui/drawer.tsx
new file mode 100644
index 0000000..42c699b
--- /dev/null
+++ b/packages/web/src/components/ui/drawer.tsx
@@ -0,0 +1,228 @@
+"use client"
+
+import * as React from "react"
+import { Drawer as DrawerPrimitive } from "@base-ui/react/drawer"
+
+import { cn } from "@/lib/utils"
+
+type DrawerContextProps = {
+  hasSnapPoints: boolean
+  modal: DrawerPrimitive.Root.Props["modal"]
+  showSwipeHandle: boolean
+  swipeDirection: NonNullable<DrawerPrimitive.Root.Props["swipeDirection"]>
+}
+
+const DrawerContext = React.createContext<DrawerContextProps | null>(null)
+
+function useDrawer() {
+  const context = React.useContext(DrawerContext)
+
+  if (!context) {
+    throw new Error("useDrawer must be used within a Drawer.")
+  }
+
+  return context
+}
+
+function Drawer({
+  modal = true,
+  showSwipeHandle = false,
+  snapPoints,
+  swipeDirection = "down",
+  ...props
+}: DrawerPrimitive.Root.Props & {
+  showSwipeHandle?: boolean
+}) {
+  const hasSnapPoints = snapPoints != null && snapPoints.length > 0
+  const contextValue = React.useMemo(
+    () => ({ hasSnapPoints, modal, showSwipeHandle, swipeDirection }),
+    [hasSnapPoints, modal, showSwipeHandle, swipeDirection]
+  )
+
+  return (
+    <DrawerContext.Provider value={contextValue}>
+      <DrawerPrimitive.Root
+        data-slot="drawer"
+        modal={modal}
+        snapPoints={snapPoints}
+        swipeDirection={swipeDirection}
+        {...props}
+      />
+    </DrawerContext.Provider>
+  )
+}
+
+function DrawerTrigger({ ...props }: DrawerPrimitive.Trigger.Props) {
+  return <DrawerPrimitive.Trigger data-slot="drawer-trigger" {...props} />
+}
+
+function DrawerPortal({ ...props }: DrawerPrimitive.Portal.Props) {
+  return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />
+}
+
+function DrawerClose({ ...props }: DrawerPrimitive.Close.Props) {
+  return <DrawerPrimitive.Close data-slot="drawer-close" {...props} />
+}
+
+function DrawerOverlay({
+  className,
+  ...props
+}: DrawerPrimitive.Backdrop.Props) {
+  return (
+    <DrawerPrimitive.Backdrop
+      data-slot="drawer-overlay"
+      className={cn(
+        "fixed inset-0 z-50 min-h-dvh bg-black/30 opacity-[max(var(--drawer-overlay-min-opacity,0),calc(1-var(--drawer-swipe-progress)))] transition-opacity duration-450 ease-[cubic-bezier(0.32,0.72,0,1)] select-none data-ending-style:pointer-events-none data-ending-style:opacity-0 data-ending-style:duration-[calc(var(--drawer-swipe-strength)*400ms)] data-snap-points:[--drawer-overlay-min-opacity:0.5] data-starting-style:opacity-0 data-swiping:duration-0 supports-backdrop-filter:backdrop-blur-sm supports-[-webkit-touch-callout:none]:absolute",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DrawerSwipeHandle({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="drawer-swipe-handle"
+      aria-hidden="true"
+      className={cn(
+        "relative z-10 flex shrink-0 cursor-grab transition-opacity duration-200 group-data-nested-drawer-open/drawer-popup:opacity-0 group-data-nested-drawer-swiping/drawer-popup:opacity-100 group-data-[swipe-axis=x]/drawer-popup:h-full group-data-[swipe-axis=x]/drawer-popup:w-3 group-data-[swipe-axis=x]/drawer-popup:items-center group-data-[swipe-axis=y]/drawer-popup:h-3 group-data-[swipe-axis=y]/drawer-popup:w-full group-data-[swipe-axis=y]/drawer-popup:justify-center group-data-[swipe-direction=down]/drawer-popup:items-end group-data-[swipe-direction=left]/drawer-popup:order-last group-data-[swipe-direction=left]/drawer-popup:justify-start group-data-[swipe-direction=right]/drawer-popup:justify-end group-data-[swipe-direction=up]/drawer-popup:order-last group-data-[swipe-direction=up]/drawer-popup:items-start after:block after:shrink-0 after:rounded-full after:bg-muted group-data-[swipe-axis=x]/drawer-popup:after:h-[100px] group-data-[swipe-axis=x]/drawer-popup:after:w-1.5 group-data-[swipe-axis=y]/drawer-popup:after:h-1.5 group-data-[swipe-axis=y]/drawer-popup:after:w-[100px] active:cursor-grabbing",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DrawerContent({
+  className,
+  children,
+  ...props
+}: DrawerPrimitive.Popup.Props) {
+  const { hasSnapPoints, modal, showSwipeHandle, swipeDirection } = useDrawer()
+  const swipeAxis =
+    swipeDirection === "down" || swipeDirection === "up" ? "y" : "x"
+
+  return (
+    <DrawerPortal data-slot="drawer-portal">
+      {modal === true && (
+        <DrawerOverlay data-snap-points={hasSnapPoints ? "" : undefined} />
+      )}
+      <DrawerPrimitive.Viewport
+        data-slot="drawer-viewport"
+        data-modal={modal}
+        className="pointer-events-none fixed inset-0 z-50 select-none data-[modal=true]:pointer-events-auto"
+      >
+        <DrawerPrimitive.Popup
+          data-slot="drawer-popup"
+          data-swipe-axis={swipeAxis}
+          data-snap-points={hasSnapPoints ? "" : undefined}
+          className={cn(
+            // Base.
+            "group/drawer-popup pointer-events-auto fixed z-50 m-(--drawer-inset,0px) flex h-(--drawer-content-height) max-h-(--drawer-content-max-height,none) min-h-0 w-(--drawer-content-width,auto) transform-[translate3d(var(--translate-x,0px),var(--translate-y,0px),0)_scale(var(--stack-scale))] flex-col rounded-[min(var(--radius-4xl),24px)] border border-popover bg-popover text-sm text-popover-foreground shadow-xl transition-[transform,height,opacity,filter] duration-450 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform outline-none select-none [--drawer-bleed-background:transparent] [--drawer-inset:--spacing(2)] [--drawer-stacked-shadow:0_-20px_25px_-5px_rgb(0_0_0/0.1),0_-8px_10px_-6px_rgb(0_0_0/0.1)] [interpolate-size:allow-keywords] data-[swipe-direction=down]:data-nested-drawer-open:shadow-(--drawer-stacked-shadow) dark:border-border",
+            // Nested.
+            "data-nested-drawer-open:overflow-hidden data-nested-drawer-open:brightness-95",
+            // Bleed.
+            "after:pointer-events-none after:absolute after:bg-(--drawer-bleed-background,var(--color-popover)) data-[swipe-axis=x]:after:inset-y-0 data-[swipe-axis=x]:after:w-(--bleed) data-[swipe-axis=y]:after:inset-x-0 data-[swipe-axis=y]:after:h-(--bleed) data-[swipe-direction=down]:after:top-full data-[swipe-direction=left]:after:right-full data-[swipe-direction=right]:after:left-full data-[swipe-direction=up]:after:bottom-full",
+            // Sizing.
+            "[--drawer-content-height:var(--drawer-height,auto)] data-[swipe-axis=x]:[--drawer-content-width:75%] data-[swipe-axis=y]:[--drawer-content-max-height:calc(100dvh-6rem)] data-[swipe-axis=y]:data-snap-points:[--drawer-content-height:100dvh] data-[swipe-axis=x]:sm:[--drawer-content-width:24rem]",
+            // Stack.
+            "[--bleed:3rem] [--peek:1rem] [--stack-height:var(--drawer-frontmost-height,var(--drawer-height,0px))] [--stack-peek-offset:max(0px,calc((var(--nested-drawers)-var(--stack-progress))*var(--peek)))] [--stack-progress:clamp(0,var(--drawer-swipe-progress),1)] [--stack-scale-base:max(0,calc(1-(var(--nested-drawers)*var(--stack-step))))] [--stack-scale:clamp(0,calc(var(--stack-scale-base)+(var(--stack-step)*var(--stack-progress))),1)] [--stack-shrink:calc(1-var(--stack-scale))] [--stack-step:0.05]",
+            // Transitions.
+            "data-ending-style:transform-(--closed-transform) data-ending-style:opacity-[0.9999] data-ending-style:duration-[calc(var(--drawer-swipe-strength)*400ms)] data-nested-drawer-swiping:duration-0 data-ending-style:data-nested-drawer-swiping:duration-[calc(var(--drawer-swipe-strength)*400ms)] data-starting-style:transform-(--closed-transform) data-swiping:duration-0 data-ending-style:data-swiping:duration-[calc(var(--drawer-swipe-strength)*400ms)]",
+            // Axis: y.
+            "data-[swipe-axis=y]:inset-x-0 data-[swipe-axis=y]:data-nested-drawer-open:h-(--stack-height)",
+            // Axis: x.
+            "data-[swipe-axis=x]:inset-y-0 data-[swipe-axis=x]:flex-row",
+            // Direction: down.
+            "data-[swipe-direction=down]:bottom-0 data-[swipe-direction=down]:origin-bottom data-[swipe-direction=down]:[--closed-transform:translate3d(0,calc(100%+var(--drawer-inset,0px)+2px),0)] data-[swipe-direction=down]:[--translate-y:calc(var(--drawer-snap-point-offset,0px)+var(--drawer-swipe-movement-y)-var(--stack-peek-offset)-(var(--stack-shrink)*var(--stack-height)))]",
+            // Direction: up.
+            "data-[swipe-direction=up]:top-0 data-[swipe-direction=up]:origin-top data-[swipe-direction=up]:[--closed-transform:translate3d(0,calc(-100%-var(--drawer-inset,0px)-2px),0)] data-[swipe-direction=up]:[--translate-y:calc(var(--drawer-snap-point-offset,0px)+var(--drawer-swipe-movement-y)+var(--stack-peek-offset)+(var(--stack-shrink)*var(--stack-height)))]",
+            // Direction: left.
+            "data-[swipe-direction=left]:left-0 data-[swipe-direction=left]:origin-left data-[swipe-direction=left]:[--closed-transform:translate3d(calc(-100%-var(--drawer-inset,0px)-2px),0,0)] data-[swipe-direction=left]:[--translate-x:calc(var(--drawer-swipe-movement-x)+var(--stack-peek-offset)+(var(--stack-shrink)*100%))]",
+            // Direction: right.
+            "data-[swipe-direction=right]:right-0 data-[swipe-direction=right]:origin-right data-[swipe-direction=right]:[--closed-transform:translate3d(calc(100%+var(--drawer-inset,0px)+2px),0,0)] data-[swipe-direction=right]:[--translate-x:calc(var(--drawer-swipe-movement-x)-var(--stack-peek-offset)-(var(--stack-shrink)*100%))]",
+            className
+          )}
+          {...props}
+        >
+          {showSwipeHandle && <DrawerSwipeHandle />}
+          <DrawerPrimitive.Content
+            data-slot="drawer-content"
+            className={cn(
+              "flex min-h-0 flex-1 flex-col overflow-hidden overscroll-contain rounded-[inherit] transition-opacity duration-300 ease-[cubic-bezier(0.45,1.005,0,1.005)] select-text group-data-nested-drawer-open/drawer-popup:opacity-0 group-data-nested-drawer-swiping/drawer-popup:opacity-100 group-data-swiping/drawer-popup:select-none"
+            )}
+          >
+            {children}
+          </DrawerPrimitive.Content>
+        </DrawerPrimitive.Popup>
+      </DrawerPrimitive.Viewport>
+    </DrawerPortal>
+  )
+}
+
+function DrawerHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="drawer-header"
+      className={cn(
+        "flex shrink-0 flex-col gap-0.5 p-4 pb-0 group-data-[swipe-axis=y]/drawer-popup:text-center md:gap-1.5 md:text-left",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DrawerFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="drawer-footer"
+      className={cn("mt-auto flex shrink-0 flex-col gap-2 p-4 pt-0", className)}
+      {...props}
+    />
+  )
+}
+
+function DrawerTitle({ className, ...props }: DrawerPrimitive.Title.Props) {
+  return (
+    <DrawerPrimitive.Title
+      data-slot="drawer-title"
+      className={cn(
+        "font-heading text-base font-medium text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DrawerDescription({
+  className,
+  ...props
+}: DrawerPrimitive.Description.Props) {
+  return (
+    <DrawerPrimitive.Description
+      data-slot="drawer-description"
+      className={cn("text-sm text-balance text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Drawer,
+  DrawerPortal,
+  DrawerOverlay,
+  DrawerSwipeHandle,
+  DrawerTrigger,
+  DrawerClose,
+  DrawerContent,
+  DrawerHeader,
+  DrawerFooter,
+  DrawerTitle,
+  DrawerDescription,
+}
diff --git a/packages/web/src/components/ui/dropdown-menu.tsx b/packages/web/src/components/ui/dropdown-menu.tsx
new file mode 100644
index 0000000..04a92d2
--- /dev/null
+++ b/packages/web/src/components/ui/dropdown-menu.tsx
@@ -0,0 +1,265 @@
+import * as React from "react"
+import { Menu as MenuPrimitive } from "@base-ui/react/menu"
+
+import { cn } from "@/lib/utils"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { ArrowRight01Icon, Tick02Icon } from "@hugeicons/core-free-icons"
+
+function DropdownMenu({ ...props }: MenuPrimitive.Root.Props) {
+  return <MenuPrimitive.Root data-slot="dropdown-menu" {...props} />
+}
+
+function DropdownMenuPortal({ ...props }: MenuPrimitive.Portal.Props) {
+  return <MenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />
+}
+
+function DropdownMenuTrigger({ ...props }: MenuPrimitive.Trigger.Props) {
+  return <MenuPrimitive.Trigger data-slot="dropdown-menu-trigger" {...props} />
+}
+
+function DropdownMenuContent({
+  align = "start",
+  alignOffset = 0,
+  side = "bottom",
+  sideOffset = 4,
+  className,
+  ...props
+}: MenuPrimitive.Popup.Props &
+  Pick<
+    MenuPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset"
+  >) {
+  return (
+    <MenuPrimitive.Portal>
+      <MenuPrimitive.Positioner
+        className="isolate z-50 outline-none"
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+      >
+        <MenuPrimitive.Popup
+          data-slot="dropdown-menu-content"
+          className={cn("z-50 max-h-(--available-height) w-(--anchor-width) min-w-32 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-2xl p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/5 duration-100 outline-none data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:overflow-hidden data-closed:fade-out-0 data-closed:zoom-out-95 animate-none! relative bg-popover/70 before:pointer-events-none before:absolute before:inset-0 before:-z-1 before:rounded-[inherit] before:backdrop-blur-2xl before:backdrop-saturate-150 **:data-[slot$=-item]:focus:bg-foreground/10 **:data-[slot$=-item]:data-highlighted:bg-foreground/10 **:data-[slot$=-separator]:bg-foreground/5 **:data-[slot$=-trigger]:focus:bg-foreground/10 **:data-[slot$=-trigger]:aria-expanded:bg-foreground/10! **:data-[variant=destructive]:focus:bg-foreground/10! **:data-[variant=destructive]:text-accent-foreground! **:data-[variant=destructive]:**:text-accent-foreground!", className )}
+          {...props}
+        />
+      </MenuPrimitive.Positioner>
+    </MenuPrimitive.Portal>
+  )
+}
+
+function DropdownMenuGroup({ ...props }: MenuPrimitive.Group.Props) {
+  return <MenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />
+}
+
+function DropdownMenuLabel({
+  className,
+  inset,
+  ...props
+}: MenuPrimitive.GroupLabel.Props & {
+  inset?: boolean
+}) {
+  return (
+    <MenuPrimitive.GroupLabel
+      data-slot="dropdown-menu-label"
+      data-inset={inset}
+      className={cn(
+        "px-2 py-1 text-xs text-muted-foreground data-inset:pl-7",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuItem({
+  className,
+  inset,
+  variant = "default",
+  ...props
+}: MenuPrimitive.Item.Props & {
+  inset?: boolean
+  variant?: "default" | "destructive"
+}) {
+  return (
+    <MenuPrimitive.Item
+      data-slot="dropdown-menu-item"
+      data-inset={inset}
+      data-variant={variant}
+      className={cn(
+        "group/dropdown-menu-item relative flex min-h-7 cursor-default items-center gap-2 rounded-xl px-2 py-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-7 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-[variant=destructive]:*:[svg]:text-destructive",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuSub({ ...props }: MenuPrimitive.SubmenuRoot.Props) {
+  return <MenuPrimitive.SubmenuRoot data-slot="dropdown-menu-sub" {...props} />
+}
+
+function DropdownMenuSubTrigger({
+  className,
+  inset,
+  children,
+  ...props
+}: MenuPrimitive.SubmenuTrigger.Props & {
+  inset?: boolean
+}) {
+  return (
+    <MenuPrimitive.SubmenuTrigger
+      data-slot="dropdown-menu-sub-trigger"
+      data-inset={inset}
+      className={cn(
+        "flex min-h-7 cursor-default items-center gap-2 rounded-xl px-2 py-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-7 data-popup-open:bg-accent data-popup-open:text-accent-foreground data-open:bg-accent data-open:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <HugeiconsIcon icon={ArrowRight01Icon} strokeWidth={2} className="ml-auto" />
+    </MenuPrimitive.SubmenuTrigger>
+  )
+}
+
+function DropdownMenuSubContent({
+  align = "start",
+  alignOffset = -3,
+  side = "right",
+  sideOffset = 0,
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuContent>) {
+  return (
+    <DropdownMenuContent
+      data-slot="dropdown-menu-sub-content"
+      className={cn("w-auto min-w-[96px] rounded-2xl p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/5 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 animate-none! relative bg-popover/70 before:pointer-events-none before:absolute before:inset-0 before:-z-1 before:rounded-[inherit] before:backdrop-blur-2xl before:backdrop-saturate-150 **:data-[slot$=-item]:focus:bg-foreground/10 **:data-[slot$=-item]:data-highlighted:bg-foreground/10 **:data-[slot$=-separator]:bg-foreground/5 **:data-[slot$=-trigger]:focus:bg-foreground/10 **:data-[slot$=-trigger]:aria-expanded:bg-foreground/10! **:data-[variant=destructive]:focus:bg-foreground/10! **:data-[variant=destructive]:text-accent-foreground! **:data-[variant=destructive]:**:text-accent-foreground!", className )}
+      align={align}
+      alignOffset={alignOffset}
+      side={side}
+      sideOffset={sideOffset}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuCheckboxItem({
+  className,
+  children,
+  checked,
+  inset,
+  ...props
+}: MenuPrimitive.CheckboxItem.Props & {
+  inset?: boolean
+}) {
+  return (
+    <MenuPrimitive.CheckboxItem
+      data-slot="dropdown-menu-checkbox-item"
+      data-inset={inset}
+      className={cn(
+        "relative flex min-h-7 cursor-default items-center gap-2 rounded-xl py-1.5 pr-8 pl-2 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      checked={checked}
+      {...props}
+    >
+      <span
+        className="pointer-events-none absolute right-2 flex items-center justify-center"
+        data-slot="dropdown-menu-checkbox-item-indicator"
+      >
+        <MenuPrimitive.CheckboxItemIndicator>
+          <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} />
+        </MenuPrimitive.CheckboxItemIndicator>
+      </span>
+      {children}
+    </MenuPrimitive.CheckboxItem>
+  )
+}
+
+function DropdownMenuRadioGroup({ ...props }: MenuPrimitive.RadioGroup.Props) {
+  return (
+    <MenuPrimitive.RadioGroup
+      data-slot="dropdown-menu-radio-group"
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuRadioItem({
+  className,
+  children,
+  inset,
+  ...props
+}: MenuPrimitive.RadioItem.Props & {
+  inset?: boolean
+}) {
+  return (
+    <MenuPrimitive.RadioItem
+      data-slot="dropdown-menu-radio-item"
+      data-inset={inset}
+      className={cn(
+        "relative flex min-h-7 cursor-default items-center gap-2 rounded-xl py-1.5 pr-8 pl-2 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <span
+        className="pointer-events-none absolute right-2 flex items-center justify-center"
+        data-slot="dropdown-menu-radio-item-indicator"
+      >
+        <MenuPrimitive.RadioItemIndicator>
+          <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} />
+        </MenuPrimitive.RadioItemIndicator>
+      </span>
+      {children}
+    </MenuPrimitive.RadioItem>
+  )
+}
+
+function DropdownMenuSeparator({
+  className,
+  ...props
+}: MenuPrimitive.Separator.Props) {
+  return (
+    <MenuPrimitive.Separator
+      data-slot="dropdown-menu-separator"
+      className={cn("-mx-1 my-1 h-px bg-border/50", className)}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="dropdown-menu-shortcut"
+      className={cn(
+        "ml-auto text-xs tracking-widest text-muted-foreground group-focus/dropdown-menu-item:text-accent-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  DropdownMenu,
+  DropdownMenuPortal,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+}
diff --git a/packages/web/src/components/ui/empty.tsx b/packages/web/src/components/ui/empty.tsx
new file mode 100644
index 0000000..b1f429a
--- /dev/null
+++ b/packages/web/src/components/ui/empty.tsx
@@ -0,0 +1,104 @@
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+function Empty({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="empty"
+      className={cn(
+        "flex w-full min-w-0 flex-1 flex-col items-center justify-center gap-4 rounded-3xl border-dashed p-12 text-center text-balance",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function EmptyHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="empty-header"
+      className={cn("flex max-w-sm flex-col items-center gap-2", className)}
+      {...props}
+    />
+  )
+}
+
+const emptyMediaVariants = cva(
+  "mb-2 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        icon: "flex size-10 shrink-0 items-center justify-center rounded-xl bg-muted text-foreground [&_svg:not([class*='size-'])]:size-5",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function EmptyMedia({
+  className,
+  variant = "default",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof emptyMediaVariants>) {
+  return (
+    <div
+      data-slot="empty-icon"
+      data-variant={variant}
+      className={cn(emptyMediaVariants({ variant, className }))}
+      {...props}
+    />
+  )
+}
+
+function EmptyTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="empty-title"
+      className={cn(
+        "font-heading text-lg font-medium tracking-tight",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function EmptyDescription({ className, ...props }: React.ComponentProps<"p">) {
+  return (
+    <div
+      data-slot="empty-description"
+      className={cn(
+        "text-sm/relaxed text-muted-foreground [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function EmptyContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="empty-content"
+      className={cn(
+        "flex w-full max-w-sm min-w-0 flex-col items-center gap-4 text-sm text-balance",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Empty,
+  EmptyHeader,
+  EmptyTitle,
+  EmptyDescription,
+  EmptyContent,
+  EmptyMedia,
+}
diff --git a/packages/web/src/components/ui/field.tsx b/packages/web/src/components/ui/field.tsx
new file mode 100644
index 0000000..adcc3a6
--- /dev/null
+++ b/packages/web/src/components/ui/field.tsx
@@ -0,0 +1,238 @@
+"use client"
+
+import { useMemo } from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { Label } from "@/components/ui/label"
+import { Separator } from "@/components/ui/separator"
+
+function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
+  return (
+    <fieldset
+      data-slot="field-set"
+      className={cn(
+        "flex flex-col gap-6 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldLegend({
+  className,
+  variant = "legend",
+  ...props
+}: React.ComponentProps<"legend"> & { variant?: "legend" | "label" }) {
+  return (
+    <legend
+      data-slot="field-legend"
+      data-variant={variant}
+      className={cn(
+        "mb-3 font-medium data-[variant=label]:text-sm data-[variant=legend]:text-base",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-group"
+      className={cn(
+        "group/field-group @container/field-group flex w-full flex-col gap-6 data-[slot=checkbox-group]:gap-3 *:data-[slot=field-group]:gap-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const fieldVariants = cva(
+  "group/field flex w-full gap-3 data-[invalid=true]:text-destructive",
+  {
+    variants: {
+      orientation: {
+        vertical: "flex-col *:w-full [&>.sr-only]:w-auto",
+        horizontal:
+          "flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+        responsive:
+          "flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+      },
+    },
+    defaultVariants: {
+      orientation: "vertical",
+    },
+  }
+)
+
+function Field({
+  className,
+  orientation = "vertical",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="field"
+      data-orientation={orientation}
+      className={cn(fieldVariants({ orientation }), className)}
+      {...props}
+    />
+  )
+}
+
+function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-content"
+      className={cn(
+        "group/field-content flex flex-1 flex-col gap-1 leading-snug",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldLabel({
+  className,
+  ...props
+}: React.ComponentProps<typeof Label>) {
+  return (
+    <Label
+      data-slot="field-label"
+      className={cn(
+        "group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50 has-data-checked:bg-input/30 has-[>[data-slot=field]]:rounded-2xl has-[>[data-slot=field]]:border *:data-[slot=field]:p-4",
+        "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-label"
+      className={cn(
+        "flex w-fit items-center gap-2 text-sm font-medium group-data-[disabled=true]/field:opacity-50",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
+  return (
+    <p
+      data-slot="field-description"
+      className={cn(
+        "text-left text-sm leading-normal font-normal text-muted-foreground group-has-data-horizontal/field:text-balance [[data-variant=legend]+&]:-mt-1.5",
+        "last:mt-0 nth-last-2:-mt-1",
+        "[&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldSeparator({
+  children,
+  className,
+  ...props
+}: React.ComponentProps<"div"> & {
+  children?: React.ReactNode
+}) {
+  return (
+    <div
+      data-slot="field-separator"
+      data-content={!!children}
+      className={cn(
+        "relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2",
+        className
+      )}
+      {...props}
+    >
+      <Separator className="absolute inset-0 top-1/2" />
+      {children && (
+        <span
+          className="relative mx-auto block w-fit bg-background px-2 text-muted-foreground"
+          data-slot="field-separator-content"
+        >
+          {children}
+        </span>
+      )}
+    </div>
+  )
+}
+
+function FieldError({
+  className,
+  children,
+  errors,
+  ...props
+}: React.ComponentProps<"div"> & {
+  errors?: Array<{ message?: string } | undefined>
+}) {
+  const content = useMemo(() => {
+    if (children) {
+      return children
+    }
+
+    if (!errors?.length) {
+      return null
+    }
+
+    const uniqueErrors = [
+      ...new Map(errors.map((error) => [error?.message, error])).values(),
+    ]
+
+    if (uniqueErrors?.length == 1) {
+      return uniqueErrors[0]?.message
+    }
+
+    return (
+      <ul className="ml-4 flex list-disc flex-col gap-1">
+        {uniqueErrors.map(
+          (error, index) =>
+            error?.message && <li key={index}>{error.message}</li>
+        )}
+      </ul>
+    )
+  }, [children, errors])
+
+  if (!content) {
+    return null
+  }
+
+  return (
+    <div
+      role="alert"
+      data-slot="field-error"
+      className={cn("text-sm font-normal text-destructive", className)}
+      {...props}
+    >
+      {content}
+    </div>
+  )
+}
+
+export {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLegend,
+  FieldSeparator,
+  FieldSet,
+  FieldContent,
+  FieldTitle,
+}
diff --git a/packages/web/src/components/ui/hover-card.tsx b/packages/web/src/components/ui/hover-card.tsx
new file mode 100644
index 0000000..9960988
--- /dev/null
+++ b/packages/web/src/components/ui/hover-card.tsx
@@ -0,0 +1,51 @@
+"use client"
+
+import { PreviewCard as PreviewCardPrimitive } from "@base-ui/react/preview-card"
+
+import { cn } from "@/lib/utils"
+
+function HoverCard({ ...props }: PreviewCardPrimitive.Root.Props) {
+  return <PreviewCardPrimitive.Root data-slot="hover-card" {...props} />
+}
+
+function HoverCardTrigger({ ...props }: PreviewCardPrimitive.Trigger.Props) {
+  return (
+    <PreviewCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
+  )
+}
+
+function HoverCardContent({
+  className,
+  side = "bottom",
+  sideOffset = 4,
+  align = "center",
+  alignOffset = 4,
+  ...props
+}: PreviewCardPrimitive.Popup.Props &
+  Pick<
+    PreviewCardPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset"
+  >) {
+  return (
+    <PreviewCardPrimitive.Portal data-slot="hover-card-portal">
+      <PreviewCardPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+        className="isolate z-50"
+      >
+        <PreviewCardPrimitive.Popup
+          data-slot="hover-card-content"
+          className={cn(
+            "z-50 w-72 origin-(--transform-origin) rounded-3xl bg-popover p-4 text-sm text-popover-foreground shadow-lg ring-1 ring-foreground/5 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            className
+          )}
+          {...props}
+        />
+      </PreviewCardPrimitive.Positioner>
+    </PreviewCardPrimitive.Portal>
+  )
+}
+
+export { HoverCard, HoverCardTrigger, HoverCardContent }
diff --git a/packages/web/src/components/ui/input-group.tsx b/packages/web/src/components/ui/input-group.tsx
new file mode 100644
index 0000000..e33b511
--- /dev/null
+++ b/packages/web/src/components/ui/input-group.tsx
@@ -0,0 +1,155 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Textarea } from "@/components/ui/textarea"
+
+function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="input-group"
+      role="group"
+      className={cn(
+        "group/input-group relative flex h-8 w-full min-w-0 items-center rounded-2xl border border-transparent bg-input/50 transition-[color,box-shadow] duration-200 outline-none in-data-[slot=combobox-content]:focus-within:border-inherit in-data-[slot=combobox-content]:focus-within:ring-0 has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-3 has-[[data-slot=input-group-control]:focus-visible]:ring-ring/30 has-[[data-slot][aria-invalid=true]]:border-destructive has-[[data-slot][aria-invalid=true]]:ring-3 has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>textarea]:h-auto dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40 has-[>[data-align=block-end]]:[&>input]:pt-3 has-[>[data-align=block-start]]:[&>input]:pb-3 has-[>[data-align=inline-end]]:[&>input]:pr-1.5 has-[>[data-align=inline-start]]:[&>input]:pl-1.5",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const inputGroupAddonVariants = cva(
+  "flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 **:data-[slot=kbd]:rounded-2xl **:data-[slot=kbd]:bg-muted-foreground/10 **:data-[slot=kbd]:px-1.5 [&>svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      align: {
+        "inline-start":
+          "order-first pl-2 has-[>button]:ml-[-0.3rem] has-[>kbd]:ml-[-0.15rem]",
+        "inline-end":
+          "order-last pr-2 has-[>button]:mr-[-0.3rem] has-[>kbd]:mr-[-0.15rem]",
+        "block-start":
+          "order-first w-full justify-start px-2.5 pt-2 group-has-[>input]/input-group:pt-2 [.border-b]:pb-2",
+        "block-end":
+          "order-last w-full justify-start px-2.5 pb-2 group-has-[>input]/input-group:pb-2 [.border-t]:pt-2",
+      },
+    },
+    defaultVariants: {
+      align: "inline-start",
+    },
+  }
+)
+
+function InputGroupAddon({
+  className,
+  align = "inline-start",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="input-group-addon"
+      data-align={align}
+      className={cn(inputGroupAddonVariants({ align }), className)}
+      onClick={(e) => {
+        if ((e.target as HTMLElement).closest("button")) {
+          return
+        }
+        e.currentTarget.parentElement?.querySelector("input")?.focus()
+      }}
+      {...props}
+    />
+  )
+}
+
+const inputGroupButtonVariants = cva(
+  "flex items-center gap-2 rounded-2xl text-sm shadow-none",
+  {
+    variants: {
+      size: {
+        xs: "h-6 gap-1 rounded-xl px-1.5 [&>svg:not([class*='size-'])]:size-3.5",
+        sm: "",
+        "icon-xs": "size-6 rounded-xl p-0 has-[>svg]:p-0",
+        "icon-sm": "size-8 p-0 has-[>svg]:p-0",
+      },
+    },
+    defaultVariants: {
+      size: "xs",
+    },
+  }
+)
+
+function InputGroupButton({
+  className,
+  type = "button",
+  variant = "ghost",
+  size = "xs",
+  ...props
+}: Omit<React.ComponentProps<typeof Button>, "size" | "type"> &
+  VariantProps<typeof inputGroupButtonVariants> & {
+    type?: "button" | "submit" | "reset"
+  }) {
+  return (
+    <Button
+      type={type}
+      data-size={size}
+      variant={variant}
+      className={cn(inputGroupButtonVariants({ size }), className)}
+      {...props}
+    />
+  )
+}
+
+function InputGroupText({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      className={cn(
+        "flex items-center gap-2 text-sm text-muted-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function InputGroupInput({
+  className,
+  ...props
+}: React.ComponentProps<"input">) {
+  return (
+    <Input
+      data-slot="input-group-control"
+      className={cn(
+        "flex-1 rounded-none border-0 bg-transparent shadow-none ring-0 focus-visible:ring-0 aria-invalid:ring-0 dark:bg-transparent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function InputGroupTextarea({
+  className,
+  ...props
+}: React.ComponentProps<"textarea">) {
+  return (
+    <Textarea
+      data-slot="input-group-control"
+      className={cn(
+        "flex-1 resize-none rounded-none border-0 bg-transparent py-2 shadow-none ring-0 focus-visible:ring-0 aria-invalid:ring-0 dark:bg-transparent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupText,
+  InputGroupInput,
+  InputGroupTextarea,
+}
diff --git a/packages/web/src/components/ui/input-otp.tsx b/packages/web/src/components/ui/input-otp.tsx
new file mode 100644
index 0000000..5b73326
--- /dev/null
+++ b/packages/web/src/components/ui/input-otp.tsx
@@ -0,0 +1,85 @@
+import * as React from "react"
+import { OTPInput, OTPInputContext } from "input-otp"
+
+import { cn } from "@/lib/utils"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { MinusSignIcon } from "@hugeicons/core-free-icons"
+
+function InputOTP({
+  className,
+  containerClassName,
+  ...props
+}: React.ComponentProps<typeof OTPInput> & {
+  containerClassName?: string
+}) {
+  return (
+    <OTPInput
+      data-slot="input-otp"
+      containerClassName={cn(
+        "cn-input-otp flex items-center has-disabled:opacity-50",
+        containerClassName
+      )}
+      spellCheck={false}
+      className={cn("disabled:cursor-not-allowed", className)}
+      {...props}
+    />
+  )
+}
+
+function InputOTPGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="input-otp-group"
+      className={cn(
+        "flex items-center rounded-2xl has-aria-invalid:border-destructive has-aria-invalid:ring-3 has-aria-invalid:ring-destructive/20 dark:has-aria-invalid:ring-destructive/40",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function InputOTPSlot({
+  index,
+  className,
+  ...props
+}: React.ComponentProps<"div"> & {
+  index: number
+}) {
+  const inputOTPContext = React.useContext(OTPInputContext)
+  const { char, hasFakeCaret, isActive } = inputOTPContext?.slots[index] ?? {}
+
+  return (
+    <div
+      data-slot="input-otp-slot"
+      data-active={isActive}
+      className={cn(
+        "relative flex size-8 items-center justify-center border-y border-r border-input bg-input/50 text-sm transition-[color,box-shadow] duration-200 outline-none first:rounded-l-2xl first:border-l last:rounded-r-2xl aria-invalid:border-destructive data-[active=true]:z-10 data-[active=true]:border-ring data-[active=true]:ring-3 data-[active=true]:ring-ring/30 data-[active=true]:aria-invalid:ring-destructive/20 dark:data-[active=true]:aria-invalid:ring-destructive/40",
+        className
+      )}
+      {...props}
+    >
+      {char}
+      {hasFakeCaret && (
+        <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
+          <div className="h-4 w-px animate-caret-blink bg-foreground duration-1000" />
+        </div>
+      )}
+    </div>
+  )
+}
+
+function InputOTPSeparator({ ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="input-otp-separator"
+      className="flex items-center [&_svg:not([class*='size-'])]:size-4"
+      role="separator"
+      {...props}
+    >
+      <HugeiconsIcon icon={MinusSignIcon} strokeWidth={2} />
+    </div>
+  )
+}
+
+export { InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator }
diff --git a/packages/web/src/components/ui/input.tsx b/packages/web/src/components/ui/input.tsx
new file mode 100644
index 0000000..f40013f
--- /dev/null
+++ b/packages/web/src/components/ui/input.tsx
@@ -0,0 +1,20 @@
+import * as React from "react"
+import { Input as InputPrimitive } from "@base-ui/react/input"
+
+import { cn } from "@/lib/utils"
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <InputPrimitive
+      type={type}
+      data-slot="input"
+      className={cn(
+        "h-8 w-full min-w-0 rounded-2xl border border-transparent bg-input/50 px-2.5 py-1 text-base transition-[color,box-shadow] duration-200 outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input }
diff --git a/packages/web/src/components/ui/item.tsx b/packages/web/src/components/ui/item.tsx
new file mode 100644
index 0000000..b48cfa9
--- /dev/null
+++ b/packages/web/src/components/ui/item.tsx
@@ -0,0 +1,201 @@
+import * as React from "react"
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { Separator } from "@/components/ui/separator"
+
+function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      role="list"
+      data-slot="item-group"
+      className={cn(
+        "group/item-group flex w-full flex-col gap-4 has-data-[size=sm]:gap-2.5 has-data-[size=xs]:gap-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ItemSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof Separator>) {
+  return (
+    <Separator
+      data-slot="item-separator"
+      orientation="horizontal"
+      className={cn("my-2", className)}
+      {...props}
+    />
+  )
+}
+
+const itemVariants = cva(
+  "group/item flex w-full flex-wrap items-center rounded-2xl border text-sm transition-colors duration-100 outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 [a]:transition-colors [a]:hover:bg-muted",
+  {
+    variants: {
+      variant: {
+        default: "border-transparent",
+        outline: "border-border",
+        muted: "border-transparent bg-muted/50",
+      },
+      size: {
+        default: "gap-3.5 px-4 py-3.5",
+        sm: "gap-3.5 px-3.5 py-3",
+        xs: "gap-2 px-2.5 py-2 in-data-[slot=dropdown-menu-content]:p-0",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function Item({
+  className,
+  variant = "default",
+  size = "default",
+  render,
+  ...props
+}: useRender.ComponentProps<"div"> & VariantProps<typeof itemVariants>) {
+  return useRender({
+    defaultTagName: "div",
+    props: mergeProps<"div">(
+      {
+        className: cn(itemVariants({ variant, size, className })),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "item",
+      variant,
+      size,
+    },
+  })
+}
+
+const itemMediaVariants = cva(
+  "flex shrink-0 items-center justify-center gap-2 group-has-data-[slot=item-description]/item:translate-y-0.5 group-has-data-[slot=item-description]/item:self-start [&_svg]:pointer-events-none",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        icon: "[&_svg:not([class*='size-'])]:size-4",
+        image:
+          "size-10 overflow-hidden rounded-xl group-data-[size=sm]/item:size-8 group-data-[size=xs]/item:size-6 group-data-[size=xs]/item:rounded-lg [&_img]:size-full [&_img]:object-cover",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function ItemMedia({
+  className,
+  variant = "default",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof itemMediaVariants>) {
+  return (
+    <div
+      data-slot="item-media"
+      data-variant={variant}
+      className={cn(itemMediaVariants({ variant, className }))}
+      {...props}
+    />
+  )
+}
+
+function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="item-content"
+      className={cn(
+        "flex flex-1 flex-col gap-1 group-data-[size=xs]/item:gap-0.5 [&+[data-slot=item-content]]:flex-none",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="item-title"
+      className={cn(
+        "line-clamp-1 flex w-fit items-center gap-2 text-sm leading-snug font-medium underline-offset-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ItemDescription({ className, ...props }: React.ComponentProps<"p">) {
+  return (
+    <p
+      data-slot="item-description"
+      className={cn(
+        "line-clamp-2 text-left text-sm font-normal text-muted-foreground [&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="item-actions"
+      className={cn("flex items-center gap-2", className)}
+      {...props}
+    />
+  )
+}
+
+function ItemHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="item-header"
+      className={cn(
+        "flex basis-full items-center justify-between gap-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ItemFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="item-footer"
+      className={cn(
+        "flex basis-full items-center justify-between gap-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemActions,
+  ItemGroup,
+  ItemSeparator,
+  ItemTitle,
+  ItemDescription,
+  ItemHeader,
+  ItemFooter,
+}
diff --git a/packages/web/src/components/ui/kbd.tsx b/packages/web/src/components/ui/kbd.tsx
new file mode 100644
index 0000000..53819c3
--- /dev/null
+++ b/packages/web/src/components/ui/kbd.tsx
@@ -0,0 +1,26 @@
+import { cn } from "@/lib/utils"
+
+function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {
+  return (
+    <kbd
+      data-slot="kbd"
+      className={cn(
+        "pointer-events-none inline-flex h-5 w-fit min-w-5 items-center justify-center gap-1 rounded-lg bg-muted px-1 font-sans text-xs font-medium text-muted-foreground select-none in-data-[slot=input-group]:bg-input in-data-[slot=tooltip-content]:bg-background/20 in-data-[slot=tooltip-content]:text-background dark:in-data-[slot=tooltip-content]:bg-background/10 [&_svg:not([class*='size-'])]:size-3",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function KbdGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <kbd
+      data-slot="kbd-group"
+      className={cn("inline-flex items-center gap-1", className)}
+      {...props}
+    />
+  )
+}
+
+export { Kbd, KbdGroup }
diff --git a/packages/web/src/components/ui/label.tsx b/packages/web/src/components/ui/label.tsx
new file mode 100644
index 0000000..74da65c
--- /dev/null
+++ b/packages/web/src/components/ui/label.tsx
@@ -0,0 +1,20 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Label({ className, ...props }: React.ComponentProps<"label">) {
+  return (
+    <label
+      data-slot="label"
+      className={cn(
+        "flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Label }
diff --git a/packages/web/src/components/ui/marker.tsx b/packages/web/src/components/ui/marker.tsx
new file mode 100644
index 0000000..f59cca4
--- /dev/null
+++ b/packages/web/src/components/ui/marker.tsx
@@ -0,0 +1,71 @@
+import * as React from "react"
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const markerVariants = cva(
+  "group/marker relative flex min-h-4 w-full items-center gap-2 text-left text-sm text-muted-foreground [&_svg:not([class*='size-'])]:size-4 [a]:underline [a]:underline-offset-3 [a]:hover:text-foreground",
+  {
+    variants: {
+      variant: {
+        default: "",
+        separator:
+          "before:mr-1 before:h-px before:min-w-0 before:flex-1 before:bg-border after:ml-1 after:h-px after:min-w-0 after:flex-1 after:bg-border",
+        border: "border-b border-border pb-2",
+      },
+    },
+  }
+)
+
+function Marker({
+  className,
+  variant = "default",
+  render,
+  ...props
+}: useRender.ComponentProps<"div"> & VariantProps<typeof markerVariants>) {
+  return useRender({
+    defaultTagName: "div",
+    props: mergeProps<"div">(
+      {
+        className: cn(markerVariants({ variant, className })),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "marker",
+      variant,
+    },
+  })
+}
+
+function MarkerIcon({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="marker-icon"
+      aria-hidden="true"
+      className={cn(
+        "size-4 shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MarkerContent({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="marker-content"
+      className={cn(
+        "min-w-0 wrap-break-word group-data-[variant=separator]/marker:flex-none group-data-[variant=separator]/marker:text-center *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Marker, MarkerIcon, MarkerContent, markerVariants }
diff --git a/packages/web/src/components/ui/menubar.tsx b/packages/web/src/components/ui/menubar.tsx
new file mode 100644
index 0000000..f8742a3
--- /dev/null
+++ b/packages/web/src/components/ui/menubar.tsx
@@ -0,0 +1,277 @@
+import * as React from "react"
+import { Menu as MenuPrimitive } from "@base-ui/react/menu"
+import { Menubar as MenubarPrimitive } from "@base-ui/react/menubar"
+
+import { cn } from "@/lib/utils"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuPortal,
+  DropdownMenuRadioGroup,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { Tick02Icon } from "@hugeicons/core-free-icons"
+
+function Menubar({ className, ...props }: MenubarPrimitive.Props) {
+  return (
+    <MenubarPrimitive
+      data-slot="menubar"
+      className={cn(
+        "flex h-8 items-center rounded-2xl border p-[3px]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MenubarMenu({ ...props }: React.ComponentProps<typeof DropdownMenu>) {
+  return <DropdownMenu data-slot="menubar-menu" {...props} />
+}
+
+function MenubarGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuGroup>) {
+  return <DropdownMenuGroup data-slot="menubar-group" {...props} />
+}
+
+function MenubarPortal({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPortal>) {
+  return <DropdownMenuPortal data-slot="menubar-portal" {...props} />
+}
+
+function MenubarTrigger({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuTrigger>) {
+  return (
+    <DropdownMenuTrigger
+      data-slot="menubar-trigger"
+      className={cn(
+        "flex items-center rounded-2xl px-1.5 py-[2px] text-sm font-medium outline-hidden select-none hover:bg-muted aria-expanded:bg-muted",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MenubarContent({
+  className,
+  align = "start",
+  alignOffset = -4,
+  sideOffset = 8,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuContent>) {
+  return (
+    <DropdownMenuContent
+      data-slot="menubar-content"
+      align={align}
+      alignOffset={alignOffset}
+      sideOffset={sideOffset}
+      className={cn("min-w-36 rounded-2xl p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/5 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 animate-none! relative bg-popover/70 before:pointer-events-none before:absolute before:inset-0 before:-z-1 before:rounded-[inherit] before:backdrop-blur-2xl before:backdrop-saturate-150 **:data-[slot$=-item]:focus:bg-foreground/10 **:data-[slot$=-item]:data-highlighted:bg-foreground/10 **:data-[slot$=-separator]:bg-foreground/5 **:data-[slot$=-trigger]:focus:bg-foreground/10 **:data-[slot$=-trigger]:aria-expanded:bg-foreground/10! **:data-[variant=destructive]:focus:bg-foreground/10! **:data-[variant=destructive]:text-accent-foreground! **:data-[variant=destructive]:**:text-accent-foreground!", className )}
+      {...props}
+    />
+  )
+}
+
+function MenubarItem({
+  className,
+  inset,
+  variant = "default",
+  ...props
+}: React.ComponentProps<typeof DropdownMenuItem>) {
+  return (
+    <DropdownMenuItem
+      data-slot="menubar-item"
+      data-inset={inset}
+      data-variant={variant}
+      className={cn(
+        "group/menubar-item min-h-7 gap-2 rounded-xl px-2 py-1.5 text-sm focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-7 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 data-disabled:opacity-50 [&_svg:not([class*='size-'])]:size-4 data-[variant=destructive]:*:[svg]:text-destructive!",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MenubarCheckboxItem({
+  className,
+  children,
+  checked,
+  inset,
+  ...props
+}: MenuPrimitive.CheckboxItem.Props & {
+  inset?: boolean
+}) {
+  return (
+    <MenuPrimitive.CheckboxItem
+      data-slot="menubar-checkbox-item"
+      data-inset={inset}
+      className={cn(
+        "relative flex min-h-7 cursor-default items-center gap-2 rounded-xl py-1.5 pr-1.5 pl-7 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        className
+      )}
+      checked={checked}
+      {...props}
+    >
+      <span className="pointer-events-none absolute left-1.5 flex size-4 items-center justify-center [&_svg:not([class*='size-'])]:size-4">
+        <MenuPrimitive.CheckboxItemIndicator>
+          <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} />
+        </MenuPrimitive.CheckboxItemIndicator>
+      </span>
+      {children}
+    </MenuPrimitive.CheckboxItem>
+  )
+}
+
+function MenubarRadioGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuRadioGroup>) {
+  return <DropdownMenuRadioGroup data-slot="menubar-radio-group" {...props} />
+}
+
+function MenubarRadioItem({
+  className,
+  children,
+  inset,
+  ...props
+}: MenuPrimitive.RadioItem.Props & {
+  inset?: boolean
+}) {
+  return (
+    <MenuPrimitive.RadioItem
+      data-slot="menubar-radio-item"
+      data-inset={inset}
+      className={cn(
+        "relative flex min-h-7 cursor-default items-center gap-2 rounded-xl py-1.5 pr-1.5 pl-7 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <span className="pointer-events-none absolute left-1.5 flex size-4 items-center justify-center [&_svg:not([class*='size-'])]:size-4">
+        <MenuPrimitive.RadioItemIndicator>
+          <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} />
+        </MenuPrimitive.RadioItemIndicator>
+      </span>
+      {children}
+    </MenuPrimitive.RadioItem>
+  )
+}
+
+function MenubarLabel({
+  className,
+  inset,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuLabel> & {
+  inset?: boolean
+}) {
+  return (
+    <DropdownMenuLabel
+      data-slot="menubar-label"
+      data-inset={inset}
+      className={cn(
+        "px-2 py-1 text-sm text-muted-foreground data-inset:pl-7",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MenubarSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuSeparator>) {
+  return (
+    <DropdownMenuSeparator
+      data-slot="menubar-separator"
+      className={cn("-mx-1 my-1 h-px bg-border/50", className)}
+      {...props}
+    />
+  )
+}
+
+function MenubarShortcut({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuShortcut>) {
+  return (
+    <DropdownMenuShortcut
+      data-slot="menubar-shortcut"
+      className={cn(
+        "ml-auto text-xs tracking-widest text-muted-foreground group-focus/menubar-item:text-accent-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MenubarSub({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuSub>) {
+  return <DropdownMenuSub data-slot="menubar-sub" {...props} />
+}
+
+function MenubarSubTrigger({
+  className,
+  inset,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuSubTrigger> & {
+  inset?: boolean
+}) {
+  return (
+    <DropdownMenuSubTrigger
+      data-slot="menubar-sub-trigger"
+      data-inset={inset}
+      className={cn(
+        "min-h-7 gap-2 rounded-xl px-2 py-1.5 text-sm focus:bg-accent focus:text-accent-foreground data-inset:pl-7 data-open:bg-accent data-open:text-accent-foreground [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MenubarSubContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuSubContent>) {
+  return (
+    <DropdownMenuSubContent
+      data-slot="menubar-sub-content"
+      className={cn("min-w-32 rounded-2xl p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/5 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 animate-none! relative bg-popover/70 before:pointer-events-none before:absolute before:inset-0 before:-z-1 before:rounded-[inherit] before:backdrop-blur-2xl before:backdrop-saturate-150 **:data-[slot$=-item]:focus:bg-foreground/10 **:data-[slot$=-item]:data-highlighted:bg-foreground/10 **:data-[slot$=-separator]:bg-foreground/5 **:data-[slot$=-trigger]:focus:bg-foreground/10 **:data-[slot$=-trigger]:aria-expanded:bg-foreground/10! **:data-[variant=destructive]:focus:bg-foreground/10! **:data-[variant=destructive]:text-accent-foreground! **:data-[variant=destructive]:**:text-accent-foreground!", className )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Menubar,
+  MenubarPortal,
+  MenubarMenu,
+  MenubarTrigger,
+  MenubarContent,
+  MenubarGroup,
+  MenubarSeparator,
+  MenubarLabel,
+  MenubarItem,
+  MenubarShortcut,
+  MenubarCheckboxItem,
+  MenubarRadioGroup,
+  MenubarRadioItem,
+  MenubarSub,
+  MenubarSubTrigger,
+  MenubarSubContent,
+}
diff --git a/packages/web/src/components/ui/message-scroller.tsx b/packages/web/src/components/ui/message-scroller.tsx
new file mode 100644
index 0000000..fe23132
--- /dev/null
+++ b/packages/web/src/components/ui/message-scroller.tsx
@@ -0,0 +1,131 @@
+"use client"
+
+import * as React from "react"
+import {
+  MessageScroller as MessageScrollerPrimitive,
+  useMessageScroller,
+  useMessageScrollerScrollable,
+  useMessageScrollerVisibility,
+} from "@shadcn/react/message-scroller"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { ArrowDown02Icon } from "@hugeicons/core-free-icons"
+
+function MessageScrollerProvider(
+  props: React.ComponentProps<typeof MessageScrollerPrimitive.Provider>
+) {
+  return <MessageScrollerPrimitive.Provider {...props} />
+}
+
+function MessageScroller({
+  className,
+  ...props
+}: React.ComponentProps<typeof MessageScrollerPrimitive.Root>) {
+  return (
+    <MessageScrollerPrimitive.Root
+      data-slot="message-scroller"
+      className={cn(
+        "group/message-scroller relative flex size-full min-h-0 flex-col overflow-hidden",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageScrollerViewport({
+  className,
+  ...props
+}: React.ComponentProps<typeof MessageScrollerPrimitive.Viewport>) {
+  return (
+    <MessageScrollerPrimitive.Viewport
+      data-slot="message-scroller-viewport"
+      className={cn(
+        "size-full min-h-0 min-w-0 scroll-fade-b scrollbar-thin scrollbar-gutter-stable overflow-y-auto overscroll-contain contain-content data-autoscrolling:scrollbar-thumb-transparent data-autoscrolling:scrollbar-track-transparent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageScrollerContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof MessageScrollerPrimitive.Content>) {
+  return (
+    <MessageScrollerPrimitive.Content
+      data-slot="message-scroller-content"
+      className={cn("flex h-max min-h-full flex-col gap-8", className)}
+      {...props}
+    />
+  )
+}
+
+function MessageScrollerItem({
+  className,
+  scrollAnchor = false,
+  ...props
+}: React.ComponentProps<typeof MessageScrollerPrimitive.Item>) {
+  return (
+    <MessageScrollerPrimitive.Item
+      data-slot="message-scroller-item"
+      scrollAnchor={scrollAnchor}
+      className={cn(
+        "min-w-0 shrink-0 [contain-intrinsic-size:auto_10rem] [content-visibility:auto]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageScrollerButton({
+  direction = "end",
+  className,
+  children,
+  render,
+  variant = "secondary",
+  size = "icon-sm",
+  ...props
+}: React.ComponentProps<typeof MessageScrollerPrimitive.Button> &
+  Pick<React.ComponentProps<typeof Button>, "variant" | "size">) {
+  return (
+    <MessageScrollerPrimitive.Button
+      data-slot="message-scroller-button"
+      data-direction={direction}
+      data-variant={variant}
+      data-size={size}
+      direction={direction}
+      className={cn(
+        "absolute inset-s-1/2 -translate-x-1/2 border-border bg-background text-foreground transition-[translate,scale,opacity] duration-200 hover:bg-muted hover:text-foreground data-[active=false]:pointer-events-none data-[active=false]:scale-95 data-[active=false]:opacity-0 data-[active=false]:duration-400 data-[active=false]:ease-[cubic-bezier(0.7,0,0.84,0)] data-[active=true]:translate-y-0 data-[active=true]:scale-100 data-[active=true]:opacity-100 data-[active=true]:ease-[cubic-bezier(0.23,1,0.32,1)] data-[direction=end]:bottom-4 data-[direction=end]:data-[active=false]:translate-y-full data-[direction=start]:top-4 data-[direction=start]:data-[active=false]:-translate-y-full rtl:translate-x-1/2 data-[direction=start]:[&_svg]:rotate-180",
+        className
+      )}
+      render={render ?? <Button variant={variant} size={size} />}
+      {...props}
+    >
+      {children ?? (
+        <>
+          <HugeiconsIcon icon={ArrowDown02Icon} strokeWidth={2} />
+          <span className="sr-only">
+            {direction === "end" ? "Scroll to end" : "Scroll to start"}
+          </span>
+        </>
+      )}
+    </MessageScrollerPrimitive.Button>
+  )
+}
+
+export {
+  MessageScrollerProvider,
+  MessageScroller,
+  MessageScrollerViewport,
+  MessageScrollerContent,
+  MessageScrollerItem,
+  MessageScrollerButton,
+  useMessageScroller,
+  useMessageScrollerScrollable,
+  useMessageScrollerVisibility,
+}
diff --git a/packages/web/src/components/ui/message.tsx b/packages/web/src/components/ui/message.tsx
new file mode 100644
index 0000000..53437e8
--- /dev/null
+++ b/packages/web/src/components/ui/message.tsx
@@ -0,0 +1,92 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function MessageGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="message-group"
+      className={cn("flex min-w-0 flex-col gap-2", className)}
+      {...props}
+    />
+  )
+}
+
+function Message({
+  className,
+  align = "start",
+  ...props
+}: React.ComponentProps<"div"> & { align?: "start" | "end" }) {
+  return (
+    <div
+      data-slot="message"
+      data-align={align}
+      className={cn(
+        "group/message relative flex w-full min-w-0 gap-2 text-sm data-[align=end]:flex-row-reverse",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageAvatar({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="message-avatar"
+      className={cn(
+        "flex w-fit min-w-8 shrink-0 items-center justify-center self-end overflow-hidden rounded-full bg-muted group-has-data-[slot=message-footer]/message:-translate-y-8",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="message-content"
+      className={cn(
+        "flex w-full min-w-0 flex-col gap-2.5 wrap-break-word group-data-[align=end]/message:*:data-slot:self-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="message-header"
+      className={cn(
+        "flex max-w-full min-w-0 items-center px-3 text-xs font-medium text-muted-foreground group-has-data-[variant=ghost]/message:px-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function MessageFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="message-footer"
+      className={cn(
+        "flex max-w-full min-w-0 items-center px-3 text-xs font-medium text-muted-foreground group-has-data-[variant=ghost]/message:px-0 group-data-[align=end]/message:justify-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  MessageGroup,
+  Message,
+  MessageAvatar,
+  MessageContent,
+  MessageFooter,
+  MessageHeader,
+}
diff --git a/packages/web/src/components/ui/native-select.tsx b/packages/web/src/components/ui/native-select.tsx
new file mode 100644
index 0000000..a5ba767
--- /dev/null
+++ b/packages/web/src/components/ui/native-select.tsx
@@ -0,0 +1,62 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { UnfoldMoreIcon } from "@hugeicons/core-free-icons"
+
+type NativeSelectProps = Omit<React.ComponentProps<"select">, "size"> & {
+  size?: "sm" | "default"
+}
+
+function NativeSelect({
+  className,
+  size = "default",
+  ...props
+}: NativeSelectProps) {
+  return (
+    <div
+      className={cn(
+        "group/native-select relative w-fit has-[select:disabled]:opacity-50",
+        className
+      )}
+      data-slot="native-select-wrapper"
+      data-size={size}
+    >
+      <select
+        data-slot="native-select"
+        data-size={size}
+        className="h-8 w-full min-w-0 appearance-none rounded-2xl border border-transparent bg-input/50 py-1 pr-8 pl-2.5 text-sm transition-[color,box-shadow] duration-200 outline-none select-none selection:bg-primary selection:text-primary-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 disabled:pointer-events-none disabled:cursor-not-allowed aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-[size=sm]:h-7 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40"
+        {...props}
+      />
+      <HugeiconsIcon icon={UnfoldMoreIcon} strokeWidth={2} className="pointer-events-none absolute top-1/2 right-2.5 size-4 -translate-y-1/2 text-muted-foreground select-none" aria-hidden="true" data-slot="native-select-icon" />
+    </div>
+  )
+}
+
+function NativeSelectOption({
+  className,
+  ...props
+}: React.ComponentProps<"option">) {
+  return (
+    <option
+      data-slot="native-select-option"
+      className={cn("bg-[Canvas] text-[CanvasText]", className)}
+      {...props}
+    />
+  )
+}
+
+function NativeSelectOptGroup({
+  className,
+  ...props
+}: React.ComponentProps<"optgroup">) {
+  return (
+    <optgroup
+      data-slot="native-select-optgroup"
+      className={cn("bg-[Canvas] text-[CanvasText]", className)}
+      {...props}
+    />
+  )
+}
+
+export { NativeSelect, NativeSelectOptGroup, NativeSelectOption }
diff --git a/packages/web/src/components/ui/navigation-menu.tsx b/packages/web/src/components/ui/navigation-menu.tsx
new file mode 100644
index 0000000..56cd409
--- /dev/null
+++ b/packages/web/src/components/ui/navigation-menu.tsx
@@ -0,0 +1,169 @@
+import { NavigationMenu as NavigationMenuPrimitive } from "@base-ui/react/navigation-menu"
+import { cva } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { ArrowDown01Icon } from "@hugeicons/core-free-icons"
+
+function NavigationMenu({
+  align = "start",
+  className,
+  children,
+  ...props
+}: NavigationMenuPrimitive.Root.Props &
+  Pick<NavigationMenuPrimitive.Positioner.Props, "align">) {
+  return (
+    <NavigationMenuPrimitive.Root
+      data-slot="navigation-menu"
+      className={cn(
+        "group/navigation-menu relative flex max-w-max flex-1 items-center justify-center",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <NavigationMenuPositioner align={align} />
+    </NavigationMenuPrimitive.Root>
+  )
+}
+
+function NavigationMenuList({
+  className,
+  ...props
+}: React.ComponentPropsWithRef<typeof NavigationMenuPrimitive.List>) {
+  return (
+    <NavigationMenuPrimitive.List
+      data-slot="navigation-menu-list"
+      className={cn(
+        "group flex flex-1 list-none items-center justify-center gap-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function NavigationMenuItem({
+  className,
+  ...props
+}: React.ComponentPropsWithRef<typeof NavigationMenuPrimitive.Item>) {
+  return (
+    <NavigationMenuPrimitive.Item
+      data-slot="navigation-menu-item"
+      className={cn("relative", className)}
+      {...props}
+    />
+  )
+}
+
+const navigationMenuTriggerStyle = cva(
+  "group/navigation-menu-trigger inline-flex h-9 w-max items-center justify-center rounded-2xl px-2.5 py-1.5 text-sm font-medium transition-all outline-none hover:bg-muted focus:bg-muted focus-visible:ring-3 focus-visible:ring-ring/30 focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 data-popup-open:bg-muted/50 data-popup-open:hover:bg-muted data-open:bg-muted/50 data-open:hover:bg-muted data-open:focus:bg-muted"
+)
+
+function NavigationMenuTrigger({
+  className,
+  children,
+  ...props
+}: NavigationMenuPrimitive.Trigger.Props) {
+  return (
+    <NavigationMenuPrimitive.Trigger
+      data-slot="navigation-menu-trigger"
+      className={cn(navigationMenuTriggerStyle(), "group", className)}
+      {...props}
+    >
+      {children}{" "}
+      <HugeiconsIcon icon={ArrowDown01Icon} strokeWidth={2} className="relative top-px ml-1 size-3 transition duration-300 group-data-popup-open/navigation-menu-trigger:rotate-180 group-data-open/navigation-menu-trigger:rotate-180" aria-hidden="true" />
+    </NavigationMenuPrimitive.Trigger>
+  )
+}
+
+function NavigationMenuContent({
+  className,
+  ...props
+}: NavigationMenuPrimitive.Content.Props) {
+  return (
+    <NavigationMenuPrimitive.Content
+      data-slot="navigation-menu-content"
+      className={cn(
+        "data-ending-style:data-activation-direction=left:translate-x-[50%] data-ending-style:data-activation-direction=right:translate-x-[-50%] data-starting-style:data-activation-direction=left:translate-x-[-50%] data-starting-style:data-activation-direction=right:translate-x-[50%] h-full w-auto p-1.5 transition-[opacity,transform,translate] duration-[0.35s] ease-[cubic-bezier(0.22,1,0.36,1)] group-data-[viewport=false]/navigation-menu:rounded-2xl group-data-[viewport=false]/navigation-menu:bg-popover group-data-[viewport=false]/navigation-menu:text-popover-foreground group-data-[viewport=false]/navigation-menu:shadow-lg group-data-[viewport=false]/navigation-menu:ring-1 group-data-[viewport=false]/navigation-menu:ring-foreground/5 group-data-[viewport=false]/navigation-menu:duration-300 data-ending-style:opacity-0 data-starting-style:opacity-0 data-[motion=from-end]:slide-in-from-right-52 data-[motion=from-start]:slide-in-from-left-52 data-[motion=to-end]:slide-out-to-right-52 data-[motion=to-start]:slide-out-to-left-52 data-[motion^=from-]:animate-in data-[motion^=from-]:fade-in data-[motion^=to-]:animate-out data-[motion^=to-]:fade-out **:data-[slot=navigation-menu-link]:focus:ring-0 **:data-[slot=navigation-menu-link]:focus:outline-none group-data-[viewport=false]/navigation-menu:dark:ring-foreground/10 group-data-[viewport=false]/navigation-menu:data-open:animate-in group-data-[viewport=false]/navigation-menu:data-open:fade-in-0 group-data-[viewport=false]/navigation-menu:data-open:zoom-in-95 group-data-[viewport=false]/navigation-menu:data-closed:animate-out group-data-[viewport=false]/navigation-menu:data-closed:fade-out-0 group-data-[viewport=false]/navigation-menu:data-closed:zoom-out-95",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function NavigationMenuPositioner({
+  className,
+  side = "bottom",
+  sideOffset = 8,
+  align = "start",
+  alignOffset = 0,
+  ...props
+}: NavigationMenuPrimitive.Positioner.Props) {
+  return (
+    <NavigationMenuPrimitive.Portal>
+      <NavigationMenuPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
+        className={cn(
+          "isolate z-50 h-(--positioner-height) w-(--positioner-width) max-w-(--available-width) transition-[top,left,right,bottom] duration-[0.35s] ease-[cubic-bezier(0.22,1,0.36,1)] data-instant:transition-none data-[side=bottom]:before:top-[-10px] data-[side=bottom]:before:right-0 data-[side=bottom]:before:left-0",
+          className
+        )}
+        {...props}
+      >
+        <NavigationMenuPrimitive.Popup className="data-[ending-style]:easing-[ease] xs:w-(--popup-width) relative h-(--popup-height) w-(--popup-width) origin-(--transform-origin) rounded-3xl bg-popover text-popover-foreground shadow-lg ring-1 ring-foreground/5 transition-[opacity,transform,width,height,scale,translate] duration-[0.35s] ease-[cubic-bezier(0.22,1,0.36,1)] outline-none data-ending-style:scale-90 data-ending-style:opacity-0 data-ending-style:duration-150 data-starting-style:scale-90 data-starting-style:opacity-0 dark:ring-foreground/10">
+          <NavigationMenuPrimitive.Viewport className="relative size-full overflow-hidden" />
+        </NavigationMenuPrimitive.Popup>
+      </NavigationMenuPrimitive.Positioner>
+    </NavigationMenuPrimitive.Portal>
+  )
+}
+
+function NavigationMenuLink({
+  className,
+  ...props
+}: NavigationMenuPrimitive.Link.Props) {
+  return (
+    <NavigationMenuPrimitive.Link
+      data-slot="navigation-menu-link"
+      className={cn(
+        "flex items-center gap-2 rounded-2xl px-2.5 py-1.5 text-sm font-medium transition-all outline-none hover:bg-muted focus:bg-muted focus-visible:ring-3 focus-visible:ring-ring/30 focus-visible:outline-1 in-data-[slot=navigation-menu-content]:w-full in-data-[slot=navigation-menu-content]:rounded-xl in-data-[slot=navigation-menu-content]:p-2 in-data-[slot=navigation-menu-content]:font-normal data-[active=true]:bg-muted/50 data-[active=true]:hover:bg-muted data-[active=true]:focus:bg-muted [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function NavigationMenuIndicator({
+  className,
+  ...props
+}: React.ComponentPropsWithRef<typeof NavigationMenuPrimitive.Icon>) {
+  return (
+    <NavigationMenuPrimitive.Icon
+      data-slot="navigation-menu-indicator"
+      className={cn(
+        "top-full z-1 flex h-1.5 items-end justify-center overflow-hidden data-[state=hidden]:animate-out data-[state=hidden]:fade-out data-[state=visible]:animate-in data-[state=visible]:fade-in",
+        className
+      )}
+      {...props}
+    >
+      <div className="relative top-[60%] h-2 w-2 rotate-45 rounded-tl-sm bg-border shadow-md" />
+    </NavigationMenuPrimitive.Icon>
+  )
+}
+
+export {
+  NavigationMenu,
+  NavigationMenuContent,
+  NavigationMenuIndicator,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuTrigger,
+  navigationMenuTriggerStyle,
+  NavigationMenuPositioner,
+}
diff --git a/packages/web/src/components/ui/pagination.tsx b/packages/web/src/components/ui/pagination.tsx
new file mode 100644
index 0000000..4f66f76
--- /dev/null
+++ b/packages/web/src/components/ui/pagination.tsx
@@ -0,0 +1,130 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { ArrowLeft01Icon, ArrowRight01Icon, MoreHorizontalCircle01Icon } from "@hugeicons/core-free-icons"
+
+function Pagination({ className, ...props }: React.ComponentProps<"nav">) {
+  return (
+    <nav
+      role="navigation"
+      aria-label="pagination"
+      data-slot="pagination"
+      className={cn("mx-auto flex w-full justify-center", className)}
+      {...props}
+    />
+  )
+}
+
+function PaginationContent({
+  className,
+  ...props
+}: React.ComponentProps<"ul">) {
+  return (
+    <ul
+      data-slot="pagination-content"
+      className={cn("flex items-center gap-1", className)}
+      {...props}
+    />
+  )
+}
+
+function PaginationItem({ ...props }: React.ComponentProps<"li">) {
+  return <li data-slot="pagination-item" {...props} />
+}
+
+type PaginationLinkProps = {
+  isActive?: boolean
+} & Pick<React.ComponentProps<typeof Button>, "size"> &
+  React.ComponentProps<"a">
+
+function PaginationLink({
+  className,
+  isActive,
+  size = "icon",
+  ...props
+}: PaginationLinkProps) {
+  return (
+    <Button
+      variant={isActive ? "outline" : "ghost"}
+      size={size}
+      className={cn(className)}
+      nativeButton={false}
+      render={
+        <a
+          aria-current={isActive ? "page" : undefined}
+          data-slot="pagination-link"
+          data-active={isActive}
+          {...props}
+        />
+      }
+    />
+  )
+}
+
+function PaginationPrevious({
+  className,
+  text = "Previous",
+  ...props
+}: React.ComponentProps<typeof PaginationLink> & { text?: string }) {
+  return (
+    <PaginationLink
+      aria-label="Go to previous page"
+      size="default"
+      className={cn("pl-1.5!", className)}
+      {...props}
+    >
+      <HugeiconsIcon icon={ArrowLeft01Icon} strokeWidth={2} data-icon="inline-start" />
+      <span className="hidden sm:block">{text}</span>
+    </PaginationLink>
+  )
+}
+
+function PaginationNext({
+  className,
+  text = "Next",
+  ...props
+}: React.ComponentProps<typeof PaginationLink> & { text?: string }) {
+  return (
+    <PaginationLink
+      aria-label="Go to next page"
+      size="default"
+      className={cn("pr-1.5!", className)}
+      {...props}
+    >
+      <span className="hidden sm:block">{text}</span>
+      <HugeiconsIcon icon={ArrowRight01Icon} strokeWidth={2} data-icon="inline-end" />
+    </PaginationLink>
+  )
+}
+
+function PaginationEllipsis({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      aria-hidden
+      data-slot="pagination-ellipsis"
+      className={cn(
+        "flex size-8 items-center justify-center [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <HugeiconsIcon icon={MoreHorizontalCircle01Icon} strokeWidth={2} />
+      <span className="sr-only">More pages</span>
+    </span>
+  )
+}
+
+export {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+}
diff --git a/packages/web/src/components/ui/popover.tsx b/packages/web/src/components/ui/popover.tsx
new file mode 100644
index 0000000..c7f9ceb
--- /dev/null
+++ b/packages/web/src/components/ui/popover.tsx
@@ -0,0 +1,88 @@
+import * as React from "react"
+import { Popover as PopoverPrimitive } from "@base-ui/react/popover"
+
+import { cn } from "@/lib/utils"
+
+function Popover({ ...props }: PopoverPrimitive.Root.Props) {
+  return <PopoverPrimitive.Root data-slot="popover" {...props} />
+}
+
+function PopoverTrigger({ ...props }: PopoverPrimitive.Trigger.Props) {
+  return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />
+}
+
+function PopoverContent({
+  className,
+  align = "center",
+  alignOffset = 0,
+  side = "bottom",
+  sideOffset = 4,
+  ...props
+}: PopoverPrimitive.Popup.Props &
+  Pick<
+    PopoverPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset"
+  >) {
+  return (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+        className="isolate z-50"
+      >
+        <PopoverPrimitive.Popup
+          data-slot="popover-content"
+          className={cn(
+            "z-50 flex w-72 origin-(--transform-origin) flex-col gap-4 rounded-3xl bg-popover p-4 text-sm text-popover-foreground shadow-lg ring-1 ring-foreground/5 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            className
+          )}
+          {...props}
+        />
+      </PopoverPrimitive.Positioner>
+    </PopoverPrimitive.Portal>
+  )
+}
+
+function PopoverHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="popover-header"
+      className={cn("flex flex-col gap-1 text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function PopoverTitle({ className, ...props }: PopoverPrimitive.Title.Props) {
+  return (
+    <PopoverPrimitive.Title
+      data-slot="popover-title"
+      className={cn("text-base font-medium", className)}
+      {...props}
+    />
+  )
+}
+
+function PopoverDescription({
+  className,
+  ...props
+}: PopoverPrimitive.Description.Props) {
+  return (
+    <PopoverPrimitive.Description
+      data-slot="popover-description"
+      className={cn("text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Popover,
+  PopoverContent,
+  PopoverDescription,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverTrigger,
+}
diff --git a/packages/web/src/components/ui/progress.tsx b/packages/web/src/components/ui/progress.tsx
new file mode 100644
index 0000000..16a8ece
--- /dev/null
+++ b/packages/web/src/components/ui/progress.tsx
@@ -0,0 +1,83 @@
+"use client"
+
+import { Progress as ProgressPrimitive } from "@base-ui/react/progress"
+
+import { cn } from "@/lib/utils"
+
+function Progress({
+  className,
+  children,
+  value,
+  ...props
+}: ProgressPrimitive.Root.Props) {
+  return (
+    <ProgressPrimitive.Root
+      value={value}
+      data-slot="progress"
+      className={cn("flex flex-wrap gap-3", className)}
+      {...props}
+    >
+      {children}
+      <ProgressTrack>
+        <ProgressIndicator />
+      </ProgressTrack>
+    </ProgressPrimitive.Root>
+  )
+}
+
+function ProgressTrack({ className, ...props }: ProgressPrimitive.Track.Props) {
+  return (
+    <ProgressPrimitive.Track
+      className={cn(
+        "relative flex h-2 w-full items-center overflow-x-hidden rounded-2xl bg-muted",
+        className
+      )}
+      data-slot="progress-track"
+      {...props}
+    />
+  )
+}
+
+function ProgressIndicator({
+  className,
+  ...props
+}: ProgressPrimitive.Indicator.Props) {
+  return (
+    <ProgressPrimitive.Indicator
+      data-slot="progress-indicator"
+      className={cn("h-full bg-primary transition-all", className)}
+      {...props}
+    />
+  )
+}
+
+function ProgressLabel({ className, ...props }: ProgressPrimitive.Label.Props) {
+  return (
+    <ProgressPrimitive.Label
+      className={cn("text-sm font-medium", className)}
+      data-slot="progress-label"
+      {...props}
+    />
+  )
+}
+
+function ProgressValue({ className, ...props }: ProgressPrimitive.Value.Props) {
+  return (
+    <ProgressPrimitive.Value
+      className={cn(
+        "ml-auto text-sm text-muted-foreground tabular-nums",
+        className
+      )}
+      data-slot="progress-value"
+      {...props}
+    />
+  )
+}
+
+export {
+  Progress,
+  ProgressTrack,
+  ProgressIndicator,
+  ProgressLabel,
+  ProgressValue,
+}
diff --git a/packages/web/src/components/ui/radio-group.tsx b/packages/web/src/components/ui/radio-group.tsx
new file mode 100644
index 0000000..a16e50a
--- /dev/null
+++ b/packages/web/src/components/ui/radio-group.tsx
@@ -0,0 +1,36 @@
+import { Radio as RadioPrimitive } from "@base-ui/react/radio"
+import { RadioGroup as RadioGroupPrimitive } from "@base-ui/react/radio-group"
+
+import { cn } from "@/lib/utils"
+
+function RadioGroup({ className, ...props }: RadioGroupPrimitive.Props) {
+  return (
+    <RadioGroupPrimitive
+      data-slot="radio-group"
+      className={cn("grid w-full gap-3", className)}
+      {...props}
+    />
+  )
+}
+
+function RadioGroupItem({ className, ...props }: RadioPrimitive.Root.Props) {
+  return (
+    <RadioPrimitive.Root
+      data-slot="radio-group-item"
+      className={cn(
+        "group/radio-group-item peer relative flex aspect-square size-4 shrink-0 rounded-2xl border border-transparent bg-input/90 outline-none after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:bg-primary data-checked:text-primary-foreground dark:data-checked:bg-primary",
+        className
+      )}
+      {...props}
+    >
+      <RadioPrimitive.Indicator
+        data-slot="radio-group-indicator"
+        className="flex size-4 items-center justify-center"
+      >
+        <span className="absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2 rounded-full bg-primary-foreground dark:size-2.5" />
+      </RadioPrimitive.Indicator>
+    </RadioPrimitive.Root>
+  )
+}
+
+export { RadioGroup, RadioGroupItem }
diff --git a/packages/web/src/components/ui/resizable.tsx b/packages/web/src/components/ui/resizable.tsx
new file mode 100644
index 0000000..c9e767a
--- /dev/null
+++ b/packages/web/src/components/ui/resizable.tsx
@@ -0,0 +1,50 @@
+"use client"
+
+import * as ResizablePrimitive from "react-resizable-panels"
+
+import { cn } from "@/lib/utils"
+
+function ResizablePanelGroup({
+  className,
+  ...props
+}: ResizablePrimitive.GroupProps) {
+  return (
+    <ResizablePrimitive.Group
+      data-slot="resizable-panel-group"
+      className={cn(
+        "flex h-full w-full aria-[orientation=vertical]:flex-col",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ResizablePanel({ ...props }: ResizablePrimitive.PanelProps) {
+  return <ResizablePrimitive.Panel data-slot="resizable-panel" {...props} />
+}
+
+function ResizableHandle({
+  withHandle,
+  className,
+  ...props
+}: ResizablePrimitive.SeparatorProps & {
+  withHandle?: boolean
+}) {
+  return (
+    <ResizablePrimitive.Separator
+      data-slot="resizable-handle"
+      className={cn(
+        "relative flex w-px items-center justify-center bg-border ring-offset-background after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:ring-1 focus-visible:ring-ring focus-visible:outline-hidden aria-[orientation=horizontal]:h-px aria-[orientation=horizontal]:w-full aria-[orientation=horizontal]:after:left-0 aria-[orientation=horizontal]:after:h-1 aria-[orientation=horizontal]:after:w-full aria-[orientation=horizontal]:after:translate-x-0 aria-[orientation=horizontal]:after:-translate-y-1/2 [&[aria-orientation=horizontal]>div]:rotate-90",
+        className
+      )}
+      {...props}
+    >
+      {withHandle && (
+        <div className="z-10 flex h-6 w-1 shrink-0 rounded-lg bg-border" />
+      )}
+    </ResizablePrimitive.Separator>
+  )
+}
+
+export { ResizableHandle, ResizablePanel, ResizablePanelGroup }
diff --git a/packages/web/src/components/ui/scroll-area.tsx b/packages/web/src/components/ui/scroll-area.tsx
new file mode 100644
index 0000000..74d916f
--- /dev/null
+++ b/packages/web/src/components/ui/scroll-area.tsx
@@ -0,0 +1,53 @@
+import * as React from "react"
+import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area"
+
+import { cn } from "@/lib/utils"
+
+function ScrollArea({
+  className,
+  children,
+  ...props
+}: ScrollAreaPrimitive.Root.Props) {
+  return (
+    <ScrollAreaPrimitive.Root
+      data-slot="scroll-area"
+      className={cn("relative", className)}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Viewport
+        data-slot="scroll-area-viewport"
+        className="size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1"
+      >
+        {children}
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  )
+}
+
+function ScrollBar({
+  className,
+  orientation = "vertical",
+  ...props
+}: ScrollAreaPrimitive.Scrollbar.Props) {
+  return (
+    <ScrollAreaPrimitive.Scrollbar
+      data-slot="scroll-area-scrollbar"
+      data-orientation={orientation}
+      orientation={orientation}
+      className={cn(
+        "flex touch-none p-px transition-colors select-none data-horizontal:h-2.5 data-horizontal:flex-col data-horizontal:border-t data-horizontal:border-t-transparent data-vertical:h-full data-vertical:w-2.5 data-vertical:border-l data-vertical:border-l-transparent",
+        className
+      )}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Thumb
+        data-slot="scroll-area-thumb"
+        className="relative flex-1 rounded-full bg-border"
+      />
+    </ScrollAreaPrimitive.Scrollbar>
+  )
+}
+
+export { ScrollArea, ScrollBar }
diff --git a/packages/web/src/components/ui/select.tsx b/packages/web/src/components/ui/select.tsx
new file mode 100644
index 0000000..ec1f43f
--- /dev/null
+++ b/packages/web/src/components/ui/select.tsx
@@ -0,0 +1,200 @@
+"use client"
+
+import * as React from "react"
+import { Select as SelectPrimitive } from "@base-ui/react/select"
+
+import { cn } from "@/lib/utils"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { UnfoldMoreIcon, Tick02Icon, ArrowUp01Icon, ArrowDown01Icon } from "@hugeicons/core-free-icons"
+
+const Select = SelectPrimitive.Root
+
+function SelectGroup({ className, ...props }: SelectPrimitive.Group.Props) {
+  return (
+    <SelectPrimitive.Group
+      data-slot="select-group"
+      className={cn("scroll-my-1.5 p-1", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectValue({ className, ...props }: SelectPrimitive.Value.Props) {
+  return (
+    <SelectPrimitive.Value
+      data-slot="select-value"
+      className={cn("flex flex-1 text-left", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectTrigger({
+  className,
+  size = "default",
+  children,
+  ...props
+}: SelectPrimitive.Trigger.Props & {
+  size?: "sm" | "default"
+}) {
+  return (
+    <SelectPrimitive.Trigger
+      data-slot="select-trigger"
+      data-size={size}
+      className={cn(
+        "flex w-fit items-center justify-between gap-1.5 rounded-2xl border border-transparent bg-input/50 px-3 py-2 text-sm whitespace-nowrap transition-[color,box-shadow] duration-200 outline-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-placeholder:text-muted-foreground data-[size=default]:h-8 data-[size=sm]:h-7 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <SelectPrimitive.Icon
+        render={
+          <HugeiconsIcon icon={UnfoldMoreIcon} strokeWidth={2} className="pointer-events-none size-4 text-muted-foreground" />
+        }
+      />
+    </SelectPrimitive.Trigger>
+  )
+}
+
+function SelectContent({
+  className,
+  children,
+  side = "bottom",
+  sideOffset = 4,
+  align = "center",
+  alignOffset = 0,
+  alignItemWithTrigger = true,
+  ...props
+}: SelectPrimitive.Popup.Props &
+  Pick<
+    SelectPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset" | "alignItemWithTrigger"
+  >) {
+  return (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Positioner
+        side={side}
+        sideOffset={sideOffset}
+        align={align}
+        alignOffset={alignOffset}
+        alignItemWithTrigger={alignItemWithTrigger}
+        className="isolate z-50"
+      >
+        <SelectPrimitive.Popup
+          data-slot="select-content"
+          data-align-trigger={alignItemWithTrigger}
+          className={cn("isolate z-50 max-h-(--available-height) w-(--anchor-width) min-w-36 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-2xl text-popover-foreground shadow-lg ring-1 ring-foreground/5 duration-100 data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95 animate-none! relative bg-popover/70 before:pointer-events-none before:absolute before:inset-0 before:-z-1 before:rounded-[inherit] before:backdrop-blur-2xl before:backdrop-saturate-150 **:data-[slot$=-item]:focus:bg-foreground/10 **:data-[slot$=-item]:data-highlighted:bg-foreground/10 **:data-[slot$=-separator]:bg-foreground/5 **:data-[slot$=-trigger]:focus:bg-foreground/10 **:data-[slot$=-trigger]:aria-expanded:bg-foreground/10! **:data-[variant=destructive]:focus:bg-foreground/10! **:data-[variant=destructive]:text-accent-foreground! **:data-[variant=destructive]:**:text-accent-foreground!", className )}
+          {...props}
+        >
+          <SelectScrollUpButton />
+          <SelectPrimitive.List>{children}</SelectPrimitive.List>
+          <SelectScrollDownButton />
+        </SelectPrimitive.Popup>
+      </SelectPrimitive.Positioner>
+    </SelectPrimitive.Portal>
+  )
+}
+
+function SelectLabel({
+  className,
+  ...props
+}: SelectPrimitive.GroupLabel.Props) {
+  return (
+    <SelectPrimitive.GroupLabel
+      data-slot="select-label"
+      className={cn("px-2 py-1 text-xs text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectItem({
+  className,
+  children,
+  ...props
+}: SelectPrimitive.Item.Props) {
+  return (
+    <SelectPrimitive.Item
+      data-slot="select-item"
+      className={cn(
+        "relative flex min-h-7 w-full cursor-default items-center gap-2 rounded-xl py-1.5 pr-8 pl-2 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        className
+      )}
+      {...props}
+    >
+      <SelectPrimitive.ItemText className="flex flex-1 shrink-0 gap-2 whitespace-nowrap">
+        {children}
+      </SelectPrimitive.ItemText>
+      <SelectPrimitive.ItemIndicator
+        render={
+          <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center" />
+        }
+      >
+        <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} className="pointer-events-none" />
+      </SelectPrimitive.ItemIndicator>
+    </SelectPrimitive.Item>
+  )
+}
+
+function SelectSeparator({
+  className,
+  ...props
+}: SelectPrimitive.Separator.Props) {
+  return (
+    <SelectPrimitive.Separator
+      data-slot="select-separator"
+      className={cn("pointer-events-none -mx-1 my-1 h-px bg-border", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectScrollUpButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollUpArrow>) {
+  return (
+    <SelectPrimitive.ScrollUpArrow
+      data-slot="select-scroll-up-button"
+      className={cn(
+        "top-0 z-10 flex w-full cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <HugeiconsIcon icon={ArrowUp01Icon} strokeWidth={2} />
+    </SelectPrimitive.ScrollUpArrow>
+  )
+}
+
+function SelectScrollDownButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollDownArrow>) {
+  return (
+    <SelectPrimitive.ScrollDownArrow
+      data-slot="select-scroll-down-button"
+      className={cn(
+        "bottom-0 z-10 flex w-full cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <HugeiconsIcon icon={ArrowDown01Icon} strokeWidth={2} />
+    </SelectPrimitive.ScrollDownArrow>
+  )
+}
+
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+}
diff --git a/packages/web/src/components/ui/separator.tsx b/packages/web/src/components/ui/separator.tsx
new file mode 100644
index 0000000..4f65961
--- /dev/null
+++ b/packages/web/src/components/ui/separator.tsx
@@ -0,0 +1,23 @@
+import { Separator as SeparatorPrimitive } from "@base-ui/react/separator"
+
+import { cn } from "@/lib/utils"
+
+function Separator({
+  className,
+  orientation = "horizontal",
+  ...props
+}: SeparatorPrimitive.Props) {
+  return (
+    <SeparatorPrimitive
+      data-slot="separator"
+      orientation={orientation}
+      className={cn(
+        "shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Separator }
diff --git a/packages/web/src/components/ui/sheet.tsx b/packages/web/src/components/ui/sheet.tsx
new file mode 100644
index 0000000..9b08eb0
--- /dev/null
+++ b/packages/web/src/components/ui/sheet.tsx
@@ -0,0 +1,136 @@
+import * as React from "react"
+import { Dialog as SheetPrimitive } from "@base-ui/react/dialog"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { Cancel01Icon } from "@hugeicons/core-free-icons"
+
+function Sheet({ ...props }: SheetPrimitive.Root.Props) {
+  return <SheetPrimitive.Root data-slot="sheet" {...props} />
+}
+
+function SheetTrigger({ ...props }: SheetPrimitive.Trigger.Props) {
+  return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />
+}
+
+function SheetClose({ ...props }: SheetPrimitive.Close.Props) {
+  return <SheetPrimitive.Close data-slot="sheet-close" {...props} />
+}
+
+function SheetPortal({ ...props }: SheetPrimitive.Portal.Props) {
+  return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />
+}
+
+function SheetOverlay({ className, ...props }: SheetPrimitive.Backdrop.Props) {
+  return (
+    <SheetPrimitive.Backdrop
+      data-slot="sheet-overlay"
+      className={cn(
+        "fixed inset-0 z-50 bg-black/30 transition-opacity duration-150 data-ending-style:opacity-0 data-starting-style:opacity-0 supports-backdrop-filter:backdrop-blur-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SheetContent({
+  className,
+  children,
+  side = "right",
+  showCloseButton = true,
+  ...props
+}: SheetPrimitive.Popup.Props & {
+  side?: "top" | "right" | "bottom" | "left"
+  showCloseButton?: boolean
+}) {
+  return (
+    <SheetPortal>
+      <SheetOverlay />
+      <SheetPrimitive.Popup
+        data-slot="sheet-content"
+        data-side={side}
+        className={cn(
+          "fixed z-50 flex flex-col bg-popover bg-clip-padding text-sm text-popover-foreground shadow-xl transition duration-200 ease-in-out data-ending-style:opacity-0 data-starting-style:opacity-0 data-[side=bottom]:inset-x-0 data-[side=bottom]:bottom-0 data-[side=bottom]:h-auto data-[side=bottom]:border-t data-[side=bottom]:data-ending-style:translate-y-[2.5rem] data-[side=bottom]:data-starting-style:translate-y-[2.5rem] data-[side=left]:inset-y-0 data-[side=left]:left-0 data-[side=left]:h-full data-[side=left]:w-3/4 data-[side=left]:border-r data-[side=left]:data-ending-style:translate-x-[-2.5rem] data-[side=left]:data-starting-style:translate-x-[-2.5rem] data-[side=right]:inset-y-0 data-[side=right]:right-0 data-[side=right]:h-full data-[side=right]:w-3/4 data-[side=right]:border-l data-[side=right]:data-ending-style:translate-x-[2.5rem] data-[side=right]:data-starting-style:translate-x-[2.5rem] data-[side=top]:inset-x-0 data-[side=top]:top-0 data-[side=top]:h-auto data-[side=top]:border-b data-[side=top]:data-ending-style:translate-y-[-2.5rem] data-[side=top]:data-starting-style:translate-y-[-2.5rem] data-[side=left]:sm:max-w-sm data-[side=right]:sm:max-w-sm",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <SheetPrimitive.Close
+            data-slot="sheet-close"
+            render={
+              <Button
+                variant="ghost"
+                className="absolute top-4 right-4 bg-secondary"
+                size="icon-sm"
+              />
+            }
+          >
+            <HugeiconsIcon icon={Cancel01Icon} strokeWidth={2} />
+            <span className="sr-only">Close</span>
+          </SheetPrimitive.Close>
+        )}
+      </SheetPrimitive.Popup>
+    </SheetPortal>
+  )
+}
+
+function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-header"
+      className={cn("flex flex-col gap-1.5 p-6", className)}
+      {...props}
+    />
+  )
+}
+
+function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-footer"
+      className={cn("mt-auto flex flex-col gap-2 p-6", className)}
+      {...props}
+    />
+  )
+}
+
+function SheetTitle({ className, ...props }: SheetPrimitive.Title.Props) {
+  return (
+    <SheetPrimitive.Title
+      data-slot="sheet-title"
+      className={cn(
+        "font-heading text-base font-medium text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SheetDescription({
+  className,
+  ...props
+}: SheetPrimitive.Description.Props) {
+  return (
+    <SheetPrimitive.Description
+      data-slot="sheet-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Sheet,
+  SheetTrigger,
+  SheetClose,
+  SheetContent,
+  SheetHeader,
+  SheetFooter,
+  SheetTitle,
+  SheetDescription,
+}
diff --git a/packages/web/src/components/ui/sidebar.tsx b/packages/web/src/components/ui/sidebar.tsx
new file mode 100644
index 0000000..85f52c1
--- /dev/null
+++ b/packages/web/src/components/ui/sidebar.tsx
@@ -0,0 +1,725 @@
+import * as React from "react"
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { useIsMobile } from "@/hooks/use-mobile"
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Separator } from "@/components/ui/separator"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet"
+import { Skeleton } from "@/components/ui/skeleton"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { SidebarLeftIcon } from "@hugeicons/core-free-icons"
+
+const SIDEBAR_COOKIE_NAME = "sidebar_state"
+const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7
+const SIDEBAR_WIDTH = "16rem"
+const SIDEBAR_WIDTH_MOBILE = "18rem"
+const SIDEBAR_WIDTH_ICON = "3rem"
+const SIDEBAR_KEYBOARD_SHORTCUT = "b"
+
+type SidebarContextProps = {
+  state: "expanded" | "collapsed"
+  open: boolean
+  setOpen: (open: boolean) => void
+  openMobile: boolean
+  setOpenMobile: (open: boolean) => void
+  isMobile: boolean
+  toggleSidebar: () => void
+}
+
+const SidebarContext = React.createContext<SidebarContextProps | null>(null)
+
+function useSidebar() {
+  const context = React.useContext(SidebarContext)
+  if (!context) {
+    throw new Error("useSidebar must be used within a SidebarProvider.")
+  }
+
+  return context
+}
+
+function SidebarProvider({
+  defaultOpen = true,
+  open: openProp,
+  onOpenChange: setOpenProp,
+  className,
+  style,
+  children,
+  ...props
+}: React.ComponentProps<"div"> & {
+  defaultOpen?: boolean
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+}) {
+  const isMobile = useIsMobile()
+  const [openMobile, setOpenMobile] = React.useState(false)
+
+  // This is the internal state of the sidebar.
+  // We use openProp and setOpenProp for control from outside the component.
+  const [_open, _setOpen] = React.useState(defaultOpen)
+  const open = openProp ?? _open
+  const setOpen = React.useCallback(
+    (value: boolean | ((value: boolean) => boolean)) => {
+      const openState = typeof value === "function" ? value(open) : value
+      if (setOpenProp) {
+        setOpenProp(openState)
+      } else {
+        _setOpen(openState)
+      }
+
+      // This sets the cookie to keep the sidebar state.
+      document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`
+    },
+    [setOpenProp, open]
+  )
+
+  // Helper to toggle the sidebar.
+  const toggleSidebar = React.useCallback(() => {
+    return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open)
+  }, [isMobile, setOpen, setOpenMobile])
+
+  // Adds a keyboard shortcut to toggle the sidebar.
+  React.useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (
+        event.key === SIDEBAR_KEYBOARD_SHORTCUT &&
+        (event.metaKey || event.ctrlKey)
+      ) {
+        event.preventDefault()
+        toggleSidebar()
+      }
+    }
+
+    window.addEventListener("keydown", handleKeyDown)
+    return () => window.removeEventListener("keydown", handleKeyDown)
+  }, [toggleSidebar])
+
+  // We add a state so that we can do data-state="expanded" or "collapsed".
+  // This makes it easier to style the sidebar with Tailwind classes.
+  const state = open ? "expanded" : "collapsed"
+
+  const contextValue = React.useMemo<SidebarContextProps>(
+    () => ({
+      state,
+      open,
+      setOpen,
+      isMobile,
+      openMobile,
+      setOpenMobile,
+      toggleSidebar,
+    }),
+    [state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar]
+  )
+
+  return (
+    <SidebarContext.Provider value={contextValue}>
+      <div
+        data-slot="sidebar-wrapper"
+        style={
+          {
+            "--sidebar-width": SIDEBAR_WIDTH,
+            "--sidebar-width-icon": SIDEBAR_WIDTH_ICON,
+            ...style,
+          } as React.CSSProperties
+        }
+        className={cn(
+          "group/sidebar-wrapper flex min-h-svh w-full has-data-[variant=inset]:bg-sidebar",
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    </SidebarContext.Provider>
+  )
+}
+
+function Sidebar({
+  side = "left",
+  variant = "sidebar",
+  collapsible = "offcanvas",
+  className,
+  children,
+  dir,
+  ...props
+}: React.ComponentProps<"div"> & {
+  side?: "left" | "right"
+  variant?: "sidebar" | "floating" | "inset"
+  collapsible?: "offcanvas" | "icon" | "none"
+}) {
+  const { isMobile, state, openMobile, setOpenMobile } = useSidebar()
+
+  if (collapsible === "none") {
+    return (
+      <div
+        data-slot="sidebar"
+        className={cn(
+          "flex h-full w-(--sidebar-width) flex-col bg-sidebar text-sidebar-foreground",
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    )
+  }
+
+  if (isMobile) {
+    return (
+      <Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}>
+        <SheetContent
+          dir={dir}
+          data-sidebar="sidebar"
+          data-slot="sidebar"
+          data-mobile="true"
+          className="w-(--sidebar-width) bg-sidebar p-0 text-sidebar-foreground [&>button]:hidden"
+          style={
+            {
+              "--sidebar-width": SIDEBAR_WIDTH_MOBILE,
+            } as React.CSSProperties
+          }
+          side={side}
+        >
+          <SheetHeader className="sr-only">
+            <SheetTitle>Sidebar</SheetTitle>
+            <SheetDescription>Displays the mobile sidebar.</SheetDescription>
+          </SheetHeader>
+          <div className="flex h-full w-full flex-col">{children}</div>
+        </SheetContent>
+      </Sheet>
+    )
+  }
+
+  return (
+    <div
+      className="group peer hidden text-sidebar-foreground md:block"
+      data-state={state}
+      data-collapsible={state === "collapsed" ? collapsible : ""}
+      data-variant={variant}
+      data-side={side}
+      data-slot="sidebar"
+    >
+      {/* This is what handles the sidebar gap on desktop */}
+      <div
+        data-slot="sidebar-gap"
+        className={cn(
+          "relative w-(--sidebar-width) bg-transparent transition-[width] duration-200 ease-linear",
+          "group-data-[collapsible=offcanvas]:w-0",
+          "group-data-[side=right]:rotate-180",
+          variant === "floating" || variant === "inset"
+            ? "group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4)))]"
+            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon)"
+        )}
+      />
+      <div
+        data-slot="sidebar-container"
+        data-side={side}
+        className={cn(
+          "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear data-[side=left]:left-0 data-[side=left]:group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)] data-[side=right]:right-0 data-[side=right]:group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)] md:flex",
+          // Adjust the padding for floating and inset variants.
+          variant === "floating" || variant === "inset"
+            ? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]"
+            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r group-data-[side=right]:border-l",
+          className
+        )}
+        {...props}
+      >
+        <div
+          data-sidebar="sidebar"
+          data-slot="sidebar-inner"
+          className="flex size-full flex-col bg-sidebar group-data-[variant=floating]:rounded-2xl group-data-[variant=floating]:shadow-sm group-data-[variant=floating]:ring-1 group-data-[variant=floating]:ring-sidebar-border"
+        >
+          {children}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function SidebarTrigger({
+  className,
+  onClick,
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  const { toggleSidebar } = useSidebar()
+
+  return (
+    <Button
+      data-sidebar="trigger"
+      data-slot="sidebar-trigger"
+      variant="ghost"
+      size="icon-sm"
+      className={cn(className)}
+      onClick={(event) => {
+        onClick?.(event)
+        toggleSidebar()
+      }}
+      {...props}
+    >
+      <HugeiconsIcon icon={SidebarLeftIcon} strokeWidth={2} />
+      <span className="sr-only">Toggle Sidebar</span>
+    </Button>
+  )
+}
+
+function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
+  const { toggleSidebar } = useSidebar()
+
+  return (
+    <button
+      data-sidebar="rail"
+      data-slot="sidebar-rail"
+      aria-label="Toggle Sidebar"
+      tabIndex={-1}
+      onClick={toggleSidebar}
+      title="Toggle Sidebar"
+      className={cn(
+        "absolute inset-y-0 z-20 hidden w-4 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:start-1/2 after:w-[2px] hover:after:bg-sidebar-border sm:flex ltr:-translate-x-1/2 rtl:-translate-x-1/2",
+        "in-data-[side=left]:cursor-w-resize in-data-[side=right]:cursor-e-resize",
+        "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize",
+        "group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full hover:group-data-[collapsible=offcanvas]:bg-sidebar",
+        "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2",
+        "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
+  return (
+    <main
+      data-slot="sidebar-inset"
+      className={cn(
+        "relative flex w-full flex-1 flex-col bg-background md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-2xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarInput({
+  className,
+  ...props
+}: React.ComponentProps<typeof Input>) {
+  return (
+    <Input
+      data-slot="sidebar-input"
+      data-sidebar="input"
+      className={cn("h-8 w-full bg-input/50 shadow-none", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-header"
+      data-sidebar="header"
+      className={cn(
+        "flex flex-col gap-2 p-2 [--radius:var(--radius-xl)]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-footer"
+      data-sidebar="footer"
+      className={cn("flex flex-col gap-2 p-2", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof Separator>) {
+  return (
+    <Separator
+      data-slot="sidebar-separator"
+      data-sidebar="separator"
+      className={cn("mx-2 w-auto bg-sidebar-border", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-content"
+      data-sidebar="content"
+      className={cn(
+        "no-scrollbar flex min-h-0 flex-1 flex-col gap-2 overflow-auto [--radius:var(--radius-xl)] group-data-[collapsible=icon]:overflow-hidden",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-group"
+      data-sidebar="group"
+      className={cn("relative flex w-full min-w-0 flex-col p-2", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarGroupLabel({
+  className,
+  render,
+  ...props
+}: useRender.ComponentProps<"div"> & React.ComponentProps<"div">) {
+  return useRender({
+    defaultTagName: "div",
+    props: mergeProps<"div">(
+      {
+        className: cn(
+          "flex h-8 shrink-0 items-center rounded-xl px-3 text-xs font-medium text-sidebar-foreground/70 ring-sidebar-ring outline-hidden transition-[margin,opacity] duration-200 ease-linear group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-3 [&>svg]:size-4 [&>svg]:shrink-0",
+          className
+        ),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "sidebar-group-label",
+      sidebar: "group-label",
+    },
+  })
+}
+
+function SidebarGroupAction({
+  className,
+  render,
+  ...props
+}: useRender.ComponentProps<"button"> & React.ComponentProps<"button">) {
+  return useRender({
+    defaultTagName: "button",
+    props: mergeProps<"button">(
+      {
+        className: cn(
+          "absolute top-3.5 right-3 flex aspect-square w-5 items-center justify-center rounded-xl p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden after:absolute after:-inset-2 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-3 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0",
+          className
+        ),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "sidebar-group-action",
+      sidebar: "group-action",
+    },
+  })
+}
+
+function SidebarGroupContent({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-group-content"
+      data-sidebar="group-content"
+      className={cn("w-full text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">) {
+  return (
+    <ul
+      data-slot="sidebar-menu"
+      data-sidebar="menu"
+      className={cn("flex w-full min-w-0 flex-col gap-0.5", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="sidebar-menu-item"
+      data-sidebar="menu-item"
+      className={cn("group/menu-item relative", className)}
+      {...props}
+    />
+  )
+}
+
+const sidebarMenuButtonVariants = cva(
+  "peer/menu-button group/menu-button flex w-full items-center gap-2 overflow-hidden rounded-xl px-3 py-2 text-left text-sm whitespace-nowrap ring-sidebar-ring outline-hidden transition-[width,height,padding] duration-200 group-has-data-[sidebar=menu-action]/menu-item:pr-8 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-3 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 has-[>svg:first-child]:pl-2.5 has-[>svg:last-child]:pr-2.5 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground data-active:bg-sidebar-accent data-active:font-medium data-active:text-sidebar-accent-foreground [&_svg]:size-4 [&_svg]:shrink-0 [&>span:last-child]:truncate",
+  {
+    variants: {
+      variant: {
+        default: "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+        outline:
+          "bg-background shadow-[0_0_0_1px_hsl(var(--sidebar-border))] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground hover:shadow-[0_0_0_1px_hsl(var(--sidebar-accent))]",
+      },
+      size: {
+        default: "h-8 text-sm",
+        sm: "h-7 text-xs",
+        lg: "h-12 px-3 text-sm group-data-[collapsible=icon]:p-0!",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function SidebarMenuButton({
+  render,
+  isActive = false,
+  variant = "default",
+  size = "default",
+  tooltip,
+  className,
+  ...props
+}: useRender.ComponentProps<"button"> &
+  React.ComponentProps<"button"> & {
+    isActive?: boolean
+    tooltip?: string | React.ComponentProps<typeof TooltipContent>
+  } & VariantProps<typeof sidebarMenuButtonVariants>) {
+  const { isMobile, state } = useSidebar()
+  const comp = useRender({
+    defaultTagName: "button",
+    props: mergeProps<"button">(
+      {
+        className: cn(sidebarMenuButtonVariants({ variant, size }), className),
+      },
+      props
+    ),
+    render: !tooltip ? render : <TooltipTrigger render={render} />,
+    state: {
+      slot: "sidebar-menu-button",
+      sidebar: "menu-button",
+      size,
+      active: isActive,
+    },
+  })
+
+  if (!tooltip) {
+    return comp
+  }
+
+  if (typeof tooltip === "string") {
+    tooltip = {
+      children: tooltip,
+    }
+  }
+
+  return (
+    <Tooltip>
+      {comp}
+      <TooltipContent
+        side="right"
+        align="center"
+        hidden={state !== "collapsed" || isMobile}
+        {...tooltip}
+      />
+    </Tooltip>
+  )
+}
+
+function SidebarMenuAction({
+  className,
+  render,
+  showOnHover = false,
+  ...props
+}: useRender.ComponentProps<"button"> &
+  React.ComponentProps<"button"> & {
+    showOnHover?: boolean
+  }) {
+  return useRender({
+    defaultTagName: "button",
+    props: mergeProps<"button">(
+      {
+        className: cn(
+          "absolute top-1.5 right-1 flex aspect-square w-5 items-center justify-center rounded-xl p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 after:absolute after:-inset-2 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-3 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0",
+          showOnHover &&
+            "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 peer-data-active/menu-button:text-sidebar-accent-foreground aria-expanded:opacity-100 md:opacity-0",
+          className
+        ),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "sidebar-menu-action",
+      sidebar: "menu-action",
+    },
+  })
+}
+
+function SidebarMenuBadge({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-menu-badge"
+      data-sidebar="menu-badge"
+      className={cn(
+        "pointer-events-none absolute right-1 flex h-5 min-w-5 items-center justify-center rounded-xl px-1 text-xs font-medium text-sidebar-foreground tabular-nums select-none group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 peer-data-active/menu-button:text-sidebar-accent-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuSkeleton({
+  className,
+  showIcon = false,
+  ...props
+}: React.ComponentProps<"div"> & {
+  showIcon?: boolean
+}) {
+  // Random width between 50 to 90%.
+  const [width] = React.useState(() => {
+    return `${Math.floor(Math.random() * 40) + 50}%`
+  })
+
+  return (
+    <div
+      data-slot="sidebar-menu-skeleton"
+      data-sidebar="menu-skeleton"
+      className={cn("flex h-8 items-center gap-2 rounded-xl px-2", className)}
+      {...props}
+    >
+      {showIcon && (
+        <Skeleton
+          className="size-4 rounded-xl"
+          data-sidebar="menu-skeleton-icon"
+        />
+      )}
+      <Skeleton
+        className="h-4 max-w-(--skeleton-width) flex-1"
+        data-sidebar="menu-skeleton-text"
+        style={
+          {
+            "--skeleton-width": width,
+          } as React.CSSProperties
+        }
+      />
+    </div>
+  )
+}
+
+function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">) {
+  return (
+    <ul
+      data-slot="sidebar-menu-sub"
+      data-sidebar="menu-sub"
+      className={cn(
+        "mx-3.5 flex min-w-0 translate-x-px flex-col gap-1 border-l border-sidebar-border px-2.5 py-0.5 group-data-[collapsible=icon]:hidden",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuSubItem({
+  className,
+  ...props
+}: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="sidebar-menu-sub-item"
+      data-sidebar="menu-sub-item"
+      className={cn("group/menu-sub-item relative", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuSubButton({
+  render,
+  size = "md",
+  isActive = false,
+  className,
+  ...props
+}: useRender.ComponentProps<"a"> &
+  React.ComponentProps<"a"> & {
+    size?: "sm" | "md"
+    isActive?: boolean
+  }) {
+  return useRender({
+    defaultTagName: "a",
+    props: mergeProps<"a">(
+      {
+        className: cn(
+          "flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-xl px-3 text-sidebar-foreground ring-sidebar-ring outline-hidden group-data-[collapsible=icon]:hidden hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-3 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[size=md]:text-sm data-[size=sm]:text-xs data-active:bg-sidebar-accent data-active:text-sidebar-accent-foreground [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-sidebar-accent-foreground",
+          className
+        ),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "sidebar-menu-sub-button",
+      sidebar: "menu-sub-button",
+      size,
+      active: isActive,
+    },
+  })
+}
+
+export {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupAction,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarInput,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuAction,
+  SidebarMenuBadge,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSkeleton,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarProvider,
+  SidebarRail,
+  SidebarSeparator,
+  SidebarTrigger,
+  useSidebar,
+}
diff --git a/packages/web/src/components/ui/skeleton.tsx b/packages/web/src/components/ui/skeleton.tsx
new file mode 100644
index 0000000..d598583
--- /dev/null
+++ b/packages/web/src/components/ui/skeleton.tsx
@@ -0,0 +1,13 @@
+import { cn } from "@/lib/utils"
+
+function Skeleton({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="skeleton"
+      className={cn("animate-pulse rounded-2xl bg-muted", className)}
+      {...props}
+    />
+  )
+}
+
+export { Skeleton }
diff --git a/packages/web/src/components/ui/slider.tsx b/packages/web/src/components/ui/slider.tsx
new file mode 100644
index 0000000..4dcdfb7
--- /dev/null
+++ b/packages/web/src/components/ui/slider.tsx
@@ -0,0 +1,52 @@
+import { Slider as SliderPrimitive } from "@base-ui/react/slider"
+
+import { cn } from "@/lib/utils"
+
+function Slider({
+  className,
+  defaultValue,
+  value,
+  min = 0,
+  max = 100,
+  ...props
+}: SliderPrimitive.Root.Props) {
+  const _values = Array.isArray(value)
+    ? value
+    : Array.isArray(defaultValue)
+      ? defaultValue
+      : [min, max]
+
+  return (
+    <SliderPrimitive.Root
+      className={cn("data-horizontal:w-full data-vertical:h-full", className)}
+      data-slot="slider"
+      defaultValue={defaultValue}
+      value={value}
+      min={min}
+      max={max}
+      thumbAlignment="edge"
+      {...props}
+    >
+      <SliderPrimitive.Control className="relative flex w-full touch-none items-center select-none data-disabled:opacity-50 data-vertical:h-full data-vertical:min-h-40 data-vertical:w-auto data-vertical:flex-col">
+        <SliderPrimitive.Track
+          data-slot="slider-track"
+          className="relative grow overflow-hidden rounded-2xl bg-input/90 select-none data-horizontal:h-1 data-horizontal:w-full data-vertical:h-full data-vertical:w-1"
+        >
+          <SliderPrimitive.Indicator
+            data-slot="slider-range"
+            className="bg-primary select-none data-horizontal:h-full data-vertical:w-full"
+          />
+        </SliderPrimitive.Track>
+        {Array.from({ length: _values.length }, (_, index) => (
+          <SliderPrimitive.Thumb
+            data-slot="slider-thumb"
+            key={index}
+            className="block size-4 shrink-0 rounded-2xl bg-white shadow-md ring-1 ring-black/10 transition-[color,box-shadow] duration-200 select-none not-dark:bg-clip-padding hover:ring-4 hover:ring-ring/30 focus-visible:ring-4 focus-visible:ring-ring/30 focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50"
+          />
+        ))}
+      </SliderPrimitive.Control>
+    </SliderPrimitive.Root>
+  )
+}
+
+export { Slider }
diff --git a/packages/web/src/components/ui/sonner.tsx b/packages/web/src/components/ui/sonner.tsx
new file mode 100644
index 0000000..e81f838
--- /dev/null
+++ b/packages/web/src/components/ui/sonner.tsx
@@ -0,0 +1,50 @@
+"use client"
+
+import { useTheme } from "next-themes"
+import { Toaster as Sonner, type ToasterProps } from "sonner"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { CheckmarkCircle02Icon, InformationCircleIcon, Alert02Icon, MultiplicationSignCircleIcon, Loading03Icon } from "@hugeicons/core-free-icons"
+
+const Toaster = ({ ...props }: ToasterProps) => {
+  const { theme = "system" } = useTheme()
+
+  return (
+    <Sonner
+      theme={theme as ToasterProps["theme"]}
+      className="toaster group"
+      icons={{
+        success: (
+          <HugeiconsIcon icon={CheckmarkCircle02Icon} strokeWidth={2} className="size-4" />
+        ),
+        info: (
+          <HugeiconsIcon icon={InformationCircleIcon} strokeWidth={2} className="size-4" />
+        ),
+        warning: (
+          <HugeiconsIcon icon={Alert02Icon} strokeWidth={2} className="size-4" />
+        ),
+        error: (
+          <HugeiconsIcon icon={MultiplicationSignCircleIcon} strokeWidth={2} className="size-4" />
+        ),
+        loading: (
+          <HugeiconsIcon icon={Loading03Icon} strokeWidth={2} className="size-4 animate-spin" />
+        ),
+      }}
+      style={
+        {
+          "--normal-bg": "var(--popover)",
+          "--normal-text": "var(--popover-foreground)",
+          "--normal-border": "var(--border)",
+          "--border-radius": "var(--radius)",
+        } as React.CSSProperties
+      }
+      toastOptions={{
+        classNames: {
+          toast: "cn-toast",
+        },
+      }}
+      {...props}
+    />
+  )
+}
+
+export { Toaster }
diff --git a/packages/web/src/components/ui/spinner.tsx b/packages/web/src/components/ui/spinner.tsx
new file mode 100644
index 0000000..27db0ba
--- /dev/null
+++ b/packages/web/src/components/ui/spinner.tsx
@@ -0,0 +1,14 @@
+import { cn } from "@/lib/utils"
+import { HugeiconsIcon, type HugeiconsProps } from "@hugeicons/react"
+import { Loading03Icon } from "@hugeicons/core-free-icons"
+
+// Registry ships React.ComponentProps<"svg"> here, whose `strokeWidth:
+// string | number` conflicts with HugeiconsIcon's `number` (known preset
+// bug, same fix as clawsgo). Re-apply after `shadcn apply` rewrites.
+function Spinner({ className, ...props }: Omit<HugeiconsProps, "icon">) {
+  return (
+    <HugeiconsIcon icon={Loading03Icon} strokeWidth={2} data-slot="spinner" role="status" aria-label="Loading" className={cn("size-4 animate-spin", className)} {...props} />
+  )
+}
+
+export { Spinner }
diff --git a/packages/web/src/components/ui/switch.tsx b/packages/web/src/components/ui/switch.tsx
new file mode 100644
index 0000000..add5028
--- /dev/null
+++ b/packages/web/src/components/ui/switch.tsx
@@ -0,0 +1,30 @@
+import { Switch as SwitchPrimitive } from "@base-ui/react/switch"
+
+import { cn } from "@/lib/utils"
+
+function Switch({
+  className,
+  size = "default",
+  ...props
+}: SwitchPrimitive.Root.Props & {
+  size?: "sm" | "default"
+}) {
+  return (
+    <SwitchPrimitive.Root
+      data-slot="switch"
+      data-size={size}
+      className={cn(
+        "peer group/switch relative inline-flex shrink-0 items-center rounded-2xl border-2 transition-all outline-none after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-[size=default]:h-5 data-[size=default]:w-8 data-[size=sm]:h-4 data-[size=sm]:w-6 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:border-primary data-checked:bg-primary data-unchecked:border-transparent data-unchecked:bg-input/90 data-disabled:cursor-not-allowed data-disabled:opacity-50",
+        className
+      )}
+      {...props}
+    >
+      <SwitchPrimitive.Thumb
+        data-slot="switch-thumb"
+        className="pointer-events-none block rounded-2xl bg-background shadow-sm ring-0 transition-transform not-dark:bg-clip-padding group-data-[size=default]/switch:size-4 group-data-[size=sm]/switch:size-3 data-checked:translate-x-[calc(100%-4px)] dark:data-checked:bg-primary-foreground data-unchecked:translate-x-0 dark:data-unchecked:bg-foreground"
+      />
+    </SwitchPrimitive.Root>
+  )
+}
+
+export { Switch }
diff --git a/packages/web/src/components/ui/table.tsx b/packages/web/src/components/ui/table.tsx
new file mode 100644
index 0000000..abeaced
--- /dev/null
+++ b/packages/web/src/components/ui/table.tsx
@@ -0,0 +1,116 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Table({ className, ...props }: React.ComponentProps<"table">) {
+  return (
+    <div
+      data-slot="table-container"
+      className="relative w-full overflow-x-auto"
+    >
+      <table
+        data-slot="table"
+        className={cn("w-full caption-bottom text-sm", className)}
+        {...props}
+      />
+    </div>
+  )
+}
+
+function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
+  return (
+    <thead
+      data-slot="table-header"
+      className={cn("[&_tr]:border-b", className)}
+      {...props}
+    />
+  )
+}
+
+function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
+  return (
+    <tbody
+      data-slot="table-body"
+      className={cn("[&_tr:last-child]:border-0", className)}
+      {...props}
+    />
+  )
+}
+
+function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
+  return (
+    <tfoot
+      data-slot="table-footer"
+      className={cn(
+        "border-t bg-muted/50 font-medium [&>tr]:last:border-b-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
+  return (
+    <tr
+      data-slot="table-row"
+      className={cn(
+        "border-b transition-colors hover:bg-muted/50 has-aria-expanded:bg-muted/50 data-[state=selected]:bg-muted",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableHead({ className, ...props }: React.ComponentProps<"th">) {
+  return (
+    <th
+      data-slot="table-head"
+      className={cn(
+        "h-10 px-2 text-left align-middle font-medium whitespace-nowrap text-foreground [&:has([role=checkbox])]:pr-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableCell({ className, ...props }: React.ComponentProps<"td">) {
+  return (
+    <td
+      data-slot="table-cell"
+      className={cn(
+        "p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TableCaption({
+  className,
+  ...props
+}: React.ComponentProps<"caption">) {
+  return (
+    <caption
+      data-slot="table-caption"
+      className={cn("mt-4 text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+}
diff --git a/packages/web/src/components/ui/tabs.tsx b/packages/web/src/components/ui/tabs.tsx
new file mode 100644
index 0000000..b08542c
--- /dev/null
+++ b/packages/web/src/components/ui/tabs.tsx
@@ -0,0 +1,80 @@
+import { Tabs as TabsPrimitive } from "@base-ui/react/tabs"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+function Tabs({
+  className,
+  orientation = "horizontal",
+  ...props
+}: TabsPrimitive.Root.Props) {
+  return (
+    <TabsPrimitive.Root
+      data-slot="tabs"
+      data-orientation={orientation}
+      className={cn(
+        "group/tabs flex gap-2 data-horizontal:flex-col",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const tabsListVariants = cva(
+  "group/tabs-list inline-flex w-fit items-center justify-center rounded-2xl p-[3px] text-muted-foreground group-data-horizontal/tabs:h-8 group-data-vertical/tabs:h-fit group-data-vertical/tabs:flex-col group-data-vertical/tabs:p-1 data-[variant=line]:rounded-none",
+  {
+    variants: {
+      variant: {
+        default: "bg-muted",
+        line: "gap-1 bg-transparent",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function TabsList({
+  className,
+  variant = "default",
+  ...props
+}: TabsPrimitive.List.Props & VariantProps<typeof tabsListVariants>) {
+  return (
+    <TabsPrimitive.List
+      data-slot="tabs-list"
+      data-variant={variant}
+      className={cn(tabsListVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}
+
+function TabsTrigger({ className, ...props }: TabsPrimitive.Tab.Props) {
+  return (
+    <TabsPrimitive.Tab
+      data-slot="tabs-trigger"
+      className={cn(
+        "relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-2xl border border-transparent! px-1.5 py-0.5 text-sm font-medium whitespace-nowrap text-foreground/60 transition-all group-data-vertical/tabs:w-full group-data-vertical/tabs:justify-start group-data-vertical/tabs:px-3 group-data-vertical/tabs:py-0.5 hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 dark:text-muted-foreground dark:hover:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent dark:group-data-[variant=line]/tabs-list:data-active:border-transparent dark:group-data-[variant=line]/tabs-list:data-active:bg-transparent",
+        "data-active:bg-background data-active:text-foreground dark:data-active:border-input dark:data-active:bg-input/30 dark:data-active:text-foreground",
+        "after:absolute after:bg-foreground after:opacity-0 after:transition-opacity group-data-horizontal/tabs:after:inset-x-0 group-data-horizontal/tabs:after:bottom-[-5px] group-data-horizontal/tabs:after:h-0.5 group-data-vertical/tabs:after:inset-y-0 group-data-vertical/tabs:after:-right-1 group-data-vertical/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-active:after:opacity-100",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TabsContent({ className, ...props }: TabsPrimitive.Panel.Props) {
+  return (
+    <TabsPrimitive.Panel
+      data-slot="tabs-content"
+      className={cn("flex-1 text-sm outline-none", className)}
+      {...props}
+    />
+  )
+}
+
+export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants }
diff --git a/packages/web/src/components/ui/textarea.tsx b/packages/web/src/components/ui/textarea.tsx
new file mode 100644
index 0000000..f88469f
--- /dev/null
+++ b/packages/web/src/components/ui/textarea.tsx
@@ -0,0 +1,18 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(
+        "flex field-sizing-content min-h-16 w-full resize-none rounded-2xl border border-transparent bg-input/50 px-2.5 py-2 text-base transition-[color,box-shadow] duration-200 outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Textarea }
diff --git a/packages/web/src/components/ui/toggle-group.tsx b/packages/web/src/components/ui/toggle-group.tsx
new file mode 100644
index 0000000..71c92d8
--- /dev/null
+++ b/packages/web/src/components/ui/toggle-group.tsx
@@ -0,0 +1,89 @@
+"use client"
+
+import * as React from "react"
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle"
+import { ToggleGroup as ToggleGroupPrimitive } from "@base-ui/react/toggle-group"
+import { type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { toggleVariants } from "@/components/ui/toggle"
+
+const ToggleGroupContext = React.createContext<
+  VariantProps<typeof toggleVariants> & {
+    spacing?: number
+    orientation?: "horizontal" | "vertical"
+  }
+>({
+  size: "default",
+  variant: "default",
+  spacing: 2,
+  orientation: "horizontal",
+})
+
+function ToggleGroup({
+  className,
+  variant,
+  size,
+  spacing = 2,
+  orientation = "horizontal",
+  children,
+  ...props
+}: ToggleGroupPrimitive.Props &
+  VariantProps<typeof toggleVariants> & {
+    spacing?: number
+    orientation?: "horizontal" | "vertical"
+  }) {
+  return (
+    <ToggleGroupPrimitive
+      data-slot="toggle-group"
+      data-variant={variant}
+      data-size={size}
+      data-spacing={spacing}
+      data-orientation={orientation}
+      style={{ "--gap": spacing } as React.CSSProperties}
+      className={cn(
+        "group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))] data-[spacing=0]:data-[variant=outline]:rounded-2xl data-vertical:flex-col data-vertical:items-stretch",
+        className
+      )}
+      {...props}
+    >
+      <ToggleGroupContext.Provider
+        value={{ variant, size, spacing, orientation }}
+      >
+        {children}
+      </ToggleGroupContext.Provider>
+    </ToggleGroupPrimitive>
+  )
+}
+
+function ToggleGroupItem({
+  className,
+  children,
+  variant = "default",
+  size = "default",
+  ...props
+}: TogglePrimitive.Props & VariantProps<typeof toggleVariants>) {
+  const context = React.useContext(ToggleGroupContext)
+
+  return (
+    <TogglePrimitive
+      data-slot="toggle-group-item"
+      data-variant={context.variant || variant}
+      data-size={context.size || size}
+      data-spacing={context.spacing}
+      className={cn(
+        "shrink-0 group-data-[spacing=0]/toggle-group:rounded-none group-data-[spacing=0]/toggle-group:px-2 group-data-[spacing=0]/toggle-group:shadow-none focus:z-10 focus-visible:z-10 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-end]:pr-1.5 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-start]:pl-1.5 group-data-horizontal/toggle-group:data-[spacing=0]:first:rounded-l-2xl group-data-vertical/toggle-group:data-[spacing=0]:first:rounded-t-2xl group-data-horizontal/toggle-group:data-[spacing=0]:last:rounded-r-2xl group-data-vertical/toggle-group:data-[spacing=0]:last:rounded-b-2xl data-[state=on]:bg-muted group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:border-l-0 group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:border-t-0 group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-l group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-t",
+        toggleVariants({
+          variant: context.variant || variant,
+          size: context.size || size,
+        }),
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </TogglePrimitive>
+  )
+}
+
+export { ToggleGroup, ToggleGroupItem }
diff --git a/packages/web/src/components/ui/toggle.tsx b/packages/web/src/components/ui/toggle.tsx
new file mode 100644
index 0000000..bec62a6
--- /dev/null
+++ b/packages/web/src/components/ui/toggle.tsx
@@ -0,0 +1,45 @@
+"use client"
+
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const toggleVariants = cva(
+  "group/toggle inline-flex items-center justify-center gap-1 rounded-2xl text-sm font-medium whitespace-nowrap transition-colors outline-none hover:bg-muted hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/30 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-pressed:bg-muted dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        outline: "border border-input bg-transparent hover:bg-muted",
+      },
+      size: {
+        default:
+          "h-8 min-w-8 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        sm: "h-7 min-w-7 px-2.5 has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5",
+        lg: "h-9 min-w-9 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function Toggle({
+  className,
+  variant = "default",
+  size = "default",
+  ...props
+}: TogglePrimitive.Props & VariantProps<typeof toggleVariants>) {
+  return (
+    <TogglePrimitive
+      data-slot="toggle"
+      className={cn(toggleVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+}
+
+export { Toggle, toggleVariants }
diff --git a/packages/web/src/components/ui/tooltip.tsx b/packages/web/src/components/ui/tooltip.tsx
new file mode 100644
index 0000000..aad8238
--- /dev/null
+++ b/packages/web/src/components/ui/tooltip.tsx
@@ -0,0 +1,64 @@
+import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip"
+
+import { cn } from "@/lib/utils"
+
+function TooltipProvider({
+  delay = 0,
+  ...props
+}: TooltipPrimitive.Provider.Props) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delay={delay}
+      {...props}
+    />
+  )
+}
+
+function Tooltip({ ...props }: TooltipPrimitive.Root.Props) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+}
+
+function TooltipTrigger({ ...props }: TooltipPrimitive.Trigger.Props) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+  className,
+  side = "top",
+  sideOffset = 4,
+  align = "center",
+  alignOffset = 0,
+  children,
+  ...props
+}: TooltipPrimitive.Popup.Props &
+  Pick<
+    TooltipPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset"
+  >) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+        className="isolate z-50"
+      >
+        <TooltipPrimitive.Popup
+          data-slot="tooltip-content"
+          className={cn(
+            "z-50 inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-xl bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-lg data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            className
+          )}
+          {...props}
+        >
+          {children}
+          <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground data-[side=bottom]:top-1 data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:translate-x-[1.5px] data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:translate-x-[-1.5px] data-[side=inline-start]:-translate-y-1/2 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:translate-x-[-1.5px] data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:translate-x-[1.5px] data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5" />
+        </TooltipPrimitive.Popup>
+      </TooltipPrimitive.Positioner>
+    </TooltipPrimitive.Portal>
+  )
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }
diff --git a/packages/web/src/features/auth/pages/LoginPage.tsx b/packages/web/src/features/auth/pages/LoginPage.tsx
new file mode 100644
index 0000000..6a509e2
--- /dev/null
+++ b/packages/web/src/features/auth/pages/LoginPage.tsx
@@ -0,0 +1,81 @@
+import { useMutation } from '@tanstack/react-query';
+import { useSearch } from '@tanstack/react-router';
+import { useState } from 'react';
+import { Button } from '@/components/ui/button';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import { Field, FieldError, FieldLabel } from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import { login } from '@/lib/api';
+import { setSessionMarker } from '@/lib/session';
+
+/**
+ * One field, one button. The token is posted once and comes back as an
+ * httpOnly session cookie — it is never stored anywhere the page can read.
+ * Success does a full-page jump (not a client-side navigate): the cookie is
+ * brand new, and a reload guarantees every query starts from it.
+ */
+export function LoginPage() {
+  const { redirect } = useSearch({ from: '/login' });
+  const [token, setToken] = useState('');
+  const mutation = useMutation({
+    mutationFn: login,
+    onSuccess: () => {
+      setSessionMarker();
+      window.location.href = redirect ?? '/ui/';
+    },
+  });
+
+  return (
+    <main className="flex min-h-screen items-center justify-center p-4">
+      <Card className="w-full max-w-sm">
+        <CardHeader>
+          <CardTitle className="text-2xl">Dormice</CardTitle>
+          <CardDescription>
+            Paste the daemon's API token to open the console.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <form
+            onSubmit={(event) => {
+              event.preventDefault();
+              mutation.mutate(token);
+            }}
+            className="flex flex-col gap-6"
+          >
+            <Field data-invalid={mutation.isError || undefined}>
+              <FieldLabel htmlFor="api-token">API token</FieldLabel>
+              <Input
+                id="api-token"
+                type="password"
+                autoFocus
+                value={token}
+                onChange={(event) => setToken(event.target.value)}
+                placeholder="DORMICE_API_TOKEN"
+                className="font-mono"
+                aria-invalid={mutation.isError || undefined}
+              />
+              {mutation.isError && (
+                <FieldError>{mutation.error.message}</FieldError>
+              )}
+            </Field>
+            <Button
+              type="submit"
+              disabled={token.length === 0 || mutation.isPending}
+              className="w-full"
+            >
+              {mutation.isPending && <Spinner />}
+              Sign in
+            </Button>
+          </form>
+        </CardContent>
+      </Card>
+    </main>
+  );
+}
diff --git a/packages/web/src/features/sandboxes/components/CreateSandboxDialog.tsx b/packages/web/src/features/sandboxes/components/CreateSandboxDialog.tsx
new file mode 100644
index 0000000..817121c
--- /dev/null
+++ b/packages/web/src/features/sandboxes/components/CreateSandboxDialog.tsx
@@ -0,0 +1,183 @@
+import type { AcquireRequest } from '@dormice/shared';
+import { Add01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@/components/ui/dialog';
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+} from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import { Switch } from '@/components/ui/switch';
+import { useAcquireSandbox } from '../hooks/useSandboxes';
+
+/**
+ * The console speaks the same verb as everyone else: acquire. Same key,
+ * same sandbox — "creating" an existing key just returns it (the policy
+ * override only applies when the acquire actually creates).
+ *
+ * The two policy knobs are optional; empty means the daemon's default.
+ * Archive has no knob here on purpose: there is no archiver yet, so the
+ * only honest value is the default (never).
+ */
+export function CreateSandboxDialog() {
+  const [open, setOpen] = useState(false);
+  const [userKey, setUserKey] = useState('');
+  const [freezeAfter, setFreezeAfter] = useState('');
+  const [neverStop, setNeverStop] = useState(false);
+  const [stopAfter, setStopAfter] = useState('');
+  const mutation = useAcquireSandbox();
+
+  const reset = () => {
+    setUserKey('');
+    setFreezeAfter('');
+    setNeverStop(false);
+    setStopAfter('');
+    mutation.reset();
+  };
+
+  const submit = () => {
+    const policy: NonNullable<AcquireRequest['policy']> = {};
+    if (freezeAfter !== '') policy.freezeAfterSeconds = Number(freezeAfter);
+    if (neverStop) policy.stopAfterSeconds = null;
+    else if (stopAfter !== '') policy.stopAfterSeconds = Number(stopAfter);
+
+    mutation.mutate(
+      {
+        userKey,
+        ...(Object.keys(policy).length > 0 ? { policy } : {}),
+      },
+      {
+        onSuccess: ({ sandbox }) => {
+          toast.success(`Sandbox ready for “${sandbox.userKey}”`);
+          setOpen(false);
+          reset();
+        },
+      },
+    );
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) reset();
+      }}
+    >
+      <DialogTrigger
+        render={
+          <Button size="sm">
+            <HugeiconsIcon icon={Add01Icon} />
+            Create sandbox
+          </Button>
+        }
+      />
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>Create a sandbox</DialogTitle>
+          <DialogDescription>
+            Acquire is idempotent: if this key already has a sandbox, you get
+            that one back and the policy below is ignored.
+          </DialogDescription>
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            submit();
+          }}
+        >
+          <FieldGroup>
+            <Field>
+              <FieldLabel htmlFor="create-user-key">User key</FieldLabel>
+              <Input
+                id="create-user-key"
+                value={userKey}
+                onChange={(event) => setUserKey(event.target.value)}
+                placeholder="my-agent"
+                maxLength={128}
+                className="font-mono"
+              />
+              <FieldDescription>
+                The caller-chosen identity acquire is idempotent on — the same
+                key always comes back to the same sandbox.
+              </FieldDescription>
+            </Field>
+            <Field>
+              <FieldLabel htmlFor="create-freeze-after">
+                Freeze after idle (seconds)
+              </FieldLabel>
+              <Input
+                id="create-freeze-after"
+                type="number"
+                min={1}
+                value={freezeAfter}
+                onChange={(event) => setFreezeAfter(event.target.value)}
+                placeholder="600 (daemon default)"
+              />
+              <FieldDescription>
+                Idle time until active → frozen: memory squeezed to swap, ~50ms
+                to wake.
+              </FieldDescription>
+            </Field>
+            <Field orientation="horizontal">
+              <Switch
+                id="create-never-stop"
+                checked={neverStop}
+                onCheckedChange={setNeverStop}
+              />
+              <FieldLabel htmlFor="create-never-stop">
+                Never stop (resident agent)
+              </FieldLabel>
+            </Field>
+            {!neverStop && (
+              <Field>
+                <FieldLabel htmlFor="create-stop-after">
+                  Stop after idle (seconds)
+                </FieldLabel>
+                <Input
+                  id="create-stop-after"
+                  type="number"
+                  min={1}
+                  value={stopAfter}
+                  onChange={(event) => setStopAfter(event.target.value)}
+                  placeholder="259200 (daemon default)"
+                />
+                <FieldDescription>
+                  Idle time until frozen → stopped: only the disk stays, waking
+                  is a cold start.
+                </FieldDescription>
+              </Field>
+            )}
+            {mutation.isError && (
+              <FieldError>{mutation.error.message}</FieldError>
+            )}
+          </FieldGroup>
+          <DialogFooter className="mt-6">
+            <Button
+              type="submit"
+              disabled={userKey.length === 0 || mutation.isPending}
+            >
+              {mutation.isPending && <Spinner />}
+              Create
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/packages/web/src/features/sandboxes/components/ReleaseSandboxButton.tsx b/packages/web/src/features/sandboxes/components/ReleaseSandboxButton.tsx
new file mode 100644
index 0000000..a75702d
--- /dev/null
+++ b/packages/web/src/features/sandboxes/components/ReleaseSandboxButton.tsx
@@ -0,0 +1,68 @@
+import { toast } from 'sonner';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@/components/ui/alert-dialog';
+import { Button } from '@/components/ui/button';
+import { Spinner } from '@/components/ui/spinner';
+import { useReleaseSandbox } from '../hooks/useSandboxes';
+
+/**
+ * Release destroys the sandbox AND its disk — the one irreversible action in
+ * the console, so it is the one action behind a confirmation dialog.
+ */
+export function ReleaseSandboxButton({
+  userKey,
+  onReleased,
+}: {
+  userKey: string;
+  onReleased?: () => void;
+}) {
+  const mutation = useReleaseSandbox();
+
+  const release = () =>
+    mutation.mutate(userKey, {
+      onSuccess: ({ released }) => {
+        toast.success(
+          released ? `Released ${userKey}` : `${userKey} was already gone`,
+        );
+        onReleased?.();
+      },
+      onError: (error) => toast.error(error.message),
+    });
+
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger
+        render={
+          <Button variant="destructive" size="sm" disabled={mutation.isPending}>
+            {mutation.isPending && <Spinner />}
+            Release
+          </Button>
+        }
+      />
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Release “{userKey}”?</AlertDialogTitle>
+          <AlertDialogDescription>
+            This destroys the sandbox and its disk. The key stays valid — the
+            next acquire starts from a blank sandbox.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Keep it</AlertDialogCancel>
+          <AlertDialogAction variant="destructive" onClick={release}>
+            Release
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
diff --git a/packages/web/src/features/sandboxes/components/SandboxStateBadge.tsx b/packages/web/src/features/sandboxes/components/SandboxStateBadge.tsx
new file mode 100644
index 0000000..0fee679
--- /dev/null
+++ b/packages/web/src/features/sandboxes/components/SandboxStateBadge.tsx
@@ -0,0 +1,24 @@
+import type { SandboxState } from '@dormice/shared';
+import { Badge } from '@/components/ui/badge';
+import { cn } from '@/lib/utils';
+
+// Lifecycle rungs, coldest last — one hue per rung so the list reads at a
+// glance: green is paying for RAM, blue is parked in swap, grey is disk-only.
+const STATE_STYLES: Record<SandboxState, string> = {
+  active:
+    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+  frozen: 'border-sky-500/40 bg-sky-500/10 text-sky-600 dark:text-sky-400',
+  stopped: 'border-border bg-muted text-muted-foreground',
+  archived:
+    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  restoring:
+    'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
+};
+
+export function SandboxStateBadge({ state }: { state: SandboxState }) {
+  return (
+    <Badge variant="outline" className={cn('font-medium', STATE_STYLES[state])}>
+      {state}
+    </Badge>
+  );
+}
diff --git a/packages/web/src/features/sandboxes/format.ts b/packages/web/src/features/sandboxes/format.ts
new file mode 100644
index 0000000..70c91ee
--- /dev/null
+++ b/packages/web/src/features/sandboxes/format.ts
@@ -0,0 +1,30 @@
+import type { Sandbox } from '@dormice/shared';
+
+export function formatDuration(totalSeconds: number): string {
+  const s = Math.max(0, Math.floor(totalSeconds));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
+  if (s < 86400)
+    return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+  return `${Math.floor(s / 86400)}d ${Math.floor((s % 86400) / 3600)}h`;
+}
+
+export function since(iso: string): string {
+  return formatDuration((Date.now() - Date.parse(iso)) / 1000);
+}
+
+/** One knob as text: "freeze 5m" / "stop never". */
+export function policyStep(label: string, seconds: number | null): string {
+  return seconds === null
+    ? `${label} never`
+    : `${label} ${formatDuration(seconds)}`;
+}
+
+/** The three knobs in one line: how this sandbox cools down when idle. */
+export function policyLine(policy: Sandbox['policy']): string {
+  return [
+    policyStep('freeze', policy.freezeAfterSeconds),
+    policyStep('stop', policy.stopAfterSeconds),
+    policyStep('archive', policy.archiveAfterSeconds),
+  ].join(' · ');
+}
diff --git a/packages/web/src/features/sandboxes/hooks/useSandboxes.ts b/packages/web/src/features/sandboxes/hooks/useSandboxes.ts
new file mode 100644
index 0000000..1437fe0
--- /dev/null
+++ b/packages/web/src/features/sandboxes/hooks/useSandboxes.ts
@@ -0,0 +1,44 @@
+import type { AcquireRequest } from '@dormice/shared';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { acquireSandbox, listSandboxes, releaseSandbox } from '@/lib/api';
+
+/**
+ * One entity, one file: every sandbox query and mutation lives here.
+ * The list is the only read the daemon offers (it IS the observation
+ * window), so the detail view selects from the same cache entry instead of
+ * inventing a second endpoint.
+ */
+export function useSandboxes() {
+  return useQuery({
+    queryKey: ['sandboxes'],
+    queryFn: listSandboxes,
+    // The observation window observes: a short poll against a local SQLite
+    // read is effectively free, and 2s is faster than the human eye needs.
+    refetchInterval: 2000,
+    retry: false,
+  });
+}
+
+export function useSandbox(userKey: string) {
+  const query = useSandboxes();
+  return {
+    ...query,
+    sandbox: query.data?.sandboxes.find((s) => s.userKey === userKey),
+  };
+}
+
+export function useAcquireSandbox() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (request: AcquireRequest) => acquireSandbox(request),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
+  });
+}
+
+export function useReleaseSandbox() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (userKey: string) => releaseSandbox(userKey),
+    onSettled: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
+  });
+}
diff --git a/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx
new file mode 100644
index 0000000..dfdd7b1
--- /dev/null
+++ b/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -0,0 +1,109 @@
+import { ArrowLeft01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { Link, useNavigate, useParams } from '@tanstack/react-router';
+import type { ReactNode } from 'react';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent } from '@/components/ui/card';
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import { ReleaseSandboxButton } from '../components/ReleaseSandboxButton';
+import { SandboxStateBadge } from '../components/SandboxStateBadge';
+import { formatDuration, since } from '../format';
+import { useSandbox } from '../hooks/useSandboxes';
+
+function Row({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <div className="flex items-baseline justify-between gap-6 border-b py-3 text-sm last:border-b-0">
+      <dt className="shrink-0 text-muted-foreground">{label}</dt>
+      <dd className="truncate text-right font-mono">{children}</dd>
+    </div>
+  );
+}
+
+/**
+ * Everything /listSandboxes knows about one key. The list is the only read
+ * the daemon offers, so this page selects from the same 2s-polled cache —
+ * no second endpoint, no second truth.
+ */
+export function SandboxDetailPage() {
+  const { userKey } = useParams({ from: '/_app/sandboxes/$userKey' });
+  const navigate = useNavigate();
+  const { sandbox, isSuccess } = useSandbox(userKey);
+
+  if (!sandbox) {
+    return (
+      <main className="mx-auto min-h-screen w-full max-w-3xl px-6 py-10">
+        {isSuccess && (
+          <Empty className="border border-dashed">
+            <EmptyHeader>
+              <EmptyTitle>No sandbox for “{userKey}”</EmptyTitle>
+              <EmptyDescription>
+                It may have been released — the key is free to acquire again.
+              </EmptyDescription>
+            </EmptyHeader>
+            <EmptyContent>
+              <Button variant="outline" size="sm" render={<Link to="/" />}>
+                Back to sandboxes
+              </Button>
+            </EmptyContent>
+          </Empty>
+        )}
+      </main>
+    );
+  }
+
+  return (
+    <main className="mx-auto min-h-screen w-full max-w-3xl px-6">
+      <header className="flex items-center justify-between py-5">
+        <div className="flex items-center gap-3">
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            render={<Link to="/" aria-label="Back to sandboxes" />}
+          >
+            <HugeiconsIcon icon={ArrowLeft01Icon} />
+          </Button>
+          <h1 className="font-mono text-lg font-semibold">{sandbox.userKey}</h1>
+          <SandboxStateBadge state={sandbox.state} />
+        </div>
+        <ReleaseSandboxButton
+          userKey={sandbox.userKey}
+          onReleased={() => navigate({ to: '/' })}
+        />
+      </header>
+
+      <Card>
+        <CardContent>
+          <dl>
+            <Row label="Sandbox ID">{sandbox.sandboxId}</Row>
+            <Row label="Node">{sandbox.nodeId}</Row>
+            <Row label="Endpoint">{sandbox.endpoint}</Row>
+            <Row label="Created">
+              {new Date(sandbox.createdAt).toLocaleString()} ·{' '}
+              {since(sandbox.createdAt)} ago
+            </Row>
+            <Row label="Last active">{since(sandbox.lastActiveAt)} ago</Row>
+            <Row label="Freeze after">
+              {formatDuration(sandbox.policy.freezeAfterSeconds)} idle
+            </Row>
+            <Row label="Stop after">
+              {sandbox.policy.stopAfterSeconds === null
+                ? 'never (resident agent)'
+                : `${formatDuration(sandbox.policy.stopAfterSeconds)} idle`}
+            </Row>
+            <Row label="Archive after">
+              {sandbox.policy.archiveAfterSeconds === null
+                ? 'never'
+                : `${formatDuration(sandbox.policy.archiveAfterSeconds)} idle`}
+            </Row>
+          </dl>
+        </CardContent>
+      </Card>
+    </main>
+  );
+}
diff --git a/packages/web/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/web/src/features/sandboxes/pages/SandboxesPage.tsx
new file mode 100644
index 0000000..5e7ba2b
--- /dev/null
+++ b/packages/web/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -0,0 +1,127 @@
+import { PackageIcon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { Link } from '@tanstack/react-router';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Button } from '@/components/ui/button';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { logout } from '@/lib/api';
+import { clearSessionMarker } from '@/lib/session';
+import { CreateSandboxDialog } from '../components/CreateSandboxDialog';
+import { ReleaseSandboxButton } from '../components/ReleaseSandboxButton';
+import { SandboxStateBadge } from '../components/SandboxStateBadge';
+import { policyLine, since } from '../format';
+import { useSandboxes } from '../hooks/useSandboxes';
+
+async function signOut() {
+  // Best effort: the cookie may already be dead, and that's fine — what
+  // matters is clearing the marker and starting over from the login page.
+  await logout().catch(() => undefined);
+  clearSessionMarker();
+  window.location.href = '/ui/login';
+}
+
+export function SandboxesPage() {
+  const query = useSandboxes();
+  const sandboxes = query.data?.sandboxes ?? [];
+
+  return (
+    <main className="mx-auto min-h-screen w-full max-w-5xl px-6">
+      <header className="flex items-center justify-between py-5">
+        <div className="flex items-baseline gap-3">
+          <h1 className="text-lg font-semibold">Dormice</h1>
+          <span className="text-sm text-muted-foreground">
+            {sandboxes.length} sandbox{sandboxes.length === 1 ? '' : 'es'}
+          </span>
+        </div>
+        <div className="flex items-center gap-2">
+          <CreateSandboxDialog />
+          <Button variant="ghost" size="sm" onClick={signOut}>
+            Sign out
+          </Button>
+        </div>
+      </header>
+
+      {query.isError && (
+        <Alert variant="destructive" className="mb-4">
+          <AlertDescription>{query.error.message}</AlertDescription>
+        </Alert>
+      )}
+
+      {query.isSuccess && sandboxes.length === 0 && (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyMedia variant="icon">
+              <HugeiconsIcon icon={PackageIcon} />
+            </EmptyMedia>
+            <EmptyTitle>No sandboxes yet</EmptyTitle>
+            <EmptyDescription>
+              Create one here, or acquire one via the SDK — it appears within
+              two seconds either way.
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      )}
+
+      {sandboxes.length > 0 && (
+        <div className="overflow-x-auto rounded-lg border">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>User key</TableHead>
+                <TableHead>State</TableHead>
+                <TableHead>Idle</TableHead>
+                <TableHead>Lifecycle policy</TableHead>
+                <TableHead>Age</TableHead>
+                <TableHead className="text-right">Actions</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {sandboxes.map((sandbox) => (
+                <TableRow key={sandbox.sandboxId}>
+                  <TableCell>
+                    <Link
+                      to="/sandboxes/$userKey"
+                      params={{ userKey: sandbox.userKey }}
+                      className="font-mono font-medium hover:underline"
+                    >
+                      {sandbox.userKey}
+                    </Link>
+                  </TableCell>
+                  <TableCell>
+                    <SandboxStateBadge state={sandbox.state} />
+                  </TableCell>
+                  <TableCell className="tabular-nums text-muted-foreground">
+                    {since(sandbox.lastActiveAt)}
+                  </TableCell>
+                  <TableCell className="text-xs text-muted-foreground">
+                    {policyLine(sandbox.policy)}
+                  </TableCell>
+                  <TableCell className="tabular-nums text-muted-foreground">
+                    {since(sandbox.createdAt)}
+                  </TableCell>
+                  <TableCell className="text-right">
+                    <ReleaseSandboxButton userKey={sandbox.userKey} />
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </div>
+      )}
+    </main>
+  );
+}
diff --git a/packages/web/src/hooks/use-mobile.ts b/packages/web/src/hooks/use-mobile.ts
new file mode 100644
index 0000000..2b0fe1d
--- /dev/null
+++ b/packages/web/src/hooks/use-mobile.ts
@@ -0,0 +1,19 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}
diff --git a/packages/web/src/index.css b/packages/web/src/index.css
new file mode 100644
index 0000000..c01d53b
--- /dev/null
+++ b/packages/web/src/index.css
@@ -0,0 +1,4 @@
+/* Style entry: imports only, plus project-level overrides. src/shadcn.css is
+   owned by the shadcn CLI (rewritten wholesale by `shadcn apply`) — custom
+   styles live here, never there. */
+@import "./shadcn.css";
diff --git a/packages/web/src/lib/api.ts b/packages/web/src/lib/api.ts
new file mode 100644
index 0000000..f48bfc0
--- /dev/null
+++ b/packages/web/src/lib/api.ts
@@ -0,0 +1,79 @@
+import type { AcquireRequest, AcquireResponse, Sandbox } from '@dormice/shared';
+import { clearSessionMarker, hasSessionMarker } from './session';
+
+/**
+ * The console talks to the daemon's native RPC routes — the same routes,
+ * same truth as the SDK and CLI — authenticated by the httpOnly session
+ * cookie the browser attaches on its own. The custom header is the second
+ * half of the CSRF defense: a cross-origin page cannot send it without a
+ * CORS preflight, and the daemon answers no preflights.
+ */
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * Session-expiry backstop, in one place instead of per page: any business
+ * call answered 401 while we believed we were signed in means the cookie
+ * died (expired, or the API token was rotated). Clear the stale marker and
+ * do a full-page jump to the login route — a reload guarantees no leftover
+ * query cache or component state survives, and the redirect param brings
+ * the operator back to where they were.
+ */
+function interceptUnauthorized(): void {
+  if (!hasSessionMarker()) return;
+  clearSessionMarker();
+  const here = window.location.pathname + window.location.search;
+  window.location.href = `/ui/login?redirect=${encodeURIComponent(here)}`;
+}
+
+async function rpc<T>(
+  path: string,
+  body: unknown = {},
+  { intercept401 = true } = {},
+): Promise<T> {
+  const res = await fetch(path, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'x-dormice-console': '1',
+    },
+    body: JSON.stringify(body),
+  });
+  if (res.status === 401 && intercept401) {
+    interceptUnauthorized();
+  }
+  if (!res.ok) {
+    const message = await res
+      .json()
+      .then((data: { message?: string }) => data.message)
+      .catch(() => undefined);
+    throw new ApiError(
+      message ?? `${path} failed with ${res.status}`,
+      res.status,
+    );
+  }
+  return res.json() as Promise<T>;
+}
+
+// Login's own 401 means "wrong token", a form error to show in place — the
+// interceptor is for sessions dying mid-flight, not for failed sign-ins.
+export const login = (token: string) =>
+  rpc<{ loggedIn: true }>('/ui/auth/login', { token }, { intercept401: false });
+
+export const logout = () =>
+  rpc<{ loggedIn: false }>('/ui/auth/logout', {}, { intercept401: false });
+
+export const listSandboxes = () =>
+  rpc<{ sandboxes: Sandbox[] }>('/listSandboxes');
+
+export const acquireSandbox = (request: AcquireRequest) =>
+  rpc<AcquireResponse>('/acquireSandbox', request);
+
+export const releaseSandbox = (userKey: string) =>
+  rpc<{ released: boolean }>('/releaseSandbox', { userKey });
diff --git a/packages/web/src/lib/queryClient.ts b/packages/web/src/lib/queryClient.ts
new file mode 100644
index 0000000..6d46de5
--- /dev/null
+++ b/packages/web/src/lib/queryClient.ts
@@ -0,0 +1,3 @@
+import { QueryClient } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient();
diff --git a/packages/web/src/lib/session.ts b/packages/web/src/lib/session.ts
new file mode 100644
index 0000000..0aff526
--- /dev/null
+++ b/packages/web/src/lib/session.ts
@@ -0,0 +1,21 @@
+/**
+ * The real credential is the httpOnly session cookie — page code can never
+ * read it, which is the point (XSS cannot steal it). This localStorage flag
+ * is a worthless-to-attackers hint that a session probably exists, so the
+ * router guard can skip rendering protected pages without a network round
+ * trip. The daemon never sees it; the 401 interceptor in api.ts is the
+ * actual arbiter of session validity.
+ */
+const MARKER_KEY = 'dormice.console.signed-in';
+
+export function hasSessionMarker(): boolean {
+  return localStorage.getItem(MARKER_KEY) !== null;
+}
+
+export function setSessionMarker(): void {
+  localStorage.setItem(MARKER_KEY, '1');
+}
+
+export function clearSessionMarker(): void {
+  localStorage.removeItem(MARKER_KEY);
+}
diff --git a/packages/web/src/lib/utils.ts b/packages/web/src/lib/utils.ts
new file mode 100644
index 0000000..bd0c391
--- /dev/null
+++ b/packages/web/src/lib/utils.ts
@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
diff --git a/packages/web/src/main.tsx b/packages/web/src/main.tsx
index f9f9ee9..3b612b7 100644
--- a/packages/web/src/main.tsx
+++ b/packages/web/src/main.tsx
@@ -1,37 +1,15 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import {
-  createRootRoute,
-  createRoute,
-  createRouter,
-  Outlet,
-  RouterProvider,
-} from '@tanstack/react-router';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { createRouter, RouterProvider } from '@tanstack/react-router';
+import { ThemeProvider } from 'next-themes';
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { LoginPage } from './pages/login';
-import { SandboxesPage } from './pages/sandboxes';
-import './styles.css';
-
-const rootRoute = createRootRoute({ component: Outlet });
-
-const sandboxesRoute = createRoute({
-  getParentRoute: () => rootRoute,
-  path: '/',
-  component: SandboxesPage,
-});
-
-const loginRoute = createRoute({
-  getParentRoute: () => rootRoute,
-  path: '/login',
-  component: LoginPage,
-});
+import { queryClient } from '@/lib/queryClient';
+import { routeTree } from './routeTree.gen';
+import './index.css';
 
 // The daemon serves the console under /ui; the router lives there too so
 // server paths and client paths are the same strings everywhere.
-const router = createRouter({
-  routeTree: rootRoute.addChildren([sandboxesRoute, loginRoute]),
-  basepath: '/ui',
-});
+const router = createRouter({ routeTree, basepath: '/ui' });
 
 declare module '@tanstack/react-router' {
   interface Register {
@@ -39,13 +17,13 @@ declare module '@tanstack/react-router' {
   }
 }
 
-const queryClient = new QueryClient();
-
 // biome-ignore lint/style/noNonNullAssertion: index.html always has #root
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
-    <QueryClientProvider client={queryClient}>
-      <RouterProvider router={router} />
-    </QueryClientProvider>
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+      <QueryClientProvider client={queryClient}>
+        <RouterProvider router={router} />
+      </QueryClientProvider>
+    </ThemeProvider>
   </StrictMode>,
 );
diff --git a/packages/web/src/pages/login.tsx b/packages/web/src/pages/login.tsx
deleted file mode 100644
index 436bb9f..0000000
--- a/packages/web/src/pages/login.tsx
+++ /dev/null
@@ -1,53 +0,0 @@
-import { useMutation } from '@tanstack/react-query';
-import { useNavigate } from '@tanstack/react-router';
-import { useState } from 'react';
-import { login } from '../api';
-
-/**
- * One field, one button. The token is posted once and comes back as an
- * httpOnly session cookie — it is never stored anywhere the page can read.
- */
-export function LoginPage() {
-  const navigate = useNavigate();
-  const [token, setToken] = useState('');
-  const mutation = useMutation({
-    mutationFn: login,
-    onSuccess: () => navigate({ to: '/' }),
-  });
-
-  return (
-    <main className="flex min-h-screen items-center justify-center bg-slate-950 text-slate-100">
-      <form
-        className="w-full max-w-sm rounded-xl border border-slate-800 bg-slate-900 p-8 shadow-lg"
-        onSubmit={(event) => {
-          event.preventDefault();
-          mutation.mutate(token);
-        }}
-      >
-        <h1 className="text-2xl font-semibold">Dormice</h1>
-        <p className="mt-1 text-sm text-slate-400">
-          Paste the daemon's API token to open the console.
-        </p>
-        <input
-          type="password"
-          // biome-ignore lint/a11y/noAutofocus: the page has exactly one input and exists only to receive it
-          autoFocus
-          value={token}
-          onChange={(event) => setToken(event.target.value)}
-          placeholder="DORMICE_API_TOKEN"
-          className="mt-6 w-full rounded-md border border-slate-700 bg-slate-950 px-3 py-2 font-mono text-sm placeholder:text-slate-600 focus:border-sky-500 focus:outline-none"
-        />
-        {mutation.isError && (
-          <p className="mt-3 text-sm text-red-400">{mutation.error.message}</p>
-        )}
-        <button
-          type="submit"
-          disabled={token.length === 0 || mutation.isPending}
-          className="mt-6 w-full rounded-md bg-sky-600 py-2 font-medium text-white hover:bg-sky-500 disabled:opacity-50"
-        >
-          {mutation.isPending ? 'Signing in…' : 'Sign in'}
-        </button>
-      </form>
-    </main>
-  );
-}
diff --git a/packages/web/src/pages/sandboxes.tsx b/packages/web/src/pages/sandboxes.tsx
deleted file mode 100644
index 2077dcb..0000000
--- a/packages/web/src/pages/sandboxes.tsx
+++ /dev/null
@@ -1,204 +0,0 @@
-import type { Sandbox, SandboxState } from '@dormice/shared';
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { useNavigate } from '@tanstack/react-router';
-import { useEffect, useState } from 'react';
-import {
-  listSandboxes,
-  logout,
-  releaseSandbox,
-  UnauthorizedError,
-} from '../api';
-
-const STATE_STYLES: Record<SandboxState, string> = {
-  active: 'bg-emerald-500/15 text-emerald-400 border-emerald-500/30',
-  frozen: 'bg-sky-500/15 text-sky-400 border-sky-500/30',
-  stopped: 'bg-slate-500/15 text-slate-400 border-slate-500/30',
-  archived: 'bg-violet-500/15 text-violet-400 border-violet-500/30',
-  restoring: 'bg-amber-500/15 text-amber-400 border-amber-500/30',
-};
-
-function formatDuration(totalSeconds: number): string {
-  const s = Math.max(0, Math.floor(totalSeconds));
-  if (s < 60) return `${s}s`;
-  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
-  if (s < 86400)
-    return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
-  return `${Math.floor(s / 86400)}d ${Math.floor((s % 86400) / 3600)}h`;
-}
-
-function since(iso: string): string {
-  return formatDuration((Date.now() - Date.parse(iso)) / 1000);
-}
-
-/** The three knobs in one line: how this sandbox cools down when idle. */
-function policyLine(policy: Sandbox['policy']): string {
-  const step = (label: string, seconds: number | null) =>
-    seconds === null ? `${label} never` : `${label} ${formatDuration(seconds)}`;
-  return [
-    step('freeze', policy.freezeAfterSeconds),
-    step('stop', policy.stopAfterSeconds),
-    step('archive', policy.archiveAfterSeconds),
-  ].join(' · ');
-}
-
-function ReleaseButton({ userKey }: { userKey: string }) {
-  const queryClient = useQueryClient();
-  const [armed, setArmed] = useState(false);
-  const mutation = useMutation({
-    mutationFn: releaseSandbox,
-    onSettled: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
-  });
-
-  // Two clicks on purpose: release destroys the sandbox and its disk, and a
-  // modal library is more machinery than one armed state.
-  if (!armed) {
-    return (
-      <button
-        type="button"
-        onClick={() => setArmed(true)}
-        className="rounded-md border border-slate-700 px-3 py-1 text-xs text-slate-300 hover:border-red-500/50 hover:text-red-400"
-      >
-        Release
-      </button>
-    );
-  }
-  return (
-    <span className="flex items-center justify-end gap-2">
-      <button
-        type="button"
-        onClick={() => mutation.mutate(userKey)}
-        disabled={mutation.isPending}
-        className="rounded-md bg-red-600 px-3 py-1 text-xs font-medium text-white hover:bg-red-500 disabled:opacity-50"
-      >
-        {mutation.isPending ? 'Releasing…' : 'Destroy it'}
-      </button>
-      <button
-        type="button"
-        onClick={() => setArmed(false)}
-        className="rounded-md border border-slate-700 px-3 py-1 text-xs text-slate-400"
-      >
-        Keep
-      </button>
-    </span>
-  );
-}
-
-export function SandboxesPage() {
-  const navigate = useNavigate();
-  const queryClient = useQueryClient();
-  const query = useQuery({
-    queryKey: ['sandboxes'],
-    queryFn: listSandboxes,
-    // The observation window observes: a short poll against a local SQLite
-    // read is effectively free, and 2s is faster than the human eye needs.
-    refetchInterval: 2000,
-    retry: false,
-  });
-
-  useEffect(() => {
-    if (query.error instanceof UnauthorizedError) {
-      navigate({ to: '/login' });
-    }
-  }, [query.error, navigate]);
-
-  const logoutMutation = useMutation({
-    mutationFn: logout,
-    onSuccess: () => {
-      queryClient.clear();
-      navigate({ to: '/login' });
-    },
-  });
-
-  const sandboxes = query.data?.sandboxes ?? [];
-
-  return (
-    <main className="min-h-screen bg-slate-950 text-slate-100">
-      <header className="flex items-center justify-between border-b border-slate-800 px-6 py-4">
-        <div className="flex items-baseline gap-3">
-          <h1 className="text-lg font-semibold">Dormice</h1>
-          <span className="text-sm text-slate-400">
-            {sandboxes.length} sandbox{sandboxes.length === 1 ? '' : 'es'}
-          </span>
-        </div>
-        <button
-          type="button"
-          onClick={() => logoutMutation.mutate()}
-          className="rounded-md border border-slate-700 px-3 py-1 text-sm text-slate-300 hover:border-slate-500"
-        >
-          Sign out
-        </button>
-      </header>
-
-      <section className="px-6 py-6">
-        {query.isError && !(query.error instanceof UnauthorizedError) && (
-          <p className="mb-4 rounded-md border border-red-500/30 bg-red-500/10 px-4 py-2 text-sm text-red-400">
-            {query.error.message}
-          </p>
-        )}
-
-        {query.isSuccess && sandboxes.length === 0 && (
-          <div className="rounded-xl border border-slate-800 bg-slate-900 px-6 py-12 text-center text-slate-400">
-            <p className="font-medium text-slate-300">No sandboxes yet</p>
-            <p className="mt-2 text-sm">
-              Acquire one via the SDK or{' '}
-              <code className="rounded bg-slate-800 px-1.5 py-0.5 font-mono text-xs">
-                POST /acquireSandbox
-              </code>{' '}
-              — it will appear here within two seconds.
-            </p>
-          </div>
-        )}
-
-        {sandboxes.length > 0 && (
-          <div className="overflow-x-auto rounded-xl border border-slate-800">
-            <table className="w-full text-left text-sm">
-              <thead className="border-b border-slate-800 bg-slate-900 text-xs uppercase tracking-wide text-slate-500">
-                <tr>
-                  <th className="px-4 py-3">User key</th>
-                  <th className="px-4 py-3">State</th>
-                  <th className="px-4 py-3">Idle</th>
-                  <th className="px-4 py-3">Lifecycle policy</th>
-                  <th className="px-4 py-3">Sandbox ID</th>
-                  <th className="px-4 py-3">Age</th>
-                  <th className="px-4 py-3 text-right">Actions</th>
-                </tr>
-              </thead>
-              <tbody className="divide-y divide-slate-800/70">
-                {sandboxes.map((sandbox) => (
-                  <tr key={sandbox.sandboxId} className="hover:bg-slate-900/60">
-                    <td className="px-4 py-3 font-mono">{sandbox.userKey}</td>
-                    <td className="px-4 py-3">
-                      <span
-                        className={`inline-block rounded-full border px-2.5 py-0.5 text-xs font-medium ${STATE_STYLES[sandbox.state]}`}
-                      >
-                        {sandbox.state}
-                      </span>
-                    </td>
-                    <td className="px-4 py-3 tabular-nums text-slate-400">
-                      {since(sandbox.lastActiveAt)}
-                    </td>
-                    <td className="px-4 py-3 text-xs text-slate-400">
-                      {policyLine(sandbox.policy)}
-                    </td>
-                    <td
-                      className="max-w-40 truncate px-4 py-3 font-mono text-xs text-slate-500"
-                      title={sandbox.sandboxId}
-                    >
-                      {sandbox.sandboxId}
-                    </td>
-                    <td className="px-4 py-3 tabular-nums text-slate-400">
-                      {since(sandbox.createdAt)}
-                    </td>
-                    <td className="px-4 py-3 text-right">
-                      <ReleaseButton userKey={sandbox.userKey} />
-                    </td>
-                  </tr>
-                ))}
-              </tbody>
-            </table>
-          </div>
-        )}
-      </section>
-    </main>
-  );
-}
diff --git a/packages/web/src/routeTree.gen.ts b/packages/web/src/routeTree.gen.ts
new file mode 100644
index 0000000..9a3942b
--- /dev/null
+++ b/packages/web/src/routeTree.gen.ts
@@ -0,0 +1,118 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as LoginRouteImport } from './routes/login'
+import { Route as AppRouteImport } from './routes/_app'
+import { Route as AppIndexRouteImport } from './routes/_app/index'
+import { Route as AppSandboxesUserKeyRouteImport } from './routes/_app/sandboxes/$userKey'
+
+const LoginRoute = LoginRouteImport.update({
+  id: '/login',
+  path: '/login',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const AppRoute = AppRouteImport.update({
+  id: '/_app',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const AppIndexRoute = AppIndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => AppRoute,
+} as any)
+const AppSandboxesUserKeyRoute = AppSandboxesUserKeyRouteImport.update({
+  id: '/sandboxes/$userKey',
+  path: '/sandboxes/$userKey',
+  getParentRoute: () => AppRoute,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof AppIndexRoute
+  '/login': typeof LoginRoute
+  '/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
+}
+export interface FileRoutesByTo {
+  '/login': typeof LoginRoute
+  '/': typeof AppIndexRoute
+  '/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/_app': typeof AppRouteWithChildren
+  '/login': typeof LoginRoute
+  '/_app/': typeof AppIndexRoute
+  '/_app/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/login' | '/sandboxes/$userKey'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/login' | '/' | '/sandboxes/$userKey'
+  id: '__root__' | '/_app' | '/login' | '/_app/' | '/_app/sandboxes/$userKey'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  AppRoute: typeof AppRouteWithChildren
+  LoginRoute: typeof LoginRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/login': {
+      id: '/login'
+      path: '/login'
+      fullPath: '/login'
+      preLoaderRoute: typeof LoginRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/_app': {
+      id: '/_app'
+      path: ''
+      fullPath: '/'
+      preLoaderRoute: typeof AppRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/_app/': {
+      id: '/_app/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof AppIndexRouteImport
+      parentRoute: typeof AppRoute
+    }
+    '/_app/sandboxes/$userKey': {
+      id: '/_app/sandboxes/$userKey'
+      path: '/sandboxes/$userKey'
+      fullPath: '/sandboxes/$userKey'
+      preLoaderRoute: typeof AppSandboxesUserKeyRouteImport
+      parentRoute: typeof AppRoute
+    }
+  }
+}
+
+interface AppRouteChildren {
+  AppIndexRoute: typeof AppIndexRoute
+  AppSandboxesUserKeyRoute: typeof AppSandboxesUserKeyRoute
+}
+
+const AppRouteChildren: AppRouteChildren = {
+  AppIndexRoute: AppIndexRoute,
+  AppSandboxesUserKeyRoute: AppSandboxesUserKeyRoute,
+}
+
+const AppRouteWithChildren = AppRoute._addFileChildren(AppRouteChildren)
+
+const rootRouteChildren: RootRouteChildren = {
+  AppRoute: AppRouteWithChildren,
+  LoginRoute: LoginRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
diff --git a/packages/web/src/routes/__root.tsx b/packages/web/src/routes/__root.tsx
new file mode 100644
index 0000000..cccb3c1
--- /dev/null
+++ b/packages/web/src/routes/__root.tsx
@@ -0,0 +1,11 @@
+import { createRootRoute, Outlet } from '@tanstack/react-router';
+import { Toaster } from '@/components/ui/sonner';
+
+export const Route = createRootRoute({
+  component: () => (
+    <>
+      <Outlet />
+      <Toaster />
+    </>
+  ),
+});
diff --git a/packages/web/src/routes/_app.tsx b/packages/web/src/routes/_app.tsx
new file mode 100644
index 0000000..31fbb82
--- /dev/null
+++ b/packages/web/src/routes/_app.tsx
@@ -0,0 +1,18 @@
+import { createFileRoute, redirect } from '@tanstack/react-router';
+import { hasSessionMarker } from '@/lib/session';
+
+/**
+ * The gate for everything signed-in, written once — child routes inherit it.
+ * The marker is only a hint (the real credential is the httpOnly cookie the
+ * page cannot read); a stale "yes" is corrected by the 401 interceptor in
+ * api.ts on the first request. What the guard buys is the common case:
+ * a signed-out visitor never sees a protected page flash before the
+ * redirect, and the deep link they wanted survives the trip through login.
+ */
+export const Route = createFileRoute('/_app')({
+  beforeLoad: ({ location }) => {
+    if (!hasSessionMarker()) {
+      throw redirect({ to: '/login', search: { redirect: location.href } });
+    }
+  },
+});
diff --git a/packages/web/src/routes/_app/index.tsx b/packages/web/src/routes/_app/index.tsx
new file mode 100644
index 0000000..90ed5a9
--- /dev/null
+++ b/packages/web/src/routes/_app/index.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { SandboxesPage } from '@/features/sandboxes/pages/SandboxesPage';
+
+export const Route = createFileRoute('/_app/')({
+  component: SandboxesPage,
+});
diff --git a/packages/web/src/routes/_app/sandboxes/$userKey.tsx b/packages/web/src/routes/_app/sandboxes/$userKey.tsx
new file mode 100644
index 0000000..fd4ba9f
--- /dev/null
+++ b/packages/web/src/routes/_app/sandboxes/$userKey.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { SandboxDetailPage } from '@/features/sandboxes/pages/SandboxDetailPage';
+
+export const Route = createFileRoute('/_app/sandboxes/$userKey')({
+  component: SandboxDetailPage,
+});
diff --git a/packages/web/src/routes/login.tsx b/packages/web/src/routes/login.tsx
new file mode 100644
index 0000000..3bad3ee
--- /dev/null
+++ b/packages/web/src/routes/login.tsx
@@ -0,0 +1,30 @@
+import { createFileRoute, redirect } from '@tanstack/react-router';
+import { LoginPage } from '@/features/auth/pages/LoginPage';
+import { hasSessionMarker } from '@/lib/session';
+
+/**
+ * Open-redirect protection for `?redirect=`: only an in-app absolute path
+ * (single leading slash — `//evil.com` is protocol-relative) is honored;
+ * anything else is dropped, not rejected — a broken deep link should not
+ * break signing in.
+ */
+export type LoginSearch = { redirect?: string };
+
+export const Route = createFileRoute('/login')({
+  validateSearch: (search): LoginSearch => {
+    const value = search.redirect;
+    return typeof value === 'string' &&
+      value.startsWith('/') &&
+      !value.startsWith('//')
+      ? { redirect: value }
+      : {};
+  },
+  // Reverse guard: someone who is (probably) signed in has no business on
+  // the login page — send them to their target, or the sandbox list.
+  beforeLoad: ({ search }) => {
+    if (!hasSessionMarker()) return;
+    if (search.redirect) throw redirect({ href: search.redirect });
+    throw redirect({ to: '/' });
+  },
+  component: LoginPage,
+});
diff --git a/packages/web/src/shadcn.css b/packages/web/src/shadcn.css
new file mode 100644
index 0000000..ec63aa5
--- /dev/null
+++ b/packages/web/src/shadcn.css
@@ -0,0 +1,130 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "@fontsource-variable/inter";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+    --font-heading: var(--font-sans);
+    --font-sans: 'Inter Variable', sans-serif;
+    --color-sidebar-ring: var(--sidebar-ring);
+    --color-sidebar-border: var(--sidebar-border);
+    --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+    --color-sidebar-accent: var(--sidebar-accent);
+    --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+    --color-sidebar-primary: var(--sidebar-primary);
+    --color-sidebar-foreground: var(--sidebar-foreground);
+    --color-sidebar: var(--sidebar);
+    --color-chart-5: var(--chart-5);
+    --color-chart-4: var(--chart-4);
+    --color-chart-3: var(--chart-3);
+    --color-chart-2: var(--chart-2);
+    --color-chart-1: var(--chart-1);
+    --color-ring: var(--ring);
+    --color-input: var(--input);
+    --color-border: var(--border);
+    --color-destructive: var(--destructive);
+    --color-accent-foreground: var(--accent-foreground);
+    --color-accent: var(--accent);
+    --color-muted-foreground: var(--muted-foreground);
+    --color-muted: var(--muted);
+    --color-secondary-foreground: var(--secondary-foreground);
+    --color-secondary: var(--secondary);
+    --color-primary-foreground: var(--primary-foreground);
+    --color-primary: var(--primary);
+    --color-popover-foreground: var(--popover-foreground);
+    --color-popover: var(--popover);
+    --color-card-foreground: var(--card-foreground);
+    --color-card: var(--card);
+    --color-foreground: var(--foreground);
+    --color-background: var(--background);
+    --radius-sm: calc(var(--radius) * 0.6);
+    --radius-md: calc(var(--radius) * 0.8);
+    --radius-lg: var(--radius);
+    --radius-xl: calc(var(--radius) * 1.4);
+    --radius-2xl: calc(var(--radius) * 1.8);
+    --radius-3xl: calc(var(--radius) * 2.2);
+    --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+:root {
+    --background: oklch(1 0 0);
+    --foreground: oklch(0.145 0 0);
+    --card: oklch(1 0 0);
+    --card-foreground: oklch(0.145 0 0);
+    --popover: oklch(1 0 0);
+    --popover-foreground: oklch(0.145 0 0);
+    --primary: oklch(0.488 0.243 264.376);
+    --primary-foreground: oklch(0.97 0.014 254.604);
+    --secondary: oklch(0.967 0.001 286.375);
+    --secondary-foreground: oklch(0.21 0.006 285.885);
+    --muted: oklch(0.97 0 0);
+    --muted-foreground: oklch(0.556 0 0);
+    --accent: oklch(0.97 0 0);
+    --accent-foreground: oklch(0.205 0 0);
+    --destructive: oklch(0.577 0.245 27.325);
+    --border: oklch(0.922 0 0);
+    --input: oklch(0.922 0 0);
+    --ring: oklch(0.708 0 0);
+    --chart-1: oklch(0.809 0.105 251.813);
+    --chart-2: oklch(0.623 0.214 259.815);
+    --chart-3: oklch(0.546 0.245 262.881);
+    --chart-4: oklch(0.488 0.243 264.376);
+    --chart-5: oklch(0.424 0.199 265.638);
+    --radius: 0.625rem;
+    --sidebar: oklch(0.985 0 0);
+    --sidebar-foreground: oklch(0.145 0 0);
+    --sidebar-primary: oklch(0.546 0.245 262.881);
+    --sidebar-primary-foreground: oklch(0.97 0.014 254.604);
+    --sidebar-accent: oklch(0.97 0 0);
+    --sidebar-accent-foreground: oklch(0.205 0 0);
+    --sidebar-border: oklch(0.922 0 0);
+    --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+    --background: oklch(0.145 0 0);
+    --foreground: oklch(0.985 0 0);
+    --card: oklch(0.205 0 0);
+    --card-foreground: oklch(0.985 0 0);
+    --popover: oklch(0.205 0 0);
+    --popover-foreground: oklch(0.985 0 0);
+    --primary: oklch(0.424 0.199 265.638);
+    --primary-foreground: oklch(0.97 0.014 254.604);
+    --secondary: oklch(0.274 0.006 286.033);
+    --secondary-foreground: oklch(0.985 0 0);
+    --muted: oklch(0.269 0 0);
+    --muted-foreground: oklch(0.708 0 0);
+    --accent: oklch(0.269 0 0);
+    --accent-foreground: oklch(0.985 0 0);
+    --destructive: oklch(0.704 0.191 22.216);
+    --border: oklch(1 0 0 / 10%);
+    --input: oklch(1 0 0 / 15%);
+    --ring: oklch(0.556 0 0);
+    --chart-1: oklch(0.809 0.105 251.813);
+    --chart-2: oklch(0.623 0.214 259.815);
+    --chart-3: oklch(0.546 0.245 262.881);
+    --chart-4: oklch(0.488 0.243 264.376);
+    --chart-5: oklch(0.424 0.199 265.638);
+    --sidebar: oklch(0.205 0 0);
+    --sidebar-foreground: oklch(0.985 0 0);
+    --sidebar-primary: oklch(0.623 0.214 259.815);
+    --sidebar-primary-foreground: oklch(0.97 0.014 254.604);
+    --sidebar-accent: oklch(0.269 0 0);
+    --sidebar-accent-foreground: oklch(0.985 0 0);
+    --sidebar-border: oklch(1 0 0 / 10%);
+    --sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+    }
+  body {
+    @apply bg-background text-foreground;
+    }
+  html {
+    @apply font-sans;
+    }
+}
\ No newline at end of file
diff --git a/packages/web/src/styles.css b/packages/web/src/styles.css
deleted file mode 100644
index f1d8c73..0000000
--- a/packages/web/src/styles.css
+++ /dev/null
@@ -1 +0,0 @@
-@import "tailwindcss";
diff --git a/packages/web/tsconfig.json b/packages/web/tsconfig.json
index 2cf299c..8659bfa 100644
--- a/packages/web/tsconfig.json
+++ b/packages/web/tsconfig.json
@@ -3,7 +3,9 @@
   "compilerOptions": {
     "lib": ["ES2023", "DOM", "DOM.Iterable"],
     "types": ["vite/client"],
-    "jsx": "react-jsx"
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "paths": { "@/*": ["./src/*"] }
   },
   "include": ["src", "vite.config.ts"]
 }
diff --git a/packages/web/vite.config.ts b/packages/web/vite.config.ts
index a0346ba..4ab13df 100644
--- a/packages/web/vite.config.ts
+++ b/packages/web/vite.config.ts
@@ -1,11 +1,21 @@
+import { fileURLToPath } from 'node:url';
 import tailwindcss from '@tailwindcss/vite';
+import { tanstackRouter } from '@tanstack/router-plugin/vite';
 import react from '@vitejs/plugin-react';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
   // The daemon serves the built console under /ui — assets must resolve there.
   base: '/ui/',
-  plugins: [react(), tailwindcss()],
+  plugins: [
+    // Must come before react(): it generates routeTree.gen.ts from routes/.
+    tanstackRouter({ target: 'react', autoCodeSplitting: true }),
+    react(),
+    tailwindcss(),
+  ],
+  resolve: {
+    alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
+  },
   server: {
     // Dev mode: Vite owns /ui, the daemon (fake executor is fine) owns the
     // API — same paths the browser uses in production, so no API base knob.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2fbfec5..d4e7df7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -116,18 +116,72 @@ importers:
 
   packages/web:
     dependencies:
+      '@base-ui/react':
+        specifier: ^1.6.0
+        version: 1.6.0(@date-fns/tz@1.5.0)(@types/react@19.2.17)(date-fns@4.4.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@fontsource-variable/inter':
+        specifier: ^5.2.8
+        version: 5.2.8
+      '@hugeicons/core-free-icons':
+        specifier: ^4.2.2
+        version: 4.2.2
+      '@hugeicons/react':
+        specifier: ^1.1.9
+        version: 1.1.9(react@19.2.7)
+      '@shadcn/react':
+        specifier: ^0.2.1
+        version: 0.2.1(@types/react@19.2.17)(react@19.2.7)
       '@tanstack/react-query':
         specifier: ^5.101.2
         version: 5.101.2(react@19.2.7)
       '@tanstack/react-router':
         specifier: ^1.170.17
         version: 1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      class-variance-authority:
+        specifier: ^0.7.1
+        version: 0.7.1
+      clsx:
+        specifier: ^2.1.1
+        version: 2.1.1
+      cmdk:
+        specifier: ^1.1.1
+        version: 1.1.1(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      date-fns:
+        specifier: ^4.4.0
+        version: 4.4.0
+      embla-carousel-react:
+        specifier: ^8.6.0
+        version: 8.6.0(react@19.2.7)
+      input-otp:
+        specifier: ^1.4.2
+        version: 1.4.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      next-themes:
+        specifier: ^0.4.6
+        version: 0.4.6(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       react:
         specifier: ^19.2.7
         version: 19.2.7
+      react-day-picker:
+        specifier: ^10.0.1
+        version: 10.0.1(@types/react@19.2.17)(react@19.2.7)
       react-dom:
         specifier: ^19.2.7
         version: 19.2.7(react@19.2.7)
+      react-resizable-panels:
+        specifier: ^4.12.1
+        version: 4.12.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      recharts:
+        specifier: 3.8.0
+        version: 3.8.0(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react-is@19.2.7)(react@19.2.7)(redux@5.0.1)
+      sonner:
+        specifier: ^2.0.7
+        version: 2.0.7(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      tailwind-merge:
+        specifier: ^3.6.0
+        version: 3.6.0
+      tw-animate-css:
+        specifier: ^1.4.0
+        version: 1.4.0
     devDependencies:
       '@dormice/shared':
         specifier: workspace:*
@@ -135,6 +189,9 @@ importers:
       '@tailwindcss/vite':
         specifier: ^4.3.2
         version: 4.3.2(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
+      '@tanstack/router-plugin':
+        specifier: ^1.168.19
+        version: 1.168.19(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(esbuild@0.28.1)(rolldown@1.1.4)(rollup@4.62.2)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
       '@types/react':
         specifier: ^19.2.17
         version: 19.2.17
@@ -144,6 +201,9 @@ importers:
       '@vitejs/plugin-react':
         specifier: ^6.0.3
         version: 6.0.3(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
+      shadcn:
+        specifier: ^4.13.0
+        version: 4.13.0(typescript@6.0.3)
       tailwindcss:
         specifier: ^4.3.2
         version: 4.3.2
@@ -153,9 +213,169 @@ importers:
 
 packages:
 
+  '@babel/code-frame@7.29.7':
+    resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/compat-data@7.29.7':
+    resolution: {integrity: sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/core@7.29.7':
+    resolution: {integrity: sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/generator@7.29.7':
+    resolution: {integrity: sha512-DkXD5OJQaAQIdZ1bt3UZdEnHAn9Imd3IVBdX03UFe+ony9Ojw5pzr9YVKGDY1jt+Gcn/FnGkNf8r+Vj5NOJWtQ==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-annotate-as-pure@7.29.7':
+    resolution: {integrity: sha512-OoK6239jHPuSQOoS0kfTVKn0b/rVTk0seKq4Gd2UMLtmOVLjDC0ki3e+c90Trqv2gMfvJFqkiljrr568+qddiw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-compilation-targets@7.29.7':
+    resolution: {integrity: sha512-wem6WaBj4NaVYVdNhLPPVacES6ZJ+KBBfSkTMD3YZxbP3rm3Di85tJU5ljaUNhaOynt+Aj0xruhYuzQBt8n71g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-create-class-features-plugin@7.29.7':
+    resolution: {integrity: sha512-IY3ZD9Tmooqr3TUhc3DUWxiuo8xx1DWLhd5M7hQ+ZWJamqM2BbalrBJb2MisSLoYorOj75U03qULCxQTY9r3hg==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-globals@7.29.7':
+    resolution: {integrity: sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-member-expression-to-functions@7.29.7':
+    resolution: {integrity: sha512-j+7JYmk1JYDtACIGj0QJqqWZjoUpMoEikQGADMaHgCMCSDqd2+P32rfcibUNrGOMWrlzK1WJBdxrB3JJQZwWtg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-imports@7.29.7':
+    resolution: {integrity: sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-transforms@7.29.7':
+    resolution: {integrity: sha512-UPUVSyXbOh627KiCIGQSgwWzGeBKLkaJ9PJEdrngIwMSzxLR4jS4+f1f1jb7VzBbg8nFLaYotvVPFCTqdrmTAg==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-optimise-call-expression@7.29.7':
+    resolution: {integrity: sha512-+kmGVjcT9RGYzoDwdwEqEvGgKe3BYq+O1iGzjFubaNgZHwYHP6lsF2Yghf4kEuv9BV7tYDZ913aBW9am6YKong==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-plugin-utils@7.29.7':
+    resolution: {integrity: sha512-G7sHYigPY17oO5SYWnfD/0MTBwVR781S/JI643e/JhUYgVgWE/61SoW3NH9KWUKyKq5LVh3npif99Wkt6j86Jw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-replace-supers@7.29.7':
+    resolution: {integrity: sha512-atfGXWSeCiF4DnKZIfmJfQRkSw9b9gNNXR1kqKjbhG4pGYCOnkp8OcTB8E3NXjBu8NpheSnOeNKz8KT7UNFTmQ==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-skip-transparent-expression-wrappers@7.29.7':
+    resolution: {integrity: sha512-brcMGQaVzIeUb+6/bs1Av0f8YuNNjKY2JyvfRCsFuFsdKccEQ5Ges2y74D74NZ1Rz8lKJ9ksJkfqwQFJ/iNEyQ==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-string-parser@7.29.7':
+    resolution: {integrity: sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-identifier@7.29.7':
+    resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-option@7.29.7':
+    resolution: {integrity: sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helpers@7.29.7':
+    resolution: {integrity: sha512-1k2lAGRMfHTcwuNYcCNUmaUffmQv8KWMfh2iJUUeRlwlwH4FdNG7mfPI10NPfLHJFThE4Tyr4mv7kTNZOiPuBg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/parser@7.29.7':
+    resolution: {integrity: sha512-hnORnjP/1P/zFEndoeX+n+t1RwWRJiJpM/jO7FW32Kn9r5+sJB2JWOdYo4L6k78j15eCwY3Gm/7364B1EMwtNg==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  '@babel/plugin-syntax-jsx@7.29.7':
+    resolution: {integrity: sha512-TSu8+mHCoEaaCDEZ0I3+6mvTBYR4PCxQwf2z9/r5Tbztv6NaLR3B9thGTTxX2WGuGHJqRiAbKPeGTJ5XWXVg6A==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-syntax-typescript@7.29.7':
+    resolution: {integrity: sha512-ngr+82Sh0xMz25TPCZi+nC2iTzjfCdWS2ONXTp/PtSCHCgaCNBpdMqgvJ2ccdLlClVZ7sisIgB914j/JFe+RZA==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-modules-commonjs@7.29.7':
+    resolution: {integrity: sha512-j0vCldybPC5b5dwCQOJ21uKtHzt7hxLygJTg9eF1ScfaikEDNfzn94XoW5Fi+seBR0nCyL23xaBFFkq7dTM8XQ==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-typescript@7.29.7':
+    resolution: {integrity: sha512-jK52h8LaLc7JarhQV2ofeFMts4H7vnOXnqZNA6fYglBTZewRBE51KWt3BUltW1P+KoPsYkHoJeXePuz4zo2LMw==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/preset-typescript@7.29.7':
+    resolution: {integrity: sha512-/Foi8vKY2EVbed/1eZx0gJEEwHAIxogrySI7rULcRIvhZzbvoE/b5qG5Ghc0WKAFKOHA9SD1x7RsFlOYdutIiQ==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/runtime@7.29.7':
+    resolution: {integrity: sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/template@7.29.7':
+    resolution: {integrity: sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/traverse@7.29.7':
+    resolution: {integrity: sha512-EhlfNQtZ+NK22w5BM61ciuiq1m58ed33Wr1Xan//ZRTy6hgjnwyCffRYwzsGXdASJSUJ1guZILsErh1eQcl+zw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/types@7.29.7':
+    resolution: {integrity: sha512-4zBIxpPzowiZpusoFkyGVwakdRJUyuH5PxQ/PrqghfdFWWasvnCdPfQXHrenDai+gyLARulZjZowCOj6fjT4pA==}
+    engines: {node: '>=6.9.0'}
+
   '@balena/dockerignore@1.0.2':
     resolution: {integrity: sha512-wMue2Sy4GAVTk6Ic4tJVcnfdau+gx2EnG7S+uAEe+TWJFqE4YoWN4/H8MSLj4eYJKxGg26lZwboEniNiNwZQ6Q==}
 
+  '@base-ui/react@1.6.0':
+    resolution: {integrity: sha512-/jzjTWJYXhRFO45Bev9lc3cHbmjzCMpUqbMZ2AgKy/z25mY9B6shGSNcXcjQar9n5doM0KYW1W8fcFv2jZBuMw==}
+    engines: {node: '>=14.0.0'}
+    peerDependencies:
+      '@date-fns/tz': ^1.2.0
+      '@types/react': ^17 || ^18 || ^19
+      date-fns: ^4.0.0
+      react: ^17 || ^18 || ^19
+      react-dom: ^17 || ^18 || ^19
+    peerDependenciesMeta:
+      '@date-fns/tz':
+        optional: true
+      '@types/react':
+        optional: true
+      date-fns:
+        optional: true
+
+  '@base-ui/utils@0.3.1':
+    resolution: {integrity: sha512-gFFiltORVmW/N6IILTGxizP3PBpVpysqML1ALY5Vk0mH+7faVkCknOU31goYHN5Aoek2dkjxva1XOD2Ce9WuIg==}
+    peerDependencies:
+      '@types/react': ^17 || ^18 || ^19
+      react: ^17 || ^18 || ^19
+      react-dom: ^17 || ^18 || ^19
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
   '@biomejs/biome@2.5.2':
     resolution: {integrity: sha512-VQ3RCqr7JmDIX+w6stWYl+g/3bYofN3q2wDBHUKKc/c7i5QWrFKFBZYCYPWTE6agsUPMIZZe6/CMmVUfUAhkKA==}
     engines: {node: '>=14.21.3'}
@@ -227,6 +447,16 @@ packages:
     peerDependencies:
       '@bufbuild/protobuf': ^2.2.0
 
+  '@date-fns/tz@1.5.0':
+    resolution: {integrity: sha512-lwYN/vDPeNRULcepoE/LO2Pgx+7/RV+S9ARfbc9lr2DtGkOD7pAiruHvbR1RX3Qyf6ja47EWJDMsNK5vK08DJg==}
+
+  '@dotenvx/dotenvx@1.75.1':
+    resolution: {integrity: sha512-/BITOC9dmS/edY2zQwZNicQ059O6RKabtQfyEafV0nGtfYRNHYy1DIPiYVcov40+tob9hfmBnbR963dS+EQ1DQ==}
+    hasBin: true
+
+  '@dotenvx/primitives@0.8.0':
+    resolution: {integrity: sha512-VYJy0uhFm9zTJ1TxBaW/pA8bjbOM/OttaNMwZ1RHG4JKyRG7DhSdiqD1ipQoAyoD22olUtxbP78W9xY3Wd11bg==}
+
   '@drizzle-team/brocli@0.10.2':
     resolution: {integrity: sha512-z33Il7l5dKjUgGULTqBsQBQwckHh5AbIuxhdsIxDDiZAzBOrZO6q9ogcWC65kU382AfynTfgNumVcNIjuIua6w==}
 
@@ -889,6 +1119,24 @@ packages:
   '@fastify/swagger@9.7.0':
     resolution: {integrity: sha512-Vp1SC1GC2Hrkd3faFILv86BzUNyFz5N4/xdExqtCgkGASOzn/x+eMe4qXIGq7cdT6wif/P/oa6r1Ruqx19paZA==}
 
+  '@floating-ui/core@1.7.5':
+    resolution: {integrity: sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==}
+
+  '@floating-ui/dom@1.7.6':
+    resolution: {integrity: sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==}
+
+  '@floating-ui/react-dom@2.1.8':
+    resolution: {integrity: sha512-cC52bHwM/n/CxS87FH0yWdngEZrjdtLW/qVruo68qg+prK7ZQ4YGdut2GyDVpoGeAYe/h899rVeOVm6Oi40k2A==}
+    peerDependencies:
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
+
+  '@floating-ui/utils@0.2.11':
+    resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
+
+  '@fontsource-variable/inter@5.2.8':
+    resolution: {integrity: sha512-kOfP2D+ykbcX/P3IFnokOhVRNoTozo5/JxhAIVYLpea/UBmCQ/YWPBfWIDuBImXX/15KH+eKh4xpEUyS2sQQGQ==}
+
   '@grpc/grpc-js@1.14.4':
     resolution: {integrity: sha512-k9Dj3DV/itK9D06Y8f190Qgop7/Ui+D0njFV3LHMPwPT75DpXLQohE9Wmz0QElrJnzsjB7KPWiKJbOl7IPDArQ==}
     engines: {node: '>=12.10.0'}
@@ -903,6 +1151,20 @@ packages:
     engines: {node: '>=6'}
     hasBin: true
 
+  '@hono/node-server@1.19.14':
+    resolution: {integrity: sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==}
+    engines: {node: '>=18.14.1'}
+    peerDependencies:
+      hono: ^4
+
+  '@hugeicons/core-free-icons@4.2.2':
+    resolution: {integrity: sha512-fjQW3p6cwoJmwK3oCnV8Z3PC5sHihDvr2jkAHax8cxqp62GaV/D7B/Rnao+JwicW8fmLZUQ6QrzWfoyMFOEQlQ==}
+
+  '@hugeicons/react@1.1.9':
+    resolution: {integrity: sha512-O+lWSWjbijoAvMCxn4K2bQWCGN5+mP1y5j+X99j23mXMj+s0X25fs71T6t9YJLaBodwmZdaewD27dzS/PiboQw==}
+    peerDependencies:
+      react: '>=16.0.0'
+
   '@isaacs/cliui@9.0.0':
     resolution: {integrity: sha512-AokJm4tuBHillT+FpMtxQ60n8ObyXBatq7jD2/JA9dxbDDokKQm8KMht5ibGzLVU9IJDIKK4TPKgMHEYMn3lMg==}
     engines: {node: '>=18'}
@@ -934,12 +1196,34 @@ packages:
     resolution: {integrity: sha512-9I2Zn6+NJLfaGoz9jN3lpwDgAYvfGeNYdbAIjJOqzs4Tpc+VU3Jqq4IofSUBKajiDS8k9fZIg18/z13mpk1bsA==}
     engines: {node: '>=8'}
 
+  '@modelcontextprotocol/sdk@1.29.0':
+    resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@cfworker/json-schema': ^4.1.1
+      zod: ^3.25 || ^4.0
+    peerDependenciesMeta:
+      '@cfworker/json-schema':
+        optional: true
+
   '@napi-rs/wasm-runtime@1.1.6':
     resolution: {integrity: sha512-ZLv/JdUfkvOy9eCnnBaGfiO+XimbjebAeO+MRQqD/B+FR1tnRN0tpKSJHRbE8sFfS6aqsXZ67TQjfwfsxULVbg==}
     peerDependencies:
       '@emnapi/core': ^1.7.1
       '@emnapi/runtime': ^1.7.1
 
+  '@nodelib/fs.scandir@2.1.5':
+    resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.stat@2.0.5':
+    resolution: {integrity: sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.walk@1.2.8':
+    resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
+    engines: {node: '>= 8'}
+
   '@oxc-project/types@0.138.0':
     resolution: {integrity: sha512-1a7ZKmrRTCoN1XMZ4L0PyyqrMnrNlLyPuOkdSX2MZg7IiIGRUyurNhAm73ptDOraoBcIordsIGKNPKUzy3ZmfA==}
 
@@ -973,6 +1257,179 @@ packages:
   '@protobufjs/utf8@1.1.2':
     resolution: {integrity: sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==}
 
+  '@radix-ui/primitive@1.1.5':
+    resolution: {integrity: sha512-d86WIWFYNtGA0H/d8exstrTRTp7eWJYlYJbtNofxr/3ljupZYn6EFDG/Qgu/0Kc8v7yMUxySagqJsL1+PdYjWg==}
+
+  '@radix-ui/react-compose-refs@1.1.3':
+    resolution: {integrity: sha512-rYOP8OMnuuPMQF1uhPVlGNcCDlkokKqGFE3JcxFViIkAXP7EvFWUliJAstrapypaBLJNHbZL6jGhbVDGTwmVhA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-context@1.2.0':
+    resolution: {integrity: sha512-fOE+JtN9rygNZkCnHRBEP0TAvLldlhyOxMsbwFvTP4nAs+nBmfnna+o/Zski2wkmY1YMrFC0aSzsHoLY47iLrg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-dialog@1.1.19':
+    resolution: {integrity: sha512-+HhbN2+YtkRgVirjZ2afMeutQRuGOrdkWR5+EFC58SJojGmtyNQwYzgi6tHBpOxvFHefMtPeHdgtjz0BOGxFQg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-dismissable-layer@1.1.15':
+    resolution: {integrity: sha512-b0XaRlzn2QKuo10XyNgi2DAJDf5XC9d1nD3FJcuvCjbR7+4Ad28zmZsLsqx+hvDEzMnRuZaZxZm9gYObV6RmRA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-focus-guards@1.1.4':
+    resolution: {integrity: sha512-cot/aB/mOm0IYVYTTmQcEEK1M48lZWi8FlYe5nDPQQ8NYZUlXEFgncJ9p2Kzer3RKSrY7cTTpEMLZKNo9QoP5Q==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-focus-scope@1.1.12':
+    resolution: {integrity: sha512-jjk/lqTeNL0azUx5ZYzVrl4NgaDIrdzTNE4mABV9yBFI7FQqN7pIgzV1bTleUezP2QiTGA1BFTqY8MegDgWX9A==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-id@1.1.2':
+    resolution: {integrity: sha512-orBC88futVpqCmhX1p4cvquNHsELQ+w+vBJnuj3ftETI5bJb0bZn3Tqu3SWN2IOcPycTnMGnhwoermvISt72sA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-portal@1.1.13':
+    resolution: {integrity: sha512-z3oXfmaHLJTF1wktbjgD6cn9jiEbq3WSondB10LIuIt2m2Ym4iJlrW04/euMwENDdWDdE7z+OuY7Qyp1YpRSwA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-presence@1.1.7':
+    resolution: {integrity: sha512-zBZ4QM5XG3JRanDmqXYf3MD6th4AFXFmgU6KNMFzUaV6F3uw9I5/zjMUvFriSEn5ewo1nxuibvyxJdmLlDcslA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-primitive@2.1.7':
+    resolution: {integrity: sha512-bC3NiwsprbxKjuon9l7X6BUTw7FPVzEYaL92MPEY5SCd/9hUTPXVFtVwRix7778wtRsVao+zE062gL79FZleeQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-slot@1.3.0':
+    resolution: {integrity: sha512-MojKku4U/miO8Av4Dkb+ctMAQx7JmY96LmtDQlAarCRtd7rN52QCSzBF+XAvr5S6coSVj9HEPBgHAHKEJVk/WA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-callback-ref@1.1.2':
+    resolution: {integrity: sha512-xCso9j1/u8sEgP1RNHjFrXJLApL8LiqOkI1R4ywuN00rxWdYg4oQXuwKLS3i0j5NWLromUD27/4nlxj2UFVvIw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-controllable-state@1.2.3':
+    resolution: {integrity: sha512-PLzC90MS+ReootmjC597dvopoelpZ8Q61HJkDXZSExitIq7PL55vHNnesAHwguHK0aPfBnpdNzQtv1uliaqQrA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-effect-event@0.0.3':
+    resolution: {integrity: sha512-6c8ZqvPTWILEKnyVkP53EGRCcpnJiKTC21sS/6R1GF5xKyHJJWQEPfkqlcgUkdRQivd6tb23abUwe4ngWmY0JA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-layout-effect@1.1.2':
+    resolution: {integrity: sha512-jrBWOxZITuGcnjRCM2t2U5ZPkCLxD+Ym6DjfssS5haTj2iiak/DOb64JeN6OdLfLgptb6/e2kKR+ZuTrGoZTPA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@reduxjs/toolkit@2.12.0':
+    resolution: {integrity: sha512-KiT+RzZbp6mQET+Mg+h2c97+9j1sNflUxQkIHI7Yuzf6Peu+OYpmkn6nbHWmLLWj+1ZODUJFwGZ7gx3L9R9EOw==}
+    peerDependencies:
+      react: ^16.9.0 || ^17.0.0 || ^18 || ^19
+      react-redux: ^7.2.1 || ^8.1.3 || ^9.0.0
+    peerDependenciesMeta:
+      react:
+        optional: true
+      react-redux:
+        optional: true
+
   '@rolldown/binding-android-arm64@1.1.4':
     resolution: {integrity: sha512-EZLpf/8y7GXkkra90ML47kzik/GMP3EMcE9bPyHmRfxLC6z9+aW5A8poCsoxjrT5GfEcNAAvWwUHjvP1pUQkfw==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -1212,6 +1669,17 @@ packages:
   '@sec-ant/readable-stream@0.4.1':
     resolution: {integrity: sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==}
 
+  '@shadcn/react@0.2.1':
+    resolution: {integrity: sha512-5krgi3dRMKb5jH6a+qPzVJUy/54s0kKE4Rw4LjDfLqOdVQTWKUgxWf1kW8r912I0jX/Lzxqc+pgjkjWxUIK5BQ==}
+    peerDependencies:
+      '@types/react': '>=19'
+      react: '>=19'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      react:
+        optional: true
+
   '@sindresorhus/merge-streams@4.0.0':
     resolution: {integrity: sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==}
     engines: {node: '>=18'}
@@ -1219,6 +1687,9 @@ packages:
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
+  '@standard-schema/utils@0.3.0':
+    resolution: {integrity: sha512-e7Mew686owMaPJVNNLs55PUvgz371nKgwsc4vxE49zsODpJEnxgxRo2y/OKrqueavXgZNMDVj3DdHFlaSAeU8g==}
+
   '@tailwindcss/node@4.3.2':
     resolution: {integrity: sha512-yWP/sqEcBLaD8JuA6zNwxoYKr75qxTioYwlRwekj5Jr/I5GXnoJfjetH/psLUIv74cYTH2lBUEzBkinthoYcBg==}
 
@@ -1342,9 +1813,45 @@ packages:
     resolution: {integrity: sha512-Mo3hwx0qB0cJsVYGDjG0+Ouf7VV74h/vsoDMGztdlyzDanp4gBA2s7IVvm6hFrmQM6GpD9F0Z7SqD7OldfLE7g==}
     engines: {node: '>=20.19'}
 
+  '@tanstack/router-generator@1.167.18':
+    resolution: {integrity: sha512-kFvM4caRds9Q3EXg64bZubJ6rbDxyV0YDSBSGvOGzmKspQPdz5Xrh0uj5T1Ov8avUUg+c761u04VQAaEzSBXRw==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/router-plugin@1.168.19':
+    resolution: {integrity: sha512-aFglwLc+bbPTgZlkXn3PvOwpjJAfgUyPGSuql4MP3XrqTTh6WkBiy2RYb6oaG5h0s7EKwivEuq85K3Y4V0Mt1g==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      '@rsbuild/core': '>=1.0.2 || ^2.0.0'
+      '@tanstack/react-router': ^1.170.17
+      vite: '>=5.0.0 || >=6.0.0 || >=7.0.0 || >=8.0.0'
+      vite-plugin-solid: ^2.11.10 || ^3.0.0-0
+      webpack: '>=5.92.0'
+    peerDependenciesMeta:
+      '@rsbuild/core':
+        optional: true
+      '@tanstack/react-router':
+        optional: true
+      vite:
+        optional: true
+      vite-plugin-solid:
+        optional: true
+      webpack:
+        optional: true
+
+  '@tanstack/router-utils@1.162.2':
+    resolution: {integrity: sha512-hTWqJtqIFFdvuCl8WXNyrodp2L9zo2G37xKRrcVmVRWpAB2h+U1LuRAfS4tsFTiWOIoE/B+WDVFB8JpoEdw6jQ==}
+    engines: {node: '>=20.19'}
+
   '@tanstack/store@0.9.3':
     resolution: {integrity: sha512-8reSzl/qGWGGVKhBoxXPMWzATSbZLZFWhwBAFO9NAyp0TxzfBP0mIrGb8CP8KrQTmvzXlR/vFPPUrHTLBGyFyw==}
 
+  '@tanstack/virtual-file-routes@1.162.0':
+    resolution: {integrity: sha512-uhOeFyxLcU41HzvrxsGpiWdcMbScY1EDgbZ5K7DVRMYInbLYWAC0EA/kx9wXAoSM8q82bUG2hRl8+EAjE6XAbA==}
+    engines: {node: '>=20.19'}
+
+  '@ts-morph/common@0.27.0':
+    resolution: {integrity: sha512-Wf29UqxWDpc+i61k3oIOzcUfQt79PIT9y/MWfAGlrkjg6lBC1hwDECLXPVJAhWjiGbfBCxZd65F/LIZF3+jeJQ==}
+
   '@tybys/wasm-util@0.10.3':
     resolution: {integrity: sha512-F3fo1MYrRJYL3zER0OUOmkutjr1Vp23m7OsSgp7nq4SP6OqX6C/56XFIPAl5bt3zaBRjmW7SGz3u/6LwFpYcOg==}
 
@@ -1354,6 +1861,33 @@ packages:
   '@types/chai@5.2.3':
     resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
 
+  '@types/d3-array@3.2.2':
+    resolution: {integrity: sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw==}
+
+  '@types/d3-color@3.1.3':
+    resolution: {integrity: sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==}
+
+  '@types/d3-ease@3.0.2':
+    resolution: {integrity: sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA==}
+
+  '@types/d3-interpolate@3.0.4':
+    resolution: {integrity: sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==}
+
+  '@types/d3-path@3.1.1':
+    resolution: {integrity: sha512-VMZBYyQvbGmWyWVea0EHs/BwLgxc+MKi1zLDCONksozI4YJMcTt8ZEuIR4Sb1MMTE8MMW49v0IwI5+b7RmfWlg==}
+
+  '@types/d3-scale@4.0.9':
+    resolution: {integrity: sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==}
+
+  '@types/d3-shape@3.1.8':
+    resolution: {integrity: sha512-lae0iWfcDeR7qt7rA88BNiqdvPS5pFVPpo5OfjElwNaT2yyekbM0C9vK+yqBqEmHr6lDkRnYNoTBYlAgJa7a4w==}
+
+  '@types/d3-time@3.0.4':
+    resolution: {integrity: sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g==}
+
+  '@types/d3-timer@3.0.2':
+    resolution: {integrity: sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==}
+
   '@types/deep-eql@4.0.2':
     resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
 
@@ -1383,6 +1917,12 @@ packages:
   '@types/ssh2@1.15.5':
     resolution: {integrity: sha512-N1ASjp/nXH3ovBHddRJpli4ozpk6UdDYIX4RJWFa9L1YKnzdhTlVmiGHm4DZnj/jLbqZpes4aeR30EFGQtvhQQ==}
 
+  '@types/use-sync-external-store@0.0.6':
+    resolution: {integrity: sha512-zFDAD+tlpf2r4asuHEj0XH6pY6i0g5NeAHPn+15wk3BV6JA69eERFXC1gyGThDkVa1zCyKr5jox1+2LbV/AMLg==}
+
+  '@types/validate-npm-package-name@4.0.2':
+    resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}
+
   '@vitejs/plugin-react@6.0.3':
     resolution: {integrity: sha512-vmFvco5/QuC2f9Oj+wTk0+9XeDFkHxSamwZKYc7MxYwKICfvUvlMhqKI0VuICPltGqh1neqBKDvO4kes1ya8vg==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -1428,11 +1968,23 @@ packages:
   abstract-logging@2.0.1:
     resolution: {integrity: sha512-2BjRTZxTPvheOvGbBslFSYOUkr+SjPtOnrLP33f+VIWLzezQpZcqVg7ja3L4dBXmzzgwT+a029jRx5PCi3JuiA==}
 
+  accepts@2.0.0:
+    resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
+    engines: {node: '>= 0.6'}
+
   acorn@8.17.0:
     resolution: {integrity: sha512-xRQbDb9BnwDafYNn6Vwl839DYVjqXYb1XVGtWAZ1kcDc6iwAL4hg3B1dZlRiuENFeO2H53gFG3in621AdERVAg==}
     engines: {node: '>=0.4.0'}
     hasBin: true
 
+  ajv-formats@2.1.1:
+    resolution: {integrity: sha512-Wx0Kx52hxE7C18hkMEggYlEifqWZtYaRgouJor+WMdPnQyEK13vgEWyVNup7SoeeoLMsr4kf5h6dOW11I15MUA==}
+    peerDependencies:
+      ajv: ^8.0.0
+    peerDependenciesMeta:
+      ajv:
+        optional: true
+
   ajv-formats@3.0.1:
     resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==}
     peerDependencies:
@@ -1444,17 +1996,36 @@ packages:
   ajv@8.20.0:
     resolution: {integrity: sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==}
 
+  ansi-colors@4.1.3:
+    resolution: {integrity: sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==}
+    engines: {node: '>=6'}
+
   ansi-regex@5.0.1:
     resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
     engines: {node: '>=8'}
 
+  ansi-regex@6.2.2:
+    resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
+    engines: {node: '>=12'}
+
   ansi-styles@4.3.0:
     resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
     engines: {node: '>=8'}
 
+  ansis@4.3.1:
+    resolution: {integrity: sha512-BJ8/l4R5LRE7hW9WdSuGYrLSHi2ynxeFpDFbH0K/CgNeY/tyhk+vO6TYxXC5r5CpUhNVX310xzPsN/H9lCdfOA==}
+    engines: {node: '>=14'}
+
   any-promise@1.3.0:
     resolution: {integrity: sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==}
 
+  argparse@2.0.1:
+    resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+
+  aria-hidden@1.2.6:
+    resolution: {integrity: sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==}
+    engines: {node: '>=10'}
+
   asn1@0.2.6:
     resolution: {integrity: sha512-ix/FxPn0MDjeyJ7i/yoHGFt/EX6LyNbxSEhPPXODPL+KB0VPk86UYfL0lMdy+KCnv+fmvIzySwaK5COwqVbWTQ==}
 
@@ -1462,13 +2033,24 @@ packages:
     resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
     engines: {node: '>=12'}
 
+  ast-types@0.16.1:
+    resolution: {integrity: sha512-6t10qk83GOG8p0vKmaCr8eiilZwO171AvbROMtvvNiwrTly62t+7XkA8RdIIVbpMhCASAsxgAzdRSwh6nw/5Dg==}
+    engines: {node: '>=4'}
+
   atomic-sleep@1.0.0:
     resolution: {integrity: sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ==}
     engines: {node: '>=8.0.0'}
 
+  atomically@1.7.0:
+    resolution: {integrity: sha512-Xcz9l0z7y9yQ9rdDaxlmaI4uJHf/T8g9hOEzJcsEqX2SjCj4J20uK7+ldkDHMbpJDK76wF7xEIgxc/vSlsfw5w==}
+    engines: {node: '>=10.12.0'}
+
   avvio@9.2.0:
     resolution: {integrity: sha512-2t/sy01ArdHHE0vRH5Hsay+RtCZt3dLPji7W7/MMOCEgze5b7SNDC4j5H6FnVgPkI1MTNFGzHdHrVXDDl7QSSQ==}
 
+  babel-dead-code-elimination@1.0.12:
+    resolution: {integrity: sha512-GERT7L2TiYcYDtYk1IpD+ASAYXjKbLTDPhBtYj7X1NuRMDTMtAx9kyBenub1Ev41lo91OHCKdmP+egTDmfQ7Ig==}
+
   balanced-match@4.0.4:
     resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
     engines: {node: 18 || 20 || >=22}
@@ -1476,6 +2058,11 @@ packages:
   base64-js@1.5.1:
     resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
 
+  baseline-browser-mapping@2.10.42:
+    resolution: {integrity: sha512-c/jurFrDLyui7o1J86yLkRu4LMsTYcBohveus7/I2Hzdn9KIP2bdJPTue/lR1KH46enoPbD77GKeSYNdyPoD3Q==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
   bcrypt-pbkdf@1.0.2:
     resolution: {integrity: sha512-qeFIXtP4MSoi6NLqO12WfqARWWuCKi2Rn/9hJLEmtB5yTNr9DqFWkJRCf2qShWzPeAMRnOgCrq0sg/KLv5ES9w==}
 
@@ -1489,10 +2076,23 @@ packages:
   bl@4.1.0:
     resolution: {integrity: sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==}
 
+  body-parser@2.3.0:
+    resolution: {integrity: sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==}
+    engines: {node: '>=18'}
+
   brace-expansion@5.0.7:
     resolution: {integrity: sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA==}
     engines: {node: 18 || 20 || >=22}
 
+  braces@3.0.3:
+    resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==}
+    engines: {node: '>=8'}
+
+  browserslist@4.28.5:
+    resolution: {integrity: sha512-Cu2E6QejHWzuDMTkuwgpABFgDfZrXLQq5V13YOACZx4mFAG4IwGTbTfHPMr4WtxlHoXSM8FIuRwYYCz5XiabaQ==}
+    engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
+    hasBin: true
+
   buffer-from@1.1.2:
     resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==}
 
@@ -1503,16 +2103,39 @@ packages:
     resolution: {integrity: sha512-lHblz4ahamxpTmnsk+MNTRWsjYKv965MwOrSJyeD588rR3Jcu7swE+0wN5F+PbL5cjgu/9ObkhfzEPuofEMwLA==}
     engines: {node: '>=10.0.0'}
 
+  bundle-name@4.1.0:
+    resolution: {integrity: sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==}
+    engines: {node: '>=18'}
+
   bundle-require@5.1.0:
     resolution: {integrity: sha512-3WrrOuZiyaaZPWiEt4G3+IffISVC9HYlWueJEBWED4ZH4aIAC2PnkdnuRrR94M+w6yGWn4AglWtJtBI8YqvgoA==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
     peerDependencies:
       esbuild: '>=0.18'
 
+  bytes@3.1.2:
+    resolution: {integrity: sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==}
+    engines: {node: '>= 0.8'}
+
   cac@6.7.14:
     resolution: {integrity: sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==}
     engines: {node: '>=8'}
 
+  call-bind-apply-helpers@1.0.2:
+    resolution: {integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==}
+    engines: {node: '>= 0.4'}
+
+  call-bound@1.0.4:
+    resolution: {integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==}
+    engines: {node: '>= 0.4'}
+
+  callsites@3.1.0:
+    resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==}
+    engines: {node: '>=6'}
+
+  caniuse-lite@1.0.30001803:
+    resolution: {integrity: sha512-g/uHREV2ZpK9qMalCsWaxmA6ol+DX8GYhuf3T40RKoP+oL7vhRJh8LNt73PCjpnR6l14FzfPrB5Yux4PKm2meg==}
+
   chai@6.2.2:
     resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
     engines: {node: '>=18'}
@@ -1525,6 +2148,10 @@ packages:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
 
+  chokidar@5.0.0:
+    resolution: {integrity: sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw==}
+    engines: {node: '>= 20.19.0'}
+
   chownr@1.1.4:
     resolution: {integrity: sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==}
 
@@ -1532,17 +2159,45 @@ packages:
     resolution: {integrity: sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==}
     engines: {node: '>=18'}
 
+  class-variance-authority@0.7.1:
+    resolution: {integrity: sha512-Ka+9Trutv7G8M6WT6SeiRWz792K5qEqIGEGzXKhAE6xOWAY6pPH8U+9IY3oCMv6kqTmLsv7Xh/2w2RigkePMsg==}
+
+  cli-cursor@5.0.0:
+    resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
+    engines: {node: '>=18'}
+
+  cli-spinners@2.9.2:
+    resolution: {integrity: sha512-ywqV+5MmyL4E7ybXgKys4DugZbX0FC6LnwrhjuykIjnK9k8OQacQ7axGKnjDXWNhns0xot3bZI5h55H8yo9cJg==}
+    engines: {node: '>=6'}
+
   cliui@8.0.1:
     resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==}
     engines: {node: '>=12'}
 
-  color-convert@2.0.1:
-    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
-    engines: {node: '>=7.0.0'}
+  clsx@2.1.1:
+    resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}
+    engines: {node: '>=6'}
+
+  cmdk@1.1.1:
+    resolution: {integrity: sha512-Vsv7kFaXm+ptHDMZ7izaRsP70GgrW9NBNGswt9OZaVBLlE0SNpDq8eu/VGXyF9r7M0azK3Wy7OlYXsuyYLFzHg==}
+    peerDependencies:
+      react: ^18 || ^19 || ^19.0.0-rc
+      react-dom: ^18 || ^19 || ^19.0.0-rc
+
+  code-block-writer@13.0.3:
+    resolution: {integrity: sha512-Oofo0pq3IKnsFtuHqSF7TqBfr71aeyZDVJ0HpmqB7FBM2qEigL0iPONSCZSO9pE9dZTAxANe5XHG9Uy0YMv8cg==}
+
+  color-convert@2.0.1:
+    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
+    engines: {node: '>=7.0.0'}
 
   color-name@1.1.4:
     resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
 
+  commander@11.1.0:
+    resolution: {integrity: sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==}
+    engines: {node: '>=16'}
+
   commander@14.0.3:
     resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==}
     engines: {node: '>=20'}
@@ -1554,6 +2209,10 @@ packages:
   compare-versions@6.1.1:
     resolution: {integrity: sha512-4hm4VPpIecmlg59CHXnRDnqGplJFrbLG4aFEl5vl6cK1u76ws3LLvX7ikFnTDl5vo39sjWD6AaDPYodJp/NNHg==}
 
+  conf@10.2.0:
+    resolution: {integrity: sha512-8fLl9F04EJqjSqH+QjITQfJF8BrOVaYr1jewVgSRAEWePfxT0sku4w2hrGQ60BC/TNLGQ2pgxNlTbWQmMPFvXg==}
+    engines: {node: '>=12'}
+
   confbox@0.1.8:
     resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==}
 
@@ -1565,16 +2224,45 @@ packages:
     resolution: {integrity: sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==}
     engines: {node: '>=18'}
 
+  content-type@1.0.5:
+    resolution: {integrity: sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==}
+    engines: {node: '>= 0.6'}
+
+  content-type@2.0.0:
+    resolution: {integrity: sha512-j/O/d7GcZCyNl7/hwZAb606rzqkyvaDctLmckbxLzHvFBzTJHuGEdodATcP3yIRoDrLHkIATJuvzbFlp/ki2cQ==}
+    engines: {node: '>=18'}
+
   convert-source-map@2.0.0:
     resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
 
   cookie-es@3.1.1:
     resolution: {integrity: sha512-UaXxwISYJPTr9hwQxMFYZ7kNhSXboMXP+Z3TRX6f1/NyaGPfuNUZOWP1pUEb75B2HjfklIYLVRfWiFZJyC6Npg==}
 
+  cookie-signature@1.2.2:
+    resolution: {integrity: sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==}
+    engines: {node: '>=6.6.0'}
+
+  cookie@0.7.2:
+    resolution: {integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==}
+    engines: {node: '>= 0.6'}
+
   cookie@1.1.1:
     resolution: {integrity: sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==}
     engines: {node: '>=18'}
 
+  cors@2.8.6:
+    resolution: {integrity: sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==}
+    engines: {node: '>= 0.10'}
+
+  cosmiconfig@9.0.2:
+    resolution: {integrity: sha512-gtTZxTDau1wL7Y7zifc2dd8jHSK/k6BTx/2Xp/BpdlAdnlYWFVt7qhJqgwi7637yRwRQ3qL4ZidbB4I8tA5VOg==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      typescript: '>=4.9.5'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
   cpu-features@0.0.10:
     resolution: {integrity: sha512-9IkYqtX3YHPCzoVg1Py+o9057a3i0fp7S530UWokCSaFVTc7CwXPRiOjRjBQQ18ZCNafx78YfnG+HALxtVmOGA==}
     engines: {node: '>=10.0.0'}
@@ -1583,9 +2271,65 @@ packages:
     resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
     engines: {node: '>= 8'}
 
+  cssesc@3.0.0:
+    resolution: {integrity: sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==}
+    engines: {node: '>=4'}
+    hasBin: true
+
   csstype@3.2.3:
     resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
 
+  d3-array@3.2.4:
+    resolution: {integrity: sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==}
+    engines: {node: '>=12'}
+
+  d3-color@3.1.0:
+    resolution: {integrity: sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==}
+    engines: {node: '>=12'}
+
+  d3-ease@3.0.1:
+    resolution: {integrity: sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==}
+    engines: {node: '>=12'}
+
+  d3-format@3.1.2:
+    resolution: {integrity: sha512-AJDdYOdnyRDV5b6ArilzCPPwc1ejkHcoyFarqlPqT7zRYjhavcT3uSrqcMvsgh2CgoPbK3RCwyHaVyxYcP2Arg==}
+    engines: {node: '>=12'}
+
+  d3-interpolate@3.0.1:
+    resolution: {integrity: sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==}
+    engines: {node: '>=12'}
+
+  d3-path@3.1.0:
+    resolution: {integrity: sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==}
+    engines: {node: '>=12'}
+
+  d3-scale@4.0.2:
+    resolution: {integrity: sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==}
+    engines: {node: '>=12'}
+
+  d3-shape@3.2.0:
+    resolution: {integrity: sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==}
+    engines: {node: '>=12'}
+
+  d3-time-format@4.1.0:
+    resolution: {integrity: sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==}
+    engines: {node: '>=12'}
+
+  d3-time@3.1.0:
+    resolution: {integrity: sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==}
+    engines: {node: '>=12'}
+
+  d3-timer@3.0.1:
+    resolution: {integrity: sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==}
+    engines: {node: '>=12'}
+
+  date-fns@4.4.0:
+    resolution: {integrity: sha512-+1UMbeh68lH1SegH83CGWwpb6OHHbpSgr3+s5Eww5M4CAgswBpoWS0AjTOfEJ33HiYKz1hdj/KTFprzXHmq/6w==}
+
+  debounce-fn@4.0.0:
+    resolution: {integrity: sha512-8pYCQiL9Xdcg0UPSD3d+0KMlOjp+KGU5EPwYddgzQ7DATsg4fuUDjQtsYLmWjnk2obnNHgV3vE2Y4jejSOJVBQ==}
+    engines: {node: '>=10'}
+
   debug@4.4.3:
     resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
     engines: {node: '>=6.0'}
@@ -1595,14 +2339,45 @@ packages:
       supports-color:
         optional: true
 
+  decimal.js-light@2.5.1:
+    resolution: {integrity: sha512-qIMFpTMZmny+MMIitAB6D7iVPEorVw6YQRWkvarTkT4tBeSLLiHzcwj6q0MmYSFCiVpiqPJTJEYIrpcPzVEIvg==}
+
   decompress-response@6.0.0:
     resolution: {integrity: sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==}
     engines: {node: '>=10'}
 
+  dedent@1.7.2:
+    resolution: {integrity: sha512-WzMx3mW98SN+zn3hgemf4OzdmyNhhhKz5Ay0pUfQiMQ3e1g+xmTJWp/pKdwKVXhdSkAEGIIzqeuWrL3mV/AXbA==}
+    peerDependencies:
+      babel-plugin-macros: ^3.1.0
+    peerDependenciesMeta:
+      babel-plugin-macros:
+        optional: true
+
   deep-extend@0.6.0:
     resolution: {integrity: sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==}
     engines: {node: '>=4.0.0'}
 
+  deepmerge@4.3.1:
+    resolution: {integrity: sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==}
+    engines: {node: '>=0.10.0'}
+
+  default-browser-id@5.0.1:
+    resolution: {integrity: sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q==}
+    engines: {node: '>=18'}
+
+  default-browser@5.5.0:
+    resolution: {integrity: sha512-H9LMLr5zwIbSxrmvikGuI/5KGhZ8E2zH3stkMgM5LpOWDutGM2JZaj460Udnf1a+946zc7YBgrqEWwbk7zHvGw==}
+    engines: {node: '>=18'}
+
+  define-lazy-prop@2.0.0:
+    resolution: {integrity: sha512-Ds09qNh8yw3khSjiJjiUInaGX9xlqZDY7JVryGxdxV7NPeuqQfplOpQ66yJFZut3jLa5zOwkXw1g9EI2uKh4Og==}
+    engines: {node: '>=8'}
+
+  define-lazy-prop@3.0.0:
+    resolution: {integrity: sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==}
+    engines: {node: '>=12'}
+
   depd@2.0.0:
     resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
     engines: {node: '>= 0.8'}
@@ -1615,6 +2390,13 @@ packages:
     resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
     engines: {node: '>=8'}
 
+  detect-node-es@1.1.0:
+    resolution: {integrity: sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==}
+
+  diff@8.0.4:
+    resolution: {integrity: sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==}
+    engines: {node: '>=0.3.1'}
+
   docker-modem@5.0.7:
     resolution: {integrity: sha512-XJgGhoR/CLpqshm4d3L7rzH6t8NgDFUIIpztYlLHIApeJjMZKYJMz2zxPsYxnejq5h3ELYSw/RBsi3t5h7gNTA==}
     engines: {node: '>= 8.0'}
@@ -1626,6 +2408,14 @@ packages:
     resolution: {integrity: sha512-avsq/xk4YPIrn0CgleX5bjT9Y8IT1p9PxrNQ++RBQ2WEyFfHCTDsT9kmyxz+H/axnjAwg8wJWEIuPGOUuNupiA==}
     engines: {node: '>= 14.17'}
 
+  dot-prop@6.0.1:
+    resolution: {integrity: sha512-tE7ztYzXHIeyvc7N+hR3oi7FIbf/NIjVP9hmAt3yMXzrQ072/fpjGLx2GxNxGxUl5V73MEqYzioOMoVhGMJ5cA==}
+    engines: {node: '>=10'}
+
+  dotenv@17.4.2:
+    resolution: {integrity: sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==}
+    engines: {node: '>=12'}
+
   drizzle-kit@0.31.10:
     resolution: {integrity: sha512-7OZcmQUrdGI+DUNNsKBn1aW8qSoKuTH7d0mYgSP8bAzdFzKoovxEFnoGQp2dVs82EOJeYycqRtciopszwUf8bw==}
     hasBin: true
@@ -1722,13 +2512,43 @@ packages:
       sqlite3:
         optional: true
 
+  dunder-proto@1.0.1:
+    resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
+    engines: {node: '>= 0.4'}
+
   e2b@2.31.0:
     resolution: {integrity: sha512-vXQomb16mOk+ufi3YFfN6eURm6eC0NZGMK49PXibfpsmy0azcvLbQuHxCkhgyAk5z5GVfrEUwc08QKVtt6KNFg==}
     engines: {node: '>=20.18.1'}
 
+  ee-first@1.1.1:
+    resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
+
+  electron-to-chromium@1.5.389:
+    resolution: {integrity: sha512-cEto7aeOqBfU1D+c5py5pE+ooscKE75JifxLBdFUZsqAxRS6y7kebtxAZvICszSl05gPjYHDTjY+lXpyGvpJbg==}
+
+  embla-carousel-react@8.6.0:
+    resolution: {integrity: sha512-0/PjqU7geVmo6F734pmPqpyHqiM99olvyecY7zdweCw+6tKEXnrE90pBiBbMMU8s5tICemzpQ3hi5EpxzGW+JA==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.1 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+
+  embla-carousel-reactive-utils@8.6.0:
+    resolution: {integrity: sha512-fMVUDUEx0/uIEDM0Mz3dHznDhfX+znCCDCeIophYb1QGVM7YThSWX+wz11zlYwWFOr74b4QLGg0hrGPJeG2s4A==}
+    peerDependencies:
+      embla-carousel: 8.6.0
+
+  embla-carousel@8.6.0:
+    resolution: {integrity: sha512-SjWyZBHJPbqxHOzckOfo8lHisEaJWmwd23XppYFYVh10bU66/Pn5tkVkbkCMZVdbUE5eTCI2nD8OyIP4Z+uwkA==}
+
+  emoji-regex@10.6.0:
+    resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==}
+
   emoji-regex@8.0.0:
     resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
 
+  encodeurl@2.0.0:
+    resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
+    engines: {node: '>= 0.8'}
+
   end-of-stream@1.4.5:
     resolution: {integrity: sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==}
 
@@ -1736,9 +2556,35 @@ packages:
     resolution: {integrity: sha512-aNnGCvbJ/RIyWo1IuhNdVjnNF+EjH9wpzpNHt+ci/m9He9LJvUN8wrCcXjp9cWsGNAuvSpVFTx/vraAFQ8qGjQ==}
     engines: {node: '>=10.13.0'}
 
+  enquirer@2.4.1:
+    resolution: {integrity: sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==}
+    engines: {node: '>=8.6'}
+
+  env-paths@2.2.1:
+    resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==}
+    engines: {node: '>=6'}
+
+  error-ex@1.3.4:
+    resolution: {integrity: sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==}
+
+  es-define-property@1.0.1:
+    resolution: {integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==}
+    engines: {node: '>= 0.4'}
+
+  es-errors@1.3.0:
+    resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==}
+    engines: {node: '>= 0.4'}
+
   es-module-lexer@2.3.0:
     resolution: {integrity: sha512-KLdwQm2NvGLDkQDCGvmiQrhkd0JbMzXthwQAUgWjQuQdBLFa3eiBP5arXZyA+f8x+x7OXgud6bq2rxjGtHV2tw==}
 
+  es-object-atoms@1.1.2:
+    resolution: {integrity: sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==}
+    engines: {node: '>= 0.4'}
+
+  es-toolkit@1.49.0:
+    resolution: {integrity: sha512-G5iZ6Pc/FNRY/soKZHC+TxGDD83rHUDXxzaWhGCX44vAv/tMs56WMusnm/KMNK+luUPsgA9U28cGr4RDlSzL2g==}
+
   esbuild@0.18.20:
     resolution: {integrity: sha512-ceqxoedUrcayh7Y7ZX6NdbbDzGROiyVBgC4PriJThBKSVPWnnFHZAkfI1lJT8QFkOwH4qOS2SJkS4wvpGl8BpA==}
     engines: {node: '>=12'}
@@ -1766,9 +2612,33 @@ packages:
   escape-html@1.0.3:
     resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
 
+  esprima@4.0.1:
+    resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==}
+    engines: {node: '>=4'}
+    hasBin: true
+
   estree-walker@3.0.3:
     resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
 
+  etag@1.8.1:
+    resolution: {integrity: sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==}
+    engines: {node: '>= 0.6'}
+
+  eventemitter3@5.0.4:
+    resolution: {integrity: sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==}
+
+  eventsource-parser@3.1.0:
+    resolution: {integrity: sha512-kJezFj9YFAMLeORyi7aCLxLbD5/qWMQnoMVlVPyHIll7lgRJCc3JVln9Vgl9nwQi0YkMnhdGTMNn7CkRRAptMg==}
+    engines: {node: '>=18.0.0'}
+
+  eventsource@3.0.7:
+    resolution: {integrity: sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==}
+    engines: {node: '>=18.0.0'}
+
+  execa@5.1.1:
+    resolution: {integrity: sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg==}
+    engines: {node: '>=10'}
+
   execa@9.6.1:
     resolution: {integrity: sha512-9Be3ZoN4LmYR90tUoVu2te2BsbzHfhJyfEiAVfz7N5/zv+jduIfLrV2xdQXOHbaD6KgpGdO9PRPM1Y4Q9QkPkA==}
     engines: {node: ^18.19.0 || >=20.5.0}
@@ -1781,12 +2651,26 @@ packages:
     resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
     engines: {node: '>=12.0.0'}
 
+  express-rate-limit@8.5.2:
+    resolution: {integrity: sha512-5Kb34ipNX694DH48vN9irak1Qx30nb0PLYHXfJgw4YEjiC3ZEmZJhwOp+VfiCYwFzvFTdB9QkArYS5kXa2cx2A==}
+    engines: {node: '>= 16'}
+    peerDependencies:
+      express: '>= 4.11'
+
+  express@5.2.1:
+    resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
+    engines: {node: '>= 18'}
+
   fast-decode-uri-component@1.0.1:
     resolution: {integrity: sha512-WKgKWg5eUxvRZGwW8FvfbaH7AXSh2cL+3j5fMGzUMCxWBJ3dV3a7Wz8y2f/uQ0e3B6WmodD3oS54jTQ9HVTIIg==}
 
   fast-deep-equal@3.1.3:
     resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
 
+  fast-glob@3.3.3:
+    resolution: {integrity: sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==}
+    engines: {node: '>=8.6.0'}
+
   fast-json-stringify@7.0.0:
     resolution: {integrity: sha512-YV53BAbR3Qwq37wfD1oZ97YJ0nYj6CwfzKXQ38ock9XxI2EnLOdl5psKms6Evook6ACckytZJOaKY0ThmIi1uw==}
 
@@ -1829,10 +2713,22 @@ packages:
   file-uri-to-path@1.0.0:
     resolution: {integrity: sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw==}
 
+  fill-range@7.1.1:
+    resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==}
+    engines: {node: '>=8'}
+
+  finalhandler@2.1.1:
+    resolution: {integrity: sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==}
+    engines: {node: '>= 18.0.0'}
+
   find-my-way@9.6.0:
     resolution: {integrity: sha512-Zf4Xve4RymLl7NgaavNebZ01joJ8MfVerOG43wy7SHLO+r+K0C6d/SE0BiR7AV5V1VOCFlOP7ecdo+I4qmiHrQ==}
     engines: {node: '>=20'}
 
+  find-up@3.0.0:
+    resolution: {integrity: sha512-1yD6RmLI1XBfxugvORwlck6f75tYL+iR0jqwsOrOxMZyGYqUuDhJ0l4AXdO1iX/FTs9cBAMEk1gWSEx1kSbylg==}
+    engines: {node: '>=6'}
+
   fix-dts-default-cjs-exports@1.0.1:
     resolution: {integrity: sha512-pVIECanWFC61Hzl2+oOCtoJ3F17kglZC/6N94eRWycFgBH35hHx0Li604ZIzhseh97mf2p0cv7vVrOZGoqhlEg==}
 
@@ -1840,18 +2736,64 @@ packages:
     resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==}
     engines: {node: '>=14'}
 
+  forwarded@0.2.0:
+    resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==}
+    engines: {node: '>= 0.6'}
+
+  fresh@2.0.0:
+    resolution: {integrity: sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==}
+    engines: {node: '>= 0.8'}
+
   fs-constants@1.0.0:
     resolution: {integrity: sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==}
 
+  fs-extra@11.3.6:
+    resolution: {integrity: sha512-w8ZNZr2mKIc7qeNaQ9AVPT1+iFaI+Avd4xudVOvdDJ8VytREi1Ft5Ih7hd9jjehod8vAM5GMsfQ/TpPf4EyoEA==}
+    engines: {node: '>=14.14'}
+
   fsevents@2.3.3:
     resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
     engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
     os: [darwin]
 
+  function-bind@1.1.2:
+    resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
+
+  fuzzysort@3.1.0:
+    resolution: {integrity: sha512-sR9BNCjBg6LNgwvxlBd0sBABvQitkLzoVY9MYYROQVX/FvfJ4Mai9LsGhDgd8qYdds0bY77VzYd5iuB+v5rwQQ==}
+
+  gensync@1.0.0-beta.2:
+    resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==}
+    engines: {node: '>=6.9.0'}
+
   get-caller-file@2.0.5:
     resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
     engines: {node: 6.* || 8.* || >= 10.*}
 
+  get-east-asian-width@1.6.0:
+    resolution: {integrity: sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==}
+    engines: {node: '>=18'}
+
+  get-intrinsic@1.3.0:
+    resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
+    engines: {node: '>= 0.4'}
+
+  get-nonce@1.0.1:
+    resolution: {integrity: sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==}
+    engines: {node: '>=6'}
+
+  get-own-enumerable-keys@1.0.0:
+    resolution: {integrity: sha512-PKsK2FSrQCyxcGHsGrLDcK0lx+0Ke+6e8KFFozA9/fIQLhQzPaRvJFdcz7+Axg3jUH/Mq+NI4xa5u/UT2tQskA==}
+    engines: {node: '>=14.16'}
+
+  get-proto@1.0.1:
+    resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==}
+    engines: {node: '>= 0.4'}
+
+  get-stream@6.0.1:
+    resolution: {integrity: sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==}
+    engines: {node: '>=10'}
+
   get-stream@9.0.1:
     resolution: {integrity: sha512-kVCxPF3vQM/N0B1PmoqVUqgHP+EeVjmZSQn+1oCRPxd2P21P2F19lIgbR3HBosbB1PUhOAoctJnfEn2GbN2eZA==}
     engines: {node: '>=18'}
@@ -1862,6 +2804,10 @@ packages:
   github-from-package@0.0.0:
     resolution: {integrity: sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==}
 
+  glob-parent@5.1.2:
+    resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
+    engines: {node: '>= 6'}
+
   glob@11.1.0:
     resolution: {integrity: sha512-vuNwKSaKiqm7g0THUBu2x7ckSs3XJLXE+2ssL7/MfTGPLLcrJQ/4Uq1CjPTtO5cCIiRxqvN6Twy1qOwhL0Xjcw==}
     engines: {node: 20 || >=22}
@@ -1871,46 +2817,171 @@ packages:
     resolution: {integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==}
     engines: {node: 18 || 20 || >=22}
 
+  gopd@1.2.0:
+    resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==}
+    engines: {node: '>= 0.4'}
+
   graceful-fs@4.2.11:
     resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
 
+  has-symbols@1.1.0:
+    resolution: {integrity: sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==}
+    engines: {node: '>= 0.4'}
+
+  hasown@2.0.4:
+    resolution: {integrity: sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==}
+    engines: {node: '>= 0.4'}
+
+  hono@4.12.28:
+    resolution: {integrity: sha512-YwUvVpSF7m1yOblFPrU3Hbo8XhPheBoiyfGuII6z19LnOr6JpDnyyp7LFNrfV56wS8tpvtBFGRISHN02pDdLOA==}
+    engines: {node: '>=16.9.0'}
+
   http-errors@2.0.1:
     resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
     engines: {node: '>= 0.8'}
 
+  human-signals@2.1.0:
+    resolution: {integrity: sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw==}
+    engines: {node: '>=10.17.0'}
+
   human-signals@8.0.1:
     resolution: {integrity: sha512-eKCa6bwnJhvxj14kZk5NCPc6Hb6BdsU9DZcOnmQKSnO1VKrfV0zCvtttPZUsBvjmNDn8rpcJfpwSYnHBjc95MQ==}
     engines: {node: '>=18.18.0'}
 
+  iconv-lite@0.7.3:
+    resolution: {integrity: sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ==}
+    engines: {node: '>=0.10.0'}
+
   ieee754@1.2.1:
     resolution: {integrity: sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==}
 
+  ignore@5.3.2:
+    resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
+    engines: {node: '>= 4'}
+
+  immer@10.2.0:
+    resolution: {integrity: sha512-d/+XTN3zfODyjr89gM3mPq1WNX2B8pYsu7eORitdwyA2sBubnTl3laYlBk4sXY5FUa5qTZGBDPJICVbvqzjlbw==}
+
+  immer@11.1.11:
+    resolution: {integrity: sha512-qzXuyXAkPySAGYkfsAwodDPWT8Zm7/Uo5BNt4BjhMhG5WlWyZZ4wQqnWwdS8kjlQ1Cwu6gjw3A6+0gTQwlyYtw==}
+
+  import-fresh@3.3.1:
+    resolution: {integrity: sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==}
+    engines: {node: '>=6'}
+
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
   ini@1.3.8:
     resolution: {integrity: sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==}
 
+  input-otp@1.4.2:
+    resolution: {integrity: sha512-l3jWwYNvrEa6NTCt7BECfCm48GvwuZzkoeG3gBL2w4CHeOXW3eKFmf9UNYkNfYc3mxMrthMnxjIE07MT0zLBQA==}
+    peerDependencies:
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
+
+  internmap@2.0.3:
+    resolution: {integrity: sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==}
+    engines: {node: '>=12'}
+
+  ip-address@10.2.0:
+    resolution: {integrity: sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==}
+    engines: {node: '>= 12'}
+
+  ipaddr.js@1.9.1:
+    resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
+    engines: {node: '>= 0.10'}
+
   ipaddr.js@2.4.0:
     resolution: {integrity: sha512-9VGk3HGanVE6JoZXHiCpnGy5X0jYDnN4EA4lntFPj+1vIWlFhIylq2CrrCOJH9EAhc5CYhq18F2Av2tgoAPsYQ==}
     engines: {node: '>= 10'}
 
+  is-arrayish@0.2.1:
+    resolution: {integrity: sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==}
+
+  is-docker@2.2.1:
+    resolution: {integrity: sha512-F+i2BKsFrH66iaUFc0woD8sLy8getkwTwtOBjvs56Cx4CgJDeKQeqfz8wAYiSb8JOprWhHH5p77PbmYCvvUuXQ==}
+    engines: {node: '>=8'}
+    hasBin: true
+
+  is-docker@3.0.0:
+    resolution: {integrity: sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+    hasBin: true
+
+  is-extglob@2.1.1:
+    resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
+    engines: {node: '>=0.10.0'}
+
   is-fullwidth-code-point@3.0.0:
     resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==}
     engines: {node: '>=8'}
 
+  is-glob@4.0.3:
+    resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
+    engines: {node: '>=0.10.0'}
+
+  is-in-ssh@1.0.0:
+    resolution: {integrity: sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw==}
+    engines: {node: '>=20'}
+
+  is-inside-container@1.0.0:
+    resolution: {integrity: sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==}
+    engines: {node: '>=14.16'}
+    hasBin: true
+
+  is-interactive@2.0.0:
+    resolution: {integrity: sha512-qP1vozQRI+BMOPcjFzrjXuQvdak2pHNUMZoeG2eRbiSqyvbEf/wQtEOTOX1guk6E3t36RkaqiSt8A/6YElNxLQ==}
+    engines: {node: '>=12'}
+
+  is-number@7.0.0:
+    resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==}
+    engines: {node: '>=0.12.0'}
+
+  is-obj@2.0.0:
+    resolution: {integrity: sha512-drqDG3cbczxxEJRoOXcOjtdp1J/lyp1mNn0xaznRs8+muBhgQcrnbspox5X5fOw0HnMnbfDzvnEMEtqDEJEo8w==}
+    engines: {node: '>=8'}
+
+  is-obj@3.0.0:
+    resolution: {integrity: sha512-IlsXEHOjtKhpN8r/tRFj2nDyTmHvcfNeu/nrRIcXE17ROeatXchkojffa1SpdqW4cr/Fj6QkEf/Gn4zf6KKvEQ==}
+    engines: {node: '>=12'}
+
   is-plain-obj@4.1.0:
     resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==}
     engines: {node: '>=12'}
 
+  is-promise@4.0.0:
+    resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}
+
+  is-regexp@3.1.0:
+    resolution: {integrity: sha512-rbku49cWloU5bSMI+zaRaXdQHXnthP6DZ/vLnfdSKyL4zUzuWnomtOEiZZOd+ioQ+avFo/qau3KPTc7Fjy1uPA==}
+    engines: {node: '>=12'}
+
+  is-stream@2.0.1:
+    resolution: {integrity: sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==}
+    engines: {node: '>=8'}
+
   is-stream@4.0.1:
     resolution: {integrity: sha512-Dnz92NInDqYckGEUJv689RbRiTSEHCQ7wOVeALbkOz999YpqT46yMRIGtSNl2iCL1waAZSx40+h59NV/EwzV/A==}
     engines: {node: '>=18'}
 
+  is-unicode-supported@1.3.0:
+    resolution: {integrity: sha512-43r2mRvz+8JRIKnWJ+3j8JtjRKZ6GmjzfaE/qiBJnikNnYv/6bagRJ1kUhNk8R5EX/GkobD+r+sfxCPJsiKBLQ==}
+    engines: {node: '>=12'}
+
   is-unicode-supported@2.1.0:
     resolution: {integrity: sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ==}
     engines: {node: '>=18'}
 
+  is-wsl@2.2.0:
+    resolution: {integrity: sha512-fKzAra0rGJUUBwGBgNkHZuToZcn+TtXHpeCgmkMJMMYx1sQDYaCSyjJBSCa2nH1DGm7s3n1oBnohoVTBaN7Lww==}
+    engines: {node: '>=8'}
+
+  is-wsl@3.1.1:
+    resolution: {integrity: sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==}
+    engines: {node: '>=16'}
+
   isbot@5.2.0:
     resolution: {integrity: sha512-gbZiGCb4B5xaoxg9mS7koAyRdvJnArk10VLSHOgz6rtBG93/pi1xOFaVvXMKZ7JXgyZ8zAbNRK5uIBdIUTFSqw==}
     engines: {node: '>=18'}
@@ -1918,6 +2989,10 @@ packages:
   isexe@2.0.0:
     resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
 
+  isexe@3.1.5:
+    resolution: {integrity: sha512-6B3tLtFqtQS4ekarvLVMZ+X+VlvQekbe4taUkf/rhVO3d/h0M2rfARm/pXLcPEsjjMsFgrFgSrhQIxcSVrBz8w==}
+    engines: {node: '>=18'}
+
   jackspeak@4.2.3:
     resolution: {integrity: sha512-ykkVRwrYvFm1nb2AJfKKYPr0emF6IiXDYUaFx4Zn9ZuIH7MrzEZ3sD5RlqGXNRpHtvUHJyOnCEFxOlNDtGo7wg==}
     engines: {node: 20 || >=22}
@@ -1926,10 +3001,28 @@ packages:
     resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}
     hasBin: true
 
+  jose@6.2.3:
+    resolution: {integrity: sha512-YYVDInQKFJfR/xa3ojUTl8c2KoTwiL1R5Wg9YCydwH0x0B9grbzlg5HC7mMjCtUJjbQ/YnGEZIhI5tCgfTb4Hw==}
+
   joycon@3.1.1:
     resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==}
     engines: {node: '>=10'}
 
+  js-tokens@4.0.0:
+    resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
+
+  js-yaml@4.3.0:
+    resolution: {integrity: sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==}
+    hasBin: true
+
+  jsesc@3.1.0:
+    resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  json-parse-even-better-errors@2.3.1:
+    resolution: {integrity: sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==}
+
   json-schema-ref-resolver@3.0.0:
     resolution: {integrity: sha512-hOrZIVL5jyYFjzk7+y7n5JDzGlU8rfWDuYyHwGa2WA8/pcmMHezp2xsVwxrebD/Q9t8Nc5DboieySDpCp4WG4A==}
 
@@ -1940,6 +3033,28 @@ packages:
   json-schema-traverse@1.0.0:
     resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
 
+  json-schema-typed@7.0.3:
+    resolution: {integrity: sha512-7DE8mpG+/fVw+dTpjbxnx47TaMnDfOI1jwft9g1VybltZCduyRQPJPvc+zzKY9WPHxhPWczyFuYa6I8Mw4iU5A==}
+
+  json-schema-typed@8.0.2:
+    resolution: {integrity: sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==}
+
+  json5@2.2.3:
+    resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  jsonfile@6.2.1:
+    resolution: {integrity: sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==}
+
+  kleur@3.0.3:
+    resolution: {integrity: sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w==}
+    engines: {node: '>=6'}
+
+  kleur@4.1.5:
+    resolution: {integrity: sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==}
+    engines: {node: '>=6'}
+
   light-my-request@6.6.0:
     resolution: {integrity: sha512-CHYbu8RtboSIoVsHZ6Ye4cj4Aw/yg2oAFimlF7mNvfDV192LR7nDiKtSIfCuLT7KokPSTn/9kfVLm5OGN0A28A==}
 
@@ -2028,9 +3143,17 @@ packages:
     resolution: {integrity: sha512-IXO6OCs9yg8tMKzfPZ1YmheJbZCiEsnBdcB03l0OcfK9prKnJb96siuHCr5Fl37/yo9DnKU+TLpxzTUspw9shg==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
 
+  locate-path@3.0.0:
+    resolution: {integrity: sha512-7AO748wWnIhNqAuaty2ZWHkQHRSNfPVIsPIfwEOWO22AmaoVrWavlOcMR5nzTLNYvp36X220/maaRsrec1G65A==}
+    engines: {node: '>=6'}
+
   lodash.camelcase@4.3.0:
     resolution: {integrity: sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==}
 
+  log-symbols@6.0.0:
+    resolution: {integrity: sha512-i24m8rpwhmPIS4zscNzK6MSEhk0DUWa/8iYQWxhffV8jkI4Phvs3F+quL5xvS0gdQR0FyTCMMH33Y78dDTzzIw==}
+    engines: {node: '>=18'}
+
   long@5.3.2:
     resolution: {integrity: sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==}
 
@@ -2038,14 +3161,60 @@ packages:
     resolution: {integrity: sha512-4pfM1Ff0x50o0tQwb5ucw/RzNyD0/YJME6IVcStalZuMWxdt3sR3huStTtxz4PUmvZfRguvDejasvQ2kifR11g==}
     engines: {node: 20 || >=22}
 
+  lru-cache@5.1.1:
+    resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
+
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
+  math-intrinsics@1.1.0:
+    resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
+    engines: {node: '>= 0.4'}
+
+  media-typer@1.1.0:
+    resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==}
+    engines: {node: '>= 0.8'}
+
+  merge-descriptors@2.0.0:
+    resolution: {integrity: sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==}
+    engines: {node: '>=18'}
+
+  merge-stream@2.0.0:
+    resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==}
+
+  merge2@1.4.1:
+    resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
+    engines: {node: '>= 8'}
+
+  micromatch@4.0.8:
+    resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
+    engines: {node: '>=8.6'}
+
+  mime-db@1.54.0:
+    resolution: {integrity: sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==}
+    engines: {node: '>= 0.6'}
+
+  mime-types@3.0.2:
+    resolution: {integrity: sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==}
+    engines: {node: '>=18'}
+
   mime@3.0.0:
     resolution: {integrity: sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A==}
     engines: {node: '>=10.0.0'}
     hasBin: true
 
+  mimic-fn@2.1.0:
+    resolution: {integrity: sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==}
+    engines: {node: '>=6'}
+
+  mimic-fn@3.1.0:
+    resolution: {integrity: sha512-Ysbi9uYW9hFyfrThdDEQuykN4Ey6BuwPD2kpI5ES/nFTDn/98yxYNLZJcgUAKPT/mcrLLKaGzJR9YVxJrIdASQ==}
+    engines: {node: '>=8'}
+
+  mimic-function@5.0.1:
+    resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
+    engines: {node: '>=18'}
+
   mimic-response@3.1.0:
     resolution: {integrity: sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ==}
     engines: {node: '>=10'}
@@ -2088,10 +3257,28 @@ packages:
   napi-build-utils@2.0.0:
     resolution: {integrity: sha512-GEbrYkbfF7MoNaoh2iGG84Mnf/WZfB0GdGEsM8wz7Expx/LlWf5U8t9nvJKXSp3qr5IsEbK04cBGhol/KwOsWA==}
 
+  negotiator@1.0.0:
+    resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
+    engines: {node: '>= 0.6'}
+
+  next-themes@0.4.6:
+    resolution: {integrity: sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==}
+    peerDependencies:
+      react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
+
   node-abi@3.94.0:
     resolution: {integrity: sha512-W5ZNO5KRPB5TkYmGVD9F6YqhsglXJzE6etpbmT+f6EQElhiX/UTG551cnsRGvLG3fyZEg9HwaDmNmj5nwJ4z9g==}
     engines: {node: '>=10'}
 
+  node-releases@2.0.50:
+    resolution: {integrity: sha512-J6l92tKHX6w8Jy5nO1Vuc01NoIiRGi/d6qBKVxh+IQ8Cr3b6HbVNfKiF8ZpFKufTwpwxMmce2W3iQZ861ZRyTg==}
+    engines: {node: '>=18'}
+
+  npm-run-path@4.0.1:
+    resolution: {integrity: sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==}
+    engines: {node: '>=8'}
+
   npm-run-path@6.0.0:
     resolution: {integrity: sha512-9qny7Z9DsQU8Ou39ERsPU4OZQlSTP47ShQzuKZ6PRXpYLtIFgl/DEBYEXKlvcEa+9tHVcK8CF81Y2V72qaZhWA==}
     engines: {node: '>=18'}
@@ -2100,6 +3287,14 @@ packages:
     resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
     engines: {node: '>=0.10.0'}
 
+  object-inspect@1.13.4:
+    resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==}
+    engines: {node: '>= 0.4'}
+
+  object-treeify@1.1.33:
+    resolution: {integrity: sha512-EFVjAYfzWqWsBMRHPMAXLCDIJnpMhdWAqR7xG6M6a2cs6PMFpl/+Z20w9zDW4vkxOFfddegBKq9Rehd0bxWE7A==}
+    engines: {node: '>= 10'}
+
   obug@2.1.3:
     resolution: {integrity: sha512-9miFgM2OFba7hB+pRgvtV84pYTBaoTHohvmIgiRt6dRIzbwEOIaNaP+dIlGs2fNFoB0SeISs0Jz5WFVRid6Xyg==}
     engines: {node: '>=12.20.0'}
@@ -2108,9 +3303,29 @@ packages:
     resolution: {integrity: sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA==}
     engines: {node: '>=14.0.0'}
 
+  on-finished@2.4.1:
+    resolution: {integrity: sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==}
+    engines: {node: '>= 0.8'}
+
   once@1.4.0:
     resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==}
 
+  onetime@5.1.2:
+    resolution: {integrity: sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==}
+    engines: {node: '>=6'}
+
+  onetime@7.0.0:
+    resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==}
+    engines: {node: '>=18'}
+
+  open@11.0.0:
+    resolution: {integrity: sha512-smsWv2LzFjP03xmvFoJ331ss6h+jixfA4UUV/Bsiyuu4YJPfN+FIQGOIiv4w9/+MoHkfkJ22UIaQWRVFRfH6Vw==}
+    engines: {node: '>=20'}
+
+  open@8.4.2:
+    resolution: {integrity: sha512-7x81NCL719oNbsq/3mh+hVrAWmFuEYUqrq/Iw3kUzH8ReypT9QQ0BLoJS7/G9k6N81XjW4qHWtjWwe/9eLy1EQ==}
+    engines: {node: '>=12'}
+
   openapi-fetch@0.14.1:
     resolution: {integrity: sha512-l7RarRHxlEZYjMLd/PR0slfMVse2/vvIAGm75/F7J6MlQ8/b9uUQmUF2kCPrQhJqMXSxmYWObVgeYXbFYzZR+A==}
 
@@ -2120,13 +3335,48 @@ packages:
   openapi-typescript-helpers@0.0.15:
     resolution: {integrity: sha512-opyTPaunsklCBpTK8JGef6mfPhLSnyy5a0IN9vKtx3+4aExf+KxEqYwIy3hqkedXIB97u357uLMJsOnm3GVjsw==}
 
+  ora@8.2.0:
+    resolution: {integrity: sha512-weP+BZ8MVNnlCm8c0Qdc1WSWq4Qn7I+9CJGm7Qali6g44e/PUzbjNqJX5NJ9ljlNMosfJvg1fKEGILklK9cwnw==}
+    engines: {node: '>=18'}
+
+  p-limit@2.3.0:
+    resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==}
+    engines: {node: '>=6'}
+
+  p-locate@3.0.0:
+    resolution: {integrity: sha512-x+12w/To+4GFfgJhBEpiDcLozRJGegY+Ei7/z0tSLkMmxGZNybVMSfWj9aJn8Z5Fc7dBUNJOOVgPv2H7IwulSQ==}
+    engines: {node: '>=6'}
+
+  p-try@2.2.0:
+    resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==}
+    engines: {node: '>=6'}
+
   package-json-from-dist@1.0.1:
     resolution: {integrity: sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==}
 
+  parent-module@1.0.1:
+    resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
+    engines: {node: '>=6'}
+
+  parse-json@5.2.0:
+    resolution: {integrity: sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==}
+    engines: {node: '>=8'}
+
   parse-ms@4.0.0:
     resolution: {integrity: sha512-TXfryirbmq34y8QBwgqCVLi+8oA3oWx2eAnSn62ITyEhEYaWRlVZ2DvMM9eZbMs/RfxPu/PK/aBLyGj4IrqMHw==}
     engines: {node: '>=18'}
 
+  parseurl@1.3.3:
+    resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==}
+    engines: {node: '>= 0.8'}
+
+  path-browserify@1.0.1:
+    resolution: {integrity: sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==}
+
+  path-exists@3.0.0:
+    resolution: {integrity: sha512-bpC7GYwiDYQ4wYLe+FA8lhRjhQCMcQGuSgGGqDkg/QerRWw9CmGRT0iSOVRSZJ29NMLZgIzqaljJ63oaL4NIJQ==}
+    engines: {node: '>=4'}
+
   path-key@3.1.1:
     resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==}
     engines: {node: '>=8'}
@@ -2139,12 +3389,19 @@ packages:
     resolution: {integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==}
     engines: {node: 18 || 20 || >=22}
 
+  path-to-regexp@8.4.2:
+    resolution: {integrity: sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==}
+
   pathe@2.0.3:
     resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
 
   picocolors@1.1.1:
     resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
 
+  picomatch@2.3.2:
+    resolution: {integrity: sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==}
+    engines: {node: '>=8.6'}
+
   picomatch@4.0.5:
     resolution: {integrity: sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==}
     engines: {node: '>=12'}
@@ -2163,9 +3420,17 @@ packages:
     resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==}
     engines: {node: '>= 6'}
 
+  pkce-challenge@5.0.1:
+    resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
+    engines: {node: '>=16.20.0'}
+
   pkg-types@1.3.1:
     resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
 
+  pkg-up@3.1.0:
+    resolution: {integrity: sha512-nDywThFk1i4BQK4twPQ6TA4RT8bDY96yeuCVBWL3ePARCiEKDRSrNGbFIgUJpLp+XeIR65v8ra7WuJOFUBtkMA==}
+    engines: {node: '>=8'}
+
   platform@1.3.6:
     resolution: {integrity: sha512-fnWVljUchTro6RiCFvCXBbNhJc2NijN7oIQxbwsyL0buWJPG85v81ehlHI9fXrJsMNgTofEoWIQeClKpgxFLrg==}
 
@@ -2187,16 +3452,29 @@ packages:
       yaml:
         optional: true
 
+  postcss-selector-parser@7.1.4:
+    resolution: {integrity: sha512-HeP7D2wyhkR+XaK6v4W8oRF62Dsz4flyuczALJp61GckGm42u1saSSJ/0auvcBqxs3jMRFEcPK34At/0JBKdOg==}
+    engines: {node: '>=4'}
+
   postcss@8.5.16:
     resolution: {integrity: sha512-vuwillviilfKZsg0VGj5R/YwwcHx4SLsIOI/7K6mQkWx+l5cUHTjj5g0AasTBcyXsbfTgrwsUNmVUb5xVwyPwg==}
     engines: {node: ^10 || ^12 || >=14}
 
+  powershell-utils@0.1.0:
+    resolution: {integrity: sha512-dM0jVuXJPsDN6DvRpea484tCUaMiXWjuCn++HGTqUWzGDjv5tZkEZldAJ/UMlqRYGFrD/etByo4/xOuC/snX2A==}
+    engines: {node: '>=20'}
+
   prebuild-install@7.1.3:
     resolution: {integrity: sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug==}
     engines: {node: '>=10'}
     deprecated: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
     hasBin: true
 
+  prettier@3.9.4:
+    resolution: {integrity: sha512-yWG/o/4oJfo036EKAfK6ACAoDOfHeRHx4tuxkfBZiauURiaSmYwlpOr5LQqKtIkRD2z1PLteme2WoxEnj4tHTg==}
+    engines: {node: '>=14'}
+    hasBin: true
+
   pretty-ms@9.3.0:
     resolution: {integrity: sha512-gjVS5hOP+M3wMm5nmNOucbIrqudzs9v/57bWRHQWLYklXqoXKrVfYW2W9+glfGsqtPgpiz5WwyEEB+ksXIx3gQ==}
     engines: {node: '>=18'}
@@ -2207,25 +3485,109 @@ packages:
   process-warning@5.0.0:
     resolution: {integrity: sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA==}
 
+  prompts@2.4.2:
+    resolution: {integrity: sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==}
+    engines: {node: '>= 6'}
+
   protobufjs@7.6.5:
     resolution: {integrity: sha512-/FPD0nUc9jH6rfFjji9IBqOz4pcSE3CsT1m7Ep6Mdb0LxSUMj8hgl6GomOvZzpNpAqqGaXA0P3VSrZLFzIhQrw==}
     engines: {node: '>=12.0.0'}
 
+  proxy-addr@2.0.7:
+    resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==}
+    engines: {node: '>= 0.10'}
+
   pump@3.0.4:
     resolution: {integrity: sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==}
 
+  qs@6.15.3:
+    resolution: {integrity: sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==}
+    engines: {node: '>=0.6'}
+
+  queue-microtask@1.2.3:
+    resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
+
   quick-format-unescaped@4.0.4:
     resolution: {integrity: sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg==}
 
+  range-parser@1.3.0:
+    resolution: {integrity: sha512-hek2mFQpPuI4E1BBKrSto+BU3e3x4xuarsbiwr3+lf7p44juvFMV0XFWQAP3xUyqXA4RrXLIoaSUGbSt056ZMw==}
+    engines: {node: '>= 0.6'}
+
+  raw-body@3.0.2:
+    resolution: {integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==}
+    engines: {node: '>= 0.10'}
+
   rc@1.2.8:
     resolution: {integrity: sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw==}
     hasBin: true
 
+  react-day-picker@10.0.1:
+    resolution: {integrity: sha512-eNh6BlwcYInWaJtRv18mXQ06Ys/H6rdTZAnTaSdOYJuTpwP1JMCHNd1FDRadA+gbeinq+psdULN5Xnowy9mV8w==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@types/react': '>=16.8.0'
+      react: '>=16.8.0'
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
   react-dom@19.2.7:
     resolution: {integrity: sha512-t0BRVXvbiE/o20Hfw669rLbMCDWtYZLvmJigy2f0MxsXF+71pxhR3xOkspmsO8h3ZlNzyibAmtCa3l4lYKk6gQ==}
     peerDependencies:
       react: ^19.2.7
 
+  react-is@19.2.7:
+    resolution: {integrity: sha512-kZFnouyVv7eP/Phmrlo9FK+zcAdriZJvzxXHF1Sl1P377WSGe2G/JxVolhTrB/jeV47lKImhNUsijjHAAbcl/A==}
+
+  react-redux@9.3.0:
+    resolution: {integrity: sha512-KQopgqFo/p/fgmAs5qz6p5RWaNAzq40WAu7fJIXnQpYxFPbJYtsJPWvGeF2rOBaY/kEuV77AVsX8TsQzKm+A/g==}
+    peerDependencies:
+      '@types/react': ^18.2.25 || ^19
+      react: ^18.0 || ^19
+      redux: ^5.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      redux:
+        optional: true
+
+  react-remove-scroll-bar@2.3.8:
+    resolution: {integrity: sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-remove-scroll@2.7.2:
+    resolution: {integrity: sha512-Iqb9NjCCTt6Hf+vOdNIZGdTiH1QSqr27H/Ek9sv/a97gfueI/5h1s3yRi1nngzMUaOOToin5dI1dXKdXiF+u0Q==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-resizable-panels@4.12.1:
+    resolution: {integrity: sha512-ElE/UpOvMLRWtAqbCgyizHXcbws8RPMyN3cBqmdY17Nxr5f01+DEwzOLqhgcy68GSnjtIUFgKWKl8aIgx5aypQ==}
+    peerDependencies:
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+
+  react-style-singleton@2.2.3:
+    resolution: {integrity: sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
   react@19.2.7:
     resolution: {integrity: sha512-HNe9WslTbXmFK8o8cmwgAeJFSBvt1bPdHCVKtaaV+WlAN36mpT4hcRpwbf3fY56ar2oIXzsBpOAiIRHAdY0OlQ==}
     engines: {node: '>=0.10.0'}
@@ -2238,6 +3600,10 @@ packages:
     resolution: {integrity: sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==}
     engines: {node: '>= 14.18.0'}
 
+  readdirp@5.0.0:
+    resolution: {integrity: sha512-9u/XQ1pvrQtYyMpZe7DXKv2p5CNvyVwzUB6uhLAnQwHMSgKMBR62lc7AHljaeteeHXn11XTAaLLUVZYVZyuRBQ==}
+    engines: {node: '>= 20.19.0'}
+
   real-require@0.2.0:
     resolution: {integrity: sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg==}
     engines: {node: '>= 12.13.0'}
@@ -2245,6 +3611,26 @@ packages:
   real-require@1.0.0:
     resolution: {integrity: sha512-P4nbQYQfePJxRSmY+v/KINxVucm4NF3p3s7pJveMTtom52FR4YGltUQLB8idDXwDDWW+eYrWDFbuzUnjoWHF7g==}
 
+  recast@0.23.12:
+    resolution: {integrity: sha512-dEWRjcINDu/F4l2dYx57ugBtD7HV9KXESyxhzw/MqWLeglJrsjJKqACPyUPg+6AF8mIgm+Zi0dZ3ACoIg+QtpA==}
+    engines: {node: '>= 4'}
+
+  recharts@3.8.0:
+    resolution: {integrity: sha512-Z/m38DX3L73ExO4Tpc9/iZWHmHnlzWG4njQbxsF5aSjwqmHNDDIm0rdEBArkwsBvR8U6EirlEHiQNYWCVh9sGQ==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-is: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  redux-thunk@3.1.0:
+    resolution: {integrity: sha512-NW2r5T6ksUKXCabzhL9z+h206HQw/NJkcLm1GPImRQ8IzfXwRGqjVhKJGauHirT0DAuyy6hjdnMZaRoAcy0Klw==}
+    peerDependencies:
+      redux: ^5.0.0
+
+  redux@5.0.1:
+    resolution: {integrity: sha512-M9/ELqF6fy8FwmkpnF0S3YKOqMyoWJ4+CS5Efg2ct3oY9daQvd/Pc71FpGZsVsbl3Cpb+IIcjBDUnnyBdQbq4w==}
+
   require-directory@2.1.1:
     resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
     engines: {node: '>=0.10.0'}
@@ -2253,6 +3639,16 @@ packages:
     resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
     engines: {node: '>=0.10.0'}
 
+  reselect@5.1.1:
+    resolution: {integrity: sha512-K/BG6eIky/SBpzfHZv/dd+9JBFiS4SWV7FIujVyJRux6e45+73RaUHXLmIR1f7WOMaQ0U1km6qwklRQxpJJY0w==}
+
+  reselect@5.2.0:
+    resolution: {integrity: sha512-AgZ3UOZm3YndfrJ4OYjgrT7bmCm/1iqkjvEfH/oYjzh6PD2qw4QuT3jjnXIrpdt4MTpMXclMT3lXbmRY+XRakw==}
+
+  resolve-from@4.0.0:
+    resolution: {integrity: sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==}
+    engines: {node: '>=4'}
+
   resolve-from@5.0.0:
     resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==}
     engines: {node: '>=8'}
@@ -2260,6 +3656,10 @@ packages:
   resolve-pkg-maps@1.0.0:
     resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
 
+  restore-cursor@5.1.0:
+    resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
+    engines: {node: '>=18'}
+
   ret@0.5.0:
     resolution: {integrity: sha512-I1XxrZSQ+oErkRR4jYbAyEEu2I0avBvvMM5JN+6EBprOGRCs63ENqZ3vjavq8fBw2+62G5LF5XelKwuJpcvcxw==}
     engines: {node: '>=10'}
@@ -2281,6 +3681,17 @@ packages:
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
     hasBin: true
 
+  router@2.2.0:
+    resolution: {integrity: sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==}
+    engines: {node: '>= 18'}
+
+  run-applescript@7.1.0:
+    resolution: {integrity: sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==}
+    engines: {node: '>=18'}
+
+  run-parallel@1.2.0:
+    resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
+
   safe-buffer@5.2.1:
     resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==}
 
@@ -2301,11 +3712,19 @@ packages:
   secure-json-parse@4.1.0:
     resolution: {integrity: sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA==}
 
+  semver@6.3.1:
+    resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
+    hasBin: true
+
   semver@7.8.5:
     resolution: {integrity: sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==}
     engines: {node: '>=10'}
     hasBin: true
 
+  send@1.2.1:
+    resolution: {integrity: sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==}
+    engines: {node: '>= 18'}
+
   seroval-plugins@1.5.4:
     resolution: {integrity: sha512-S0xQPhUTefAhNvNWFg0c1J8qJArHt5KdtJ/cFAofo06KD1MVSeFWyl4iiu+ApDIuw0WhjpOfCdgConOfAnLgkw==}
     engines: {node: '>=10'}
@@ -2316,12 +3735,21 @@ packages:
     resolution: {integrity: sha512-46uFvgrXTVxZcUorgSSRZ4y+ieqLLQRMlG4bnCZKW3qI6BZm7Rg4ntMW4p1mILEEBZWrFlcpp0AyIIlM6jD9iw==}
     engines: {node: '>=10'}
 
+  serve-static@2.2.1:
+    resolution: {integrity: sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==}
+    engines: {node: '>= 18'}
+
   set-cookie-parser@2.7.2:
     resolution: {integrity: sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==}
 
   setprototypeof@1.2.0:
     resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
 
+  shadcn@4.13.0:
+    resolution: {integrity: sha512-5fuJ4jI/GcPeA/iTL4cJivCZuYQGXz/N3bIzyd+Gd/FM6xUCy2MxGG+LaDQuw2cjNy9zGPSFPTEmI048UwPTZA==}
+    engines: {node: '>=20.18.1'}
+    hasBin: true
+
   shebang-command@2.0.0:
     resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
     engines: {node: '>=8'}
@@ -2330,9 +3758,28 @@ packages:
     resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
     engines: {node: '>=8'}
 
+  side-channel-list@1.0.1:
+    resolution: {integrity: sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-map@1.0.1:
+    resolution: {integrity: sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-weakmap@1.0.2:
+    resolution: {integrity: sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==}
+    engines: {node: '>= 0.4'}
+
+  side-channel@1.1.1:
+    resolution: {integrity: sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==}
+    engines: {node: '>= 0.4'}
+
   siginfo@2.0.0:
     resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
 
+  signal-exit@3.0.7:
+    resolution: {integrity: sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==}
+
   signal-exit@4.1.0:
     resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
     engines: {node: '>=14'}
@@ -2343,9 +3790,18 @@ packages:
   simple-get@4.0.1:
     resolution: {integrity: sha512-brv7p5WgH0jmQJr1ZDDfKDOSeWWg+OVypG99A/5vYGPqJ6pxiaHLy8nxtFjBA7oMa01ebA9gfh1uMCFqOuXxvA==}
 
+  sisteransi@1.0.5:
+    resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
+
   sonic-boom@4.2.1:
     resolution: {integrity: sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q==}
 
+  sonner@2.0.7:
+    resolution: {integrity: sha512-W6ZN4p58k8aDKA4XPcx2hpIQXBRAgyiWVkYhT7CvK6D3iAu7xjvVyhQHg2/iaKJZ1XVJ4r7XuwGL+WGEK37i9w==}
+    peerDependencies:
+      react: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+
   source-map-js@1.2.1:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
     engines: {node: '>=0.10.0'}
@@ -2382,17 +3838,41 @@ packages:
   std-env@4.1.0:
     resolution: {integrity: sha512-Rq7ybcX2RuC55r9oaPVEW7/xu3tj8u4GeBYHBWCychFtzMIr86A7e3PPEBPT37sHStKX3+TiX/Fr/ACmJLVlLQ==}
 
+  stdin-discarder@0.2.2:
+    resolution: {integrity: sha512-UhDfHmA92YAlNnCfhmq0VeNL5bDbiZGg7sZ2IvPsXubGkiNa9EC+tUTsjBRsYUAz87btI6/1wf4XoVvQ3uRnmQ==}
+    engines: {node: '>=18'}
+
   string-width@4.2.3:
     resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
     engines: {node: '>=8'}
 
+  string-width@7.2.0:
+    resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==}
+    engines: {node: '>=18'}
+
   string_decoder@1.3.0:
     resolution: {integrity: sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==}
 
+  stringify-object@5.0.0:
+    resolution: {integrity: sha512-zaJYxz2FtcMb4f+g60KsRNFOpVMUyuJgA51Zi5Z1DOTC3S59+OQiVOzE9GZt0x72uBGWKsQIuBKeF9iusmKFsg==}
+    engines: {node: '>=14.16'}
+
   strip-ansi@6.0.1:
     resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
     engines: {node: '>=8'}
 
+  strip-ansi@7.2.0:
+    resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
+    engines: {node: '>=12'}
+
+  strip-bom@3.0.0:
+    resolution: {integrity: sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==}
+    engines: {node: '>=4'}
+
+  strip-final-newline@2.0.0:
+    resolution: {integrity: sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==}
+    engines: {node: '>=6'}
+
   strip-final-newline@4.0.0:
     resolution: {integrity: sha512-aulFJcD6YK8V1G7iRB5tigAP4TsHBZZrOV8pjV++zdUwmeV8uzbY7yn6h9MswN62adStNZFuCIx4haBnRuMDaw==}
     engines: {node: '>=18'}
@@ -2406,6 +3886,15 @@ packages:
     engines: {node: '>=16 || 14 >=14.17'}
     hasBin: true
 
+  systeminformation@5.31.15:
+    resolution: {integrity: sha512-7mqCtD28TK5dVdLAQONVa/Do/NBgMH2dxqf49nh6DIKoEWuDg6tkgGBP+dN22VEJVPZa/QqiHomhWNRn4WUNTQ==}
+    engines: {node: '>=8.0.0'}
+    os: [darwin, linux, win32, freebsd, openbsd, netbsd, sunos, android]
+    hasBin: true
+
+  tailwind-merge@3.6.0:
+    resolution: {integrity: sha512-uxL7qAVQriqRQPAyK3pj66VqskWqoZ37PW94jwOTwNfq/z9oyu1V+eqrZqtR2+fCiXdYOZe/Modt8GtvqNzu+w==}
+
   tailwindcss@4.3.2:
     resolution: {integrity: sha512-WtctNNSH8A9jlMIqxzuYumOHU5uGZyRv0Q5svQl+oEPy5w84YpBxdb7MdqyiSPQge5jTJ6zFQLq0PFygdccSBA==}
 
@@ -2435,6 +3924,9 @@ packages:
     resolution: {integrity: sha512-e2zZ96wSChazBsbENf/Pcm/4swHt2cEKQ92rhUjkL9GCKiTDJIaTBenjE/m9DXi0QBmTMDkFDdOomUy20A1tDQ==}
     engines: {node: '>=20'}
 
+  tiny-invariant@1.3.3:
+    resolution: {integrity: sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg==}
+
   tinybench@2.9.0:
     resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
 
@@ -2453,6 +3945,10 @@ packages:
     resolution: {integrity: sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==}
     engines: {node: '>=14.0.0'}
 
+  to-regex-range@5.0.1:
+    resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==}
+    engines: {node: '>=8.0'}
+
   toad-cache@3.7.4:
     resolution: {integrity: sha512-m1TdR/rvT7kgGJZhspNtXdsdYk0fddFpJJFlG5s+UkPFo6lkLoZ3YLOaovPYjq1R75NP5JfeTlSHaOsE09peCg==}
     engines: {node: '>=20'}
@@ -2468,6 +3964,13 @@ packages:
   ts-interface-checker@0.1.13:
     resolution: {integrity: sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==}
 
+  ts-morph@26.0.0:
+    resolution: {integrity: sha512-ztMO++owQnz8c/gIENcM9XfCEzgoGphTv+nKpYNM1bgsdOVC/jRZuEBf6N+mLLDNg68Kl+GgUZfOySaRiG1/Ug==}
+
+  tsconfig-paths@4.2.0:
+    resolution: {integrity: sha512-NoZ4roiN7LnbKn9QqE1amc9DJfzvZXxF4xDavcOWt1BPkdx+m+0gJuPM+S0vCe7zTJMYUP0R8pO2XMr+Y8oLIg==}
+    engines: {node: '>=6'}
+
   tslib@2.8.1:
     resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
 
@@ -2498,9 +4001,16 @@ packages:
   tunnel-agent@0.6.0:
     resolution: {integrity: sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w==}
 
+  tw-animate-css@1.4.0:
+    resolution: {integrity: sha512-7bziOlRqH0hJx80h/3mbicLW7o8qLsH5+RaLR2t+OHM3D0JlWGODQKQ4cxbK7WlvmUxpcj6Kgu6EKqjrGFe3QQ==}
+
   tweetnacl@0.14.5:
     resolution: {integrity: sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==}
 
+  type-is@2.1.0:
+    resolution: {integrity: sha512-faYHw0anBbc/kWF3zFTEnxSFOAGUX9GFbOBthvDdLsIlEoWOFOtS0zgCiQYwIskL9iGXZL3kAXD8OoZ4GmMATA==}
+    engines: {node: '>= 18'}
+
   typescript@6.0.3:
     resolution: {integrity: sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==}
     engines: {node: '>=14.17'}
@@ -2527,6 +4037,73 @@ packages:
     resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
     engines: {node: '>=18'}
 
+  universalify@2.0.1:
+    resolution: {integrity: sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==}
+    engines: {node: '>= 10.0.0'}
+
+  unpipe@1.0.0:
+    resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
+    engines: {node: '>= 0.8'}
+
+  unplugin@3.3.0:
+    resolution: {integrity: sha512-qa66K+crbfyE6JK10GjvbJeRrOsuC/JpbnHctfyp/i4oBTxWOzJfRZyDiOk1PtErMFRu8JhsU/wPvOdBNWe5Rg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      '@farmfe/core': '*'
+      '@rspack/core': '*'
+      bun-types-no-globals: '*'
+      esbuild: '*'
+      rolldown: '*'
+      rollup: '*'
+      unloader: '*'
+      vite: '*'
+      webpack: '*'
+    peerDependenciesMeta:
+      '@farmfe/core':
+        optional: true
+      '@rspack/core':
+        optional: true
+      bun-types-no-globals:
+        optional: true
+      esbuild:
+        optional: true
+      rolldown:
+        optional: true
+      rollup:
+        optional: true
+      unloader:
+        optional: true
+      vite:
+        optional: true
+      webpack:
+        optional: true
+
+  update-browserslist-db@1.2.3:
+    resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==}
+    hasBin: true
+    peerDependencies:
+      browserslist: '>= 4.21.0'
+
+  use-callback-ref@1.3.3:
+    resolution: {integrity: sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-sidecar@1.1.3:
+    resolution: {integrity: sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
   use-sync-external-store@1.6.0:
     resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==}
     peerDependencies:
@@ -2535,6 +4112,17 @@ packages:
   util-deprecate@1.0.2:
     resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
 
+  validate-npm-package-name@7.0.2:
+    resolution: {integrity: sha512-hVDIBwsRruT73PbK7uP5ebUt+ezEtCmzZz3F59BSr2F6OVFnJ/6h8liuvdLrQ88Xmnk6/+xGGuq+pG9WwTuy3A==}
+    engines: {node: ^20.17.0 || >=22.9.0}
+
+  vary@1.1.2:
+    resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
+    engines: {node: '>= 0.8'}
+
+  victory-vendor@37.3.6:
+    resolution: {integrity: sha512-SbPDPdDBYp+5MJHhBCAyI7wKM3d5ivekigc2Dk2s7pgbZ9wIgIBYGVw4zGHBml/qTFbexrofXW6Gu4noGxrOwQ==}
+
   vite@8.1.3:
     resolution: {integrity: sha512-Ds+gBRbj0lwRO2Y5hwnUBdxSwlAve9LeRyU4sNnAr0ewW0gWF0n5bgXgUzbgZ49MV9BVUAQUFYVcDUcilUExMA==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -2625,11 +4213,19 @@ packages:
   vscode-languageserver-types@3.18.0:
     resolution: {integrity: sha512-8TsGPNMIMiiBdkORgRSvLjuiEIiAFtO+KssmYWxQ+uSVvlf7RjK8YKCOjPzZ+YA04jXEV7+7LvkSmHkhpNS99g==}
 
+  webpack-virtual-modules@0.6.2:
+    resolution: {integrity: sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ==}
+
   which@2.0.2:
     resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
     engines: {node: '>= 8'}
     hasBin: true
 
+  which@4.0.0:
+    resolution: {integrity: sha512-GlaYyEb07DPxYCKhKzplCWBJtvxZcZMrL+4UkrTSJHHPyZU4mYYTv3qaOe77H7EODLSSopAUFAc6W8U4yqvscg==}
+    engines: {node: ^16.13.0 || >=18.0.0}
+    hasBin: true
+
   why-is-node-running@2.3.0:
     resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==}
     engines: {node: '>=8'}
@@ -2642,10 +4238,17 @@ packages:
   wrappy@1.0.2:
     resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==}
 
+  wsl-utils@0.3.1:
+    resolution: {integrity: sha512-g/eziiSUNBSsdDJtCLB8bdYEUMj4jR7AGeUo96p/3dTafgjHhpF4RiCFPiRILwjQoDXx5MqkBr4fwWtR3Ky4Wg==}
+    engines: {node: '>=20'}
+
   y18n@5.0.8:
     resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
     engines: {node: '>=10'}
 
+  yallist@3.1.1:
+    resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
+
   yallist@5.0.0:
     resolution: {integrity: sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==}
     engines: {node: '>=18'}
@@ -2663,17 +4266,242 @@ packages:
     resolution: {integrity: sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g==}
     engines: {node: '>=12'}
 
+  yocto-spinner@1.2.1:
+    resolution: {integrity: sha512-9cbFWLhbiZp+820O4pkHGNncI7+MrUGzBOjw8NMG+ewsY+aG0DdEXnr19Smxao32YOjLZRMdn1UtaxcrXOYOIg==}
+    engines: {node: '>=18.19'}
+
   yoctocolors@2.1.2:
     resolution: {integrity: sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==}
     engines: {node: '>=18'}
 
+  zod-to-json-schema@3.25.2:
+    resolution: {integrity: sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==}
+    peerDependencies:
+      zod: ^3.25.28 || ^4
+
+  zod@3.25.76:
+    resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
+
   zod@4.4.3:
     resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}
 
 snapshots:
 
+  '@babel/code-frame@7.29.7':
+    dependencies:
+      '@babel/helper-validator-identifier': 7.29.7
+      js-tokens: 4.0.0
+      picocolors: 1.1.1
+
+  '@babel/compat-data@7.29.7': {}
+
+  '@babel/core@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-compilation-targets': 7.29.7
+      '@babel/helper-module-transforms': 7.29.7(@babel/core@7.29.7)
+      '@babel/helpers': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+      '@jridgewell/remapping': 2.3.5
+      convert-source-map: 2.0.0
+      debug: 4.4.3
+      gensync: 1.0.0-beta.2
+      json5: 2.2.3
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/generator@7.29.7':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      jsesc: 3.1.0
+
+  '@babel/helper-annotate-as-pure@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@babel/helper-compilation-targets@7.29.7':
+    dependencies:
+      '@babel/compat-data': 7.29.7
+      '@babel/helper-validator-option': 7.29.7
+      browserslist: 4.28.5
+      lru-cache: 5.1.1
+      semver: 6.3.1
+
+  '@babel/helper-create-class-features-plugin@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-annotate-as-pure': 7.29.7
+      '@babel/helper-member-expression-to-functions': 7.29.7
+      '@babel/helper-optimise-call-expression': 7.29.7
+      '@babel/helper-replace-supers': 7.29.7(@babel/core@7.29.7)
+      '@babel/helper-skip-transparent-expression-wrappers': 7.29.7
+      '@babel/traverse': 7.29.7
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-globals@7.29.7': {}
+
+  '@babel/helper-member-expression-to-functions@7.29.7':
+    dependencies:
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-imports@7.29.7':
+    dependencies:
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-transforms@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-module-imports': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+      '@babel/traverse': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-optimise-call-expression@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@babel/helper-plugin-utils@7.29.7': {}
+
+  '@babel/helper-replace-supers@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-member-expression-to-functions': 7.29.7
+      '@babel/helper-optimise-call-expression': 7.29.7
+      '@babel/traverse': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-skip-transparent-expression-wrappers@7.29.7':
+    dependencies:
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-string-parser@7.29.7': {}
+
+  '@babel/helper-validator-identifier@7.29.7': {}
+
+  '@babel/helper-validator-option@7.29.7': {}
+
+  '@babel/helpers@7.29.7':
+    dependencies:
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@babel/parser@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-plugin-utils': 7.29.7
+
+  '@babel/plugin-syntax-typescript@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-plugin-utils': 7.29.7
+
+  '@babel/plugin-transform-modules-commonjs@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-module-transforms': 7.29.7(@babel/core@7.29.7)
+      '@babel/helper-plugin-utils': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/plugin-transform-typescript@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-annotate-as-pure': 7.29.7
+      '@babel/helper-create-class-features-plugin': 7.29.7(@babel/core@7.29.7)
+      '@babel/helper-plugin-utils': 7.29.7
+      '@babel/helper-skip-transparent-expression-wrappers': 7.29.7
+      '@babel/plugin-syntax-typescript': 7.29.7(@babel/core@7.29.7)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/preset-typescript@7.29.7(@babel/core@7.29.7)':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/helper-plugin-utils': 7.29.7
+      '@babel/helper-validator-option': 7.29.7
+      '@babel/plugin-syntax-jsx': 7.29.7(@babel/core@7.29.7)
+      '@babel/plugin-transform-modules-commonjs': 7.29.7(@babel/core@7.29.7)
+      '@babel/plugin-transform-typescript': 7.29.7(@babel/core@7.29.7)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/runtime@7.29.7': {}
+
+  '@babel/template@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@babel/traverse@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-globals': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/types@7.29.7':
+    dependencies:
+      '@babel/helper-string-parser': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+
   '@balena/dockerignore@1.0.2': {}
 
+  '@base-ui/react@1.6.0(@date-fns/tz@1.5.0)(@types/react@19.2.17)(date-fns@4.4.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@base-ui/utils': 0.3.1(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@floating-ui/react-dom': 2.1.8(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@floating-ui/utils': 0.2.11
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      use-sync-external-store: 1.6.0(react@19.2.7)
+    optionalDependencies:
+      '@date-fns/tz': 1.5.0
+      '@types/react': 19.2.17
+      date-fns: 4.4.0
+
+  '@base-ui/utils@0.3.1(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@floating-ui/utils': 0.2.11
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      reselect: 5.2.0
+      use-sync-external-store: 1.6.0(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+
   '@biomejs/biome@2.5.2':
     optionalDependencies:
       '@biomejs/cli-darwin-arm64': 2.5.2
@@ -2720,6 +4548,29 @@ snapshots:
     dependencies:
       '@bufbuild/protobuf': 2.12.1
 
+  '@date-fns/tz@1.5.0': {}
+
+  '@dotenvx/dotenvx@1.75.1':
+    dependencies:
+      '@dotenvx/primitives': 0.8.0
+      commander: 11.1.0
+      conf: 10.2.0
+      dotenv: 17.4.2
+      enquirer: 2.4.1
+      env-paths: 2.2.1
+      execa: 5.1.1
+      fdir: 6.5.0(picomatch@4.0.5)
+      ignore: 5.3.2
+      object-treeify: 1.1.33
+      open: 8.4.2
+      picomatch: 4.0.5
+      systeminformation: 5.31.15
+      undici: 7.28.0
+      which: 4.0.0
+      yocto-spinner: 1.2.1
+
+  '@dotenvx/primitives@0.8.0': {}
+
   '@drizzle-team/brocli@0.10.2': {}
 
   '@emnapi/core@1.11.1':
@@ -3117,6 +4968,25 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  '@floating-ui/core@1.7.5':
+    dependencies:
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/dom@1.7.6':
+    dependencies:
+      '@floating-ui/core': 1.7.5
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/react-dom@2.1.8(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@floating-ui/dom': 1.7.6
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
+  '@floating-ui/utils@0.2.11': {}
+
+  '@fontsource-variable/inter@5.2.8': {}
+
   '@grpc/grpc-js@1.14.4':
     dependencies:
       '@grpc/proto-loader': 0.8.1
@@ -3136,6 +5006,16 @@ snapshots:
       protobufjs: 7.6.5
       yargs: 17.7.3
 
+  '@hono/node-server@1.19.14(hono@4.12.28)':
+    dependencies:
+      hono: 4.12.28
+
+  '@hugeicons/core-free-icons@4.2.2': {}
+
+  '@hugeicons/react@1.1.9(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+
   '@isaacs/cliui@9.0.0': {}
 
   '@isaacs/fs-minipass@4.0.1':
@@ -3165,6 +5045,28 @@ snapshots:
 
   '@lukeed/ms@2.0.2': {}
 
+  '@modelcontextprotocol/sdk@1.29.0(zod@3.25.76)':
+    dependencies:
+      '@hono/node-server': 1.19.14(hono@4.12.28)
+      ajv: 8.20.0
+      ajv-formats: 3.0.1(ajv@8.20.0)
+      content-type: 1.0.5
+      cors: 2.8.6
+      cross-spawn: 7.0.6
+      eventsource: 3.0.7
+      eventsource-parser: 3.1.0
+      express: 5.2.1
+      express-rate-limit: 8.5.2(express@5.2.1)
+      hono: 4.12.28
+      jose: 6.2.3
+      json-schema-typed: 8.0.2
+      pkce-challenge: 5.0.1
+      raw-body: 3.0.2
+      zod: 3.25.76
+      zod-to-json-schema: 3.25.2(zod@3.25.76)
+    transitivePeerDependencies:
+      - supports-color
+
   '@napi-rs/wasm-runtime@1.1.6(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
     dependencies:
       '@emnapi/core': 1.11.1
@@ -3172,6 +5074,18 @@ snapshots:
       '@tybys/wasm-util': 0.10.3
     optional: true
 
+  '@nodelib/fs.scandir@2.1.5':
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      run-parallel: 1.2.0
+
+  '@nodelib/fs.stat@2.0.5': {}
+
+  '@nodelib/fs.walk@1.2.8':
+    dependencies:
+      '@nodelib/fs.scandir': 2.1.5
+      fastq: 1.20.1
+
   '@oxc-project/types@0.138.0': {}
 
   '@pinojs/redact@0.4.0': {}
@@ -3196,6 +5110,153 @@ snapshots:
 
   '@protobufjs/utf8@1.1.2': {}
 
+  '@radix-ui/primitive@1.1.5': {}
+
+  '@radix-ui/react-compose-refs@1.1.3(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-context@1.2.0(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-dialog@1.1.19(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.5
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-dismissable-layer': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-focus-guards': 1.1.4(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-focus-scope': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-portal': 1.1.13(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
+      aria-hidden: 1.2.6
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      react-remove-scroll: 2.7.2(@types/react@19.2.17)(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-dismissable-layer@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.5
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-focus-guards@1.1.4(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-focus-scope@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-id@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-portal@1.1.13(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-presence@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-primitive@2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-slot@1.3.0(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-use-callback-ref@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-use-controllable-state@1.2.3(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-use-effect-event@0.0.3(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-use-layout-effect@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@reduxjs/toolkit@2.12.0(react-redux@9.3.0(@types/react@19.2.17)(react@19.2.7)(redux@5.0.1))(react@19.2.7)':
+    dependencies:
+      '@standard-schema/spec': 1.1.0
+      '@standard-schema/utils': 0.3.0
+      immer: 11.1.11
+      redux: 5.0.1
+      redux-thunk: 3.1.0(redux@5.0.1)
+      reselect: 5.2.0
+    optionalDependencies:
+      react: 19.2.7
+      react-redux: 9.3.0(@types/react@19.2.17)(react@19.2.7)(redux@5.0.1)
+
   '@rolldown/binding-android-arm64@1.1.4':
     optional: true
 
@@ -3324,10 +5385,17 @@ snapshots:
 
   '@sec-ant/readable-stream@0.4.1': {}
 
+  '@shadcn/react@0.2.1(@types/react@19.2.17)(react@19.2.7)':
+    optionalDependencies:
+      '@types/react': 19.2.17
+      react: 19.2.7
+
   '@sindresorhus/merge-streams@4.0.0': {}
 
   '@standard-schema/spec@1.1.0': {}
 
+  '@standard-schema/utils@0.3.0': {}
+
   '@tailwindcss/node@4.3.2':
     dependencies:
       '@jridgewell/remapping': 2.3.5
@@ -3428,8 +5496,66 @@ snapshots:
       seroval: 1.5.4
       seroval-plugins: 1.5.4(seroval@1.5.4)
 
+  '@tanstack/router-generator@1.167.18':
+    dependencies:
+      '@babel/types': 7.29.7
+      '@tanstack/router-core': 1.171.14
+      '@tanstack/router-utils': 1.162.2
+      '@tanstack/virtual-file-routes': 1.162.0
+      jiti: 2.7.0
+      magic-string: 0.30.21
+      prettier: 3.9.4
+      zod: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@tanstack/router-plugin@1.168.19(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(esbuild@0.28.1)(rolldown@1.1.4)(rollup@4.62.2)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))':
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+      '@tanstack/router-core': 1.171.14
+      '@tanstack/router-generator': 1.167.18
+      '@tanstack/router-utils': 1.162.2
+      chokidar: 5.0.0
+      unplugin: 3.3.0(esbuild@0.28.1)(rolldown@1.1.4)(rollup@4.62.2)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
+      zod: 4.4.3
+    optionalDependencies:
+      '@tanstack/react-router': 1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      vite: 8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - '@farmfe/core'
+      - '@rspack/core'
+      - bun-types-no-globals
+      - esbuild
+      - rolldown
+      - rollup
+      - supports-color
+      - unloader
+
+  '@tanstack/router-utils@1.162.2':
+    dependencies:
+      '@babel/generator': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+      ansis: 4.3.1
+      babel-dead-code-elimination: 1.0.12
+      diff: 8.0.4
+      pathe: 2.0.3
+      tinyglobby: 0.2.17
+    transitivePeerDependencies:
+      - supports-color
+
   '@tanstack/store@0.9.3': {}
 
+  '@tanstack/virtual-file-routes@1.162.0': {}
+
+  '@ts-morph/common@0.27.0':
+    dependencies:
+      fast-glob: 3.3.3
+      minimatch: 10.2.5
+      path-browserify: 1.0.1
+
   '@tybys/wasm-util@0.10.3':
     dependencies:
       tslib: 2.8.1
@@ -3444,6 +5570,30 @@ snapshots:
       '@types/deep-eql': 4.0.2
       assertion-error: 2.0.1
 
+  '@types/d3-array@3.2.2': {}
+
+  '@types/d3-color@3.1.3': {}
+
+  '@types/d3-ease@3.0.2': {}
+
+  '@types/d3-interpolate@3.0.4':
+    dependencies:
+      '@types/d3-color': 3.1.3
+
+  '@types/d3-path@3.1.1': {}
+
+  '@types/d3-scale@4.0.9':
+    dependencies:
+      '@types/d3-time': 3.0.4
+
+  '@types/d3-shape@3.1.8':
+    dependencies:
+      '@types/d3-path': 3.1.1
+
+  '@types/d3-time@3.0.4': {}
+
+  '@types/d3-timer@3.0.2': {}
+
   '@types/deep-eql@4.0.2': {}
 
   '@types/docker-modem@3.0.6':
@@ -3479,6 +5629,10 @@ snapshots:
     dependencies:
       '@types/node': 18.19.130
 
+  '@types/use-sync-external-store@0.0.6': {}
+
+  '@types/validate-npm-package-name@4.0.2': {}
+
   '@vitejs/plugin-react@6.0.3(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))':
     dependencies:
       '@rolldown/pluginutils': 1.0.1
@@ -3527,8 +5681,17 @@ snapshots:
 
   abstract-logging@2.0.1: {}
 
+  accepts@2.0.0:
+    dependencies:
+      mime-types: 3.0.2
+      negotiator: 1.0.0
+
   acorn@8.17.0: {}
 
+  ajv-formats@2.1.1(ajv@8.20.0):
+    optionalDependencies:
+      ajv: 8.20.0
+
   ajv-formats@3.0.1(ajv@8.20.0):
     optionalDependencies:
       ajv: 8.20.0
@@ -3540,31 +5703,60 @@ snapshots:
       json-schema-traverse: 1.0.0
       require-from-string: 2.0.2
 
+  ansi-colors@4.1.3: {}
+
   ansi-regex@5.0.1: {}
 
+  ansi-regex@6.2.2: {}
+
   ansi-styles@4.3.0:
     dependencies:
       color-convert: 2.0.1
 
+  ansis@4.3.1: {}
+
   any-promise@1.3.0: {}
 
+  argparse@2.0.1: {}
+
+  aria-hidden@1.2.6:
+    dependencies:
+      tslib: 2.8.1
+
   asn1@0.2.6:
     dependencies:
       safer-buffer: 2.1.2
 
   assertion-error@2.0.1: {}
 
+  ast-types@0.16.1:
+    dependencies:
+      tslib: 2.8.1
+
   atomic-sleep@1.0.0: {}
 
+  atomically@1.7.0: {}
+
   avvio@9.2.0:
     dependencies:
       '@fastify/error': 4.2.0
       fastq: 1.20.1
 
+  babel-dead-code-elimination@1.0.12:
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/traverse': 7.29.7
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
   balanced-match@4.0.4: {}
 
   base64-js@1.5.1: {}
 
+  baseline-browser-mapping@2.10.42: {}
+
   bcrypt-pbkdf@1.0.2:
     dependencies:
       tweetnacl: 0.14.5
@@ -3584,10 +5776,36 @@ snapshots:
       inherits: 2.0.4
       readable-stream: 3.6.2
 
+  body-parser@2.3.0:
+    dependencies:
+      bytes: 3.1.2
+      content-type: 2.0.0
+      debug: 4.4.3
+      http-errors: 2.0.1
+      iconv-lite: 0.7.3
+      on-finished: 2.4.1
+      qs: 6.15.3
+      raw-body: 3.0.2
+      type-is: 2.1.0
+    transitivePeerDependencies:
+      - supports-color
+
   brace-expansion@5.0.7:
     dependencies:
       balanced-match: 4.0.4
 
+  braces@3.0.3:
+    dependencies:
+      fill-range: 7.1.1
+
+  browserslist@4.28.5:
+    dependencies:
+      baseline-browser-mapping: 2.10.42
+      caniuse-lite: 1.0.30001803
+      electron-to-chromium: 1.5.389
+      node-releases: 2.0.50
+      update-browserslist-db: 1.2.3(browserslist@4.28.5)
+
   buffer-from@1.1.2: {}
 
   buffer@5.7.1:
@@ -3598,13 +5816,33 @@ snapshots:
   buildcheck@0.0.7:
     optional: true
 
+  bundle-name@4.1.0:
+    dependencies:
+      run-applescript: 7.1.0
+
   bundle-require@5.1.0(esbuild@0.27.7):
     dependencies:
       esbuild: 0.27.7
       load-tsconfig: 0.2.5
 
+  bytes@3.1.2: {}
+
   cac@6.7.14: {}
 
+  call-bind-apply-helpers@1.0.2:
+    dependencies:
+      es-errors: 1.3.0
+      function-bind: 1.1.2
+
+  call-bound@1.0.4:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      get-intrinsic: 1.3.0
+
+  callsites@3.1.0: {}
+
+  caniuse-lite@1.0.30001803: {}
+
   chai@6.2.2: {}
 
   chalk@5.6.2: {}
@@ -3613,40 +5851,107 @@ snapshots:
     dependencies:
       readdirp: 4.1.2
 
+  chokidar@5.0.0:
+    dependencies:
+      readdirp: 5.0.0
+
   chownr@1.1.4: {}
 
   chownr@3.0.0: {}
 
+  class-variance-authority@0.7.1:
+    dependencies:
+      clsx: 2.1.1
+
+  cli-cursor@5.0.0:
+    dependencies:
+      restore-cursor: 5.1.0
+
+  cli-spinners@2.9.2: {}
+
   cliui@8.0.1:
     dependencies:
       string-width: 4.2.3
       strip-ansi: 6.0.1
       wrap-ansi: 7.0.0
 
+  clsx@2.1.1: {}
+
+  cmdk@1.1.1(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-dialog': 1.1.19(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    transitivePeerDependencies:
+      - '@types/react'
+      - '@types/react-dom'
+
+  code-block-writer@13.0.3: {}
+
   color-convert@2.0.1:
     dependencies:
       color-name: 1.1.4
 
   color-name@1.1.4: {}
 
+  commander@11.1.0: {}
+
   commander@14.0.3: {}
 
   commander@4.1.1: {}
 
   compare-versions@6.1.1: {}
 
+  conf@10.2.0:
+    dependencies:
+      ajv: 8.20.0
+      ajv-formats: 2.1.1(ajv@8.20.0)
+      atomically: 1.7.0
+      debounce-fn: 4.0.0
+      dot-prop: 6.0.1
+      env-paths: 2.2.1
+      json-schema-typed: 7.0.3
+      onetime: 5.1.2
+      pkg-up: 3.1.0
+      semver: 7.8.5
+
   confbox@0.1.8: {}
 
   consola@3.4.2: {}
 
   content-disposition@1.1.0: {}
 
+  content-type@1.0.5: {}
+
+  content-type@2.0.0: {}
+
   convert-source-map@2.0.0: {}
 
   cookie-es@3.1.1: {}
 
+  cookie-signature@1.2.2: {}
+
+  cookie@0.7.2: {}
+
   cookie@1.1.1: {}
 
+  cors@2.8.6:
+    dependencies:
+      object-assign: 4.1.1
+      vary: 1.1.2
+
+  cosmiconfig@9.0.2(typescript@6.0.3):
+    dependencies:
+      env-paths: 2.2.1
+      import-fresh: 3.3.1
+      js-yaml: 4.3.0
+      parse-json: 5.2.0
+    optionalDependencies:
+      typescript: 6.0.3
+
   cpu-features@0.0.10:
     dependencies:
       buildcheck: 0.0.7
@@ -3659,24 +5964,91 @@ snapshots:
       shebang-command: 2.0.0
       which: 2.0.2
 
+  cssesc@3.0.0: {}
+
   csstype@3.2.3: {}
 
+  d3-array@3.2.4:
+    dependencies:
+      internmap: 2.0.3
+
+  d3-color@3.1.0: {}
+
+  d3-ease@3.0.1: {}
+
+  d3-format@3.1.2: {}
+
+  d3-interpolate@3.0.1:
+    dependencies:
+      d3-color: 3.1.0
+
+  d3-path@3.1.0: {}
+
+  d3-scale@4.0.2:
+    dependencies:
+      d3-array: 3.2.4
+      d3-format: 3.1.2
+      d3-interpolate: 3.0.1
+      d3-time: 3.1.0
+      d3-time-format: 4.1.0
+
+  d3-shape@3.2.0:
+    dependencies:
+      d3-path: 3.1.0
+
+  d3-time-format@4.1.0:
+    dependencies:
+      d3-time: 3.1.0
+
+  d3-time@3.1.0:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-timer@3.0.1: {}
+
+  date-fns@4.4.0: {}
+
+  debounce-fn@4.0.0:
+    dependencies:
+      mimic-fn: 3.1.0
+
   debug@4.4.3:
     dependencies:
       ms: 2.1.3
 
+  decimal.js-light@2.5.1: {}
+
   decompress-response@6.0.0:
     dependencies:
       mimic-response: 3.1.0
 
+  dedent@1.7.2: {}
+
   deep-extend@0.6.0: {}
 
+  deepmerge@4.3.1: {}
+
+  default-browser-id@5.0.1: {}
+
+  default-browser@5.5.0:
+    dependencies:
+      bundle-name: 4.1.0
+      default-browser-id: 5.0.1
+
+  define-lazy-prop@2.0.0: {}
+
+  define-lazy-prop@3.0.0: {}
+
   depd@2.0.0: {}
 
   dequal@2.0.3: {}
 
   detect-libc@2.1.2: {}
 
+  detect-node-es@1.1.0: {}
+
+  diff@8.0.4: {}
+
   docker-modem@5.0.7:
     dependencies:
       debug: 4.4.3
@@ -3702,6 +6074,12 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  dot-prop@6.0.1:
+    dependencies:
+      is-obj: 2.0.0
+
+  dotenv@17.4.2: {}
+
   drizzle-kit@0.31.10:
     dependencies:
       '@drizzle-team/brocli': 0.10.2
@@ -3714,6 +6092,12 @@ snapshots:
       '@types/better-sqlite3': 7.6.13
       better-sqlite3: 12.11.1
 
+  dunder-proto@1.0.1:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-errors: 1.3.0
+      gopd: 1.2.0
+
   e2b@2.31.0:
     dependencies:
       '@bufbuild/protobuf': 2.12.1
@@ -3728,8 +6112,28 @@ snapshots:
       tar: 7.5.19
       undici: 7.28.0
 
+  ee-first@1.1.1: {}
+
+  electron-to-chromium@1.5.389: {}
+
+  embla-carousel-react@8.6.0(react@19.2.7):
+    dependencies:
+      embla-carousel: 8.6.0
+      embla-carousel-reactive-utils: 8.6.0(embla-carousel@8.6.0)
+      react: 19.2.7
+
+  embla-carousel-reactive-utils@8.6.0(embla-carousel@8.6.0):
+    dependencies:
+      embla-carousel: 8.6.0
+
+  embla-carousel@8.6.0: {}
+
+  emoji-regex@10.6.0: {}
+
   emoji-regex@8.0.0: {}
 
+  encodeurl@2.0.0: {}
+
   end-of-stream@1.4.5:
     dependencies:
       once: 1.4.0
@@ -3739,8 +6143,29 @@ snapshots:
       graceful-fs: 4.2.11
       tapable: 2.3.3
 
+  enquirer@2.4.1:
+    dependencies:
+      ansi-colors: 4.1.3
+      strip-ansi: 6.0.1
+
+  env-paths@2.2.1: {}
+
+  error-ex@1.3.4:
+    dependencies:
+      is-arrayish: 0.2.1
+
+  es-define-property@1.0.1: {}
+
+  es-errors@1.3.0: {}
+
   es-module-lexer@2.3.0: {}
 
+  es-object-atoms@1.1.2:
+    dependencies:
+      es-errors: 1.3.0
+
+  es-toolkit@1.49.0: {}
+
   esbuild@0.18.20:
     optionalDependencies:
       '@esbuild/android-arm': 0.18.20
@@ -3857,10 +6282,34 @@ snapshots:
 
   escape-html@1.0.3: {}
 
+  esprima@4.0.1: {}
+
   estree-walker@3.0.3:
     dependencies:
       '@types/estree': 1.0.9
 
+  etag@1.8.1: {}
+
+  eventemitter3@5.0.4: {}
+
+  eventsource-parser@3.1.0: {}
+
+  eventsource@3.0.7:
+    dependencies:
+      eventsource-parser: 3.1.0
+
+  execa@5.1.1:
+    dependencies:
+      cross-spawn: 7.0.6
+      get-stream: 6.0.1
+      human-signals: 2.1.0
+      is-stream: 2.0.1
+      merge-stream: 2.0.0
+      npm-run-path: 4.0.1
+      onetime: 5.1.2
+      signal-exit: 3.0.7
+      strip-final-newline: 2.0.0
+
   execa@9.6.1:
     dependencies:
       '@sindresorhus/merge-streams': 4.0.0
@@ -3880,10 +6329,56 @@ snapshots:
 
   expect-type@1.4.0: {}
 
+  express-rate-limit@8.5.2(express@5.2.1):
+    dependencies:
+      express: 5.2.1
+      ip-address: 10.2.0
+
+  express@5.2.1:
+    dependencies:
+      accepts: 2.0.0
+      body-parser: 2.3.0
+      content-disposition: 1.1.0
+      content-type: 1.0.5
+      cookie: 0.7.2
+      cookie-signature: 1.2.2
+      debug: 4.4.3
+      depd: 2.0.0
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      finalhandler: 2.1.1
+      fresh: 2.0.0
+      http-errors: 2.0.1
+      merge-descriptors: 2.0.0
+      mime-types: 3.0.2
+      on-finished: 2.4.1
+      once: 1.4.0
+      parseurl: 1.3.3
+      proxy-addr: 2.0.7
+      qs: 6.15.3
+      range-parser: 1.3.0
+      router: 2.2.0
+      send: 1.2.1
+      serve-static: 2.2.1
+      statuses: 2.0.2
+      type-is: 2.1.0
+      vary: 1.1.2
+    transitivePeerDependencies:
+      - supports-color
+
   fast-decode-uri-component@1.0.1: {}
 
   fast-deep-equal@3.1.3: {}
 
+  fast-glob@3.3.3:
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      '@nodelib/fs.walk': 1.2.8
+      glob-parent: 5.1.2
+      merge2: 1.4.1
+      micromatch: 4.0.8
+
   fast-json-stringify@7.0.0:
     dependencies:
       '@fastify/merge-json-schemas': 0.2.1
@@ -3941,12 +6436,31 @@ snapshots:
 
   file-uri-to-path@1.0.0: {}
 
+  fill-range@7.1.1:
+    dependencies:
+      to-regex-range: 5.0.1
+
+  finalhandler@2.1.1:
+    dependencies:
+      debug: 4.4.3
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      on-finished: 2.4.1
+      parseurl: 1.3.3
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
   find-my-way@9.6.0:
     dependencies:
       fast-deep-equal: 3.1.3
       fast-querystring: 1.1.2
       safe-regex2: 5.1.1
 
+  find-up@3.0.0:
+    dependencies:
+      locate-path: 3.0.0
+
   fix-dts-default-cjs-exports@1.0.1:
     dependencies:
       magic-string: 0.30.21
@@ -3958,13 +6472,55 @@ snapshots:
       cross-spawn: 7.0.6
       signal-exit: 4.1.0
 
+  forwarded@0.2.0: {}
+
+  fresh@2.0.0: {}
+
   fs-constants@1.0.0: {}
 
+  fs-extra@11.3.6:
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 6.2.1
+      universalify: 2.0.1
+
   fsevents@2.3.3:
     optional: true
 
+  function-bind@1.1.2: {}
+
+  fuzzysort@3.1.0: {}
+
+  gensync@1.0.0-beta.2: {}
+
   get-caller-file@2.0.5: {}
 
+  get-east-asian-width@1.6.0: {}
+
+  get-intrinsic@1.3.0:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.2
+      function-bind: 1.1.2
+      get-proto: 1.0.1
+      gopd: 1.2.0
+      has-symbols: 1.1.0
+      hasown: 2.0.4
+      math-intrinsics: 1.1.0
+
+  get-nonce@1.0.1: {}
+
+  get-own-enumerable-keys@1.0.0: {}
+
+  get-proto@1.0.1:
+    dependencies:
+      dunder-proto: 1.0.1
+      es-object-atoms: 1.1.2
+
+  get-stream@6.0.1: {}
+
   get-stream@9.0.1:
     dependencies:
       '@sec-ant/readable-stream': 0.4.1
@@ -3976,6 +6532,10 @@ snapshots:
 
   github-from-package@0.0.0: {}
 
+  glob-parent@5.1.2:
+    dependencies:
+      is-glob: 4.0.3
+
   glob@11.1.0:
     dependencies:
       foreground-child: 3.3.1
@@ -3991,8 +6551,18 @@ snapshots:
       minipass: 7.1.3
       path-scurry: 2.0.2
 
+  gopd@1.2.0: {}
+
   graceful-fs@4.2.11: {}
 
+  has-symbols@1.1.0: {}
+
+  hasown@2.0.4:
+    dependencies:
+      function-bind: 1.1.2
+
+  hono@4.12.28: {}
+
   http-errors@2.0.1:
     dependencies:
       depd: 2.0.0
@@ -4001,35 +6571,119 @@ snapshots:
       statuses: 2.0.2
       toidentifier: 1.0.1
 
+  human-signals@2.1.0: {}
+
   human-signals@8.0.1: {}
 
+  iconv-lite@0.7.3:
+    dependencies:
+      safer-buffer: 2.1.2
+
   ieee754@1.2.1: {}
 
+  ignore@5.3.2: {}
+
+  immer@10.2.0: {}
+
+  immer@11.1.11: {}
+
+  import-fresh@3.3.1:
+    dependencies:
+      parent-module: 1.0.1
+      resolve-from: 4.0.0
+
   inherits@2.0.4: {}
 
   ini@1.3.8: {}
 
+  input-otp@1.4.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
+  internmap@2.0.3: {}
+
+  ip-address@10.2.0: {}
+
+  ipaddr.js@1.9.1: {}
+
   ipaddr.js@2.4.0: {}
 
+  is-arrayish@0.2.1: {}
+
+  is-docker@2.2.1: {}
+
+  is-docker@3.0.0: {}
+
+  is-extglob@2.1.1: {}
+
   is-fullwidth-code-point@3.0.0: {}
 
+  is-glob@4.0.3:
+    dependencies:
+      is-extglob: 2.1.1
+
+  is-in-ssh@1.0.0: {}
+
+  is-inside-container@1.0.0:
+    dependencies:
+      is-docker: 3.0.0
+
+  is-interactive@2.0.0: {}
+
+  is-number@7.0.0: {}
+
+  is-obj@2.0.0: {}
+
+  is-obj@3.0.0: {}
+
   is-plain-obj@4.1.0: {}
 
+  is-promise@4.0.0: {}
+
+  is-regexp@3.1.0: {}
+
+  is-stream@2.0.1: {}
+
   is-stream@4.0.1: {}
 
+  is-unicode-supported@1.3.0: {}
+
   is-unicode-supported@2.1.0: {}
 
+  is-wsl@2.2.0:
+    dependencies:
+      is-docker: 2.2.1
+
+  is-wsl@3.1.1:
+    dependencies:
+      is-inside-container: 1.0.0
+
   isbot@5.2.0: {}
 
   isexe@2.0.0: {}
 
-  jackspeak@4.2.3:
+  isexe@3.1.5: {}
+
+  jackspeak@4.2.3:
+    dependencies:
+      '@isaacs/cliui': 9.0.0
+
+  jiti@2.7.0: {}
+
+  jose@6.2.3: {}
+
+  joycon@3.1.1: {}
+
+  js-tokens@4.0.0: {}
+
+  js-yaml@4.3.0:
     dependencies:
-      '@isaacs/cliui': 9.0.0
+      argparse: 2.0.1
 
-  jiti@2.7.0: {}
+  jsesc@3.1.0: {}
 
-  joycon@3.1.1: {}
+  json-parse-even-better-errors@2.3.1: {}
 
   json-schema-ref-resolver@3.0.0:
     dependencies:
@@ -4045,6 +6699,22 @@ snapshots:
 
   json-schema-traverse@1.0.0: {}
 
+  json-schema-typed@7.0.3: {}
+
+  json-schema-typed@8.0.2: {}
+
+  json5@2.2.3: {}
+
+  jsonfile@6.2.1:
+    dependencies:
+      universalify: 2.0.1
+    optionalDependencies:
+      graceful-fs: 4.2.11
+
+  kleur@3.0.3: {}
+
+  kleur@4.1.5: {}
+
   light-my-request@6.6.0:
     dependencies:
       cookie: 1.1.1
@@ -4106,18 +6776,59 @@ snapshots:
 
   load-tsconfig@0.2.5: {}
 
+  locate-path@3.0.0:
+    dependencies:
+      p-locate: 3.0.0
+      path-exists: 3.0.0
+
   lodash.camelcase@4.3.0: {}
 
+  log-symbols@6.0.0:
+    dependencies:
+      chalk: 5.6.2
+      is-unicode-supported: 1.3.0
+
   long@5.3.2: {}
 
   lru-cache@11.5.2: {}
 
+  lru-cache@5.1.1:
+    dependencies:
+      yallist: 3.1.1
+
   magic-string@0.30.21:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  math-intrinsics@1.1.0: {}
+
+  media-typer@1.1.0: {}
+
+  merge-descriptors@2.0.0: {}
+
+  merge-stream@2.0.0: {}
+
+  merge2@1.4.1: {}
+
+  micromatch@4.0.8:
+    dependencies:
+      braces: 3.0.3
+      picomatch: 2.3.2
+
+  mime-db@1.54.0: {}
+
+  mime-types@3.0.2:
+    dependencies:
+      mime-db: 1.54.0
+
   mime@3.0.0: {}
 
+  mimic-fn@2.1.0: {}
+
+  mimic-fn@3.1.0: {}
+
+  mimic-function@5.0.1: {}
+
   mimic-response@3.1.0: {}
 
   minimatch@10.2.5:
@@ -4156,10 +6867,23 @@ snapshots:
 
   napi-build-utils@2.0.0: {}
 
+  negotiator@1.0.0: {}
+
+  next-themes@0.4.6(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
   node-abi@3.94.0:
     dependencies:
       semver: 7.8.5
 
+  node-releases@2.0.50: {}
+
+  npm-run-path@4.0.1:
+    dependencies:
+      path-key: 3.1.1
+
   npm-run-path@6.0.0:
     dependencies:
       path-key: 4.0.0
@@ -4167,14 +6891,45 @@ snapshots:
 
   object-assign@4.1.1: {}
 
+  object-inspect@1.13.4: {}
+
+  object-treeify@1.1.33: {}
+
   obug@2.1.3: {}
 
   on-exit-leak-free@2.1.2: {}
 
+  on-finished@2.4.1:
+    dependencies:
+      ee-first: 1.1.1
+
   once@1.4.0:
     dependencies:
       wrappy: 1.0.2
 
+  onetime@5.1.2:
+    dependencies:
+      mimic-fn: 2.1.0
+
+  onetime@7.0.0:
+    dependencies:
+      mimic-function: 5.0.1
+
+  open@11.0.0:
+    dependencies:
+      default-browser: 5.5.0
+      define-lazy-prop: 3.0.0
+      is-in-ssh: 1.0.0
+      is-inside-container: 1.0.0
+      powershell-utils: 0.1.0
+      wsl-utils: 0.3.1
+
+  open@8.4.2:
+    dependencies:
+      define-lazy-prop: 2.0.0
+      is-docker: 2.2.1
+      is-wsl: 2.2.0
+
   openapi-fetch@0.14.1:
     dependencies:
       openapi-typescript-helpers: 0.0.15
@@ -4183,10 +6938,49 @@ snapshots:
 
   openapi-typescript-helpers@0.0.15: {}
 
+  ora@8.2.0:
+    dependencies:
+      chalk: 5.6.2
+      cli-cursor: 5.0.0
+      cli-spinners: 2.9.2
+      is-interactive: 2.0.0
+      is-unicode-supported: 2.1.0
+      log-symbols: 6.0.0
+      stdin-discarder: 0.2.2
+      string-width: 7.2.0
+      strip-ansi: 7.2.0
+
+  p-limit@2.3.0:
+    dependencies:
+      p-try: 2.2.0
+
+  p-locate@3.0.0:
+    dependencies:
+      p-limit: 2.3.0
+
+  p-try@2.2.0: {}
+
   package-json-from-dist@1.0.1: {}
 
+  parent-module@1.0.1:
+    dependencies:
+      callsites: 3.1.0
+
+  parse-json@5.2.0:
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      error-ex: 1.3.4
+      json-parse-even-better-errors: 2.3.1
+      lines-and-columns: 1.2.4
+
   parse-ms@4.0.0: {}
 
+  parseurl@1.3.3: {}
+
+  path-browserify@1.0.1: {}
+
+  path-exists@3.0.0: {}
+
   path-key@3.1.1: {}
 
   path-key@4.0.0: {}
@@ -4196,10 +6990,14 @@ snapshots:
       lru-cache: 11.5.2
       minipass: 7.1.3
 
+  path-to-regexp@8.4.2: {}
+
   pathe@2.0.3: {}
 
   picocolors@1.1.1: {}
 
+  picomatch@2.3.2: {}
+
   picomatch@4.0.5: {}
 
   pino-abstract-transport@3.0.0:
@@ -4224,12 +7022,18 @@ snapshots:
 
   pirates@4.0.7: {}
 
+  pkce-challenge@5.0.1: {}
+
   pkg-types@1.3.1:
     dependencies:
       confbox: 0.1.8
       mlly: 1.8.2
       pathe: 2.0.3
 
+  pkg-up@3.1.0:
+    dependencies:
+      find-up: 3.0.0
+
   platform@1.3.6: {}
 
   postcss-load-config@6.0.1(jiti@2.7.0)(postcss@8.5.16)(tsx@4.23.0)(yaml@2.9.0):
@@ -4241,12 +7045,19 @@ snapshots:
       tsx: 4.23.0
       yaml: 2.9.0
 
+  postcss-selector-parser@7.1.4:
+    dependencies:
+      cssesc: 3.0.0
+      util-deprecate: 1.0.2
+
   postcss@8.5.16:
     dependencies:
       nanoid: 3.3.15
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
+  powershell-utils@0.1.0: {}
+
   prebuild-install@7.1.3:
     dependencies:
       detect-libc: 2.1.2
@@ -4262,6 +7073,8 @@ snapshots:
       tar-fs: 2.1.5
       tunnel-agent: 0.6.0
 
+  prettier@3.9.4: {}
+
   pretty-ms@9.3.0:
     dependencies:
       parse-ms: 4.0.0
@@ -4270,6 +7083,11 @@ snapshots:
 
   process-warning@5.0.0: {}
 
+  prompts@2.4.2:
+    dependencies:
+      kleur: 3.0.3
+      sisteransi: 1.0.5
+
   protobufjs@7.6.5:
     dependencies:
       '@protobufjs/aspromise': 1.1.2
@@ -4284,13 +7102,34 @@ snapshots:
       '@types/node': 26.1.0
       long: 5.3.2
 
+  proxy-addr@2.0.7:
+    dependencies:
+      forwarded: 0.2.0
+      ipaddr.js: 1.9.1
+
   pump@3.0.4:
     dependencies:
       end-of-stream: 1.4.5
       once: 1.4.0
 
+  qs@6.15.3:
+    dependencies:
+      es-define-property: 1.0.1
+      side-channel: 1.1.1
+
+  queue-microtask@1.2.3: {}
+
   quick-format-unescaped@4.0.4: {}
 
+  range-parser@1.3.0: {}
+
+  raw-body@3.0.2:
+    dependencies:
+      bytes: 3.1.2
+      http-errors: 2.0.1
+      iconv-lite: 0.7.3
+      unpipe: 1.0.0
+
   rc@1.2.8:
     dependencies:
       deep-extend: 0.6.0
@@ -4298,11 +7137,62 @@ snapshots:
       minimist: 1.2.8
       strip-json-comments: 2.0.1
 
+  react-day-picker@10.0.1(@types/react@19.2.17)(react@19.2.7):
+    dependencies:
+      '@date-fns/tz': 1.5.0
+      date-fns: 4.4.0
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
   react-dom@19.2.7(react@19.2.7):
     dependencies:
       react: 19.2.7
       scheduler: 0.27.0
 
+  react-is@19.2.7: {}
+
+  react-redux@9.3.0(@types/react@19.2.17)(react@19.2.7)(redux@5.0.1):
+    dependencies:
+      '@types/use-sync-external-store': 0.0.6
+      react: 19.2.7
+      use-sync-external-store: 1.6.0(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      redux: 5.0.1
+
+  react-remove-scroll-bar@2.3.8(@types/react@19.2.17)(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+      react-style-singleton: 2.2.3(@types/react@19.2.17)(react@19.2.7)
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  react-remove-scroll@2.7.2(@types/react@19.2.17)(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+      react-remove-scroll-bar: 2.3.8(@types/react@19.2.17)(react@19.2.7)
+      react-style-singleton: 2.2.3(@types/react@19.2.17)(react@19.2.7)
+      tslib: 2.8.1
+      use-callback-ref: 1.3.3(@types/react@19.2.17)(react@19.2.7)
+      use-sidecar: 1.1.3(@types/react@19.2.17)(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  react-resizable-panels@4.12.1(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
+  react-style-singleton@2.2.3(@types/react@19.2.17)(react@19.2.7):
+    dependencies:
+      get-nonce: 1.0.1
+      react: 19.2.7
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.17
+
   react@19.2.7: {}
 
   readable-stream@3.6.2:
@@ -4313,18 +7203,65 @@ snapshots:
 
   readdirp@4.1.2: {}
 
+  readdirp@5.0.0: {}
+
   real-require@0.2.0: {}
 
   real-require@1.0.0: {}
 
+  recast@0.23.12:
+    dependencies:
+      ast-types: 0.16.1
+      esprima: 4.0.1
+      source-map: 0.6.1
+      tiny-invariant: 1.3.3
+      tslib: 2.8.1
+
+  recharts@3.8.0(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react-is@19.2.7)(react@19.2.7)(redux@5.0.1):
+    dependencies:
+      '@reduxjs/toolkit': 2.12.0(react-redux@9.3.0(@types/react@19.2.17)(react@19.2.7)(redux@5.0.1))(react@19.2.7)
+      clsx: 2.1.1
+      decimal.js-light: 2.5.1
+      es-toolkit: 1.49.0
+      eventemitter3: 5.0.4
+      immer: 10.2.0
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      react-is: 19.2.7
+      react-redux: 9.3.0(@types/react@19.2.17)(react@19.2.7)(redux@5.0.1)
+      reselect: 5.1.1
+      tiny-invariant: 1.3.3
+      use-sync-external-store: 1.6.0(react@19.2.7)
+      victory-vendor: 37.3.6
+    transitivePeerDependencies:
+      - '@types/react'
+      - redux
+
+  redux-thunk@3.1.0(redux@5.0.1):
+    dependencies:
+      redux: 5.0.1
+
+  redux@5.0.1: {}
+
   require-directory@2.1.1: {}
 
   require-from-string@2.0.2: {}
 
+  reselect@5.1.1: {}
+
+  reselect@5.2.0: {}
+
+  resolve-from@4.0.0: {}
+
   resolve-from@5.0.0: {}
 
   resolve-pkg-maps@1.0.0: {}
 
+  restore-cursor@5.1.0:
+    dependencies:
+      onetime: 7.0.0
+      signal-exit: 4.1.0
+
   ret@0.5.0: {}
 
   reusify@1.1.0: {}
@@ -4383,6 +7320,22 @@ snapshots:
       '@rollup/rollup-win32-x64-msvc': 4.62.2
       fsevents: 2.3.3
 
+  router@2.2.0:
+    dependencies:
+      debug: 4.4.3
+      depd: 2.0.0
+      is-promise: 4.0.0
+      parseurl: 1.3.3
+      path-to-regexp: 8.4.2
+    transitivePeerDependencies:
+      - supports-color
+
+  run-applescript@7.1.0: {}
+
+  run-parallel@1.2.0:
+    dependencies:
+      queue-microtask: 1.2.3
+
   safe-buffer@5.2.1: {}
 
   safe-regex2@5.1.1:
@@ -4397,26 +7350,123 @@ snapshots:
 
   secure-json-parse@4.1.0: {}
 
+  semver@6.3.1: {}
+
   semver@7.8.5: {}
 
+  send@1.2.1:
+    dependencies:
+      debug: 4.4.3
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      fresh: 2.0.0
+      http-errors: 2.0.1
+      mime-types: 3.0.2
+      ms: 2.1.3
+      on-finished: 2.4.1
+      range-parser: 1.3.0
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
   seroval-plugins@1.5.4(seroval@1.5.4):
     dependencies:
       seroval: 1.5.4
 
   seroval@1.5.4: {}
 
+  serve-static@2.2.1:
+    dependencies:
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      parseurl: 1.3.3
+      send: 1.2.1
+    transitivePeerDependencies:
+      - supports-color
+
   set-cookie-parser@2.7.2: {}
 
   setprototypeof@1.2.0: {}
 
+  shadcn@4.13.0(typescript@6.0.3):
+    dependencies:
+      '@babel/core': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/plugin-transform-typescript': 7.29.7(@babel/core@7.29.7)
+      '@babel/preset-typescript': 7.29.7(@babel/core@7.29.7)
+      '@dotenvx/dotenvx': 1.75.1
+      '@modelcontextprotocol/sdk': 1.29.0(zod@3.25.76)
+      '@types/validate-npm-package-name': 4.0.2
+      browserslist: 4.28.5
+      commander: 14.0.3
+      cosmiconfig: 9.0.2(typescript@6.0.3)
+      dedent: 1.7.2
+      deepmerge: 4.3.1
+      diff: 8.0.4
+      execa: 9.6.1
+      fast-glob: 3.3.3
+      fs-extra: 11.3.6
+      fuzzysort: 3.1.0
+      kleur: 4.1.5
+      open: 11.0.0
+      ora: 8.2.0
+      postcss: 8.5.16
+      postcss-selector-parser: 7.1.4
+      prompts: 2.4.2
+      recast: 0.23.12
+      stringify-object: 5.0.0
+      tailwind-merge: 3.6.0
+      ts-morph: 26.0.0
+      tsconfig-paths: 4.2.0
+      undici: 7.28.0
+      validate-npm-package-name: 7.0.2
+      zod: 3.25.76
+      zod-to-json-schema: 3.25.2(zod@3.25.76)
+    transitivePeerDependencies:
+      - '@cfworker/json-schema'
+      - babel-plugin-macros
+      - supports-color
+      - typescript
+
   shebang-command@2.0.0:
     dependencies:
       shebang-regex: 3.0.0
 
   shebang-regex@3.0.0: {}
 
+  side-channel-list@1.0.1:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-map@1.0.1:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-weakmap@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-map: 1.0.1
+
+  side-channel@1.1.1:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-list: 1.0.1
+      side-channel-map: 1.0.1
+      side-channel-weakmap: 1.0.2
+
   siginfo@2.0.0: {}
 
+  signal-exit@3.0.7: {}
+
   signal-exit@4.1.0: {}
 
   simple-concat@1.0.1: {}
@@ -4427,10 +7477,17 @@ snapshots:
       once: 1.4.0
       simple-concat: 1.0.1
 
+  sisteransi@1.0.5: {}
+
   sonic-boom@4.2.1:
     dependencies:
       atomic-sleep: 1.0.0
 
+  sonner@2.0.7(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
   source-map-js@1.2.1: {}
 
   source-map-support@0.5.21:
@@ -4460,20 +7517,42 @@ snapshots:
 
   std-env@4.1.0: {}
 
+  stdin-discarder@0.2.2: {}
+
   string-width@4.2.3:
     dependencies:
       emoji-regex: 8.0.0
       is-fullwidth-code-point: 3.0.0
       strip-ansi: 6.0.1
 
+  string-width@7.2.0:
+    dependencies:
+      emoji-regex: 10.6.0
+      get-east-asian-width: 1.6.0
+      strip-ansi: 7.2.0
+
   string_decoder@1.3.0:
     dependencies:
       safe-buffer: 5.2.1
 
+  stringify-object@5.0.0:
+    dependencies:
+      get-own-enumerable-keys: 1.0.0
+      is-obj: 3.0.0
+      is-regexp: 3.1.0
+
   strip-ansi@6.0.1:
     dependencies:
       ansi-regex: 5.0.1
 
+  strip-ansi@7.2.0:
+    dependencies:
+      ansi-regex: 6.2.2
+
+  strip-bom@3.0.0: {}
+
+  strip-final-newline@2.0.0: {}
+
   strip-final-newline@4.0.0: {}
 
   strip-json-comments@2.0.1: {}
@@ -4488,6 +7567,10 @@ snapshots:
       tinyglobby: 0.2.17
       ts-interface-checker: 0.1.13
 
+  systeminformation@5.31.15: {}
+
+  tailwind-merge@3.6.0: {}
+
   tailwindcss@4.3.2: {}
 
   tapable@2.3.3: {}
@@ -4527,6 +7610,8 @@ snapshots:
     dependencies:
       real-require: 1.0.0
 
+  tiny-invariant@1.3.3: {}
+
   tinybench@2.9.0: {}
 
   tinyexec@0.3.2: {}
@@ -4540,6 +7625,10 @@ snapshots:
 
   tinyrainbow@3.1.0: {}
 
+  to-regex-range@5.0.1:
+    dependencies:
+      is-number: 7.0.0
+
   toad-cache@3.7.4: {}
 
   toidentifier@1.0.1: {}
@@ -4548,8 +7637,18 @@ snapshots:
 
   ts-interface-checker@0.1.13: {}
 
-  tslib@2.8.1:
-    optional: true
+  ts-morph@26.0.0:
+    dependencies:
+      '@ts-morph/common': 0.27.0
+      code-block-writer: 13.0.3
+
+  tsconfig-paths@4.2.0:
+    dependencies:
+      json5: 2.2.3
+      minimist: 1.2.8
+      strip-bom: 3.0.0
+
+  tslib@2.8.1: {}
 
   tsup@8.5.1(jiti@2.7.0)(postcss@8.5.16)(tsx@4.23.0)(typescript@6.0.3)(yaml@2.9.0):
     dependencies:
@@ -4589,8 +7688,16 @@ snapshots:
     dependencies:
       safe-buffer: 5.2.1
 
+  tw-animate-css@1.4.0: {}
+
   tweetnacl@0.14.5: {}
 
+  type-is@2.1.0:
+    dependencies:
+      content-type: 2.0.0
+      media-typer: 1.1.0
+      mime-types: 3.0.2
+
   typescript@6.0.3: {}
 
   ufo@1.6.4: {}
@@ -4605,12 +7712,69 @@ snapshots:
 
   unicorn-magic@0.3.0: {}
 
+  universalify@2.0.1: {}
+
+  unpipe@1.0.0: {}
+
+  unplugin@3.3.0(esbuild@0.28.1)(rolldown@1.1.4)(rollup@4.62.2)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)):
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      picomatch: 4.0.5
+      webpack-virtual-modules: 0.6.2
+    optionalDependencies:
+      esbuild: 0.28.1
+      rolldown: 1.1.4
+      rollup: 4.62.2
+      vite: 8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)
+
+  update-browserslist-db@1.2.3(browserslist@4.28.5):
+    dependencies:
+      browserslist: 4.28.5
+      escalade: 3.2.0
+      picocolors: 1.1.1
+
+  use-callback-ref@1.3.3(@types/react@19.2.17)(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  use-sidecar@1.1.3(@types/react@19.2.17)(react@19.2.7):
+    dependencies:
+      detect-node-es: 1.1.0
+      react: 19.2.7
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.17
+
   use-sync-external-store@1.6.0(react@19.2.7):
     dependencies:
       react: 19.2.7
 
   util-deprecate@1.0.2: {}
 
+  validate-npm-package-name@7.0.2: {}
+
+  vary@1.1.2: {}
+
+  victory-vendor@37.3.6:
+    dependencies:
+      '@types/d3-array': 3.2.2
+      '@types/d3-ease': 3.0.2
+      '@types/d3-interpolate': 3.0.4
+      '@types/d3-scale': 4.0.9
+      '@types/d3-shape': 3.1.8
+      '@types/d3-time': 3.0.4
+      '@types/d3-timer': 3.0.2
+      d3-array: 3.2.4
+      d3-ease: 3.0.1
+      d3-interpolate: 3.0.1
+      d3-scale: 4.0.2
+      d3-shape: 3.2.0
+      d3-time: 3.1.0
+      d3-timer: 3.0.1
+
   vite@8.1.3(@types/node@26.1.0)(esbuild@0.27.7)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0):
     dependencies:
       lightningcss: 1.32.0
@@ -4672,10 +7836,16 @@ snapshots:
 
   vscode-languageserver-types@3.18.0: {}
 
+  webpack-virtual-modules@0.6.2: {}
+
   which@2.0.2:
     dependencies:
       isexe: 2.0.0
 
+  which@4.0.0:
+    dependencies:
+      isexe: 3.1.5
+
   why-is-node-running@2.3.0:
     dependencies:
       siginfo: 2.0.0
@@ -4689,8 +7859,15 @@ snapshots:
 
   wrappy@1.0.2: {}
 
+  wsl-utils@0.3.1:
+    dependencies:
+      is-wsl: 3.1.1
+      powershell-utils: 0.1.0
+
   y18n@5.0.8: {}
 
+  yallist@3.1.1: {}
+
   yallist@5.0.0: {}
 
   yaml@2.9.0: {}
@@ -4707,6 +7884,16 @@ snapshots:
       y18n: 5.0.8
       yargs-parser: 21.1.1
 
+  yocto-spinner@1.2.1:
+    dependencies:
+      yoctocolors: 2.1.2
+
   yoctocolors@2.1.2: {}
 
+  zod-to-json-schema@3.25.2(zod@3.25.76):
+    dependencies:
+      zod: 3.25.76
+
+  zod@3.25.76: {}
+
   zod@4.4.3: {}

From eecf086b6d55f568a43fe1255eb95836ece97cb2 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 01:28:24 +0800
Subject: [PATCH 015/133] The process table lands: background commands, stdin,
 signals, reconnect
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The E2B process surface grows its real half. ExecStreamHandle gains
sendStdin/closeStdin/signal/resizePty; the docker executor wraps every
stream exec in setsid --wait plus a pidfile so a later kill can reap the
whole group, and keeps the hijacked duplex open for stdin. The fake grows
an interactive process (cat, interruptible sleep, kill switch) and yields
one macrotask so no output beats execStream's resolve.

envd's Process service now speaks Connect/List/SendInput/CloseStdin/
SendSignal/Update against a daemon-side process table: streams are just
subscribers (slowest-subscriber backpressure, no replay), a blown
connect-timeout-ms or a hung-up client only detaches — the process lives
until it exits, is signaled, or its sandbox dies, matching real envd.
The exec heartbeat now lives exactly as long as a stream is attached, so
an unwatched background process lets the sandbox freeze honestly.

Contract 47->56, compat 22->29, e2e adds the official-SDK background
family (kill 137, disconnect+connect, list, stdin round-trip).
---
 e2e/src/e2b.test.ts                      |  75 +++
 packages/server/src/app.ts               |   8 +-
 packages/server/src/e2b/compat.test.ts   | 229 ++++++++-
 packages/server/src/e2b/deps.ts          |   7 +-
 packages/server/src/e2b/envd.ts          | 561 +++++++++++++++++------
 packages/server/src/e2b/process-table.ts | 174 +++++++
 packages/server/src/executor/contract.ts | 203 ++++++++
 packages/server/src/executor/docker.ts   | 138 +++++-
 packages/server/src/executor/executor.ts |  41 +-
 packages/server/src/executor/fake.ts     | 166 ++++++-
 10 files changed, 1421 insertions(+), 181 deletions(-)
 create mode 100644 packages/server/src/e2b/process-table.ts

diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index a246b55..514528d 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -226,6 +226,81 @@ describe('official e2b SDK against the daemon', () => {
     }
   });
 
+  it('background commands: run detached, kill through the handle', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      const handle = await sbx.commands.run('sleep 30', { background: true });
+      expect(handle.pid).toBeGreaterThan(0);
+      expect(await handle.kill()).toBe(true);
+      const error = await handle.wait().catch((e) => e);
+      expect(error).toBeInstanceOf(CommandExitError);
+      expect(error.exitCode).toBe(137);
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('disconnect does not kill: commands.connect reattaches and sees the ending', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      const handle = await sbx.commands.run('sleep 1; echo late-news', {
+        background: true,
+      });
+      await handle.disconnect();
+
+      const seen: string[] = [];
+      const reattached = await sbx.commands.connect(handle.pid, {
+        onStdout: (text) => {
+          seen.push(text);
+        },
+      });
+      const result = await reattached.wait();
+      expect(result.exitCode).toBe(0);
+      expect(seen.join('')).toBe('late-news\n');
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('commands.list shows the living and empties after they exit', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      const handle = await sbx.commands.run('sleep 30', { background: true });
+      const listed = await sbx.commands.list();
+      expect(listed.map((p) => p.pid)).toContain(handle.pid);
+      expect(listed[0]?.cmd).toBe('/bin/bash');
+
+      await handle.kill();
+      await handle.wait().catch(() => {});
+      expect(await sbx.commands.list()).toEqual([]);
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('stdin: sendStdin feeds the command, closeStdin is EOF', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      const seen: string[] = [];
+      const handle = await sbx.commands.run('cat', {
+        background: true,
+        stdin: true,
+        onStdout: (text) => {
+          seen.push(text);
+        },
+      });
+      await handle.sendStdin('hello ');
+      await handle.sendStdin('dormice');
+      await handle.closeStdin();
+      const result = await handle.wait();
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toBe('hello dormice');
+      expect(seen.join('')).toBe('hello dormice');
+    } finally {
+      await sbx.kill();
+    }
+  });
+
   it('the Dormice extension: metadata.userKey makes create idempotent, data persists', async () => {
     const first = await Sandbox.create({
       ...connection(),
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 758e0ae..07df1c1 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -11,6 +11,7 @@ import { requireApiAuth } from './auth';
 import type { Config } from './config';
 import type { Db } from './db/db';
 import { registerE2bCompat } from './e2b';
+import { ProcessTable } from './e2b/process-table';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
 import { sandboxRoutes } from './routes/sandboxes';
@@ -112,9 +113,12 @@ export function buildApp({
   });
 
   // The E2B compatibility surface lives beside the native API with its own
-  // auth (X-API-KEY / X-Access-Token) and its own error dialect.
+  // auth (X-API-KEY / X-Access-Token) and its own error dialect. The process
+  // table is per-daemon state, born with the app and gone with it — a
+  // restart honestly empties it.
+  const processes = new ProcessTable();
   app.register(async (compat) => {
-    await registerE2bCompat(compat, { config, db, executor, locks });
+    await registerE2bCompat(compat, { config, db, executor, locks, processes });
   });
 
   return app;
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index d6f141a..55e676a 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -92,6 +92,15 @@ function parseEnvelopes(
   return frames;
 }
 
+/** One enveloped Connect request frame — what a streaming RPC's body looks like. */
+function enveloped(message: Record<string, unknown>): Buffer {
+  const json = Buffer.from(JSON.stringify(message), 'utf8');
+  const head = Buffer.alloc(5);
+  head.writeUInt8(0, 0);
+  head.writeUInt32BE(json.length, 1);
+  return Buffer.concat([head, json]);
+}
+
 function startCommand(
   t: TestApp,
   sandboxID: string,
@@ -99,6 +108,7 @@ function startCommand(
   opts: {
     envs?: Record<string, string>;
     headers?: Record<string, string>;
+    stdin?: boolean;
   } = {},
 ) {
   const message = {
@@ -107,11 +117,8 @@ function startCommand(
       args: ['-l', '-c', command],
       envs: opts.envs ?? {},
     },
+    ...(opts.stdin ? { stdin: true } : {}),
   };
-  const json = Buffer.from(JSON.stringify(message), 'utf8');
-  const head = Buffer.alloc(5);
-  head.writeUInt8(0, 0);
-  head.writeUInt32BE(json.length, 1);
   return t.app.inject({
     method: 'POST',
     url: '/e2b/envd/process.Process/Start',
@@ -120,10 +127,33 @@ function startCommand(
       'content-type': 'application/connect+json',
       ...opts.headers,
     },
-    payload: Buffer.concat([head, json]),
+    payload: enveloped(message),
+  });
+}
+
+function connectProcess(t: TestApp, sandboxID: string, pid: number) {
+  return t.app.inject({
+    method: 'POST',
+    url: '/e2b/envd/process.Process/Connect',
+    headers: {
+      ...envdHeaders(sandboxID),
+      'content-type': 'application/connect+json',
+    },
+    payload: enveloped({ process: { pid } }),
   });
 }
 
+/** Polls List until the sandbox shows a live process — Start's response is still in flight. */
+async function waitForPid(t: TestApp, sandboxID: string): Promise<number> {
+  for (let i = 0; i < 200; i++) {
+    const res = await envdRpc(t, sandboxID, '/process.Process/List', {});
+    const procs = res.json().processes as Array<{ pid: number }>;
+    if (procs.length > 0 && procs[0]) return procs[0].pid;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  throw new Error('process never appeared in List');
+}
+
 describe('E2B control plane', () => {
   it('guards with X-API-KEY: e2b_-prefixed and bare tokens pass, others do not', async () => {
     const t = testApp();
@@ -593,12 +623,199 @@ describe('E2B envd surface', () => {
   it('names what it does not support yet: unimplemented, with a hint', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t);
-    const res = await envdRpc(t, sandboxID, '/process.Process/SendInput', {});
+    const res = await envdRpc(t, sandboxID, '/process.Process/StreamInput', {});
     expect(res.statusCode).toBe(501);
     expect(res.json().code).toBe('unimplemented');
     expect(res.json().message).toContain('stdin');
   });
 
+  it('stdin round-trips: Start with stdin, SendInput chunks, CloseStdin ends it', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const startRes = startCommand(t, sandboxID, 'cat', { stdin: true });
+    const pid = await waitForPid(t, sandboxID);
+
+    const sent = await envdRpc(t, sandboxID, '/process.Process/SendInput', {
+      process: { pid },
+      input: { stdin: Buffer.from('hello ').toString('base64') },
+    });
+    expect(sent.statusCode).toBe(200);
+    await envdRpc(t, sandboxID, '/process.Process/SendInput', {
+      process: { pid },
+      input: { stdin: Buffer.from('world').toString('base64') },
+    });
+    const closed = await envdRpc(t, sandboxID, '/process.Process/CloseStdin', {
+      process: { pid },
+    });
+    expect(closed.statusCode).toBe(200);
+
+    const events = parseEnvelopes((await startRes).rawPayload)
+      .filter((f) => f.flags === 0)
+      .map((f) => f.json.event as Record<string, unknown>);
+    expect(events[0]).toHaveProperty('start');
+    const echoed = events
+      .filter((e) => 'data' in e)
+      .map((e) =>
+        Buffer.from(
+          (e as { data: { stdout: string } }).data.stdout,
+          'base64',
+        ).toString('utf8'),
+      )
+      .join('');
+    expect(echoed).toBe('hello world');
+    const end = events.at(-1) as { end: { exitCode: number } };
+    expect(end.end.exitCode).toBe(0);
+  });
+
+  it('a blown deadline only detaches the stream: the process lives, Connect picks it back up', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const startRes = await startCommand(t, sandboxID, 'sleep 1; echo late', {
+      headers: { 'connect-timeout-ms': '200' },
+    });
+    const startFrames = parseEnvelopes(startRes.rawPayload);
+    expect((startFrames.at(-1)?.json.error as { code: string }).code).toBe(
+      'deadline_exceeded',
+    );
+    const pid = (startFrames[0]?.json.event as { start: { pid: number } }).start
+      .pid;
+
+    // Still alive after the wire gave up — E2B's semantics, adopted on purpose.
+    const list = await envdRpc(t, sandboxID, '/process.Process/List', {});
+    expect(
+      (list.json().processes as Array<{ pid: number }>).map((p) => p.pid),
+    ).toContain(pid);
+
+    // Connect must open with a start frame, then deliver the rest.
+    const events = parseEnvelopes(
+      (await connectProcess(t, sandboxID, pid)).rawPayload,
+    )
+      .filter((f) => f.flags === 0)
+      .map((f) => f.json.event as Record<string, unknown>);
+    expect(events[0]).toEqual({ start: { pid } });
+    const late = events.find((e) => 'data' in e) as {
+      data: { stdout: string };
+    };
+    expect(Buffer.from(late.data.stdout, 'base64').toString('utf8')).toBe(
+      'late\n',
+    );
+    expect((events.at(-1) as { end: { exitCode: number } }).end.exitCode).toBe(
+      0,
+    );
+  });
+
+  it('Connect to an unknown pid answers not_found inside the stream', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const frames = parseEnvelopes(
+      (await connectProcess(t, sandboxID, 424242)).rawPayload,
+    );
+    expect(frames).toHaveLength(1);
+    expect(frames[0]?.flags).toBe(2);
+    expect((frames[0]?.json.error as { code: string }).code).toBe('not_found');
+  });
+
+  it('List echoes a complete config and empties once the process exits', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const startRes = startCommand(t, sandboxID, 'sleep 30', {
+      envs: { MARKER: 'yes' },
+    });
+    const pid = await waitForPid(t, sandboxID);
+
+    const list = await envdRpc(t, sandboxID, '/process.Process/List', {});
+    const procs = list.json().processes as Array<{
+      pid: number;
+      config: { cmd: string; args: string[]; envs: Record<string, string> };
+    }>;
+    expect(procs).toHaveLength(1);
+    // The SDK dereferences config.cmd and config.args unconditionally.
+    expect(procs[0]?.config.cmd).toBe('/bin/bash');
+    expect(procs[0]?.config.args).toEqual(['-l', '-c', 'sleep 30']);
+    expect(procs[0]?.config.envs).toEqual({ MARKER: 'yes' });
+
+    await envdRpc(t, sandboxID, '/process.Process/SendSignal', {
+      process: { pid },
+      signal: 'SIGNAL_SIGKILL',
+    });
+    await startRes;
+    const after = await envdRpc(t, sandboxID, '/process.Process/List', {});
+    expect(after.json().processes).toEqual([]);
+  });
+
+  it('SendSignal kills: the stream ends 137/killed; a dead pid answers not_found', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const startRes = startCommand(t, sandboxID, 'sleep 30');
+    const pid = await waitForPid(t, sandboxID);
+
+    const killed = await envdRpc(t, sandboxID, '/process.Process/SendSignal', {
+      process: { pid },
+      signal: 'SIGNAL_SIGKILL',
+    });
+    expect(killed.statusCode).toBe(200);
+    const events = parseEnvelopes((await startRes).rawPayload)
+      .filter((f) => f.flags === 0)
+      .map((f) => f.json.event as Record<string, unknown>);
+    const end = events.at(-1) as {
+      end: { exitCode: number; status: string };
+    };
+    expect(end.end).toMatchObject({ exitCode: 137, status: 'killed' });
+
+    // The SDK turns not_found into kill() === false.
+    const again = await envdRpc(t, sandboxID, '/process.Process/SendSignal', {
+      process: { pid },
+      signal: 'SIGNAL_SIGKILL',
+    });
+    expect(again.statusCode).toBe(404);
+    expect(again.json().code).toBe('not_found');
+  });
+
+  it("SendInput to a process started without stdin is the caller's confusion", async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const startRes = startCommand(t, sandboxID, 'sleep 30');
+    const pid = await waitForPid(t, sandboxID);
+
+    const res = await envdRpc(t, sandboxID, '/process.Process/SendInput', {
+      process: { pid },
+      input: { stdin: Buffer.from('x').toString('base64') },
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().code).toBe('invalid_argument');
+    expect(res.json().message).toBe('process was started without stdin');
+
+    await envdRpc(t, sandboxID, '/process.Process/SendSignal', {
+      process: { pid },
+      signal: 'SIGNAL_SIGKILL',
+    });
+    await startRes;
+  });
+
+  it('a detached background process does not keep the sandbox warm', async () => {
+    const t = testApp();
+    // A day-long TTL so the idle scanner speaks first — at the default 300s
+    // the kill-deadline would destroy the sandbox before freeze gets a turn.
+    const { sandboxID } = await createSandbox(t, { timeout: 86400 });
+    // Detach via the wire deadline: the process sleeps on, unwatched.
+    await startCommand(t, sandboxID, 'sleep 600', {
+      headers: { 'connect-timeout-ms': '100' },
+    });
+    expect(
+      (await envdRpc(t, sandboxID, '/process.Process/List', {})).json()
+        .processes,
+    ).toHaveLength(1);
+
+    // The idle scanner, told it is an hour later, freezes the sandbox —
+    // no heartbeat outlives its stream; only attached streams keep warmth.
+    const row = findBySandboxId(t.db, sandboxID);
+    const later = new Date(
+      Date.now() + ((row?.freezeAfterSeconds ?? 0) + 60) * 1000,
+    );
+    await scanOnce(t.db, t.executor, t.locks, later);
+    expect(t.executor.stateOf(sandboxID)).toBe('paused');
+  });
+
   it('exec on a paused sandbox answers unavailable inside the stream — like a dead E2B box', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t);
diff --git a/packages/server/src/e2b/deps.ts b/packages/server/src/e2b/deps.ts
index d24f52a..2a61fd1 100644
--- a/packages/server/src/e2b/deps.ts
+++ b/packages/server/src/e2b/deps.ts
@@ -2,11 +2,16 @@ import type { Config } from '../config';
 import type { Db } from '../db/db';
 import type { Executor } from '../executor/executor';
 import type { KeyedQueue } from '../keyed-queue';
+import type { ProcessTable } from './process-table';
 
-/** What every compat plugin needs — the same four the native routes get. */
+/**
+ * What every compat plugin needs — the native routes' four, plus the
+ * process table both e2b prefixes share (control kills what envd started).
+ */
 export interface E2bDeps {
   config: Config;
   db: Db;
   executor: Executor;
   locks: KeyedQueue;
+  processes: ProcessTable;
 }
diff --git a/packages/server/src/e2b/envd.ts b/packages/server/src/e2b/envd.ts
index 50b86a4..487dc65 100644
--- a/packages/server/src/e2b/envd.ts
+++ b/packages/server/src/e2b/envd.ts
@@ -1,4 +1,4 @@
-import type { Buffer } from 'node:buffer';
+import { Buffer } from 'node:buffer';
 import { resolveSandboxPath } from '@dormice/shared';
 import multipart from '@fastify/multipart';
 import type { FastifyReply, FastifyRequest } from 'fastify';
@@ -15,6 +15,7 @@ import {
 } from '../executor/executor';
 import { wakeSandbox } from '../lifecycle';
 import type { E2bDeps } from './deps';
+import type { ProcessRecord, ProcessSubscriber } from './process-table';
 import {
   connectError,
   E2bError,
@@ -35,7 +36,12 @@ import { e2bView } from './view';
  * is no agent inside the container.
  */
 
-/** In-flight command deadline backstop when the SDK sends no deadline header. */
+/**
+ * In-container cleanup backstop for e2b-surface processes. Deliberately not
+ * the wire deadline: connect-timeout-ms only ever closes the stream — the
+ * process lives until it exits, is signaled, or its sandbox dies (E2B's
+ * semantics; the native /execCommand keeps its own kill-at-timeout contract).
+ */
 const MAX_EXEC_SECONDS = 24 * 60 * 60;
 
 /** The SDK asks for keepalives via this header; we honor it, capped. */
@@ -44,9 +50,6 @@ const MAX_KEEPALIVE_SECONDS = 30;
 /** Effectively unbounded route body: the disk quota is the real gate. */
 const UNLIMITED_BODY_BYTES = Number.MAX_SAFE_INTEGER;
 
-/** Synthetic PIDs — the SDK only ever uses them as opaque handles. */
-let nextPid = 1000;
-
 interface StartRequest {
   process?: {
     cmd?: string;
@@ -54,6 +57,7 @@ interface StartRequest {
     envs?: Record<string, string>;
     cwd?: string;
   };
+  stdin?: boolean;
   pty?: unknown;
 }
 
@@ -108,7 +112,7 @@ function toConnectError(error: unknown): unknown {
 
 export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   app,
-  { config, db, executor, locks },
+  { config, db, executor, locks, processes },
 ) => {
   await app.register(multipart, {
     limits: {
@@ -462,9 +466,192 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
 
   // ---- process service -------------------------------------------------
 
-  app.post('/process.Process/List', async () => {
-    // No process table yet: honest empty, matching v1's supported surface.
-    return { processes: [] };
+  /**
+   * The wire face of one attached stream, shared by Start and Connect: data
+   * frames with backpressure, and the end frames written by the process's
+   * finalize. `done` settles once the ending — end event or in-stream error
+   * — is fully on the wire. The write closure touches reply.raw lazily: it
+   * is never called before the caller has hijacked (the executor emits
+   * nothing before execStream resolves, and subscription follows the
+   * hijack synchronously).
+   */
+  function streamSubscriber(write: (buf: Buffer) => Promise<void>): {
+    subscriber: ProcessSubscriber;
+    done: Promise<'ended'>;
+  } {
+    let resolveDone!: (outcome: 'ended') => void;
+    const done = new Promise<'ended'>((resolve) => {
+      resolveDone = resolve;
+    });
+    const subscriber: ProcessSubscriber = {
+      onOutput: (channel, chunk) =>
+        write(
+          envelope(FLAG_MESSAGE, {
+            event: { data: { [channel]: chunk.toString('base64') } },
+          }),
+        ),
+      onEnd: (end) => {
+        const frames =
+          end.kind === 'exit'
+            ? [
+                envelope(FLAG_MESSAGE, {
+                  event: {
+                    end: {
+                      exitCode: end.exitCode,
+                      exited: true,
+                      status: end.exitCode === 137 ? 'killed' : 'exited',
+                      ...(end.exitCode === 137
+                        ? { error: 'command killed (exit 137)' }
+                        : {}),
+                    },
+                  },
+                }),
+                envelope(FLAG_END_STREAM, {}),
+              ]
+            : [
+                // The container died under the process (a kill, a release):
+                // an in-stream internal error, which the SDK triages via its
+                // health check — the same feel as a killed E2B sandbox.
+                envelope(FLAG_END_STREAM, {
+                  error: { code: 'internal', message: end.message },
+                }),
+              ];
+        void (async () => {
+          for (const frame of frames) await write(frame);
+          resolveDone('ended');
+        })();
+      },
+    };
+    return { subscriber, done };
+  }
+
+  /** The SDK's connect-timeout-ms header, absent meaning "effectively never". */
+  function wireDeadlineMs(request: FastifyRequest): number {
+    const headerMs = Number(request.headers['connect-timeout-ms']);
+    return Number.isFinite(headerMs) && headerMs > 0
+      ? headerMs
+      : MAX_EXEC_SECONDS * 1000;
+  }
+
+  /**
+   * The attached half of a process stream: keepalives, the wire deadline,
+   * the client hanging up. The deadline and the hang-up both merely detach
+   * this stream — the process keeps running (real envd's semantics: nothing
+   * kills a process except its own exit, SendSignal, or the sandbox dying);
+   * the exec heartbeat lives exactly as long as someone is attached, so a
+   * background process nobody watches lets the sandbox freeze honestly.
+   */
+  async function pumpProcessStream(args: {
+    request: FastifyRequest;
+    reply: FastifyReply;
+    row: SandboxRow;
+    write: (buf: Buffer) => Promise<void>;
+    done: Promise<'ended'>;
+    detach: () => void;
+  }): Promise<void> {
+    const { request, reply, row, write, done, detach } = args;
+    const stopHeartbeat = startExecHeartbeat(
+      db,
+      row.sandboxId,
+      row.freezeAfterSeconds,
+    );
+    // Keepalive events on the interval the SDK asked for — what keeps
+    // proxies from cutting a silent long command.
+    const keepaliveSeconds = Math.min(
+      Number(request.headers['keepalive-ping-interval']) ||
+        MAX_KEEPALIVE_SECONDS,
+      MAX_KEEPALIVE_SECONDS,
+    );
+    const keepalive = setInterval(() => {
+      reply.raw.write(envelope(FLAG_MESSAGE, { event: { keepalive: {} } }));
+    }, keepaliveSeconds * 1000);
+    const deadlineMs = wireDeadlineMs(request);
+    let deadlineTimer: NodeJS.Timeout | undefined;
+    const deadline = new Promise<'deadline'>((resolve) => {
+      deadlineTimer = setTimeout(() => resolve('deadline'), deadlineMs);
+    });
+    const clientGone = new Promise<'gone'>((resolve) => {
+      reply.raw.once('close', () => resolve('gone'));
+    });
+    try {
+      const outcome = await Promise.race([done, deadline, clientGone]);
+      if (outcome === 'deadline') {
+        // Real envd answers a blown deadline with the Connect error, not an
+        // end event; the SDK turns it into its TimeoutError. The process
+        // stays alive — only this stream ends.
+        await write(
+          envelope(FLAG_END_STREAM, {
+            error: {
+              code: 'deadline_exceeded',
+              message: `command timed out after ${deadlineMs}ms`,
+            },
+          }),
+        );
+      }
+    } finally {
+      clearInterval(keepalive);
+      clearTimeout(deadlineTimer);
+      detach();
+      stopHeartbeat();
+      try {
+        // Watching the command was the activity: the idle countdown starts
+        // when the stream detaches, not when it attached.
+        touch(db, row.sandboxId);
+      } catch {
+        // Released mid-stream; the stream's own ending tells the story.
+      }
+      reply.raw.end();
+    }
+  }
+
+  /** Wake-for-use with streaming-dialect errors: streamError, not thrown JSON. */
+  async function wakeForStream(
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ): Promise<SandboxRow | undefined> {
+    try {
+      return await wakeForUse(sandboxIdOf(request));
+    } catch (error) {
+      if (error instanceof E2bError) {
+        // Everything this surface throws carries a Connect string code; a
+        // numeric one would be a control-plane error that leaked — treat it
+        // as the sandbox being unreachable.
+        streamError(
+          reply,
+          typeof error.code === 'string' ? error.code : 'unavailable',
+          error.message,
+        );
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  /** The backpressured raw write every process stream shares. */
+  function rawWriter(reply: FastifyReply): (buf: Buffer) => Promise<void> {
+    return (buf) =>
+      new Promise<void>((resolve) => {
+        if (!reply.raw.write(buf)) reply.raw.once('drain', resolve);
+        else resolve();
+      });
+  }
+
+  app.post('/process.Process/List', async (request) => {
+    // Read-only: no wake — looking at the table must not thaw a sandbox.
+    const row = requireRunningRow(sandboxIdOf(request));
+    return {
+      processes: processes.list(row.sandboxId).map((record) => ({
+        pid: record.pid,
+        // config is echoed verbatim and always complete: the SDK
+        // dereferences processes[].config.args unconditionally.
+        config: {
+          cmd: record.config.cmd,
+          args: record.config.args,
+          envs: record.config.envs,
+          ...(record.config.cwd ? { cwd: record.config.cwd } : {}),
+        },
+      })),
+    };
   });
 
   app.post('/process.Process/Start', async (request, reply) => {
@@ -495,143 +682,245 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         'only shell commands are supported: expected /bin/bash [-l] -c <command>',
       );
     }
-
-    let row: SandboxRow;
+    const row = await wakeForStream(request, reply);
+    if (!row) return;
+
+    const sandboxEnvs: Record<string, string> = row.envs
+      ? JSON.parse(row.envs)
+      : {};
+    const write = rawWriter(reply);
+    const { subscriber, done } = streamSubscriber(write);
+    let record: ProcessRecord;
     try {
-      row = await wakeForUse(sandboxIdOf(request));
+      record = await processes.start({
+        executor,
+        sandboxId: row.sandboxId,
+        options: {
+          command,
+          loginShell,
+          // The in-container timeout is a pathological-cleanup backstop
+          // only; the wire deadline lives in pumpProcessStream and never
+          // kills the process — E2B's semantics, adopted deliberately.
+          timeoutSeconds: MAX_EXEC_SECONDS,
+          stdin: message.stdin === true,
+          cwd: proc.cwd,
+          // Sandbox-level envs underneath, per-command envs on top.
+          env: { ...sandboxEnvs, ...(proc.envs ?? {}) },
+        },
+        config: {
+          cmd: proc.cmd,
+          args,
+          envs: proc.envs ?? {},
+          cwd: proc.cwd,
+        },
+        subscriber,
+      });
     } catch (error) {
-      if (error instanceof E2bError) {
-        // Everything this surface throws carries a Connect string code; a
-        // numeric one would be a control-plane error that leaked — treat it
-        // as the sandbox being unreachable.
-        return streamError(
-          reply,
-          typeof error.code === 'string' ? error.code : 'unavailable',
-          error.message,
-        );
-      }
-      throw error;
+      // Start order is deliberate: the start frame goes out only for a
+      // process that actually started.
+      const messageText =
+        error instanceof Error ? error.message : String(error);
+      return streamError(reply, 'internal', messageText);
     }
-
-    // The wire deadline: the SDK's connect-timeout-ms header. The daemon's
-    // timer adjudicates the wire (deadline_exceeded, like real envd); the
-    // in-container `timeout` merely cleans up the process a beat later —
-    // no guessing whether a 137 "was" a timeout.
-    const headerMs = Number(request.headers['connect-timeout-ms']);
-    const deadlineMs =
-      Number.isFinite(headerMs) && headerMs > 0
-        ? headerMs
-        : MAX_EXEC_SECONDS * 1000;
-    const timeoutSeconds = Math.min(
-      Math.ceil(deadlineMs / 1000),
-      MAX_EXEC_SECONDS,
-    );
-
     reply.hijack();
     reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
-    const write = (buf: Buffer) =>
-      new Promise<void>((resolve) => {
-        if (!reply.raw.write(buf)) reply.raw.once('drain', resolve);
-        else resolve();
-      });
-
     await write(
-      envelope(FLAG_MESSAGE, { event: { start: { pid: nextPid++ } } }),
+      envelope(FLAG_MESSAGE, { event: { start: { pid: record.pid } } }),
     );
+    await pumpProcessStream({
+      request,
+      reply,
+      row,
+      write,
+      done,
+      detach: () => processes.unsubscribe(record.pid, subscriber),
+    });
+  });
 
-    const stopHeartbeat = startExecHeartbeat(
-      db,
-      row.sandboxId,
-      row.freezeAfterSeconds,
-    );
-    // Keepalive events on the interval the SDK asked for — what keeps
-    // proxies from cutting a silent long command.
-    const keepaliveSeconds = Math.min(
-      Number(request.headers['keepalive-ping-interval']) ||
-        MAX_KEEPALIVE_SECONDS,
-      MAX_KEEPALIVE_SECONDS,
+  app.post('/process.Process/Connect', async (request, reply) => {
+    const message = readFirstMessage(request.body as Buffer) as {
+      process?: { pid?: number };
+    };
+    const pid = message.process?.pid;
+    if (typeof pid !== 'number') {
+      return streamError(reply, 'invalid_argument', 'missing process pid');
+    }
+    const row = await wakeForStream(request, reply);
+    if (!row) return;
+    const record = processes.get(row.sandboxId, pid);
+    if (!record) {
+      return streamError(reply, 'not_found', `process not found: ${pid}`);
+    }
+    const write = rawWriter(reply);
+    const { subscriber, done } = streamSubscriber(write);
+    reply.hijack();
+    reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
+    // The SDK requires a Connect stream to open with a start frame, exactly
+    // like Start's. Initiated before subscribing so no data frame can slip
+    // ahead of it (raw writes keep call order). No replay of past output —
+    // real envd's semantics.
+    const startFrame = write(
+      envelope(FLAG_MESSAGE, { event: { start: { pid: record.pid } } }),
     );
-    const keepalive = setInterval(() => {
-      reply.raw.write(envelope(FLAG_MESSAGE, { event: { keepalive: {} } }));
-    }, keepaliveSeconds * 1000);
-
-    let deadlineTimer: NodeJS.Timeout | undefined;
-    const deadline = new Promise<'deadline'>((resolve) => {
-      deadlineTimer = setTimeout(() => resolve('deadline'), deadlineMs);
+    const unsubscribe = processes.subscribe(pid, subscriber);
+    await startFrame;
+    if (!unsubscribe) {
+      // Finished between get and subscribe: report it rather than hold a
+      // stream that would never end.
+      await write(
+        envelope(FLAG_END_STREAM, {
+          error: { code: 'not_found', message: `process not found: ${pid}` },
+        }),
+      );
+      reply.raw.end();
+      return;
+    }
+    await pumpProcessStream({
+      request,
+      reply,
+      row,
+      write,
+      done,
+      detach: unsubscribe,
     });
+  });
 
+  /** {process:{pid}} — the proto3-JSON flattening of the selector oneof. */
+  function requirePid(body: unknown): number {
+    const pid = (body as { process?: { pid?: unknown } })?.process?.pid;
+    if (typeof pid !== 'number') {
+      throw connectError('invalid_argument', 'missing process pid');
+    }
+    return pid;
+  }
+
+  /** A living process for this sandbox, or the not_found the SDK expects. */
+  function requireProcess(sandboxId: string, pid: number): ProcessRecord {
+    const record = processes.get(sandboxId, pid);
+    if (!record) {
+      throw connectError('not_found', `process not found: ${pid}`);
+    }
+    return record;
+  }
+
+  app.post('/process.Process/SendInput', async (request) => {
+    const body = request.body as {
+      process?: { pid?: number };
+      input?: { stdin?: string; pty?: string };
+    };
+    const pid = requirePid(body);
+    const row = await wakeForUse(sandboxIdOf(request));
+    const record = requireProcess(row.sandboxId, pid);
+    const stdinB64 = body.input?.stdin;
+    const ptyB64 = body.input?.pty;
+    if (typeof stdinB64 !== 'string' && typeof ptyB64 !== 'string') {
+      throw connectError('invalid_argument', 'missing input');
+    }
+    // Channel and promise must match: stdin input needs a stdin:true start,
+    // pty input needs a PTY session — a mismatch is the caller's confusion.
+    if (typeof stdinB64 === 'string' && !record.stdin) {
+      throw connectError(
+        'invalid_argument',
+        'process was started without stdin',
+      );
+    }
+    if (typeof ptyB64 === 'string' && !record.pty) {
+      throw connectError('invalid_argument', 'process has no PTY');
+    }
+    const data = Buffer.from((stdinB64 ?? ptyB64) as string, 'base64');
     try {
-      const sandboxEnvs: Record<string, string> = row.envs
-        ? JSON.parse(row.envs)
-        : {};
-      const handle = await executor.execStream(row.sandboxId, {
-        command,
-        loginShell,
-        timeoutSeconds,
-        cwd: proc.cwd,
-        // Sandbox-level envs underneath, per-command envs on top.
-        env: { ...sandboxEnvs, ...(proc.envs ?? {}) },
-        onStdout: (chunk) =>
-          write(
-            envelope(FLAG_MESSAGE, {
-              event: { data: { stdout: chunk.toString('base64') } },
-            }),
-          ),
-        onStderr: (chunk) =>
-          write(
-            envelope(FLAG_MESSAGE, {
-              event: { data: { stderr: chunk.toString('base64') } },
-            }),
-          ),
-      });
-      const outcome = await Promise.race([handle.wait(), deadline]);
-      if (outcome === 'deadline') {
-        // Real envd answers a blown deadline with the Connect error, not an
-        // end event; the SDK turns it into its TimeoutError.
-        await write(
-          envelope(FLAG_END_STREAM, {
-            error: {
-              code: 'deadline_exceeded',
-              message: `command timed out after ${deadlineMs}ms`,
-            },
-          }),
-        );
-        return;
-      }
-      const { exitCode } = outcome;
-      await write(
-        envelope(FLAG_MESSAGE, {
-          event: {
-            end: {
-              exitCode,
-              exited: true,
-              status: exitCode === 137 ? 'killed' : 'exited',
-              ...(exitCode === 137
-                ? { error: 'command killed (exit 137)' }
-                : {}),
-            },
-          },
-        }),
+      await record.handle.sendStdin(data);
+    } catch (error) {
+      throw connectError(
+        'invalid_argument',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    return {};
+  });
+
+  app.post('/process.Process/CloseStdin', async (request) => {
+    const pid = requirePid(request.body);
+    const row = await wakeForUse(sandboxIdOf(request));
+    const record = requireProcess(row.sandboxId, pid);
+    if (!record.stdin) {
+      throw connectError(
+        'invalid_argument',
+        'process was started without stdin',
       );
-      await write(envelope(FLAG_END_STREAM, {}));
+    }
+    try {
+      await record.handle.closeStdin();
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      reply.raw.write(
-        envelope(FLAG_END_STREAM, { error: { code: 'internal', message } }),
+      throw connectError(
+        'invalid_argument',
+        error instanceof Error ? error.message : String(error),
       );
-    } finally {
-      clearInterval(keepalive);
-      clearTimeout(deadlineTimer);
-      stopHeartbeat();
-      try {
-        // The command itself was the activity: the idle countdown starts
-        // when it ends, not when it started.
-        touch(db, row.sandboxId);
-      } catch {
-        // Released mid-exec; the stream's own ending tells the story.
-      }
-      reply.raw.end();
     }
+    return {};
+  });
+
+  app.post('/process.Process/SendSignal', async (request) => {
+    const body = request.body as {
+      process?: { pid?: number };
+      signal?: string | number;
+    };
+    const pid = requirePid(body);
+    // proto3-JSON enums travel as their names; a numeric fallback costs
+    // nothing and covers a client that emits raw values.
+    const sig =
+      body.signal === 'SIGNAL_SIGKILL' || body.signal === 9
+        ? ('SIGKILL' as const)
+        : body.signal === 'SIGNAL_SIGTERM' || body.signal === 15
+          ? ('SIGTERM' as const)
+          : undefined;
+    if (!sig) {
+      throw connectError(
+        'invalid_argument',
+        `unsupported signal: ${String(body.signal)} — only SIGKILL and SIGTERM are supported`,
+      );
+    }
+    const row = await wakeForUse(sandboxIdOf(request));
+    const record = requireProcess(row.sandboxId, pid);
+    try {
+      await record.handle.signal(sig);
+    } catch {
+      // The process ended between lookup and signal: protocol-wise it does
+      // not exist — the SDK turns not_found into kill() === false.
+      throw connectError('not_found', `process not found: ${pid}`);
+    }
+    return {};
+  });
+
+  app.post('/process.Process/Update', async (request) => {
+    const body = request.body as {
+      process?: { pid?: number };
+      pty?: { size?: { cols?: number; rows?: number } };
+    };
+    const pid = requirePid(body);
+    const row = await wakeForUse(sandboxIdOf(request));
+    const record = requireProcess(row.sandboxId, pid);
+    if (!record.pty) {
+      throw connectError('invalid_argument', 'process has no PTY');
+    }
+    const size = body.pty?.size;
+    if (
+      typeof size?.cols !== 'number' ||
+      typeof size?.rows !== 'number' ||
+      size.cols <= 0 ||
+      size.rows <= 0
+    ) {
+      throw connectError('invalid_argument', 'missing pty size');
+    }
+    try {
+      await record.handle.resizePty({ cols: size.cols, rows: size.rows });
+    } catch (error) {
+      throw connectError(
+        'invalid_argument',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    return {};
   });
 
   /** Streaming endpoints answer errors inside the stream: 200 + end-stream frame. */
@@ -650,17 +939,9 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
 
   const unimplemented: Array<[string, string]> = [
     [
-      '/process.Process/SendInput',
-      'stdin is not supported yet — pass data via files.write and read it from your command',
-    ],
-    ['/process.Process/SendSignal', 'signaling a process is not supported yet'],
-    ['/process.Process/CloseStdin', 'stdin is not supported yet'],
-    [
-      '/process.Process/Connect',
-      'reconnecting to a running command is not supported yet',
+      '/process.Process/StreamInput',
+      'streamed stdin is not supported — the SDK sends stdin via SendInput',
     ],
-    ['/process.Process/Update', 'PTY is not supported yet'],
-    ['/process.Process/StreamInput', 'stdin is not supported yet'],
     [
       '/filesystem.Filesystem/WatchDir',
       'directory watching is not supported yet — poll files.list instead',
diff --git a/packages/server/src/e2b/process-table.ts b/packages/server/src/e2b/process-table.ts
new file mode 100644
index 0000000..1aa1d4a
--- /dev/null
+++ b/packages/server/src/e2b/process-table.ts
@@ -0,0 +1,174 @@
+import type {
+  ExecStreamHandle,
+  ExecStreamOptions,
+  Executor,
+  PtySize,
+} from '../executor/executor';
+
+/**
+ * The daemon-side process table behind the E2B process surface. E2B's
+ * defining behavior — `background: true` is the same wire as a foreground
+ * run, `disconnect()` never kills, `connect(pid)` reattaches — means a
+ * process's lifetime must be decoupled from any HTTP response's. This table
+ * is that decoupling: envd streams are just subscribers that come and go;
+ * the process lives here until it exits, is signaled, or its sandbox dies.
+ *
+ * It lives in e2b/ and not beside the executor on purpose: the pid scheme,
+ * "list shows only the living" and the no-replay rule are all E2B protocol
+ * semantics. The native API has no process verbs; hoisting this early would
+ * be abstraction ahead of need.
+ *
+ * Deliberately not persisted: a daemon restart empties the table — the
+ * in-container processes it tracked become orphans that the in-container
+ * timeout backstop or the sandbox's own death reap. Honest and documented,
+ * and better than E2B, whose registry does not even survive pause/resume.
+ */
+
+/** The process config as the SDK sent it, echoed back verbatim by List. */
+export interface WireProcessConfig {
+  cmd: string;
+  args: string[];
+  envs: Record<string, string>;
+  cwd?: string;
+}
+
+export type OutputChannel = 'stdout' | 'stderr' | 'pty';
+
+export type ProcessEnd =
+  | { kind: 'exit'; exitCode: number }
+  | { kind: 'error'; message: string };
+
+export interface ProcessSubscriber {
+  /**
+   * One output chunk. A returned promise is awaited before the next chunk
+   * reaches ANY subscriber — slowest-subscriber backpressure, the Unix pipe
+   * semantic, riding the executor's own callback contract. With zero
+   * subscribers the broadcast resolves immediately: a background process
+   * nobody watches drains and drops, it never wedges.
+   */
+  onOutput(channel: OutputChannel, chunk: Buffer): void | Promise<void>;
+  /** The process's ending. Called exactly once, after the last onOutput. */
+  onEnd(end: ProcessEnd): void;
+}
+
+export interface ProcessRecord {
+  readonly pid: number;
+  readonly sandboxId: string;
+  readonly config: WireProcessConfig;
+  /** Whether Start promised stdin — SendInput's gate. */
+  readonly stdin: boolean;
+  /** Present for PTY sessions; List shows them alongside plain commands. */
+  readonly pty?: PtySize;
+  readonly handle: ExecStreamHandle;
+}
+
+interface InternalRecord extends ProcessRecord {
+  readonly subscribers: Set<ProcessSubscriber>;
+}
+
+export class ProcessTable {
+  /** Synthetic, table-wide: the SDK only ever uses pids as opaque handles. */
+  private nextPid = 1000;
+  private readonly records = new Map<number, InternalRecord>();
+
+  /**
+   * Registers, subscribes and starts in one step, in that order: the
+   * initial subscriber is in place before the exec begins, and the executor
+   * guarantees no output before execStream resolves — together, the first
+   * chunk cannot be lost. A start failure leaves no table entry behind and
+   * rethrows as-is.
+   *
+   * The process's ending is hooked here: wait() settling — exit code or
+   * error, including the container dying under it — broadcasts onEnd to
+   * every subscriber and deletes the entry. That single finalize path is
+   * why sandbox stop/destroy needs no table hook: the physics (container
+   * death ends every exec) conducts the cleanup.
+   */
+  async start(args: {
+    executor: Executor;
+    sandboxId: string;
+    options: Omit<ExecStreamOptions, 'onStdout' | 'onStderr'>;
+    config: WireProcessConfig;
+    pty?: PtySize;
+    subscriber?: ProcessSubscriber;
+  }): Promise<ProcessRecord> {
+    const pid = this.nextPid++;
+    const subscribers = new Set<ProcessSubscriber>();
+    if (args.subscriber) subscribers.add(args.subscriber);
+    const broadcast =
+      (channel: OutputChannel) =>
+      (chunk: Buffer): Promise<void> =>
+        Promise.all(
+          [...subscribers].map((s) => s.onOutput(channel, chunk)),
+        ).then(() => {});
+    const handle = await args.executor.execStream(args.sandboxId, {
+      ...args.options,
+      // A PTY is one merged byte stream; a plain command keeps its two.
+      onStdout: broadcast(args.pty ? 'pty' : 'stdout'),
+      onStderr: broadcast('stderr'),
+    });
+    const record: InternalRecord = {
+      pid,
+      sandboxId: args.sandboxId,
+      config: args.config,
+      stdin: args.options.stdin ?? false,
+      pty: args.pty,
+      handle,
+      subscribers,
+    };
+    this.records.set(pid, record);
+    handle.wait().then(
+      ({ exitCode }) => this.finalize(record, { kind: 'exit', exitCode }),
+      (error) =>
+        this.finalize(record, {
+          kind: 'error',
+          message: error instanceof Error ? error.message : String(error),
+        }),
+    );
+    return record;
+  }
+
+  /** Living processes only; a pid from another sandbox is invisible. */
+  get(sandboxId: string, pid: number): ProcessRecord | undefined {
+    const record = this.records.get(pid);
+    return record?.sandboxId === sandboxId ? record : undefined;
+  }
+
+  list(sandboxId: string): ProcessRecord[] {
+    return [...this.records.values()].filter((r) => r.sandboxId === sandboxId);
+  }
+
+  /**
+   * Attaches a subscriber; returns the unsubscribe, or undefined when the
+   * process already ended (finalize won between the caller's get and this
+   * call) — the caller reports not_found instead of waiting on a stream
+   * that would never end. No replay: a late subscriber sees output from
+   * now on, same as real envd.
+   */
+  subscribe(
+    pid: number,
+    subscriber: ProcessSubscriber,
+  ): (() => void) | undefined {
+    const record = this.records.get(pid);
+    if (!record) return undefined;
+    record.subscribers.add(subscriber);
+    return () => record.subscribers.delete(subscriber);
+  }
+
+  /** Detaches a subscriber start() attached; gone-already is the goal state. */
+  unsubscribe(pid: number, subscriber: ProcessSubscriber): void {
+    this.records.get(pid)?.subscribers.delete(subscriber);
+  }
+
+  private finalize(record: InternalRecord, end: ProcessEnd): void {
+    if (!this.records.delete(record.pid)) return;
+    for (const subscriber of [...record.subscribers]) {
+      record.subscribers.delete(subscriber);
+      try {
+        subscriber.onEnd(end);
+      } catch {
+        // A subscriber whose stream already broke is its own ending.
+      }
+    }
+  }
+}
diff --git a/packages/server/src/executor/contract.ts b/packages/server/src/executor/contract.ts
index 3d2385f..9fa5038 100644
--- a/packages/server/src/executor/contract.ts
+++ b/packages/server/src/executor/contract.ts
@@ -450,6 +450,209 @@ export function describeExecutorContract(
       timeoutMs,
     );
 
+    it(
+      'execStream stdin round-trips: sendStdin chunks echo back, closeStdin is EOF',
+      async () => {
+        const id = await fresh();
+        const seen: string[] = [];
+        const handle = await executor.execStream(id, {
+          command: 'cat',
+          timeoutSeconds: 30,
+          stdin: true,
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        await handle.sendStdin(Buffer.from('hello '));
+        await handle.sendStdin(Buffer.from('world'));
+        await handle.closeStdin();
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(0);
+        expect(seen.join('')).toBe('hello world');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'execStream closeStdin with nothing written ends the command cleanly',
+      async () => {
+        const id = await fresh();
+        const seen: string[] = [];
+        const handle = await executor.execStream(id, {
+          command: 'cat',
+          timeoutSeconds: 30,
+          stdin: true,
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        await handle.closeStdin();
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(0);
+        expect(seen.join('')).toBe('');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'sendStdin on a command started without stdin refuses honestly',
+      async () => {
+        const id = await fresh();
+        const handle = await executor.execStream(id, {
+          command: 'sleep 5',
+          timeoutSeconds: 30,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await expect(handle.sendStdin(Buffer.from('x'))).rejects.toThrow(
+          'process was started without stdin',
+        );
+        await expect(handle.closeStdin()).rejects.toThrow(
+          'process was started without stdin',
+        );
+        await handle.signal('SIGKILL');
+        await handle.wait();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'sendStdin after closeStdin refuses: stdin is closed',
+      async () => {
+        const id = await fresh();
+        const handle = await executor.execStream(id, {
+          command: 'cat',
+          timeoutSeconds: 30,
+          stdin: true,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await handle.closeStdin();
+        await expect(handle.sendStdin(Buffer.from('late'))).rejects.toThrow(
+          'stdin is closed',
+        );
+        await handle.wait();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'signal SIGKILL lands as exit 137; delivered chunks stay delivered',
+      async () => {
+        const id = await fresh();
+        const seen: string[] = [];
+        const handle = await executor.execStream(id, {
+          command: 'echo early; sleep 30',
+          timeoutSeconds: 60,
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        // Wait for the first chunk so the kill provably interrupts, not races.
+        const before = Date.now();
+        while (seen.length === 0 && Date.now() - before < 5_000) {
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        await handle.signal('SIGKILL');
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(137);
+        expect(seen.join('')).toBe('early\n');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'signal SIGTERM lands as exit 143',
+      async () => {
+        const id = await fresh();
+        const handle = await executor.execStream(id, {
+          command: 'sleep 30',
+          timeoutSeconds: 60,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await handle.signal('SIGTERM');
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(143);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'execStream emits nothing before it resolves',
+      async () => {
+        const id = await fresh();
+        let resolved = false;
+        let leaked = false;
+        const handle = await executor.execStream(id, {
+          command: 'echo eager',
+          timeoutSeconds: 30,
+          onStdout: () => {
+            if (!resolved) leaked = true;
+          },
+          onStderr: () => {},
+        });
+        resolved = true;
+        await handle.wait();
+        expect(leaked).toBe(false);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a command survives freeze/unfreeze and completes afterwards',
+      async () => {
+        const id = await fresh();
+        const seen: string[] = [];
+        const handle = await executor.execStream(id, {
+          command: 'sleep 1; echo woke',
+          timeoutSeconds: 30,
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        await executor.freeze(id);
+        await executor.unfreeze(id);
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(0);
+        expect(seen.join('')).toContain('woke');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'stopping the sandbox settles a running command in bounded time',
+      async () => {
+        // The shape of the ending is not pinned — the real engine may report
+        // 137 or lose the exit code entirely; settling at all is the contract
+        // (a dangling wait would strand every process-table subscriber).
+        const id = await fresh();
+        const handle = await executor.execStream(id, {
+          command: 'sleep 30',
+          timeoutSeconds: 60,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await executor.freeze(id);
+        await executor.stop(id);
+        const outcome = await Promise.race([
+          handle.wait().then(
+            () => 'settled',
+            () => 'settled',
+          ),
+          new Promise((resolve) =>
+            setTimeout(() => resolve('hung'), timeoutMs - 1_000),
+          ),
+        ]);
+        expect(outcome).toBe('settled');
+      },
+      timeoutMs,
+    );
+
     it(
       'writeFiles then readFile round-trips text',
       async () => {
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 77e3c2a..2f22180 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import {
   access,
   chown,
@@ -8,6 +9,7 @@ import {
   rm,
 } from 'node:fs/promises';
 import path from 'node:path';
+import type { Duplex } from 'node:stream';
 import { Writable } from 'node:stream';
 import {
   EXEC_OUTPUT_LIMIT_BYTES,
@@ -151,6 +153,36 @@ const REMOVE_SCRIPT = [
   'exec rm -rf -- "$1"',
 ].join('\n');
 
+/**
+ * Wrapper every execStream command runs under, so the handle can signal it
+ * later. $1 = pidfile, $2 = timeout seconds, $3 = the user's command.
+ * The exec chain keeps the pid stable: the recorded $$ is the bash that
+ * becomes `timeout`, and `setsid --wait` outside made that pid a fresh
+ * process-group leader — one `kill -- -pid` reaps the command and all its
+ * descendants (GNU timeout's own group-kill relies on the same pgid).
+ * setsid needs --wait or the exec would observe the fork's instant exit 0.
+ */
+function execStreamWrapper(loginShell: boolean): string {
+  const shell = loginShell ? 'bash -l -c' : 'bash -c';
+  return [
+    'echo "$$" > "$1"',
+    `exec timeout --signal=KILL "$2" ${shell} "$3"`,
+  ].join('\n');
+}
+
+/**
+ * $1 = pidfile, $2 = signal name (SIGKILL/SIGTERM). The brief wait covers
+ * the honest race of a signal arriving before the wrapper's first line has
+ * written the pidfile. Group kill first; a leader that already died with
+ * children lingering still gets the single-pid fallback.
+ */
+const SIGNAL_SCRIPT = [
+  'for _ in $(seq 1 40); do [ -s "$1" ] && break; sleep 0.05; done',
+  'p=$(cat "$1") || exit 1',
+  '[ -n "$p" ] || exit 1',
+  'kill -s "$2" -- "-$p" 2>/dev/null || exec kill -s "$2" "$p"',
+].join('\n');
+
 /** One `find -printf` record (see LIST_DIR_SCRIPT) -> entry. */
 function entryFromFindRecord(record: string): SandboxEntry {
   const fields = record.split('\t');
@@ -474,21 +506,90 @@ export class DockerExecutor implements Executor {
   ): Promise<ExecStreamHandle> {
     const containerId = await this.expectState(sandboxId, 'running');
     const container = this.docker.getContainer(containerId);
-    const shell = opts.loginShell ? ['bash', '-l', '-c'] : ['bash', '-c'];
-    const wait = await this.startInContainer(container, sandboxId, {
+    // The pidfile is the handle's way back to the process: /tmp is the
+    // sandbox's own, so a leftover file is the sandbox's own garbage — it
+    // is deliberately not removed on kill, or a TERM that the process
+    // survives would strand the follow-up KILL.
+    const pidfile = `/tmp/.dormice-exec-${randomUUID()}.pid`;
+    const started = await this.startInContainer(container, sandboxId, {
       cmd: [
-        'timeout',
-        '--signal=KILL',
+        'setsid',
+        '--wait',
+        'bash',
+        '-c',
+        execStreamWrapper(opts.loginShell ?? false),
+        'bash',
+        pidfile,
         String(opts.timeoutSeconds),
-        ...shell,
         opts.command,
       ],
       stdout: new CallbackSink(opts.onStdout),
       stderr: new CallbackSink(opts.onStderr),
+      stdin: opts.stdin ? 'open' : undefined,
       workingDir: opts.cwd,
       env: opts.env,
     });
-    return { wait: async () => ({ exitCode: await wait() }) };
+    let finished = false;
+    const done = started.wait().then((exitCode) => {
+      finished = true;
+      return { exitCode };
+    });
+    done.catch(() => {
+      finished = true;
+    });
+    const stdinStream = started.stdinStream;
+    return {
+      wait: () => done,
+      sendStdin: async (data) => {
+        if (!stdinStream) {
+          throw new Error('process was started without stdin');
+        }
+        if (stdinStream.writableEnded) {
+          throw new Error('stdin is closed');
+        }
+        await new Promise<void>((resolve, reject) => {
+          stdinStream.write(data, (err) => (err ? reject(err) : resolve()));
+        });
+      },
+      closeStdin: async () => {
+        if (!stdinStream) {
+          throw new Error('process was started without stdin');
+        }
+        if (stdinStream.writableEnded) {
+          throw new Error('stdin is closed');
+        }
+        await new Promise<void>((resolve) => {
+          stdinStream.end(resolve);
+        });
+      },
+      signal: async (sig) => {
+        if (finished) {
+          throw new Error('process already exited');
+        }
+        await this.signalProcess(container, sandboxId, pidfile, sig);
+      },
+      resizePty: async () => {
+        throw new Error('process has no PTY');
+      },
+    };
+  }
+
+  /** Delivers a signal to an execStream'd process group via its pidfile. */
+  private async signalProcess(
+    container: Docker.Container,
+    sandboxId: string,
+    pidfile: string,
+    sig: 'SIGTERM' | 'SIGKILL',
+  ): Promise<void> {
+    const run = await this.runInContainer(container, sandboxId, {
+      cmd: ['bash', '-c', SIGNAL_SCRIPT, 'bash', pidfile, sig],
+      outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+    });
+    if (run.exitCode !== 0) {
+      throw new Error(
+        `signaling process in ${sandboxId} failed (exit ${run.exitCode}): ${run.stderr.text().trim()}`,
+      );
+    }
   }
 
   async writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void> {
@@ -577,7 +678,7 @@ export class DockerExecutor implements Executor {
     const containerId = await this.expectState(sandboxId, 'running');
     const container = this.docker.getContainer(containerId);
     const stderr = new CappedBuffer(EXEC_OUTPUT_LIMIT_BYTES);
-    const wait = await this.startInContainer(container, sandboxId, {
+    const started = await this.startInContainer(container, sandboxId, {
       cmd: [
         'timeout',
         '--signal=KILL',
@@ -591,7 +692,7 @@ export class DockerExecutor implements Executor {
       stdout: new CallbackSink(onChunk),
       stderr,
     });
-    const exitCode = await wait();
+    const exitCode = await started.wait();
     if (exitCode === NO_SUCH_FILE_EXIT) {
       throw new FileNotFoundError(`no such file: ${resolved}`);
     }
@@ -820,7 +921,7 @@ export class DockerExecutor implements Executor {
   ): Promise<{ exitCode: number; stdout: CappedBuffer; stderr: CappedBuffer }> {
     const stdout = new CappedBuffer(spec.outputCap);
     const stderr = new CappedBuffer(spec.outputCap);
-    const wait = await this.startInContainer(container, sandboxId, {
+    const started = await this.startInContainer(container, sandboxId, {
       cmd: spec.cmd,
       stdout,
       stderr,
@@ -828,7 +929,7 @@ export class DockerExecutor implements Executor {
       workingDir: spec.workingDir,
       env: spec.env,
     });
-    return { exitCode: await wait(), stdout, stderr };
+    return { exitCode: await started.wait(), stdout, stderr };
   }
 
   /**
@@ -840,6 +941,12 @@ export class DockerExecutor implements Executor {
    * multiplexed stream is what demuxStream can split back into distinct
    * stdout and stderr. Resolving means the command has started; everything
    * after start is the wait's business.
+   *
+   * stdin comes in three shapes: bytes (written and ended — EOF now), a
+   * source stream (piped, its end is the EOF), or 'open' — the hijacked
+   * duplex is handed back as stdinStream for the caller to write and
+   * half-close at will (measured with writeFiles: output keeps flowing
+   * after the write side ends).
    */
   private async startInContainer(
     container: Docker.Container,
@@ -848,11 +955,11 @@ export class DockerExecutor implements Executor {
       cmd: string[];
       stdout: Writable;
       stderr: Writable;
-      stdin?: Buffer | NodeJS.ReadableStream;
+      stdin?: Buffer | NodeJS.ReadableStream | 'open';
       workingDir?: string;
       env?: Record<string, string>;
     },
-  ): Promise<() => Promise<number>> {
+  ): Promise<{ wait: () => Promise<number>; stdinStream?: Duplex }> {
     const exec = await container.exec({
       Cmd: spec.cmd,
       AttachStdin: spec.stdin !== undefined,
@@ -868,7 +975,7 @@ export class DockerExecutor implements Executor {
       spec.stdin !== undefined ? { hijack: true, stdin: true } : {},
     );
     this.docker.modem.demuxStream(stream, spec.stdout, spec.stderr);
-    if (spec.stdin !== undefined) {
+    if (spec.stdin !== undefined && spec.stdin !== 'open') {
       if (Buffer.isBuffer(spec.stdin)) {
         stream.end(spec.stdin);
       } else {
@@ -901,7 +1008,10 @@ export class DockerExecutor implements Executor {
     // A failure before anyone calls wait must not crash the daemon as an
     // unhandled rejection; wait() still observes it through the same promise.
     finished.catch(() => {});
-    return () => finished;
+    return {
+      wait: () => finished,
+      stdinStream: spec.stdin === 'open' ? stream : undefined,
+    };
   }
 
   private imagePath(sandboxId: string): string {
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index 7130a33..7cde317 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -28,6 +28,12 @@ export interface ExecResult {
   stderrTruncated: boolean;
 }
 
+/** Terminal dimensions, the shape Process/Update's resize speaks. */
+export interface PtySize {
+  cols: number;
+  rows: number;
+}
+
 export interface ExecStreamOptions {
   /** A shell string, executed as `bash -c <command>` inside the sandbox. */
   command: string;
@@ -41,11 +47,20 @@ export interface ExecStreamOptions {
    * protocol stays true to its own contract.
    */
   loginShell?: boolean;
+  /**
+   * Keep stdin open for the handle's sendStdin/closeStdin. Absent means the
+   * command starts with stdin already at EOF (the old behavior); the handle
+   * verbs then refuse honestly instead of writing into nothing.
+   */
+  stdin?: boolean;
   /**
    * Called with each output chunk as it arrives. No cap: nothing accumulates
    * server-side. A returned promise MAY be awaited before the next chunk
    * (the real executor does — backpressure travels to the container; the
    * fake's in-memory source has nothing to press back on).
+   * Never called before execStream itself resolves: the caller gets to
+   * finish its own bookkeeping (write a wire start frame, register the
+   * process) knowing no output has slipped past it.
    */
   onStdout: (chunk: Buffer) => void | Promise<void>;
   onStderr: (chunk: Buffer) => void | Promise<void>;
@@ -53,12 +68,32 @@ export interface ExecStreamOptions {
 
 /**
  * A started command. Obtaining the handle means the exec is running; wait()
- * is its result. Deliberately handle-shaped (not a plain promise): process
- * management verbs — kill, stdin, reconnect — will grow here later without
- * reshaping every caller.
+ * is its result. The management verbs exist on every handle and refuse
+ * honestly when they do not apply — their refusal messages are part of the
+ * executor contract, because the E2B surface forwards them to clients.
  */
 export interface ExecStreamHandle {
   wait(): Promise<{ exitCode: number }>;
+  /**
+   * Writes into the command's stdin. Requires the command to have been
+   * started with `stdin: true` (else: "process was started without stdin");
+   * after closeStdin it refuses with "stdin is closed". A resolved promise
+   * means the bytes are on their way to the in-container reader.
+   */
+  sendStdin(data: Buffer): Promise<void>;
+  /** Delivers EOF to the command's stdin. Same refusals as sendStdin. */
+  closeStdin(): Promise<void>;
+  /**
+   * Delivers a signal to the command's whole process group — SIGKILL lands
+   * as exit 137 through wait(), SIGTERM as 143 (unless caught). Rejects when
+   * the process has already finished; that wording is not contract-pinned.
+   */
+  signal(sig: 'SIGTERM' | 'SIGKILL'): Promise<void>;
+  /**
+   * Resizes the command's pseudo-terminal. Refuses with "process has no PTY"
+   * for a plain command — PTY sessions arrive with the pty exec option.
+   */
+  resizePty(size: PtySize): Promise<void>;
 }
 
 export interface FileToWrite {
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index 1ba1d4d..1998a33 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -76,6 +76,71 @@ function entryFor(path: string, node: FakeNode): SandboxEntry {
   };
 }
 
+/**
+ * The live half of a fake process: a stdin mailbox and a kill switch. The
+ * interpreter reads the mailbox (cat), sleeps interruptibly against the
+ * kill promise, and the handle's verbs write into it — the same decoupling
+ * of process from stream the real executor gets from the hijacked duplex.
+ */
+class FakeProcessIO {
+  private queue: Buffer[] = [];
+  private stdinClosed = false;
+  private wakeups: Array<() => void> = [];
+  killSignal: 'SIGTERM' | 'SIGKILL' | undefined;
+  private killResolve!: (exitCode: number) => void;
+  /** Settles with the signal's exit code (KILL 137, TERM 143) when killed. */
+  readonly killed = new Promise<number>((resolve) => {
+    this.killResolve = resolve;
+  });
+
+  pushStdin(data: Buffer): void {
+    if (this.stdinClosed) throw new Error('stdin is closed');
+    this.queue.push(data);
+    this.wake();
+  }
+
+  closeStdin(): void {
+    if (this.stdinClosed) throw new Error('stdin is closed');
+    this.stdinClosed = true;
+    this.wake();
+  }
+
+  kill(sig: 'SIGTERM' | 'SIGKILL'): void {
+    if (this.killSignal) return;
+    this.killSignal = sig;
+    this.killResolve(sig === 'SIGKILL' ? 137 : 143);
+    this.wake();
+  }
+
+  /** Next stdin chunk; null is EOF — closeStdin's or the kill's. */
+  async nextStdin(): Promise<Buffer | null> {
+    while (true) {
+      const chunk = this.queue.shift();
+      if (chunk) return chunk;
+      if (this.stdinClosed || this.killSignal) return null;
+      await new Promise<void>((resolve) => this.wakeups.push(resolve));
+    }
+  }
+
+  /** Sleeps, but a kill cuts it short — a real sleep dies to SIGKILL too. */
+  async sleep(ms: number): Promise<void> {
+    let timer: NodeJS.Timeout | undefined;
+    await Promise.race([
+      new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, ms);
+      }),
+      this.killed,
+    ]);
+    clearTimeout(timer);
+  }
+
+  private wake(): void {
+    const pending = this.wakeups;
+    this.wakeups = [];
+    for (const resolve of pending) resolve();
+  }
+}
+
 /**
  * In-memory stand-in for the Docker+gVisor executor. Not a throwaway: it is
  * the permanent test double — unit tests and local development run on it;
@@ -88,6 +153,12 @@ function entryFor(path: string, node: FakeNode): SandboxEntry {
 export class FakeExecutor implements Executor {
   private readonly containers = new Map<string, ContainerState>();
   private readonly disks = new Set<string>();
+  /**
+   * Live processes per sandbox. stop/destroy/vanish kill them — on the real
+   * executor the container's death takes every exec with it, and the fake
+   * must conduct the same physics or the process table above it would leak.
+   */
+  private readonly procs = new Map<string, Set<FakeProcessIO>>();
   /**
    * Keyed like disks, not containers: files are the disk's content, so they
    * survive stop, start, and a vanished container object, and die only when
@@ -110,6 +181,7 @@ export class FakeExecutor implements Executor {
     if (!this.containers.delete(sandboxId)) {
       throw new Error(`container ${sandboxId} is absent, cannot vanish`);
     }
+    this.killProcesses(sandboxId);
   }
 
   /**
@@ -142,6 +214,7 @@ export class FakeExecutor implements Executor {
   async stop(sandboxId: string): Promise<void> {
     this.expect(sandboxId, 'paused');
     this.containers.set(sandboxId, 'stopped');
+    this.killProcesses(sandboxId);
   }
 
   async start(sandboxId: string): Promise<void> {
@@ -169,6 +242,7 @@ export class FakeExecutor implements Executor {
     const hadContainer = this.containers.delete(sandboxId);
     const hadDisk = this.disks.delete(sandboxId);
     this.fs.delete(sandboxId);
+    this.killProcesses(sandboxId);
     if (!hadContainer && !hadDisk) {
       throw new Error(`container ${sandboxId} is absent, cannot destroy`);
     }
@@ -215,39 +289,91 @@ export class FakeExecutor implements Executor {
     opts: ExecStreamOptions,
   ): Promise<ExecStreamHandle> {
     this.expect(sandboxId, 'running');
-    // The timeout races the interpreter, same outcome as the real executor's
-    // in-container `timeout --signal=KILL`: exit 137. Chunks delivered before
-    // the kill stay delivered — an emitted chunk cannot be unsent — and the
-    // flag silences anything the losing interpreter emits afterwards.
-    let timedOut = false;
+    const io = new FakeProcessIO();
+    this.trackProcess(sandboxId, io);
+    // The timeout and the kill switch race the interpreter, same outcomes
+    // as the real executor's in-container `timeout --signal=KILL` and the
+    // handle's signal(): 137/143. Chunks delivered before the kill stay
+    // delivered — an emitted chunk cannot be unsent — and the flag silences
+    // anything the losing interpreter emits afterwards.
+    let silenced = false;
     const emit = {
       stdout: (text: string) => {
-        if (!timedOut) opts.onStdout(Buffer.from(text, 'utf8'));
+        if (!silenced) opts.onStdout(Buffer.from(text, 'utf8'));
       },
       stderr: (text: string) => {
-        if (!timedOut) opts.onStderr(Buffer.from(text, 'utf8'));
+        if (!silenced) opts.onStderr(Buffer.from(text, 'utf8'));
       },
     };
+    let finished = false;
     const done = (async () => {
+      // One macrotask of quiet: no output before execStream itself resolves
+      // — the interface's promise to callers, which the real executor keeps
+      // physically (I/O events cannot preempt the awaiting caller) and the
+      // interpreter's synchronous first verb would otherwise break.
+      await new Promise((resolve) => setImmediate(resolve));
       let timer: NodeJS.Timeout | undefined;
       const deadline = new Promise<number>((resolve) => {
         timer = setTimeout(() => {
-          timedOut = true;
+          silenced = true;
           resolve(137);
         }, opts.timeoutSeconds * 1000);
       });
+      const killed = io.killed.then((exitCode) => {
+        silenced = true;
+        return exitCode;
+      });
       try {
         return {
-          exitCode: await Promise.race([interpret(opts, emit), deadline]),
+          exitCode: await Promise.race([
+            interpret(opts, emit, io),
+            deadline,
+            killed,
+          ]),
         };
       } finally {
         clearTimeout(timer);
+        this.untrackProcess(sandboxId, io);
+        finished = true;
       }
     })();
     // A failure before anyone calls wait must not become an unhandled
     // rejection; wait() still observes it through the same promise.
     done.catch(() => {});
-    return { wait: () => done };
+    return {
+      wait: () => done,
+      sendStdin: async (data) => {
+        if (!opts.stdin) throw new Error('process was started without stdin');
+        io.pushStdin(data);
+      },
+      closeStdin: async () => {
+        if (!opts.stdin) throw new Error('process was started without stdin');
+        io.closeStdin();
+      },
+      signal: async (sig) => {
+        if (finished) throw new Error('process already exited');
+        io.kill(sig);
+      },
+      resizePty: async () => {
+        throw new Error('process has no PTY');
+      },
+    };
+  }
+
+  private trackProcess(sandboxId: string, io: FakeProcessIO): void {
+    const set = this.procs.get(sandboxId) ?? new Set();
+    set.add(io);
+    this.procs.set(sandboxId, set);
+  }
+
+  private untrackProcess(sandboxId: string, io: FakeProcessIO): void {
+    this.procs.get(sandboxId)?.delete(io);
+  }
+
+  private killProcesses(sandboxId: string): void {
+    const set = this.procs.get(sandboxId);
+    if (!set) return;
+    for (const io of set) io.kill('SIGKILL');
   }
 
   async writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void> {
@@ -494,7 +620,7 @@ interface Emit {
 }
 
 /**
- * A pocket bash: the six verbs plus `;` sequencing — exactly what the
+ * A pocket bash: the seven verbs plus `;` sequencing — exactly what the
  * contract exam and the e2e suite need to exercise exec through the same
  * questions the real executor answers, nothing more. Each verb's output is
  * its own live chunk (the contract's streaming questions time the gaps).
@@ -505,6 +631,7 @@ interface Emit {
 async function interpret(
   opts: { command: string; cwd?: string; env?: Record<string, string> },
   emit: Emit,
+  io: FakeProcessIO,
 ): Promise<number> {
   let exitCode = 0;
   for (const segment of opts.command.split(';')) {
@@ -512,7 +639,7 @@ async function interpret(
     if (command === '') continue;
     const exited = command.match(/^exit (\d+)$/)?.[1];
     if (exited !== undefined) return Number(exited);
-    exitCode = await interpretVerb(command, opts, emit);
+    exitCode = await interpretVerb(command, opts, emit, io);
   }
   return exitCode;
 }
@@ -521,6 +648,7 @@ async function interpretVerb(
   command: string,
   opts: { cwd?: string; env?: Record<string, string> },
   emit: Emit,
+  io: FakeProcessIO,
 ): Promise<number> {
   const echoed = command.match(/^echo (.*)$/s)?.[1];
   if (echoed !== undefined) {
@@ -532,11 +660,19 @@ async function interpretVerb(
     // A real timer on purpose: e2e races this against the daemon's
     // wall-clock idle scanner to prove the exec heartbeat works, and the
     // contract's streaming questions time the chunk gap it creates.
-    await new Promise((resolve) =>
-      setTimeout(resolve, Number(napSeconds) * 1000),
-    );
+    // Interruptible, because a real sleep dies to the handle's SIGKILL.
+    await io.sleep(Number(napSeconds) * 1000);
     return 0;
   }
+  if (command === 'cat') {
+    // The stdin verb: echoes the mailbox chunk by chunk until EOF — the
+    // whole sendStdin/closeStdin contract observable through one command.
+    while (true) {
+      const chunk = await io.nextStdin();
+      if (chunk === null) return 0;
+      emit.stdout(chunk.toString('utf8'));
+    }
+  }
   if (command === 'pwd') {
     emit.stdout(`${opts.cwd ?? '/home/user'}\n`);
     return 0;

From 73602e5f4a8c51680f134e08064e85510ace35be Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 01:40:49 +0800
Subject: [PATCH 016/133] PTY sessions: a real terminal on the Tty exec path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

pty.create lands end to end. The docker executor grows a Tty exec path —
one merged raw byte stream (nothing to demux), resize through the
engine's own exec resize, input over the same hijacked duplex; the
session is a bare interactive login shell, deliberately unwrapped (GNU
timeout's process-group games wreck job control) and un-setsid'd (a Tty
exec is born session leader; setsid would take the terminal away). The
fake grows a matching terminal: raw echo, lines fed to the pocket
interpreter with stderr merged in, stty size as the resize observation
window.

On the wire, Start's pty block routes output through data.pty, SendInput
takes input.pty, Process/Update resizes — channel and start promise must
match, a mismatch is the caller's confusion. Contract 56->59 (echo/run,
resize visible to stty, SIGKILL as 137), compat 29->31, e2e adds the
official pty.create round trip plus a docker-only real-bash question.
---
 e2e/src/e2b.test.ts                      |  68 +++++++++++
 packages/server/src/e2b/compat.test.ts   | 106 +++++++++++++++++
 packages/server/src/e2b/envd.ts          |  29 +++--
 packages/server/src/e2b/process-table.ts |   5 +-
 packages/server/src/executor/contract.ts |  87 ++++++++++++++
 packages/server/src/executor/docker.ts   | 139 ++++++++++++++++++++---
 packages/server/src/executor/executor.ts |  24 +++-
 packages/server/src/executor/fake.ts     |  73 ++++++++++--
 8 files changed, 485 insertions(+), 46 deletions(-)

diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 514528d..40509e2 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -15,6 +15,17 @@ function sleep(seconds: number) {
   return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
 }
 
+/** Polls until the observation holds — terminal output has no fixed schedule. */
+async function until(check: () => boolean, timeoutMs = 8_000) {
+  const before = Date.now();
+  while (!check()) {
+    if (Date.now() - before > timeoutMs) {
+      throw new Error('condition never became true');
+    }
+    await sleep(0.05);
+  }
+}
+
 describe('official e2b SDK against the daemon', () => {
   it('creates a sandbox and runs a command', async () => {
     const sbx = await Sandbox.create(connection());
@@ -301,6 +312,39 @@ describe('official e2b SDK against the daemon', () => {
     }
   });
 
+  it('pty.create: a live terminal — typed input runs, resize lands, kill ends it', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      const seen: string[] = [];
+      const term = await sbx.pty.create({
+        cols: 80,
+        rows: 24,
+        onData: (data) => {
+          seen.push(Buffer.from(data).toString('utf8'));
+        },
+      });
+      expect(term.pid).toBeGreaterThan(0);
+
+      await sbx.pty.sendInput(
+        term.pid,
+        new TextEncoder().encode('echo from-the-pty\r'),
+      );
+      await until(() => seen.join('').includes('from-the-pty'));
+
+      await sbx.pty.resize(term.pid, { cols: 120, rows: 40 });
+      await sbx.pty.sendInput(
+        term.pid,
+        new TextEncoder().encode('stty size\r'),
+      );
+      await until(() => seen.join('').includes('40 120'));
+
+      expect(await sbx.pty.kill(term.pid)).toBe(true);
+      expect(await sbx.pty.kill(term.pid)).toBe(false);
+    } finally {
+      await sbx.kill();
+    }
+  });
+
   it('the Dormice extension: metadata.userKey makes create idempotent, data persists', async () => {
     const first = await Sandbox.create({
       ...connection(),
@@ -348,5 +392,29 @@ describe.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
         await sbx.kill();
       }
     });
+
+    it('the PTY runs a real interactive bash on the sandbox disk', async () => {
+      const sbx = await Sandbox.create(connection());
+      try {
+        const seen: string[] = [];
+        const term = await sbx.pty.create({
+          cols: 80,
+          rows: 24,
+          onData: (data) => {
+            seen.push(Buffer.from(data).toString('utf8'));
+          },
+        });
+        // ls of the disk root: only a real shell on the real disk shows
+        // mkfs's lost+found.
+        await sbx.pty.sendInput(
+          term.pid,
+          new TextEncoder().encode('ls /home/user\r'),
+        );
+        await until(() => seen.join('').includes('lost+found'));
+        await sbx.pty.kill(term.pid);
+      } finally {
+        await sbx.kill();
+      }
+    });
   },
 );
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 55e676a..40ae695 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -131,6 +131,26 @@ function startCommand(
   });
 }
 
+/** What pty.create sends: bash -i -l plus a pty block, no -c command. */
+function startPty(t: TestApp, sandboxID: string) {
+  return t.app.inject({
+    method: 'POST',
+    url: '/e2b/envd/process.Process/Start',
+    headers: {
+      ...envdHeaders(sandboxID),
+      'content-type': 'application/connect+json',
+    },
+    payload: enveloped({
+      process: {
+        cmd: '/bin/bash',
+        args: ['-i', '-l'],
+        envs: { TERM: 'xterm-256color' },
+      },
+      pty: { size: { cols: 80, rows: 24 } },
+    }),
+  });
+}
+
 function connectProcess(t: TestApp, sandboxID: string, pid: number) {
   return t.app.inject({
     method: 'POST',
@@ -792,6 +812,92 @@ describe('E2B envd surface', () => {
     await startRes;
   });
 
+  it('PTY on the wire: output rides data.pty, input rides input.pty, Update resizes', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const startRes = startPty(t, sandboxID);
+    const pid = await waitForPid(t, sandboxID);
+
+    const typed = (text: string) =>
+      envdRpc(t, sandboxID, '/process.Process/SendInput', {
+        process: { pid },
+        input: { pty: Buffer.from(text).toString('base64') },
+      });
+    expect((await typed('echo over-the-pty\r')).statusCode).toBe(200);
+    const resized = await envdRpc(t, sandboxID, '/process.Process/Update', {
+      process: { pid },
+      pty: { size: { cols: 100, rows: 30 } },
+    });
+    expect(resized.statusCode).toBe(200);
+    await typed('stty size\r');
+    await typed('exit\r');
+
+    const events = parseEnvelopes((await startRes).rawPayload)
+      .filter((f) => f.flags === 0)
+      .map((f) => f.json.event as Record<string, unknown>);
+    const dataFrames = events.filter((e) => 'data' in e) as Array<{
+      data: { pty?: string; stdout?: string };
+    }>;
+    // A terminal is one merged stream: every data frame rides the pty field.
+    expect(dataFrames.every((e) => e.data.pty !== undefined)).toBe(true);
+    const terminal = dataFrames
+      .map((e) => Buffer.from(e.data.pty ?? '', 'base64').toString('utf8'))
+      .join('');
+    expect(terminal).toContain('over-the-pty');
+    expect(terminal).toContain('30 100');
+    expect((events.at(-1) as { end: { exitCode: number } }).end.exitCode).toBe(
+      0,
+    );
+  });
+
+  it('input channel and start promise must match', async () => {
+    const t = testApp();
+
+    // stdin bytes into a PTY session: the terminal is not a stdin pipe.
+    const ptyBox = await createSandbox(t);
+    const ptyRes = startPty(t, ptyBox.sandboxID);
+    const ptyPid = await waitForPid(t, ptyBox.sandboxID);
+    const wrongStdin = await envdRpc(
+      t,
+      ptyBox.sandboxID,
+      '/process.Process/SendInput',
+      {
+        process: { pid: ptyPid },
+        input: { stdin: Buffer.from('x').toString('base64') },
+      },
+    );
+    expect(wrongStdin.statusCode).toBe(400);
+    expect(wrongStdin.json().message).toBe('process was started without stdin');
+
+    // pty bytes into a plain command: there is no terminal to type at.
+    const plainBox = await createSandbox(t);
+    const plainRes = startCommand(t, plainBox.sandboxID, 'sleep 30');
+    const plainPid = await waitForPid(t, plainBox.sandboxID);
+    const wrongPty = await envdRpc(
+      t,
+      plainBox.sandboxID,
+      '/process.Process/SendInput',
+      {
+        process: { pid: plainPid },
+        input: { pty: Buffer.from('x').toString('base64') },
+      },
+    );
+    expect(wrongPty.statusCode).toBe(400);
+    expect(wrongPty.json().message).toBe('process has no PTY');
+
+    // Reap both, or their day-long wire deadlines outlive the test run.
+    for (const [box, pid] of [
+      [ptyBox.sandboxID, ptyPid],
+      [plainBox.sandboxID, plainPid],
+    ] as const) {
+      await envdRpc(t, box, '/process.Process/SendSignal', {
+        process: { pid },
+        signal: 'SIGNAL_SIGKILL',
+      });
+    }
+    await Promise.all([ptyRes, plainRes]);
+  });
+
   it('a detached background process does not keep the sandbox warm', async () => {
     const t = testApp();
     // A day-long TTL so the idle scanner speaks first — at the default 300s
diff --git a/packages/server/src/e2b/envd.ts b/packages/server/src/e2b/envd.ts
index 487dc65..0c69d89 100644
--- a/packages/server/src/e2b/envd.ts
+++ b/packages/server/src/e2b/envd.ts
@@ -58,7 +58,7 @@ interface StartRequest {
     cwd?: string;
   };
   stdin?: boolean;
-  pty?: unknown;
+  pty?: { size?: { cols?: number; rows?: number } };
 }
 
 /** SandboxEntry -> proto3-JSON EntryInfo (int64 size travels as a string). */
@@ -656,17 +656,19 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
 
   app.post('/process.Process/Start', async (request, reply) => {
     const message = readFirstMessage(request.body as Buffer) as StartRequest;
-    if (message.pty) {
-      return streamError(
-        reply,
-        'unimplemented',
-        'PTY is not supported yet — run plain commands via commands.run',
-      );
-    }
     const proc = message.process ?? {};
     const args = proc.args ?? [];
-    // The SDK always sends /bin/bash [-l] -c <command>; anything else is a
-    // shape this layer does not speak yet.
+    // A pty block makes this a terminal session (the SDK sends
+    // /bin/bash -i -l; the executor hardcodes that shape anyway). Sizes
+    // default defensively — a 0x0 terminal misbehaves quietly.
+    const ptySize = message.pty
+      ? {
+          cols: message.pty.size?.cols || 80,
+          rows: message.pty.size?.rows || 24,
+        }
+      : undefined;
+    // Without a pty, the SDK always sends /bin/bash [-l] -c <command>;
+    // anything else is a shape this layer does not speak yet.
     let command: string | undefined;
     let loginShell = false;
     if (args.length === 3 && args[0] === '-l' && args[1] === '-c') {
@@ -675,11 +677,13 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     } else if (args.length === 2 && args[0] === '-c') {
       command = args[1];
     }
-    if (!proc.cmd?.endsWith('bash') || command === undefined) {
+    if (!proc.cmd?.endsWith('bash') || (!ptySize && command === undefined)) {
       return streamError(
         reply,
         'invalid_argument',
-        'only shell commands are supported: expected /bin/bash [-l] -c <command>',
+        ptySize
+          ? 'only bash PTY sessions are supported'
+          : 'only shell commands are supported: expected /bin/bash [-l] -c <command>',
       );
     }
     const row = await wakeForStream(request, reply);
@@ -698,6 +702,7 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         options: {
           command,
           loginShell,
+          pty: ptySize,
           // The in-container timeout is a pathological-cleanup backstop
           // only; the wire deadline lives in pumpProcessStream and never
           // kills the process — E2B's semantics, adopted deliberately.
diff --git a/packages/server/src/e2b/process-table.ts b/packages/server/src/e2b/process-table.ts
index 1aa1d4a..6fb096d 100644
--- a/packages/server/src/e2b/process-table.ts
+++ b/packages/server/src/e2b/process-table.ts
@@ -89,7 +89,6 @@ export class ProcessTable {
     sandboxId: string;
     options: Omit<ExecStreamOptions, 'onStdout' | 'onStderr'>;
     config: WireProcessConfig;
-    pty?: PtySize;
     subscriber?: ProcessSubscriber;
   }): Promise<ProcessRecord> {
     const pid = this.nextPid++;
@@ -104,7 +103,7 @@ export class ProcessTable {
     const handle = await args.executor.execStream(args.sandboxId, {
       ...args.options,
       // A PTY is one merged byte stream; a plain command keeps its two.
-      onStdout: broadcast(args.pty ? 'pty' : 'stdout'),
+      onStdout: broadcast(args.options.pty ? 'pty' : 'stdout'),
       onStderr: broadcast('stderr'),
     });
     const record: InternalRecord = {
@@ -112,7 +111,7 @@ export class ProcessTable {
       sandboxId: args.sandboxId,
       config: args.config,
       stdin: args.options.stdin ?? false,
-      pty: args.pty,
+      pty: args.options.pty,
       handle,
       subscribers,
     };
diff --git a/packages/server/src/executor/contract.ts b/packages/server/src/executor/contract.ts
index 9fa5038..b4d7b14 100644
--- a/packages/server/src/executor/contract.ts
+++ b/packages/server/src/executor/contract.ts
@@ -624,6 +624,93 @@ export function describeExecutorContract(
       timeoutMs,
     );
 
+    /** Polls until the observation holds — PTY output has no fixed schedule. */
+    async function until(check: () => boolean): Promise<void> {
+      const before = Date.now();
+      while (!check()) {
+        if (Date.now() - before > timeoutMs - 1_000) {
+          throw new Error('condition never became true');
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      }
+    }
+
+    it(
+      'a PTY session echoes input and runs what is typed',
+      async () => {
+        const id = await fresh();
+        const seen: string[] = [];
+        const handle = await executor.execStream(id, {
+          timeoutSeconds: 60,
+          pty: { cols: 80, rows: 24 },
+          env: { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' },
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        await handle.sendStdin(Buffer.from('echo pty-marker\r'));
+        // contains, never equals: a real bash brings PS1 and escape codes.
+        await until(() => seen.join('').includes('pty-marker'));
+        await handle.sendStdin(Buffer.from('exit\r'));
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(0);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'resizePty changes what stty size reports',
+      async () => {
+        const id = await fresh();
+        const seen: string[] = [];
+        const handle = await executor.execStream(id, {
+          timeoutSeconds: 60,
+          pty: { cols: 80, rows: 24 },
+          env: { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' },
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        await handle.resizePty({ cols: 123, rows: 45 });
+        await handle.sendStdin(Buffer.from('stty size\r'));
+        await until(() => seen.join('').includes('45 123'));
+        await handle.sendStdin(Buffer.from('exit\r'));
+        await handle.wait();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a PTY dies to SIGKILL as 137; a plain command has no PTY to resize',
+      async () => {
+        const id = await fresh();
+        const pty = await executor.execStream(id, {
+          timeoutSeconds: 60,
+          pty: { cols: 80, rows: 24 },
+          env: { TERM: 'xterm-256color' },
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await pty.signal('SIGKILL');
+        expect((await pty.wait()).exitCode).toBe(137);
+
+        const plain = await executor.execStream(id, {
+          command: 'sleep 5',
+          timeoutSeconds: 30,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await expect(plain.resizePty({ cols: 1, rows: 1 })).rejects.toThrow(
+          'process has no PTY',
+        );
+        await plain.signal('SIGKILL');
+        await plain.wait();
+      },
+      timeoutMs,
+    );
+
     it(
       'stopping the sandbox settles a running command in bounded time',
       async () => {
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 2f22180..ed89940 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -31,6 +31,7 @@ import {
   type FileToWrite,
   NotADirectoryError,
   NotAFileError,
+  type PtySize,
   type SandboxEntry,
 } from './executor';
 
@@ -183,6 +184,17 @@ const SIGNAL_SCRIPT = [
   'kill -s "$2" -- "-$p" 2>/dev/null || exec kill -s "$2" "$p"',
 ].join('\n');
 
+/**
+ * $1 = pidfile. The PTY session: an interactive login shell, nothing else.
+ * Deliberately no timeout wrapper (GNU timeout puts the child in its own
+ * process group, which wrecks interactive job control with SIGTTIN) and no
+ * setsid (a Tty exec is born session leader holding the controlling
+ * terminal; setsid would take the terminal away). The shell's own group is
+ * what the pidfile kill reaps; foreground jobs follow the closing pty
+ * master via SIGHUP. Lifetime is bounded by the sandbox's own.
+ */
+const PTY_WRAPPER = ['echo "$$" > "$1"', 'exec bash -i -l'].join('\n');
+
 /** One `find -printf` record (see LIST_DIR_SCRIPT) -> entry. */
 function entryFromFindRecord(record: string): SandboxEntry {
   const fields = record.split('\t');
@@ -511,6 +523,18 @@ export class DockerExecutor implements Executor {
     // is deliberately not removed on kill, or a TERM that the process
     // survives would strand the follow-up KILL.
     const pidfile = `/tmp/.dormice-exec-${randomUUID()}.pid`;
+    if (opts.pty) {
+      return this.startPtySession(
+        container,
+        sandboxId,
+        pidfile,
+        opts,
+        opts.pty,
+      );
+    }
+    if (opts.command === undefined) {
+      throw new Error('execStream needs a command unless pty is set');
+    }
     const started = await this.startInContainer(container, sandboxId, {
       cmd: [
         'setsid',
@@ -592,6 +616,102 @@ export class DockerExecutor implements Executor {
     }
   }
 
+  /**
+   * The PTY path: `docker exec` with Tty on — one merged raw byte stream
+   * (nothing to demux; stdout and stderr are the same terminal), resize via
+   * the engine's own exec resize, input over the same hijacked duplex.
+   */
+  private async startPtySession(
+    container: Docker.Container,
+    sandboxId: string,
+    pidfile: string,
+    opts: ExecStreamOptions,
+    size: PtySize,
+  ): Promise<ExecStreamHandle> {
+    const exec = await container.exec({
+      Cmd: ['bash', '-c', PTY_WRAPPER, 'bash', pidfile],
+      AttachStdin: true,
+      AttachStdout: true,
+      AttachStderr: true,
+      Tty: true,
+      WorkingDir: opts.cwd,
+      Env: opts.env
+        ? Object.entries(opts.env).map(([key, value]) => `${key}=${value}`)
+        : undefined,
+      User: 'user',
+    });
+    const stream = await exec.start({ hijack: true, stdin: true, Tty: true });
+    stream.pipe(new CallbackSink(opts.onStdout));
+    // The engine takes the size only after start — the terminal is born
+    // 0x0 otherwise, and a shell that stats it misbehaves.
+    await exec.resize({ h: size.rows, w: size.cols });
+    const finished = this.awaitExitCode(exec, stream, sandboxId);
+    let finishedFlag = false;
+    const done = finished.then((exitCode) => {
+      finishedFlag = true;
+      return { exitCode };
+    });
+    done.catch(() => {
+      finishedFlag = true;
+    });
+    return {
+      wait: () => done,
+      sendStdin: async (data) => {
+        if (stream.writableEnded) {
+          throw new Error('stdin is closed');
+        }
+        await new Promise<void>((resolve, reject) => {
+          stream.write(data, (err) => (err ? reject(err) : resolve()));
+        });
+      },
+      closeStdin: async () => {
+        if (stream.writableEnded) {
+          throw new Error('stdin is closed');
+        }
+        await new Promise<void>((resolve) => {
+          stream.end(resolve);
+        });
+      },
+      signal: async (sig) => {
+        if (finishedFlag) {
+          throw new Error('process already exited');
+        }
+        await this.signalProcess(container, sandboxId, pidfile, sig);
+      },
+      resizePty: async (next) => {
+        await exec.resize({ h: next.rows, w: next.cols });
+      },
+    };
+  }
+
+  /**
+   * Stream over, exit code out: the engine records the code a beat after
+   * the stream ends — the same measured lag as kill vs exited in stop().
+   * Never rejects into the void: callers hold the promise through wait().
+   */
+  private async awaitExitCode(
+    exec: Docker.Exec,
+    stream: NodeJS.ReadableStream,
+    sandboxId: string,
+  ): Promise<number> {
+    await new Promise<void>((resolve, reject) => {
+      stream.on('end', resolve);
+      stream.on('close', resolve);
+      stream.on('error', reject);
+    });
+    let info = await exec.inspect();
+    for (let i = 0; info.Running || info.ExitCode === null; i++) {
+      if (i >= 20) {
+        throw new Error(
+          `exec on ${sandboxId} ended but no exit code was recorded`,
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      info = await exec.inspect();
+    }
+    return info.ExitCode;
+  }
+
   async writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void> {
     const containerId = await this.expectState(sandboxId, 'running');
     const container = this.docker.getContainer(containerId);
@@ -987,24 +1107,7 @@ export class DockerExecutor implements Executor {
         spec.stdin.pipe(stream);
       }
     }
-    const finished = (async () => {
-      await new Promise<void>((resolve, reject) => {
-        stream.on('end', resolve);
-        stream.on('close', resolve);
-        stream.on('error', reject);
-      });
-      let info = await exec.inspect();
-      for (let i = 0; info.Running || info.ExitCode === null; i++) {
-        if (i >= 20) {
-          throw new Error(
-            `exec on ${sandboxId} ended but no exit code was recorded`,
-          );
-        }
-        await new Promise((resolve) => setTimeout(resolve, 50));
-        info = await exec.inspect();
-      }
-      return info.ExitCode;
-    })();
+    const finished = this.awaitExitCode(exec, stream, sandboxId);
     // A failure before anyone calls wait must not crash the daemon as an
     // unhandled rejection; wait() still observes it through the same promise.
     finished.catch(() => {});
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index 7cde317..c5dbd97 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -35,9 +35,17 @@ export interface PtySize {
 }
 
 export interface ExecStreamOptions {
-  /** A shell string, executed as `bash -c <command>` inside the sandbox. */
-  command: string;
-  /** Same in-container deadline as ExecOptions; on expiry exit 137. */
+  /**
+   * A shell string, executed as `bash -c <command>` inside the sandbox.
+   * Required unless `pty` is set — a PTY session is an interactive shell,
+   * not a one-shot command.
+   */
+  command?: string;
+  /**
+   * Same in-container deadline as ExecOptions; on expiry exit 137. A PTY
+   * session ignores it (GNU timeout's process-group games break interactive
+   * job control); its lifetime is bounded by the sandbox's own.
+   */
   timeoutSeconds: number;
   cwd?: string;
   env?: Record<string, string>;
@@ -50,9 +58,17 @@ export interface ExecStreamOptions {
   /**
    * Keep stdin open for the handle's sendStdin/closeStdin. Absent means the
    * command starts with stdin already at EOF (the old behavior); the handle
-   * verbs then refuse honestly instead of writing into nothing.
+   * verbs then refuse honestly instead of writing into nothing. A PTY
+   * implies an open stdin — the terminal IS an input channel.
    */
   stdin?: boolean;
+  /**
+   * Start an interactive login shell (`bash -i -l`) on a pseudo-terminal of
+   * this size instead of running `command`. Output is one merged raw tty
+   * byte stream through onStdout; onStderr never fires. Input goes through
+   * sendStdin, the size through resizePty.
+   */
+  pty?: PtySize;
   /**
    * Called with each output chunk as it arrives. No cap: nothing accumulates
    * server-side. A returned promise MAY be awaited before the next chunk
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index 1998a33..f8edf9e 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -15,6 +15,7 @@ import {
   type FileToWrite,
   NotADirectoryError,
   NotAFileError,
+  type PtySize,
   type SandboxEntry,
 } from './executor';
 
@@ -87,6 +88,8 @@ class FakeProcessIO {
   private stdinClosed = false;
   private wakeups: Array<() => void> = [];
   killSignal: 'SIGTERM' | 'SIGKILL' | undefined;
+  /** Present in PTY mode; resizePty rewrites it, `stty size` reads it. */
+  ptySize?: PtySize;
   private killResolve!: (exitCode: number) => void;
   /** Settles with the signal's exit code (KILL 137, TERM 143) when killed. */
   readonly killed = new Promise<number>((resolve) => {
@@ -289,7 +292,12 @@ export class FakeExecutor implements Executor {
     opts: ExecStreamOptions,
   ): Promise<ExecStreamHandle> {
     this.expect(sandboxId, 'running');
+    const command = opts.command;
+    if (opts.pty === undefined && command === undefined) {
+      throw new Error('execStream needs a command unless pty is set');
+    }
     const io = new FakeProcessIO();
+    if (opts.pty) io.ptySize = { ...opts.pty };
     this.trackProcess(sandboxId, io);
     // The timeout and the kill switch race the interpreter, same outcomes
     // as the real executor's in-container `timeout --signal=KILL` and the
@@ -324,12 +332,11 @@ export class FakeExecutor implements Executor {
         return exitCode;
       });
       try {
+        const run = opts.pty
+          ? ptySession(opts, emit, io)
+          : interpret({ ...opts, command: command as string }, emit, io);
         return {
-          exitCode: await Promise.race([
-            interpret(opts, emit, io),
-            deadline,
-            killed,
-          ]),
+          exitCode: await Promise.race([run, deadline, killed]),
         };
       } finally {
         clearTimeout(timer);
@@ -343,19 +350,25 @@ export class FakeExecutor implements Executor {
     return {
       wait: () => done,
       sendStdin: async (data) => {
-        if (!opts.stdin) throw new Error('process was started without stdin');
+        // A PTY implies an open stdin: the terminal IS an input channel.
+        if (!opts.stdin && !opts.pty) {
+          throw new Error('process was started without stdin');
+        }
         io.pushStdin(data);
       },
       closeStdin: async () => {
-        if (!opts.stdin) throw new Error('process was started without stdin');
+        if (!opts.stdin && !opts.pty) {
+          throw new Error('process was started without stdin');
+        }
         io.closeStdin();
       },
       signal: async (sig) => {
         if (finished) throw new Error('process already exited');
         io.kill(sig);
       },
-      resizePty: async () => {
-        throw new Error('process has no PTY');
+      resizePty: async (size) => {
+        if (!opts.pty) throw new Error('process has no PTY');
+        io.ptySize = { ...size };
       },
     };
   }
@@ -619,6 +632,48 @@ interface Emit {
   stderr: (text: string) => void;
 }
 
+/**
+ * The fake terminal: echoes input raw (a real tty with echo on does), cuts
+ * lines on \r or \n, feeds each line to the pocket interpreter with stderr
+ * merged into stdout (a terminal is one stream). `exit` ends the session;
+ * `stty size` reads the size resizePty last wrote — the resize contract's
+ * observation window. No fabricated prompt: real bash brings PS1 and
+ * escape sequences, so the contract asserts with contains, never equals.
+ */
+async function ptySession(
+  opts: { cwd?: string; env?: Record<string, string> },
+  emit: Emit,
+  io: FakeProcessIO,
+): Promise<number> {
+  const merged: Emit = { stdout: emit.stdout, stderr: emit.stdout };
+  let line = '';
+  while (true) {
+    const chunk = await io.nextStdin();
+    if (chunk === null) return 0;
+    const text = chunk.toString('utf8');
+    emit.stdout(text);
+    line += text;
+    while (true) {
+      const cut = line.search(/[\r\n]/);
+      if (cut === -1) break;
+      const commandLine = line.slice(0, cut).trim();
+      line = line.slice(cut + 1);
+      if (commandLine === '') continue;
+      if (commandLine === 'exit') return 0;
+      if (commandLine === 'stty size') {
+        const size = io.ptySize ?? { cols: 80, rows: 24 };
+        emit.stdout(`${size.rows} ${size.cols}\n`);
+        continue;
+      }
+      await interpret(
+        { command: commandLine, cwd: opts.cwd, env: opts.env },
+        merged,
+        io,
+      );
+    }
+  }
+}
+
 /**
  * A pocket bash: the seven verbs plus `;` sequencing — exactly what the
  * contract exam and the e2e suite need to exercise exec through the same

From a8667244d67b77468c8f23c5b957299e64acd83b Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 02:02:43 +0800
Subject: [PATCH 017/133] getHost lands: the sandbox port proxy behind a
 wildcard domain
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DORMICE_SANDBOX_DOMAIN turns the feature on. Set, create/connect/info
responses carry a domain field — getHost()'s raw material for
<port>-<sandboxId>.<domain> — and a serverFactory puts a Host-triaging
proxy in front of Fastify's router: matching requests dial straight into
the sandbox's port (executor.resolvePortTarget: the container's bridge
address; icc:false only blocks container-to-container), frozen sandboxes
wake on traffic, WebSocket upgrades pass through both ways, and a port
nobody listens on answers an honest 502. Unset, responses carry no
domain and the server is stock Fastify, byte for byte.

A proxied connection holds the exec heartbeat for exactly its own
lifetime — warmth follows attention, the same rule the process streams
follow. The daemon still binds 127.0.0.1: wildcard DNS and TLS are the
operator's Caddy's job (flush_interval -1, measured on the predecessor).

The fake executor answers resolvePortTarget with a lazy per-sandbox echo
upstream — its only real socket, the price of exercising the proxy end
to end without Docker. Contract 59->60, compat +1 (domain honestly
absent), a real-socket proxy suite (Host routing, 502, wake-on-traffic,
WS echo), and e2e drives getHost through the official SDK; docker-only
questions reach a python http.server through the proxy.
---
 e2e/src/e2b.test.ts                       |  97 +++++++++
 e2e/src/setup/daemon.ts                   |   3 +
 packages/server/src/app.ts                |  31 ++-
 packages/server/src/config.ts             |  20 ++
 packages/server/src/e2b/compat.test.ts    |  15 ++
 packages/server/src/e2b/control.ts        |   9 +
 packages/server/src/executor/contract.ts  |  15 ++
 packages/server/src/executor/docker.ts    |  18 ++
 packages/server/src/executor/executor.ts  |  10 +
 packages/server/src/executor/fake.ts      |  52 +++++
 packages/server/src/sandbox-proxy.test.ts | 190 ++++++++++++++++
 packages/server/src/sandbox-proxy.ts      | 251 ++++++++++++++++++++++
 12 files changed, 709 insertions(+), 2 deletions(-)
 create mode 100644 packages/server/src/sandbox-proxy.test.ts
 create mode 100644 packages/server/src/sandbox-proxy.ts

diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 40509e2..2ae751e 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -1,3 +1,4 @@
+import http from 'node:http';
 import { CommandExitError, Sandbox } from 'e2b';
 import { describe, expect, inject, it } from 'vitest';
 
@@ -26,6 +27,37 @@ async function until(check: () => boolean, timeoutMs = 8_000) {
   }
 }
 
+/**
+ * A GET at the daemon with a spoofed Host header — exactly what traffic
+ * from a wildcard-DNS reverse proxy looks like, no DNS needed (fetch
+ * refuses to set Host, so this speaks node:http directly).
+ */
+function throughProxy(
+  host: string,
+  path = '/',
+): Promise<{ status: number; body: string }> {
+  const endpoint = new URL(inject('dormiceEndpoint'));
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      {
+        host: endpoint.hostname,
+        port: endpoint.port,
+        path,
+        headers: { host },
+      },
+      (res) => {
+        let body = '';
+        res.on('data', (chunk) => {
+          body += chunk;
+        });
+        res.on('end', () => resolve({ status: res.statusCode ?? 0, body }));
+      },
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
 describe('official e2b SDK against the daemon', () => {
   it('creates a sandbox and runs a command', async () => {
     const sbx = await Sandbox.create(connection());
@@ -345,6 +377,17 @@ describe('official e2b SDK against the daemon', () => {
     }
   });
 
+  it('getHost builds the wildcard host from the served domain', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      // Pure client-side string assembly — but from OUR domain field, which
+      // is the whole point: the daemon told the SDK where sandboxes live.
+      expect(sbx.getHost(8000)).toBe(`8000-${sbx.sandboxId}.sbx.dormice.test`);
+    } finally {
+      await sbx.kill();
+    }
+  });
+
   it('the Dormice extension: metadata.userKey makes create idempotent, data persists', async () => {
     const first = await Sandbox.create({
       ...connection(),
@@ -366,6 +409,28 @@ describe('official e2b SDK against the daemon', () => {
   });
 });
 
+// The proxy's end-to-end round trip against the fake executor's echo
+// upstream; docker mode reaches a real in-sandbox server instead (below).
+describe.runIf(process.env.DORMICE_EXECUTOR !== 'docker')(
+  'sandbox port proxy, fake executor',
+  () => {
+    it('a Host-routed request lands inside the sandbox and echoes back', async () => {
+      const sbx = await Sandbox.create(connection());
+      try {
+        const host = sbx.getHost(8000);
+        const res = await throughProxy(host, '/hello?from=e2e');
+        expect(res.status).toBe(200);
+        const echo = JSON.parse(res.body);
+        expect(echo.sandboxId).toBe(sbx.sandboxId);
+        expect(echo.path).toBe('/hello?from=e2e');
+        expect(echo.host).toBe(host);
+      } finally {
+        await sbx.kill();
+      }
+    });
+  },
+);
+
 // Identity and real-shell behavior only a real container can answer; the
 // pocket interpreter has no users or profiles. The docker-mode e2e run on
 // the test machine covers these.
@@ -393,6 +458,38 @@ describe.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
       }
     });
 
+    it('getHost reaches a real server started in the sandbox', async () => {
+      const sbx = await Sandbox.create(connection());
+      try {
+        await sbx.commands.run('python3 -m http.server 8000 --directory /tmp', {
+          background: true,
+        });
+        const host = sbx.getHost(8000);
+        // The server takes a beat to bind; poll through the proxy.
+        let last = { status: 0, body: '' };
+        await until(() => {
+          void throughProxy(host, '/').then((res) => {
+            last = res;
+          });
+          return last.status === 200;
+        });
+        expect(last.body.length).toBeGreaterThan(0);
+      } finally {
+        await sbx.kill();
+      }
+    });
+
+    it('a port nobody listens on answers 502, honestly', async () => {
+      const sbx = await Sandbox.create(connection());
+      try {
+        const res = await throughProxy(sbx.getHost(9999), '/');
+        expect(res.status).toBe(502);
+        expect(JSON.parse(res.body).message).toContain('not listening');
+      } finally {
+        await sbx.kill();
+      }
+    });
+
     it('the PTY runs a real interactive bash on the sandbox disk', async () => {
       const sbx = await Sandbox.create(connection());
       try {
diff --git a/e2e/src/setup/daemon.ts b/e2e/src/setup/daemon.ts
index ee6e211..6a0f5bd 100644
--- a/e2e/src/setup/daemon.ts
+++ b/e2e/src/setup/daemon.ts
@@ -63,6 +63,9 @@ export default async function setup(project: TestProject) {
       // Sweep every second so lifecycle tests run on second-scale policies
       // instead of the production default of days.
       DORMICE_SCAN_INTERVAL_SECONDS: '1',
+      // A wildcard sandbox domain so getHost() and the port proxy are
+      // exercised — no DNS needed, tests spoof the Host header locally.
+      DORMICE_SANDBOX_DOMAIN: 'sbx.dormice.test',
     },
     stdio: ['ignore', 'pipe', 'pipe'],
   });
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 07df1c1..21b6426 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -1,5 +1,6 @@
+import http from 'node:http';
 import fastifyCookie from '@fastify/cookie';
-import fastify, { type FastifyError } from 'fastify';
+import fastify, { type FastifyError, type FastifyServerFactory } from 'fastify';
 import {
   serializerCompiler,
   validatorCompiler,
@@ -16,6 +17,7 @@ import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
 import { sandboxRoutes } from './routes/sandboxes';
 import { uiRoutes } from './routes/ui';
+import { createSandboxProxy } from './sandbox-proxy';
 
 export interface AppDeps {
   config: Config;
@@ -61,7 +63,32 @@ export function buildApp({
   // call shapes would give the instance two different types.
   const loggerInstance =
     typeof logger === 'boolean' ? pino({ enabled: logger }) : logger;
-  const app = fastify({ loggerInstance }).withTypeProvider<ZodTypeProvider>();
+  // The sandbox port proxy sits in front of routing — it triages by Host
+  // header, so it must see the request before Fastify's router 404s a
+  // wildcard host's arbitrary path. Only with the domain knob set; without
+  // it the server is stock Fastify, byte for byte. app.inject() bypasses
+  // the factory, so the proxy is exercised over real sockets only.
+  let serverFactory: FastifyServerFactory | undefined;
+  if (config.DORMICE_SANDBOX_DOMAIN) {
+    const proxy = createSandboxProxy({ config, db, executor, locks });
+    serverFactory = (handler) => {
+      const server = http.createServer((req, res) => {
+        if (proxy.matches(req)) proxy.handleRequest(req, res);
+        else handler(req, res);
+      });
+      // Fastify itself never handles upgrades; sandbox WebSockets (dev
+      // servers' HMR, notebooks) are the proxy's, everything else is cut.
+      server.on('upgrade', (req, socket, head) => {
+        if (proxy.matches(req)) proxy.handleUpgrade(req, socket, head);
+        else socket.destroy();
+      });
+      return server;
+    };
+  }
+  const app = fastify({
+    loggerInstance,
+    ...(serverFactory ? { serverFactory } : {}),
+  }).withTypeProvider<ZodTypeProvider>();
   app.setValidatorCompiler(validatorCompiler);
   app.setSerializerCompiler(serializerCompiler);
 
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index c14c947..38dde8b 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -53,6 +53,26 @@ const envSchema = z.object({
     .int()
     .positive()
     .default(45),
+  /**
+   * The sandbox wildcard domain behind getHost(): with it set, create and
+   * connect responses carry `domain`, the SDK builds
+   * `<port>-<sandboxId>.<domain>` hosts, and requests arriving with such a
+   * Host header are proxied into that sandbox's port (frozen sandboxes wake
+   * on traffic). The operator points `*.<domain>` DNS plus a TLS-terminating
+   * reverse proxy at the daemon. Unset, responses carry no domain and the
+   * proxy never engages — the feature is honestly absent, not half-present.
+   * A bare hostname: no scheme, no port, no leading or trailing dot.
+   */
+  DORMICE_SANDBOX_DOMAIN: z
+    .string()
+    .regex(
+      /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i,
+      {
+        error:
+          'DORMICE_SANDBOX_DOMAIN must be a bare hostname like sbx.example.com — no scheme, no port, no leading/trailing dots',
+      },
+    )
+    .optional(),
 });
 
 const checkedSchema = envSchema
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 40ae695..64a8047 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -378,6 +378,21 @@ describe('E2B control plane', () => {
     expect(pageTwo.headers['x-next-token']).toBeUndefined();
   });
 
+  it('carries no domain field when the sandbox domain is not configured', async () => {
+    // getHost's raw material must be honestly absent, not guessed at — the
+    // SDK would otherwise build hosts that resolve nowhere. The configured
+    // side is pinned by sandbox-proxy.test.ts over a real socket.
+    const t = testApp();
+    const created = await control(t, 'POST', '/sandboxes', {});
+    expect(created.json()).not.toHaveProperty('domain');
+    const info = await control(
+      t,
+      'GET',
+      `/sandboxes/${created.json().sandboxID}`,
+    );
+    expect(info.json()).not.toHaveProperty('domain');
+  });
+
   it('never imposes a deadline on a natively-acquired sandbox', async () => {
     const t = testApp();
     const native = await t.app.inject({
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index a2a3d88..e7d1303 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -118,6 +118,13 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     });
   });
 
+  // getHost()'s raw material: the SDK builds <port>-<sandboxId>.<domain>
+  // from this field. Present only when the operator configured the wildcard
+  // domain — an unconfigured feature is honestly absent, never guessed at.
+  const domainField = config.DORMICE_SANDBOX_DOMAIN
+    ? { domain: config.DORMICE_SANDBOX_DOMAIN }
+    : {};
+
   /** What create and connect answer with. */
   function sessionView(row: SandboxRow) {
     return {
@@ -126,6 +133,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       alias: row.userKey,
       envdVersion: ENVD_VERSION,
       envdAccessToken: mintEnvdToken(config.DORMICE_API_TOKEN, row.sandboxId),
+      ...domainField,
     };
   }
 
@@ -146,6 +154,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       cpuCount: config.DORMICE_SANDBOX_CPUS,
       memoryMB: Math.round(config.DORMICE_SANDBOX_MEMORY_GB * 1024),
       envdVersion: ENVD_VERSION,
+      ...domainField,
     };
   }
 
diff --git a/packages/server/src/executor/contract.ts b/packages/server/src/executor/contract.ts
index b4d7b14..bad0345 100644
--- a/packages/server/src/executor/contract.ts
+++ b/packages/server/src/executor/contract.ts
@@ -711,6 +711,21 @@ export function describeExecutorContract(
       timeoutMs,
     );
 
+    it(
+      'resolvePortTarget answers for a running sandbox and refuses the wrong state',
+      async () => {
+        const id = await fresh();
+        const target = await executor.resolvePortTarget(id, 8000);
+        expect(target.host).not.toBe('');
+        expect(target.port).toBeGreaterThan(0);
+        await executor.freeze(id);
+        await expect(executor.resolvePortTarget(id, 8000)).rejects.toThrow(
+          `container ${id} is paused, expected running`,
+        );
+      },
+      timeoutMs,
+    );
+
     it(
       'stopping the sandbox settles a running command in bounded time',
       async () => {
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index ed89940..b759b22 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -484,6 +484,24 @@ export class DockerExecutor implements Executor {
     await this.teardownDisk(sandboxId);
   }
 
+  async resolvePortTarget(
+    sandboxId: string,
+    port: number,
+  ): Promise<{ host: string; port: number }> {
+    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.docker.getContainer(containerId).inspect();
+    // The bridge address: icc:false only blocks container-to-container
+    // traffic, host-to-container stays open (measured on the test machine).
+    const networks = info.NetworkSettings?.Networks ?? {};
+    const ip = Object.values(networks)
+      .map((n) => n?.IPAddress)
+      .find((addr) => !!addr);
+    if (!ip) {
+      throw new Error(`container ${sandboxId} has no network address`);
+    }
+    return { host: ip, port };
+  }
+
   async exec(sandboxId: string, opts: ExecOptions): Promise<ExecResult> {
     const containerId = await this.expectState(sandboxId, 'running');
     const container = this.docker.getContainer(containerId);
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index c5dbd97..d9aa96e 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -203,6 +203,16 @@ export interface Executor {
    * Never called while the container exists — destroy tears its own disk.
    */
   removeDisk(sandboxId: string): Promise<void>;
+  /**
+   * Where the host can reach a TCP port of this sandbox — what the sandbox
+   * proxy dials to serve `<port>-<sandboxId>.<domain>` traffic. Requires
+   * state `running` (same message as every exec verb); whether anything
+   * actually listens on the port is discovered at connect time, honestly.
+   */
+  resolvePortTarget(
+    sandboxId: string,
+    port: number,
+  ): Promise<{ host: string; port: number }>;
   /**
    * Runs a shell command inside a running container and returns the fully
    * buffered result. Requires state `running` — a paused container cannot
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index f8edf9e..e0fbb9c 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -1,3 +1,5 @@
+import http from 'node:http';
+import type { AddressInfo } from 'node:net';
 import {
   EXEC_OUTPUT_LIMIT_BYTES,
   FILE_SIZE_LIMIT_BYTES,
@@ -162,6 +164,13 @@ export class FakeExecutor implements Executor {
    * must conduct the same physics or the process table above it would leak.
    */
   private readonly procs = new Map<string, Set<FakeProcessIO>>();
+  /**
+   * Lazy per-sandbox upstream servers behind resolvePortTarget — the fake's
+   * only real socket, and the price of exercising the sandbox proxy end to
+   * end without Docker. Each echoes what it received as JSON; upgrades get
+   * a bare 101 and their bytes echoed back.
+   */
+  private readonly upstreams = new Map<string, http.Server>();
   /**
    * Keyed like disks, not containers: files are the disk's content, so they
    * survive stop, start, and a vanished container object, and die only when
@@ -246,6 +255,7 @@ export class FakeExecutor implements Executor {
     const hadDisk = this.disks.delete(sandboxId);
     this.fs.delete(sandboxId);
     this.killProcesses(sandboxId);
+    this.closeUpstream(sandboxId);
     if (!hadContainer && !hadDisk) {
       throw new Error(`container ${sandboxId} is absent, cannot destroy`);
     }
@@ -264,6 +274,48 @@ export class FakeExecutor implements Executor {
     // Idempotent by contract: an absent disk already is the goal state.
     this.disks.delete(sandboxId);
     this.fs.delete(sandboxId);
+    this.closeUpstream(sandboxId);
+  }
+
+  async resolvePortTarget(
+    sandboxId: string,
+    port: number,
+  ): Promise<{ host: string; port: number }> {
+    this.expect(sandboxId, 'running');
+    let server = this.upstreams.get(sandboxId);
+    if (!server) {
+      const upstream = http.createServer((req, res) => {
+        res.setHeader('content-type', 'application/json');
+        res.end(
+          JSON.stringify({
+            sandboxId,
+            method: req.method,
+            path: req.url,
+            host: req.headers.host ?? null,
+          }),
+        );
+      });
+      upstream.on('upgrade', (_req, socket) => {
+        socket.write(
+          'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n\r\n',
+        );
+        socket.pipe(socket);
+      });
+      await new Promise<void>((resolve) =>
+        upstream.listen(0, '127.0.0.1', resolve),
+      );
+      this.upstreams.set(sandboxId, upstream);
+      server = upstream;
+    }
+    // One echo server stands in for every in-sandbox port: which port was
+    // asked for still travels in the Host header the proxy preserves.
+    void port;
+    return { host: '127.0.0.1', port: (server.address() as AddressInfo).port };
+  }
+
+  private closeUpstream(sandboxId: string): void {
+    this.upstreams.get(sandboxId)?.close();
+    this.upstreams.delete(sandboxId);
   }
 
   async exec(sandboxId: string, opts: ExecOptions): Promise<ExecResult> {
diff --git a/packages/server/src/sandbox-proxy.test.ts b/packages/server/src/sandbox-proxy.test.ts
new file mode 100644
index 0000000..166d26f
--- /dev/null
+++ b/packages/server/src/sandbox-proxy.test.ts
@@ -0,0 +1,190 @@
+import http from 'node:http';
+import net from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, it } from 'vitest';
+import { buildApp } from './app';
+import { loadConfig } from './config';
+import { migrateDb, openDb } from './db/db';
+import { findBySandboxId } from './db/ledger';
+import { FakeExecutor } from './executor/fake';
+import { KeyedQueue } from './keyed-queue';
+import { parseSandboxHost } from './sandbox-proxy';
+import { scanOnce } from './scanner';
+
+const MIGRATIONS = fileURLToPath(new URL('../drizzle', import.meta.url));
+const TOKEN = 'test-token-test-token-test-token';
+const DOMAIN = 'sbx.dormice.test';
+
+/**
+ * The proxy triages by Host header in front of Fastify's router, so
+ * app.inject() never reaches it — these tests listen on a real port and
+ * speak raw HTTP with a spoofed Host, which is exactly how traffic from a
+ * wildcard-DNS reverse proxy looks.
+ */
+describe('sandbox port proxy', () => {
+  const cleanups: Array<() => Promise<void> | void> = [];
+  afterEach(async () => {
+    while (cleanups.length > 0) await cleanups.pop()?.();
+  });
+
+  async function listeningApp() {
+    const db = openDb(':memory:');
+    migrateDb(db, MIGRATIONS);
+    const config = loadConfig({
+      DORMICE_DB_PATH: ':memory:',
+      DORMICE_NODE_ID: 'node-test',
+      DORMICE_API_TOKEN: TOKEN,
+      DORMICE_SANDBOX_DOMAIN: DOMAIN,
+    });
+    const executor = new FakeExecutor();
+    const locks = new KeyedQueue();
+    const app = buildApp({ config, db, executor, locks, logger: false });
+    await app.listen({ port: 0, host: '127.0.0.1' });
+    cleanups.push(() => app.close());
+    const address = app.server.address();
+    if (address === null || typeof address === 'string') {
+      throw new Error('no port');
+    }
+    return { app, db, executor, locks, port: address.port };
+  }
+
+  /** Raw GET with an explicit Host header (fetch refuses to set one). */
+  function rawGet(
+    port: number,
+    path: string,
+    host: string,
+  ): Promise<{ status: number; body: string }> {
+    return new Promise((resolve, reject) => {
+      const req = http.request(
+        { host: '127.0.0.1', port, path, headers: { host } },
+        (res) => {
+          let body = '';
+          res.on('data', (chunk) => {
+            body += chunk;
+          });
+          res.on('end', () => resolve({ status: res.statusCode ?? 0, body }));
+        },
+      );
+      req.on('error', reject);
+      req.end();
+    });
+  }
+
+  async function createSandbox(port: number): Promise<string> {
+    const res = await fetch(`http://127.0.0.1:${port}/e2b/api/sandboxes`, {
+      method: 'POST',
+      headers: {
+        'x-api-key': `e2b_${TOKEN}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ timeout: 3600 }),
+    });
+    expect(res.status).toBe(201);
+    const created = (await res.json()) as {
+      sandboxID: string;
+      domain?: string;
+    };
+    // The domain field is getHost's raw material — configured, so present.
+    expect(created.domain).toBe(DOMAIN);
+    return created.sandboxID;
+  }
+
+  it('parses sandbox hosts and nothing else', () => {
+    const id = '01234567-89ab-cdef-0123-456789abcdef';
+    expect(parseSandboxHost(`8000-${id}.${DOMAIN}`, DOMAIN)).toEqual({
+      port: 8000,
+      sandboxId: id,
+    });
+    // The header's own :port tail is the daemon's port, not the sandbox's.
+    expect(parseSandboxHost(`8000-${id}.${DOMAIN}:3676`, DOMAIN)).toEqual({
+      port: 8000,
+      sandboxId: id,
+    });
+    expect(parseSandboxHost(`8000-${id}.other.test`, DOMAIN)).toBeNull();
+    expect(parseSandboxHost(`${DOMAIN}`, DOMAIN)).toBeNull();
+    expect(parseSandboxHost(`0-${id}.${DOMAIN}`, DOMAIN)).toBeNull();
+    expect(parseSandboxHost(`8000-not-a-uuid.${DOMAIN}`, DOMAIN)).toBeNull();
+    expect(parseSandboxHost(undefined, DOMAIN)).toBeNull();
+  });
+
+  it('routes a sandbox Host into the sandbox, transparently', async () => {
+    const t = await listeningApp();
+    const sandboxId = await createSandbox(t.port);
+    const host = `8000-${sandboxId}.${DOMAIN}`;
+    const res = await rawGet(t.port, '/hello?x=1', host);
+    expect(res.status).toBe(200);
+    const echo = JSON.parse(res.body);
+    expect(echo.sandboxId).toBe(sandboxId);
+    expect(echo.path).toBe('/hello?x=1');
+    // Host travels unrewritten — the transparent-proxy promise.
+    expect(echo.host).toBe(host);
+  });
+
+  it('refuses an unknown sandbox with 502 and leaves other hosts to Fastify', async () => {
+    const t = await listeningApp();
+    const unknown = await rawGet(
+      t.port,
+      '/x',
+      `8000-01234567-89ab-cdef-0123-456789abcdef.${DOMAIN}`,
+    );
+    expect(unknown.status).toBe(502);
+    expect(JSON.parse(unknown.body).message).toContain('not found');
+
+    // A non-sandbox Host lands in the normal router.
+    const native = await rawGet(t.port, '/healthz', 'localhost');
+    expect(native.status).toBe(200);
+    expect(JSON.parse(native.body)).toEqual({ status: 'ok' });
+  });
+
+  it('wakes a frozen sandbox on traffic — autoResume, applied to the web', async () => {
+    const t = await listeningApp();
+    const sandboxId = await createSandbox(t.port);
+    // Freeze the real way — the idle scanner, told it is later — so the
+    // ledger and reality move together, exactly the state traffic finds.
+    const row = findBySandboxId(t.db, sandboxId);
+    const later = new Date(
+      Date.now() + ((row?.freezeAfterSeconds ?? 0) + 60) * 1000,
+    );
+    await scanOnce(t.db, t.executor, t.locks, later);
+    expect(t.executor.stateOf(sandboxId)).toBe('paused');
+
+    const res = await rawGet(t.port, '/warm', `3000-${sandboxId}.${DOMAIN}`);
+    expect(res.status).toBe(200);
+    expect(t.executor.stateOf(sandboxId)).toBe('running');
+  });
+
+  it('passes WebSocket upgrades through, both directions', async () => {
+    const t = await listeningApp();
+    const sandboxId = await createSandbox(t.port);
+    const echoed = await new Promise<string>((resolve, reject) => {
+      const socket = net.connect(t.port, '127.0.0.1', () => {
+        socket.write(
+          [
+            'GET /ws HTTP/1.1',
+            `Host: 5173-${sandboxId}.${DOMAIN}`,
+            'Connection: Upgrade',
+            'Upgrade: websocket',
+            '',
+            '',
+          ].join('\r\n'),
+        );
+      });
+      let buffer = '';
+      socket.on('data', (chunk) => {
+        buffer += chunk.toString('utf8');
+        if (buffer.includes('101') && !buffer.includes('marco')) {
+          // Handshake done — the fake upstream echoes raw bytes back.
+          socket.write('marco');
+        }
+        if (buffer.includes('marco')) {
+          socket.end();
+          resolve(buffer);
+        }
+      });
+      socket.on('error', reject);
+      setTimeout(() => reject(new Error('upgrade timed out')), 5000);
+    });
+    expect(echoed).toContain('101');
+    expect(echoed).toContain('marco');
+  });
+});
diff --git a/packages/server/src/sandbox-proxy.ts b/packages/server/src/sandbox-proxy.ts
new file mode 100644
index 0000000..15a478d
--- /dev/null
+++ b/packages/server/src/sandbox-proxy.ts
@@ -0,0 +1,251 @@
+import type http from 'node:http';
+import { request as httpRequest } from 'node:http';
+import net from 'node:net';
+import type { Duplex } from 'node:stream';
+import type { Config } from './config';
+import type { Db } from './db/db';
+import { findBySandboxId, touch } from './db/ledger';
+import type { SandboxRow } from './db/schema';
+import { e2bView } from './e2b/view';
+import { startExecHeartbeat } from './exec-heartbeat';
+import type { Executor } from './executor/executor';
+import type { KeyedQueue } from './keyed-queue';
+import { wakeSandbox } from './lifecycle';
+
+/**
+ * The sandbox port proxy: the server half of E2B's getHost(). A request
+ * whose Host header reads `<port>-<sandboxId>.<domain>` is dialed straight
+ * into that sandbox's port; a frozen sandbox wakes on traffic first — the
+ * autoResume semantics, and the product thesis (idle is free, waking is
+ * 50ms) applied to web traffic.
+ *
+ * The daemon still binds 127.0.0.1 only: public TLS and wildcard DNS are
+ * the operator's reverse proxy's job (Caddy with `flush_interval -1`,
+ * measured on the predecessor system — without it streaming responses
+ * buffer into one lump).
+ *
+ * Sandbox traffic is deliberately unauthenticated, like E2B's: a preview
+ * URL exists to be opened by whoever it is shared with. What the proxy
+ * reaches is only ever the sandbox's own ports.
+ */
+
+/**
+ * Host header -> { port, sandboxId }, or null when it is not sandbox
+ * traffic (then the request belongs to Fastify). The port suffix of the
+ * header itself (`:3676`) is not the sandbox port — the label carries that.
+ */
+export function parseSandboxHost(
+  hostHeader: string | undefined,
+  domain: string,
+): { port: number; sandboxId: string } | null {
+  if (!hostHeader) return null;
+  const host = hostHeader.replace(/:\d+$/, '').toLowerCase();
+  const suffix = `.${domain.toLowerCase()}`;
+  if (!host.endsWith(suffix)) return null;
+  const label = host.slice(0, -suffix.length);
+  const match = label.match(
+    /^(\d{1,5})-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/,
+  );
+  if (!match) return null;
+  const port = Number(match[1]);
+  if (port < 1 || port > 65535) return null;
+  return { port, sandboxId: match[2] as string };
+}
+
+export interface SandboxProxyDeps {
+  config: Config;
+  db: Db;
+  executor: Executor;
+  locks: KeyedQueue;
+}
+
+export interface SandboxProxy {
+  /** Is this request sandbox traffic? Cheap: a Host header parse. */
+  matches(req: http.IncomingMessage): boolean;
+  handleRequest(req: http.IncomingMessage, res: http.ServerResponse): void;
+  handleUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): void;
+}
+
+class ProxyRefusal extends Error {}
+
+export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
+  const { config, db, executor, locks } = deps;
+  const domain = config.DORMICE_SANDBOX_DOMAIN ?? '';
+
+  function liveRow(sandboxId: string): SandboxRow {
+    const row = findBySandboxId(db, sandboxId);
+    if (!row || e2bView(row, new Date()) !== 'running') {
+      throw new ProxyRefusal(
+        !row || e2bView(row, new Date()) === 'dead'
+          ? `sandbox ${sandboxId} not found`
+          : `sandbox ${sandboxId} is paused`,
+      );
+    }
+    return row;
+  }
+
+  /**
+   * Host -> a dialable target, waking the sandbox under its key slot like
+   * every other verb (physical wake-ups must not race the scanner or a
+   * release). Throws ProxyRefusal for everything that deserves a 502.
+   */
+  async function resolveTarget(req: http.IncomingMessage): Promise<{
+    row: SandboxRow;
+    port: number;
+    target: { host: string; port: number };
+  }> {
+    const parsed = parseSandboxHost(req.headers.host, domain);
+    if (!parsed) throw new ProxyRefusal('not sandbox traffic');
+    const before = liveRow(parsed.sandboxId);
+    const row = await locks.run(before.userKey, async () => {
+      const fresh = liveRow(parsed.sandboxId);
+      const awake = await wakeSandbox(db, executor, fresh);
+      return touch(db, awake.sandboxId);
+    });
+    const target = await executor.resolvePortTarget(row.sandboxId, parsed.port);
+    return { row, port: parsed.port, target };
+  }
+
+  function refuse(res: http.ServerResponse, message: string): void {
+    if (res.headersSent) {
+      res.destroy();
+      return;
+    }
+    const body = JSON.stringify({ message });
+    res.writeHead(502, {
+      'content-type': 'application/json',
+      'content-length': String(Buffer.byteLength(body)),
+    });
+    res.end(body);
+  }
+
+  return {
+    matches(req) {
+      return parseSandboxHost(req.headers.host, domain) !== null;
+    },
+
+    handleRequest(req, res) {
+      void (async () => {
+        let resolved: Awaited<ReturnType<typeof resolveTarget>>;
+        try {
+          resolved = await resolveTarget(req);
+        } catch (error) {
+          refuse(
+            res,
+            error instanceof ProxyRefusal
+              ? error.message
+              : 'sandbox proxy failed',
+          );
+          return;
+        }
+        const { row, port, target } = resolved;
+        // A proxied connection is activity: warmth lives exactly as long
+        // as the connection, then the idle countdown restarts.
+        const stopHeartbeat = startExecHeartbeat(
+          db,
+          row.sandboxId,
+          row.freezeAfterSeconds,
+        );
+        let settled = false;
+        const settle = () => {
+          if (settled) return;
+          settled = true;
+          stopHeartbeat();
+          try {
+            touch(db, row.sandboxId);
+          } catch {
+            // Released mid-request; the connection's ending tells the story.
+          }
+        };
+        // Host travels unrewritten — a transparent proxy, like E2B's edge;
+        // upstream servers with host allowlists (vite) configure their own.
+        const upstream = httpRequest({
+          host: target.host,
+          port: target.port,
+          method: req.method,
+          path: req.url,
+          headers: req.headers,
+        });
+        req.pipe(upstream);
+        upstream.on('response', (upRes) => {
+          res.writeHead(upRes.statusCode ?? 502, upRes.headers);
+          upRes.pipe(res);
+        });
+        upstream.on('error', () => {
+          settle();
+          refuse(
+            res,
+            `sandbox ${row.sandboxId} is not listening on port ${port}`,
+          );
+        });
+        res.on('close', () => {
+          settle();
+          upstream.destroy();
+        });
+      })();
+    },
+
+    handleUpgrade(req, socket, head) {
+      void (async () => {
+        let resolved: Awaited<ReturnType<typeof resolveTarget>>;
+        try {
+          resolved = await resolveTarget(req);
+        } catch (error) {
+          const message =
+            error instanceof ProxyRefusal
+              ? error.message
+              : 'sandbox proxy failed';
+          socket.end(
+            `HTTP/1.1 502 Bad Gateway\r\ncontent-type: application/json\r\nconnection: close\r\n\r\n${JSON.stringify({ message })}`,
+          );
+          return;
+        }
+        const { row, target } = resolved;
+        const stopHeartbeat = startExecHeartbeat(
+          db,
+          row.sandboxId,
+          row.freezeAfterSeconds,
+        );
+        let settled = false;
+        const settle = () => {
+          if (settled) return;
+          settled = true;
+          stopHeartbeat();
+          try {
+            touch(db, row.sandboxId);
+          } catch {
+            // Released mid-connection.
+          }
+        };
+        const upstream = net.connect(target.port, target.host, () => {
+          // Replay the upgrade request verbatim — rawHeaders keeps the
+          // original casing and repetition the handshake may care about.
+          let raw = `${req.method} ${req.url} HTTP/1.1\r\n`;
+          for (let i = 0; i < req.rawHeaders.length; i += 2) {
+            raw += `${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}\r\n`;
+          }
+          upstream.write(`${raw}\r\n`);
+          if (head.length > 0) upstream.write(head);
+          socket.pipe(upstream);
+          upstream.pipe(socket);
+        });
+        upstream.on('error', () => {
+          settle();
+          socket.destroy();
+        });
+        socket.on('error', () => {
+          settle();
+          upstream.destroy();
+        });
+        socket.on('close', () => {
+          settle();
+          upstream.destroy();
+        });
+        upstream.on('close', () => {
+          settle();
+          socket.destroy();
+        });
+      })();
+    },
+  };
+}

From 1340456db3712fd3d4e20ef465f04681bc237c3b Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 02:17:54 +0800
Subject: [PATCH 018/133] Reality corrects two assumptions from the real
 machine
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

setsid --wait reports a signal-killed child as the raw signal number
(9/15), not the 128+N convention E2B and the shell speak — measured on
the test machine, three contract questions red. It was also unnecessary:
GNU timeout (without --foreground) calls setpgid(0,0) itself, so the
recorded pid already leads a fresh process group and timeout's own
signal propagation preserves 137/143. The wrapper drops setsid.

The freeze-mid-command question now waits for the command's first output
before freezing: dockerd acknowledges exec start before the process has
spawned, and a zero-gap pause wins that race — the exec dies 128
'cannot exec in a paused state'. The contract's claim is about running
commands, so the exam observes one running first.

Docker contract 57/57 and e2e docker mode 50/51 (one fake-only skip)
green on the test machine: gVisor Tty exec + resize, group kill,
half-closed stdin, the official SDK's background family, pty.create on
a real interactive bash, and getHost through the Host-routed proxy to a
real in-sandbox python http.server.
---
 packages/server/src/executor/contract.ts | 13 +++++++++++--
 packages/server/src/executor/docker.ts   | 13 +++++++------
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/packages/server/src/executor/contract.ts b/packages/server/src/executor/contract.ts
index bad0345..0b68985 100644
--- a/packages/server/src/executor/contract.ts
+++ b/packages/server/src/executor/contract.ts
@@ -603,18 +603,27 @@ export function describeExecutorContract(
     );
 
     it(
-      'a command survives freeze/unfreeze and completes afterwards',
+      'a running command survives freeze/unfreeze and completes afterwards',
       async () => {
         const id = await fresh();
         const seen: string[] = [];
         const handle = await executor.execStream(id, {
-          command: 'sleep 1; echo woke',
+          command: 'echo started; sleep 1; echo woke',
           timeoutSeconds: 30,
           onStdout: (c) => {
             seen.push(c.toString('utf8'));
           },
           onStderr: () => {},
         });
+        // Wait for proof the command is actually running before freezing:
+        // dockerd acknowledges exec start before the process has spawned
+        // (measured 2026-07-10 — a zero-gap pause wins that race and the
+        // exec dies 128 "cannot exec in a paused state"). The contract's
+        // claim is about running commands, so observe one first.
+        const before = Date.now();
+        while (seen.length === 0 && Date.now() - before < 5_000) {
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        }
         await executor.freeze(id);
         await executor.unfreeze(id);
         const { exitCode } = await handle.wait();
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index b759b22..7a47ba7 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -158,10 +158,13 @@ const REMOVE_SCRIPT = [
  * Wrapper every execStream command runs under, so the handle can signal it
  * later. $1 = pidfile, $2 = timeout seconds, $3 = the user's command.
  * The exec chain keeps the pid stable: the recorded $$ is the bash that
- * becomes `timeout`, and `setsid --wait` outside made that pid a fresh
- * process-group leader — one `kill -- -pid` reaps the command and all its
- * descendants (GNU timeout's own group-kill relies on the same pgid).
- * setsid needs --wait or the exec would observe the fork's instant exit 0.
+ * becomes `timeout`, and GNU timeout itself (without --foreground) calls
+ * setpgid(0,0) — that same pid becomes a fresh process-group leader, so
+ * one `kill -- -pid` reaps the command and all its descendants.
+ * Deliberately NOT setsid --wait for the group: measured 2026-07-10,
+ * setsid reports a signal-killed child as the raw signal number (9/15)
+ * where the shell convention — and E2B — speak 128+N; timeout's own
+ * signal propagation (it re-raises on itself) preserves 137/143.
  */
 function execStreamWrapper(loginShell: boolean): string {
   const shell = loginShell ? 'bash -l -c' : 'bash -c';
@@ -555,8 +558,6 @@ export class DockerExecutor implements Executor {
     }
     const started = await this.startInContainer(container, sandboxId, {
       cmd: [
-        'setsid',
-        '--wait',
         'bash',
         '-c',
         execStreamWrapper(opts.loginShell ?? false),

From 03593ae746a8e9a24106a13daf684e19cf3ed563 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 03:22:21 +0800
Subject: [PATCH 019/133] Connect page: every client's snippets, served from
 the console's own origin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The console grows a read-only Connect page: copy-paste connection
snippets for the E2B SDK, the native SDK, and the CLI, each pointed at
window.location.origin — however the browser reached the daemon is
exactly how the SDK should. The token itself never appears (the console
cannot read it back out of the httpOnly cookie); the page says where to
find it instead. Copying falls back to the textarea trick because the
Clipboard API does not exist on plain-http origins, which the test
phase deliberately uses.

README's console section now documents both ways to reach a remote
daemon — SSH tunnel or a reverse proxy in front of 127.0.0.1:3676 —
including why a streaming proxy must not buffer.
---
 README.md                                     |  30 +++-
 .../features/connect/pages/ConnectPage.tsx    | 163 ++++++++++++++++++
 .../sandboxes/pages/SandboxesPage.tsx         |   3 +
 packages/web/src/routeTree.gen.ts             |  30 +++-
 packages/web/src/routes/_app/connect.tsx      |   6 +
 5 files changed, 225 insertions(+), 7 deletions(-)
 create mode 100644 packages/web/src/features/connect/pages/ConnectPage.tsx
 create mode 100644 packages/web/src/routes/_app/connect.tsx

diff --git a/README.md b/README.md
index 0d9c7aa..984d1ab 100644
--- a/README.md
+++ b/README.md
@@ -35,10 +35,32 @@ sign in with the API token once and it becomes an httpOnly session cookie;
 the token itself is never stored anywhere the page can read. The console
 shows every sandbox with its live lifecycle state (the same
 `/listSandboxes` the SDK sees), opens a per-sandbox detail view, creates
-sandboxes (the same idempotent `acquire`, with the lifecycle knobs), and
-releases them. Since the daemon listens on 127.0.0.1 only, reach a remote
-host's console through an SSH tunnel:
-`ssh -L 3676:127.0.0.1:3676 root@host`.
+sandboxes (the same idempotent `acquire`, with the lifecycle knobs),
+releases them, and has a Connect page with copy-paste snippets for every
+client (E2B SDK, native SDK, CLI) pointed at your own endpoint.
+
+The daemon listens on 127.0.0.1 only, so reaching it from another machine
+is a choice you make explicitly, one of two ways:
+
+- **SSH tunnel** (private, zero setup):
+  `ssh -L 3676:127.0.0.1:3676 root@host`, then open
+  `http://127.0.0.1:3676/ui`.
+- **Reverse proxy** for the console, the API, and the E2B surface at once —
+  e.g. Caddy, which also handles TLS certificates automatically once you
+  give it a domain:
+
+  ```
+  your-domain.example {
+  	reverse_proxy 127.0.0.1:3676 {
+  		flush_interval -1
+  	}
+  }
+  ```
+
+  `flush_interval -1` matters: streamed command output is written frame by
+  frame, and a buffering proxy would turn it into one lump at the end.
+  Anything exposed beyond localhost should be HTTPS — the API token and the
+  session cookie travel in every request.
 
 ## Host prerequisites (docker executor)
 
diff --git a/packages/web/src/features/connect/pages/ConnectPage.tsx b/packages/web/src/features/connect/pages/ConnectPage.tsx
new file mode 100644
index 0000000..f069967
--- /dev/null
+++ b/packages/web/src/features/connect/pages/ConnectPage.tsx
@@ -0,0 +1,163 @@
+import { ArrowLeft01Icon, Copy01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { Link } from '@tanstack/react-router';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+
+/**
+ * The Clipboard API only exists in secure contexts, and this console is
+ * deliberately reachable over plain http during the pre-TLS phase — the
+ * textarea trick is the one copy mechanism browsers still allow there.
+ */
+function copyText(text: string): Promise<void> {
+  if (navigator.clipboard) {
+    return navigator.clipboard.writeText(text);
+  }
+  const textarea = document.createElement('textarea');
+  textarea.value = text;
+  textarea.style.position = 'fixed';
+  textarea.style.opacity = '0';
+  document.body.appendChild(textarea);
+  textarea.select();
+  const copied = document.execCommand('copy');
+  textarea.remove();
+  return copied ? Promise.resolve() : Promise.reject(new Error('copy failed'));
+}
+
+function Snippet({ code }: { code: string }) {
+  return (
+    <div className="relative rounded-md border bg-muted/30">
+      <Button
+        variant="ghost"
+        size="icon-sm"
+        className="absolute top-1.5 right-1.5"
+        aria-label="Copy to clipboard"
+        onClick={() =>
+          copyText(code).then(
+            () => toast.success('Copied'),
+            () => toast.error('Copy failed — select the text manually'),
+          )
+        }
+      >
+        <HugeiconsIcon icon={Copy01Icon} />
+      </Button>
+      <pre className="overflow-x-auto p-4 pr-12 font-mono text-xs leading-relaxed">
+        <code>{code}</code>
+      </pre>
+    </div>
+  );
+}
+
+/**
+ * Read-only connection instructions. The endpoint is simply this page's
+ * origin — the daemon serves the console itself, so however the browser
+ * reached it (tunnel, reverse proxy, localhost) is exactly how the SDK
+ * should. The token is never shown: the console traded it for an httpOnly
+ * cookie at sign-in and cannot read it back.
+ */
+export function ConnectPage() {
+  const origin = window.location.origin;
+
+  const e2bSnippet = `import { Sandbox } from 'e2b';
+
+const sandbox = await Sandbox.create({
+  apiKey: 'e2b_<your API token>',
+  apiUrl: '${origin}/e2b/api',
+  sandboxUrl: '${origin}/e2b/envd',
+  // Dormice extension: the same userKey always returns the same sandbox.
+  metadata: { userKey: 'my-project' },
+});
+
+const result = await sandbox.commands.run('echo hello from dormice');`;
+
+  const sdkSnippet = `import { Dormice } from '@dormice/sdk';
+
+const client = new Dormice({
+  endpoint: '${origin}',
+  token: '<your API token>',
+});
+
+await client.acquireSandbox('my-project');
+const result = await client.execCommand('my-project', 'echo hello');`;
+
+  const cliSnippet = `export DORMICE_ENDPOINT=${origin}
+export DORMICE_API_TOKEN=<your API token>
+
+dor sandbox ls
+dor sandbox exec my-project 'uname -r'`;
+
+  return (
+    <main className="mx-auto min-h-screen w-full max-w-3xl px-6 pb-10">
+      <header className="flex items-center gap-3 py-5">
+        <Button
+          variant="ghost"
+          size="icon-sm"
+          render={<Link to="/" aria-label="Back to sandboxes" />}
+        >
+          <HugeiconsIcon icon={ArrowLeft01Icon} />
+        </Button>
+        <h1 className="text-lg font-semibold">Connect</h1>
+      </header>
+
+      <p className="mb-6 text-sm text-muted-foreground">
+        This daemon is reachable at <code className="font-mono">{origin}</code>{' '}
+        — the address you are reading this page from. Every snippet needs the
+        daemon's API token; the console never stores it, so read it on the
+        daemon host:{' '}
+        <code className="font-mono">
+          grep ^DORMICE_API_TOKEN /etc/dormice/env
+        </code>
+      </p>
+
+      <div className="flex flex-col gap-6">
+        <Card>
+          <CardHeader>
+            <CardTitle>E2B SDK</CardTitle>
+            <CardDescription>
+              The official <code className="font-mono">e2b</code> package works
+              as-is — point its two URLs here and prefix your token with{' '}
+              <code className="font-mono">e2b_</code>. No other code changes.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Snippet code={e2bSnippet} />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>Native SDK</CardTitle>
+            <CardDescription>
+              <code className="font-mono">@dormice/sdk</code> speaks the
+              daemon's native RPC — acquire is idempotent by design. Not
+              published to npm yet; build it from the repository workspace.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Snippet code={sdkSnippet} />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>CLI</CardTitle>
+            <CardDescription>
+              <code className="font-mono">dor</code> (installed alongside the
+              daemon by install.sh) reads these two environment variables.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Snippet code={cliSnippet} />
+          </CardContent>
+        </Card>
+      </div>
+    </main>
+  );
+}
diff --git a/packages/web/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/web/src/features/sandboxes/pages/SandboxesPage.tsx
index 5e7ba2b..791862e 100644
--- a/packages/web/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/web/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -48,6 +48,9 @@ export function SandboxesPage() {
           </span>
         </div>
         <div className="flex items-center gap-2">
+          <Button variant="ghost" size="sm" render={<Link to="/connect" />}>
+            Connect
+          </Button>
           <CreateSandboxDialog />
           <Button variant="ghost" size="sm" onClick={signOut}>
             Sign out
diff --git a/packages/web/src/routeTree.gen.ts b/packages/web/src/routeTree.gen.ts
index 9a3942b..d4bf369 100644
--- a/packages/web/src/routeTree.gen.ts
+++ b/packages/web/src/routeTree.gen.ts
@@ -12,6 +12,7 @@ import { Route as rootRouteImport } from './routes/__root'
 import { Route as LoginRouteImport } from './routes/login'
 import { Route as AppRouteImport } from './routes/_app'
 import { Route as AppIndexRouteImport } from './routes/_app/index'
+import { Route as AppConnectRouteImport } from './routes/_app/connect'
 import { Route as AppSandboxesUserKeyRouteImport } from './routes/_app/sandboxes/$userKey'
 
 const LoginRoute = LoginRouteImport.update({
@@ -28,6 +29,11 @@ const AppIndexRoute = AppIndexRouteImport.update({
   path: '/',
   getParentRoute: () => AppRoute,
 } as any)
+const AppConnectRoute = AppConnectRouteImport.update({
+  id: '/connect',
+  path: '/connect',
+  getParentRoute: () => AppRoute,
+} as any)
 const AppSandboxesUserKeyRoute = AppSandboxesUserKeyRouteImport.update({
   id: '/sandboxes/$userKey',
   path: '/sandboxes/$userKey',
@@ -37,10 +43,12 @@ const AppSandboxesUserKeyRoute = AppSandboxesUserKeyRouteImport.update({
 export interface FileRoutesByFullPath {
   '/': typeof AppIndexRoute
   '/login': typeof LoginRoute
+  '/connect': typeof AppConnectRoute
   '/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
 }
 export interface FileRoutesByTo {
   '/login': typeof LoginRoute
+  '/connect': typeof AppConnectRoute
   '/': typeof AppIndexRoute
   '/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
 }
@@ -48,15 +56,22 @@ export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/_app': typeof AppRouteWithChildren
   '/login': typeof LoginRoute
+  '/_app/connect': typeof AppConnectRoute
   '/_app/': typeof AppIndexRoute
   '/_app/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/' | '/login' | '/sandboxes/$userKey'
+  fullPaths: '/' | '/login' | '/connect' | '/sandboxes/$userKey'
   fileRoutesByTo: FileRoutesByTo
-  to: '/login' | '/' | '/sandboxes/$userKey'
-  id: '__root__' | '/_app' | '/login' | '/_app/' | '/_app/sandboxes/$userKey'
+  to: '/login' | '/connect' | '/' | '/sandboxes/$userKey'
+  id:
+    | '__root__'
+    | '/_app'
+    | '/login'
+    | '/_app/connect'
+    | '/_app/'
+    | '/_app/sandboxes/$userKey'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
@@ -87,6 +102,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AppIndexRouteImport
       parentRoute: typeof AppRoute
     }
+    '/_app/connect': {
+      id: '/_app/connect'
+      path: '/connect'
+      fullPath: '/connect'
+      preLoaderRoute: typeof AppConnectRouteImport
+      parentRoute: typeof AppRoute
+    }
     '/_app/sandboxes/$userKey': {
       id: '/_app/sandboxes/$userKey'
       path: '/sandboxes/$userKey'
@@ -98,11 +120,13 @@ declare module '@tanstack/react-router' {
 }
 
 interface AppRouteChildren {
+  AppConnectRoute: typeof AppConnectRoute
   AppIndexRoute: typeof AppIndexRoute
   AppSandboxesUserKeyRoute: typeof AppSandboxesUserKeyRoute
 }
 
 const AppRouteChildren: AppRouteChildren = {
+  AppConnectRoute: AppConnectRoute,
   AppIndexRoute: AppIndexRoute,
   AppSandboxesUserKeyRoute: AppSandboxesUserKeyRoute,
 }
diff --git a/packages/web/src/routes/_app/connect.tsx b/packages/web/src/routes/_app/connect.tsx
new file mode 100644
index 0000000..a29cfcc
--- /dev/null
+++ b/packages/web/src/routes/_app/connect.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { ConnectPage } from '@/features/connect/pages/ConnectPage';
+
+export const Route = createFileRoute('/_app/connect')({
+  component: ConnectPage,
+});

From 7e448a7e99faf84dcd8a761c70fe07e950e85b36 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 03:45:43 +0800
Subject: [PATCH 020/133] E2B directory watching: the WatchDir stream and the
 polling watcher trio
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The executor grows watchDir: in-container inotifywait riding the exec
pipeline (readiness gated on "Watches established.", measured working
under gVisor including -r picking up directories born later), the fake
subscribing to its own disk's mutation funnels — one contract, 8 new
questions, down to the typed errors.

The envd face implements Filesystem/WatchDir (start frame first, events
named relative to the watched dir, deadline ends watcher and stream
together) and CreateWatcher/GetWatcherEvents/RemoveWatcher for the sync
SDKs, parked in a daemon-memory watcher table. Two deliberate ceilings
real envd lacks: 8192 buffered events per watcher, 128 watchers per
sandbox — envd blows up inside the sandbox, this daemon lives on the host.

An attached watch does not keep the sandbox warm: watching is passive,
and no event can be missed frozen — the disk only changes from inside,
and reaching inside wakes the sandbox first. Reverse-proven by wrongly
attaching a heartbeat and watching the freeze e2e go red.

The base image installs inotify-tools; doctor probes for it (warn on
pre-watch images, which refuse watch honestly at runtime).
---
 e2e/src/e2b.test.ts                      | 161 ++++++++++++++++
 images/Dockerfile                        |   2 +-
 packages/cli/src/doctor.test.ts          |  18 ++
 packages/cli/src/doctor.ts               |  31 +++
 packages/server/src/app.ts               |  15 +-
 packages/server/src/e2b/compat.test.ts   | 207 ++++++++++++++++++++
 packages/server/src/e2b/deps.ts          |   5 +-
 packages/server/src/e2b/envd.ts          | 227 ++++++++++++++++++++--
 packages/server/src/e2b/watcher-table.ts |  98 ++++++++++
 packages/server/src/executor/contract.ts | 230 +++++++++++++++++++++++
 packages/server/src/executor/docker.ts   | 161 ++++++++++++++++
 packages/server/src/executor/executor.ts |  41 ++++
 packages/server/src/executor/fake.ts     | 113 ++++++++++-
 13 files changed, 1285 insertions(+), 24 deletions(-)
 create mode 100644 packages/server/src/e2b/watcher-table.ts

diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 2ae751e..51450eb 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -1,4 +1,6 @@
+import { createHmac } from 'node:crypto';
 import http from 'node:http';
+import { Dormice } from '@dormice/sdk';
 import { CommandExitError, Sandbox } from 'e2b';
 import { describe, expect, inject, it } from 'vitest';
 
@@ -388,6 +390,143 @@ describe('official e2b SDK against the daemon', () => {
     }
   });
 
+  it('watchDir streams filesystem events for changes made through the SDK', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      const events: Array<{ name: string; type: string }> = [];
+      const handle = await sbx.files.watchDir(
+        '/home/user',
+        (event) => {
+          events.push({ name: event.name, type: event.type });
+        },
+        { recursive: true, timeoutMs: 30_000 },
+      );
+      await sbx.files.write('watched.txt', 'hello');
+      await until(() =>
+        events.some((e) => e.name === 'watched.txt' && e.type === 'create'),
+      );
+      // Recursive: a change deep in the tree arrives with its relative path.
+      await sbx.files.makeDir('nested');
+      await sbx.files.write('nested/deep.txt', 'deeper');
+      await until(() =>
+        events.some((e) => e.name === 'nested/deep.txt' && e.type === 'create'),
+      );
+      await handle.stop();
+    } finally {
+      await sbx.kill();
+    }
+  });
+
+  it('an attached watch does not keep the sandbox warm; waking it resumes events', async () => {
+    // The product thesis applied to watch: watching is passive, so the idle
+    // scanner freezes a watched sandbox — and no event is lost, because the
+    // disk only changes from inside, and reaching inside wakes it first.
+    // Reverse-proven: with an exec heartbeat attached to the watch stream,
+    // the freeze below never happens and this test times out.
+    const dormice = new Dormice({
+      endpoint: inject('dormiceEndpoint'),
+      token: inject('dormiceToken'),
+    });
+    const userKey = `watch-freeze-${Date.now()}`;
+    // Native acquire sets the second-scale policy; the e2b face then joins
+    // the same sandbox through the userKey extension.
+    await dormice.acquireSandbox(userKey, {
+      freezeAfterSeconds: 1,
+      stopAfterSeconds: null,
+    });
+    const sbx = await Sandbox.create({
+      ...connection(),
+      metadata: { userKey },
+    });
+    try {
+      const events: Array<{ name: string; type: string }> = [];
+      const handle = await sbx.files.watchDir(
+        '/home/user',
+        (event) => {
+          events.push({ name: event.name, type: event.type });
+        },
+        { timeoutMs: 60_000 },
+      );
+      // The real wall-clock scanner freezes the sandbox under the open watch.
+      const frozen = async () => {
+        const sandboxes = await dormice.listSandboxes();
+        return sandboxes.find((s) => s.userKey === userKey)?.state;
+      };
+      const deadline = Date.now() + 15_000;
+      while ((await frozen()) !== 'frozen') {
+        if (Date.now() > deadline) throw new Error('sandbox never froze');
+        await sleep(0.2);
+      }
+      // Any touch from outside wakes it; the watcher resumes and reports.
+      await sbx.files.write('woke-up.txt', 'events survive the ice age');
+      await until(
+        () =>
+          events.some((e) => e.name === 'woke-up.txt' && e.type === 'create'),
+        10_000,
+      );
+      await handle.stop();
+    } finally {
+      await dormice.releaseSandbox(userKey);
+    }
+  });
+
+  it('the polling watcher trio works over the wire — what the sync SDKs use', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      // The JS SDK never calls these three; drive them as raw Connect unary
+      // posts, the way a sync SDK would. The access token is the documented
+      // envd HMAC — this stays a black-box network test.
+      const rpc = async (method: string, body: Record<string, unknown>) => {
+        const res = await fetch(
+          `${inject('dormiceEndpoint')}/e2b/envd/filesystem.Filesystem/${method}`,
+          {
+            method: 'POST',
+            headers: {
+              'content-type': 'application/json',
+              'e2b-sandbox-id': sbx.sandboxId,
+              'x-access-token': createHmac('sha256', inject('dormiceToken'))
+                .update(`envd:${sbx.sandboxId}`)
+                .digest('hex'),
+            },
+            body: JSON.stringify(body),
+          },
+        );
+        return {
+          status: res.status,
+          json: (await res.json()) as Record<string, unknown>,
+        };
+      };
+      const created = await rpc('CreateWatcher', { path: '/home/user' });
+      expect(created.status).toBe(200);
+      const watcherId = created.json.watcherId as string;
+
+      await sbx.files.write('polled.txt', 'x');
+      // Poll like a sync SDK: drain until the event shows up.
+      let drained: Array<{ name: string; type: string }> = [];
+      const deadline = Date.now() + 8_000;
+      while (
+        !drained.some(
+          (e) => e.name === 'polled.txt' && e.type === 'EVENT_TYPE_CREATE',
+        )
+      ) {
+        if (Date.now() > deadline) throw new Error('event never arrived');
+        const got = await rpc('GetWatcherEvents', { watcherId });
+        drained = drained.concat(
+          (got.json.events ?? []) as Array<{ name: string; type: string }>,
+        );
+        await sleep(0.1);
+      }
+
+      const removed = await rpc('RemoveWatcher', { watcherId });
+      expect(removed.status).toBe(200);
+      const gone = await rpc('GetWatcherEvents', { watcherId });
+      expect(gone.status).toBe(404);
+      expect(gone.json.code).toBe('not_found');
+    } finally {
+      await sbx.kill();
+    }
+  });
+
   it('the Dormice extension: metadata.userKey makes create idempotent, data persists', async () => {
     const first = await Sandbox.create({
       ...connection(),
@@ -490,6 +629,28 @@ describe.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
       }
     });
 
+    it('a real chmod arrives as a chmod event — only a real kernel emits ATTRIB', async () => {
+      const sbx = await Sandbox.create(connection());
+      try {
+        await sbx.files.write('mode-me.txt', 'x');
+        const events: Array<{ name: string; type: string }> = [];
+        const handle = await sbx.files.watchDir(
+          '/home/user',
+          (event) => {
+            events.push({ name: event.name, type: event.type });
+          },
+          { timeoutMs: 30_000 },
+        );
+        await sbx.commands.run('chmod 600 /home/user/mode-me.txt');
+        await until(() =>
+          events.some((e) => e.name === 'mode-me.txt' && e.type === 'chmod'),
+        );
+        await handle.stop();
+      } finally {
+        await sbx.kill();
+      }
+    });
+
     it('the PTY runs a real interactive bash on the sandbox disk', async () => {
       const sbx = await Sandbox.create(connection());
       try {
diff --git a/images/Dockerfile b/images/Dockerfile
index 4794a62..a729d8f 100644
--- a/images/Dockerfile
+++ b/images/Dockerfile
@@ -26,7 +26,7 @@ RUN if [ -n "$UBUNTU_MIRROR" ]; then \
  && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
       python3 python3-pip python3-venv python3-dev \
       build-essential ca-certificates curl wget git unzip xz-utils \
-      vim-tiny less jq ripgrep \
+      vim-tiny less jq ripgrep inotify-tools \
  && rm -rf /var/lib/apt/lists/* \
  && rm -f /usr/lib/python3.12/EXTERNALLY-MANAGED \
  && ln -sf /usr/bin/python3 /usr/local/bin/python
diff --git a/packages/cli/src/doctor.test.ts b/packages/cli/src/doctor.test.ts
index 87a3274..bacff58 100644
--- a/packages/cli/src/doctor.test.ts
+++ b/packages/cli/src/doctor.test.ts
@@ -66,6 +66,8 @@ function fakeHost(
     [`docker run --rm --runtime=runsc ${IMAGE} bash -c timeout 3 bash -c "</dev/tcp/100.100.100.200/80" && echo LEAK || echo BLOCKED`]:
       ok('BLOCKED\n'),
     [`docker run --rm --runtime=runsc ${IMAGE} id -u`]: ok('1000\n'),
+    [`docker run --rm --runtime=runsc ${IMAGE} bash -c command -v inotifywait || echo MISSING`]:
+      ok('/usr/bin/inotifywait\n'),
     ...overrides.commands,
   };
   const calls: string[] = [];
@@ -111,8 +113,24 @@ describe('runDoctor on a healthy host', () => {
     expect(statusOf(results, 'probe-gvisor')).toBe('skip');
     expect(statusOf(results, 'probe-metadata')).toBe('skip');
     expect(statusOf(results, 'probe-image-user')).toBe('skip');
+    expect(statusOf(results, 'probe-image-inotify')).toBe('skip');
     expect(ctx.calls.filter((call) => call.includes('docker run'))).toEqual([]);
   });
+
+  it('a pre-watch image without inotifywait warns and points at the rebuild', async () => {
+    const { results, failed } = await runDoctor(
+      fakeHost({
+        commands: {
+          [`docker run --rm --runtime=runsc ${IMAGE} bash -c command -v inotifywait || echo MISSING`]:
+            ok('MISSING\n'),
+        },
+      }),
+    );
+    // A warn: everything except E2B watch still works on the old image.
+    expect(failed).toBe(false);
+    expect(statusOf(results, 'probe-image-inotify')).toBe('warn');
+    expect(results['probe-image-inotify']?.fix).toContain('images/Dockerfile');
+  });
 });
 
 describe('platform gating', () => {
diff --git a/packages/cli/src/doctor.ts b/packages/cli/src/doctor.ts
index 8f2d6a0..9b2d8b2 100644
--- a/packages/cli/src/doctor.ts
+++ b/packages/cli/src/doctor.ts
@@ -506,6 +506,37 @@ const CHECKS: DoctorCheck[] = [
           );
     },
   },
+  {
+    id: 'probe-image-inotify',
+    title: 'probe: image has inotify-tools',
+    needs: ['gvisor-runtime', 'base-image'],
+    probe: true,
+    run: async (ctx) => {
+      const res = await ctx.run(
+        'docker',
+        [
+          'run',
+          '--rm',
+          '--runtime=runsc',
+          baseImage(ctx) as string,
+          'bash',
+          '-c',
+          'command -v inotifywait || echo MISSING',
+        ],
+        { timeoutMs: 60_000 },
+      );
+      if (!res.ok)
+        return fail(`the probe container failed: ${res.stderr.trim()}`);
+      // A warn, not a fail: everything except E2B watch works without it,
+      // and images built before 2026-07-10 honestly refuse watch at runtime.
+      return res.stdout.includes('MISSING')
+        ? warn(
+            'inotifywait is missing — E2B directory watching will refuse to start',
+            'rebuild the sandbox image from images/Dockerfile (it installs inotify-tools) and point DORMICE_BASE_IMAGE at the new tag',
+          )
+        : pass('inotifywait present — directory watching works');
+    },
+  },
 ];
 
 const ICONS: Record<CheckStatus, string> = {
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 21b6426..c6cac60 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -13,6 +13,7 @@ import type { Config } from './config';
 import type { Db } from './db/db';
 import { registerE2bCompat } from './e2b';
 import { ProcessTable } from './e2b/process-table';
+import { WatcherTable } from './e2b/watcher-table';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
 import { sandboxRoutes } from './routes/sandboxes';
@@ -141,11 +142,19 @@ export function buildApp({
 
   // The E2B compatibility surface lives beside the native API with its own
   // auth (X-API-KEY / X-Access-Token) and its own error dialect. The process
-  // table is per-daemon state, born with the app and gone with it — a
-  // restart honestly empties it.
+  // and watcher tables are per-daemon state, born with the app and gone
+  // with it — a restart honestly empties them.
   const processes = new ProcessTable();
+  const watchers = new WatcherTable();
   app.register(async (compat) => {
-    await registerE2bCompat(compat, { config, db, executor, locks, processes });
+    await registerE2bCompat(compat, {
+      config,
+      db,
+      executor,
+      locks,
+      processes,
+      watchers,
+    });
   });
 
   return app;
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 64a8047..9e1a84b 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -950,4 +950,211 @@ describe('E2B envd surface', () => {
       'unavailable',
     );
   });
+
+  // ---- directory watching -----------------------------------------------
+
+  /** WatchDir with a wire deadline: the SDK's watch shape, ending honestly. */
+  function watchDir(
+    t: TestApp,
+    sandboxID: string,
+    body: Record<string, unknown>,
+    deadlineMs: number,
+  ) {
+    return t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/filesystem.Filesystem/WatchDir',
+      headers: {
+        ...envdHeaders(sandboxID),
+        'content-type': 'application/connect+json',
+        'connect-timeout-ms': String(deadlineMs),
+      },
+      payload: enveloped(body),
+    });
+  }
+
+  it('WatchDir opens with start, streams filesystem events, and ends at the deadline', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const pending = watchDir(t, sandboxID, { path: '/home/user' }, 600);
+    // The change arrives from the side while the stream hangs open — the
+    // executor's disk is the same one the watch observes.
+    setTimeout(() => {
+      void t.executor.writeFiles(sandboxID, [
+        { path: 'watched.txt', content: Buffer.from('x') },
+      ]);
+    }, 100);
+    const res = await pending;
+    expect(res.statusCode).toBe(200);
+    const frames = parseEnvelopes(res.rawPayload);
+    // Start frame strictly first — the SDK's hard requirement.
+    expect(frames[0]?.json).toEqual({ start: {} });
+    const events = frames
+      .map((f) => f.json.filesystem as { name: string; type: string })
+      .filter(Boolean);
+    expect(events).toContainEqual({
+      name: 'watched.txt',
+      type: 'EVENT_TYPE_CREATE',
+    });
+    expect(events).toContainEqual({
+      name: 'watched.txt',
+      type: 'EVENT_TYPE_WRITE',
+    });
+    const last = frames[frames.length - 1];
+    expect(last?.flags).toBe(2);
+    expect((last?.json.error as { code: string }).code).toBe(
+      'deadline_exceeded',
+    );
+  });
+
+  it('WatchDir refuses a missing path and a file before any start frame', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const missing = await watchDir(
+      t,
+      sandboxID,
+      { path: '/home/user/nowhere' },
+      500,
+    );
+    const missingFrames = parseEnvelopes(missing.rawPayload);
+    expect(missingFrames).toHaveLength(1);
+    expect(missingFrames[0]?.flags).toBe(2);
+    expect(missingFrames[0]?.json.error).toEqual({
+      code: 'not_found',
+      message: 'no such file: /home/user/nowhere',
+    });
+
+    await t.executor.writeFiles(sandboxID, [
+      { path: 'plain.txt', content: Buffer.from('x') },
+    ]);
+    const onFile = await watchDir(t, sandboxID, { path: 'plain.txt' }, 500);
+    const fileFrames = parseEnvelopes(onFile.rawPayload);
+    expect(fileFrames).toHaveLength(1);
+    expect(fileFrames[0]?.json.error).toEqual({
+      code: 'invalid_argument',
+      message: 'not a directory: /home/user/plain.txt',
+    });
+  });
+
+  it('an attached watch does not keep the sandbox warm — the scanner freezes it', async () => {
+    const t = testApp();
+    // Day-long TTL so the idle scanner speaks before the kill deadline.
+    const { sandboxID } = await createSandbox(t, { timeout: 86400 });
+    let stateDuringWatch: string | undefined;
+    const pending = watchDir(t, sandboxID, { path: '/home/user' }, 600);
+    setTimeout(() => {
+      void (async () => {
+        const row = findBySandboxId(t.db, sandboxID);
+        const later = new Date(
+          Date.now() + ((row?.freezeAfterSeconds ?? 0) + 60) * 1000,
+        );
+        await scanOnce(t.db, t.executor, t.locks, later);
+        stateDuringWatch = t.executor.stateOf(sandboxID);
+      })();
+    }, 100);
+    const res = await pending;
+    // Frozen mid-watch: no heartbeat held the sandbox awake, and the stream
+    // itself still ended through its own deadline, not through an error.
+    expect(stateDuringWatch).toBe('paused');
+    const frames = parseEnvelopes(res.rawPayload);
+    const last = frames[frames.length - 1];
+    expect((last?.json.error as { code: string }).code).toBe(
+      'deadline_exceeded',
+    );
+  });
+
+  it('the polling trio: create, drain, drain empty, remove, then not_found', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const created = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/CreateWatcher',
+      { path: '/home/user' },
+    );
+    expect(created.statusCode).toBe(200);
+    const { watcherId } = created.json() as { watcherId: string };
+    expect(watcherId).toBeTruthy();
+
+    await t.executor.writeFiles(sandboxID, [
+      { path: 'polled.txt', content: Buffer.from('x') },
+    ]);
+    const first = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/GetWatcherEvents',
+      { watcherId },
+    );
+    expect(first.json().events).toContainEqual({
+      name: 'polled.txt',
+      type: 'EVENT_TYPE_CREATE',
+    });
+    // Drained means drained: the second poll answers empty.
+    const second = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/GetWatcherEvents',
+      { watcherId },
+    );
+    expect(second.json().events).toEqual([]);
+
+    const removed = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/RemoveWatcher',
+      { watcherId },
+    );
+    expect(removed.statusCode).toBe(200);
+    const gone = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/GetWatcherEvents',
+      { watcherId },
+    );
+    expect(gone.statusCode).toBe(404);
+    expect(gone.json()).toEqual({
+      code: 'not_found',
+      message: `watcher with id ${watcherId} not found`,
+    });
+  });
+
+  it('a polled watcher dies with its container: the next poll answers not_found', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const created = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/CreateWatcher',
+      { path: '/home/user' },
+    );
+    const { watcherId } = created.json() as { watcherId: string };
+    // The container stops under the watcher (physically, past the ledger —
+    // the conduction being tested is executor -> watcher table).
+    await t.executor.freeze(sandboxID);
+    await t.executor.stop(sandboxID);
+    await t.executor.start(sandboxID);
+    const res = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/GetWatcherEvents',
+      { watcherId },
+    );
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not_found');
+  });
+
+  it('CreateWatcher validates the path with the unary error dialect', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const missing = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/CreateWatcher',
+      { path: '/home/user/nowhere' },
+    );
+    expect(missing.statusCode).toBe(404);
+    expect(missing.json()).toEqual({
+      code: 'not_found',
+      message: 'no such file: /home/user/nowhere',
+    });
+  });
 });
diff --git a/packages/server/src/e2b/deps.ts b/packages/server/src/e2b/deps.ts
index 2a61fd1..8d66539 100644
--- a/packages/server/src/e2b/deps.ts
+++ b/packages/server/src/e2b/deps.ts
@@ -3,10 +3,12 @@ import type { Db } from '../db/db';
 import type { Executor } from '../executor/executor';
 import type { KeyedQueue } from '../keyed-queue';
 import type { ProcessTable } from './process-table';
+import type { WatcherTable } from './watcher-table';
 
 /**
  * What every compat plugin needs — the native routes' four, plus the
- * process table both e2b prefixes share (control kills what envd started).
+ * process table both e2b prefixes share (control kills what envd started)
+ * and the polling watchers' table.
  */
 export interface E2bDeps {
   config: Config;
@@ -14,4 +16,5 @@ export interface E2bDeps {
   executor: Executor;
   locks: KeyedQueue;
   processes: ProcessTable;
+  watchers: WatcherTable;
 }
diff --git a/packages/server/src/e2b/envd.ts b/packages/server/src/e2b/envd.ts
index 0c69d89..58ae088 100644
--- a/packages/server/src/e2b/envd.ts
+++ b/packages/server/src/e2b/envd.ts
@@ -12,6 +12,7 @@ import {
   NotADirectoryError,
   NotAFileError,
   type SandboxEntry,
+  type WatchEvent,
 } from '../executor/executor';
 import { wakeSandbox } from '../lifecycle';
 import type { E2bDeps } from './deps';
@@ -26,6 +27,7 @@ import {
   verifyEnvdToken,
 } from './protocol';
 import { e2bView } from './view';
+import { WatcherLimitError } from './watcher-table';
 
 /**
  * The envd surface: what the official SDK reaches through its `sandboxUrl`
@@ -112,7 +114,7 @@ function toConnectError(error: unknown): unknown {
 
 export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   app,
-  { config, db, executor, locks, processes },
+  { config, db, executor, locks, processes, watchers },
 ) => {
   await app.register(multipart, {
     limits: {
@@ -464,6 +466,213 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     return {};
   });
 
+  // ---- directory watching ----------------------------------------------
+
+  /** Executor event types -> the proto enum names proto3-JSON speaks. */
+  const WATCH_EVENT_WIRE: Record<WatchEvent['type'], string> = {
+    create: 'EVENT_TYPE_CREATE',
+    write: 'EVENT_TYPE_WRITE',
+    remove: 'EVENT_TYPE_REMOVE',
+    rename: 'EVENT_TYPE_RENAME',
+    chmod: 'EVENT_TYPE_CHMOD',
+  };
+
+  /**
+   * Path validation errors travel differently on the two watch surfaces
+   * (in-stream frame vs unary throw), but the codes and messages are one
+   * decision: not_found for a missing path, invalid_argument for a file —
+   * real envd's answers, with this codebase's own wording.
+   */
+  function watchStartError(error: unknown): { code: string; message: string } {
+    if (error instanceof FileNotFoundError) {
+      return { code: 'not_found', message: error.message };
+    }
+    if (error instanceof NotADirectoryError) {
+      return { code: 'invalid_argument', message: error.message };
+    }
+    return {
+      code: 'internal',
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  /**
+   * The streaming watch: unlike a process stream, the watcher IS the stream
+   * — real envd runs the whole watch inside one handler, so the deadline,
+   * the client hanging up, or any ending stops the watcher itself (the SDK's
+   * WatchHandle.stop() is exactly an abort of this request). Frames are the
+   * WatchDirResponse oneof at the top level: {start:{}}, {filesystem:{...}},
+   * {keepalive:{}} — no `event` wrapper, unlike the process face.
+   *
+   * Deliberately no exec heartbeat: watching is passive observation, so an
+   * attached watch lets the idle scanner freeze the sandbox. No events can
+   * be missed frozen — the disk only changes from inside, and everything
+   * that reaches inside wakes the sandbox first.
+   */
+  app.post('/filesystem.Filesystem/WatchDir', async (request, reply) => {
+    const message = readFirstMessage(request.body as Buffer) as {
+      path?: string;
+      recursive?: boolean;
+    };
+    if (!message.path) {
+      return streamError(reply, 'invalid_argument', 'missing path');
+    }
+    const row = await wakeForStream(request, reply);
+    if (!row) return;
+
+    const write = rawWriter(reply);
+    // Events hold at this gate until the start frame is on the wire — the
+    // SDK requires the stream to open with it, and a change made in the
+    // sliver between watcher start and hijack would otherwise race ahead.
+    let openGate = () => {};
+    const opened = new Promise<void>((resolve) => {
+      openGate = resolve;
+    });
+    let settleEnd: (error: Error) => void = () => {};
+    const ended = new Promise<Error>((resolve) => {
+      settleEnd = resolve;
+    });
+    let watcher: Awaited<ReturnType<typeof executor.watchDir>>;
+    try {
+      watcher = await executor.watchDir(row.sandboxId, {
+        path: message.path,
+        recursive: message.recursive === true,
+        onEvent: async (event) => {
+          await opened;
+          await write(
+            envelope(FLAG_MESSAGE, {
+              filesystem: {
+                name: event.name,
+                type: WATCH_EVENT_WIRE[event.type],
+              },
+            }),
+          );
+        },
+        onEnd: (error) =>
+          settleEnd(error ?? new Error('watcher ended unexpectedly')),
+      });
+    } catch (error) {
+      const { code, message: text } = watchStartError(error);
+      return streamError(reply, code, text);
+    }
+
+    reply.hijack();
+    reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
+    await write(envelope(FLAG_MESSAGE, { start: {} }));
+    openGate();
+
+    const keepaliveSeconds = Math.min(
+      Number(request.headers['keepalive-ping-interval']) ||
+        MAX_KEEPALIVE_SECONDS,
+      MAX_KEEPALIVE_SECONDS,
+    );
+    const keepalive = setInterval(() => {
+      reply.raw.write(envelope(FLAG_MESSAGE, { keepalive: {} }));
+    }, keepaliveSeconds * 1000);
+    const deadlineMs = wireDeadlineMs(request);
+    let deadlineTimer: NodeJS.Timeout | undefined;
+    const deadline = new Promise<'deadline'>((resolve) => {
+      deadlineTimer = setTimeout(() => resolve('deadline'), deadlineMs);
+    });
+    const clientGone = new Promise<'gone'>((resolve) => {
+      reply.raw.once('close', () => resolve('gone'));
+    });
+    try {
+      const outcome = await Promise.race([ended, deadline, clientGone]);
+      if (outcome === 'deadline') {
+        // The SDK's watch default is 60s: a blown deadline is the normal
+        // ending of most watches, answered like real envd's ctx expiry.
+        await write(
+          envelope(FLAG_END_STREAM, {
+            error: {
+              code: 'deadline_exceeded',
+              message: `watch timed out after ${deadlineMs}ms`,
+            },
+          }),
+        );
+      } else if (outcome instanceof Error) {
+        await write(
+          envelope(FLAG_END_STREAM, {
+            error: { code: 'internal', message: outcome.message },
+          }),
+        );
+      }
+    } finally {
+      clearInterval(keepalive);
+      clearTimeout(deadlineTimer);
+      try {
+        await watcher.stop();
+      } catch {
+        // The sandbox died under the watcher; its ending already spoke.
+      }
+      reply.raw.end();
+    }
+  });
+
+  // The polling trio — what the sync SDKs use instead of the WatchDir
+  // stream. Same watcher engine, parked in the daemon-memory watcher table.
+
+  app.post('/filesystem.Filesystem/CreateWatcher', async (request) => {
+    const body = request.body as { path?: string; recursive?: boolean };
+    if (!body.path) throw connectError('invalid_argument', 'missing path');
+    const row = await wakeForUse(sandboxIdOf(request));
+    try {
+      const watcherId = await watchers.create({
+        executor,
+        sandboxId: row.sandboxId,
+        path: body.path,
+        recursive: body.recursive === true,
+      });
+      return { watcherId };
+    } catch (error) {
+      if (error instanceof WatcherLimitError) {
+        throw connectError('resource_exhausted', error.message);
+      }
+      const { code, message } = watchStartError(error);
+      throw connectError(code, message);
+    }
+  });
+
+  app.post('/filesystem.Filesystem/GetWatcherEvents', async (request) => {
+    const body = request.body as { watcherId?: string };
+    if (!body.watcherId) {
+      throw connectError('invalid_argument', 'missing watcher id');
+    }
+    // No wake: this reads daemon memory. A frozen sandbox has no new events
+    // to report anyway — the disk cannot change while it is frozen.
+    const row = requireRunningRow(sandboxIdOf(request));
+    const events = watchers.drain(row.sandboxId, body.watcherId);
+    if (events === undefined) {
+      throw connectError(
+        'not_found',
+        `watcher with id ${body.watcherId} not found`,
+      );
+    }
+    return {
+      events: events.map((event) => ({
+        name: event.name,
+        type: WATCH_EVENT_WIRE[event.type],
+      })),
+    };
+  });
+
+  app.post('/filesystem.Filesystem/RemoveWatcher', async (request) => {
+    const body = request.body as { watcherId?: string };
+    if (!body.watcherId) {
+      throw connectError('invalid_argument', 'missing watcher id');
+    }
+    // Wakes: stopping the in-container inotifywait needs the container up.
+    const row = await wakeForUse(sandboxIdOf(request));
+    const removed = await watchers.remove(row.sandboxId, body.watcherId);
+    if (!removed) {
+      throw connectError(
+        'not_found',
+        `watcher with id ${body.watcherId} not found`,
+      );
+    }
+    return {};
+  });
+
   // ---- process service -------------------------------------------------
 
   /**
@@ -947,22 +1156,6 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       '/process.Process/StreamInput',
       'streamed stdin is not supported — the SDK sends stdin via SendInput',
     ],
-    [
-      '/filesystem.Filesystem/WatchDir',
-      'directory watching is not supported yet — poll files.list instead',
-    ],
-    [
-      '/filesystem.Filesystem/CreateWatcher',
-      'directory watching is not supported yet — poll files.list instead',
-    ],
-    [
-      '/filesystem.Filesystem/GetWatcherEvents',
-      'directory watching is not supported yet',
-    ],
-    [
-      '/filesystem.Filesystem/RemoveWatcher',
-      'directory watching is not supported yet',
-    ],
   ];
   for (const [path, hint] of unimplemented) {
     app.post(path, async () => {
diff --git a/packages/server/src/e2b/watcher-table.ts b/packages/server/src/e2b/watcher-table.ts
new file mode 100644
index 0000000..7d3a5ba
--- /dev/null
+++ b/packages/server/src/e2b/watcher-table.ts
@@ -0,0 +1,98 @@
+import { randomUUID } from 'node:crypto';
+import type {
+  Executor,
+  WatchDirHandle,
+  WatchEvent,
+} from '../executor/executor';
+
+/**
+ * The polling half of directory watching — what the sync SDKs use instead
+ * of the WatchDir stream: CreateWatcher parks a watcher here, GetWatcherEvents
+ * drains its buffer, RemoveWatcher stops it. Daemon memory, like the process
+ * table: a daemon restart empties it honestly, and a watcher's death (its
+ * container stopping) deletes its record through physical conduction — the
+ * next poll answers not_found, no lifecycle hooks involved.
+ *
+ * Two ceilings real envd does not have, on purpose: envd runs inside the
+ * sandbox, so its unbounded buffer can only blow up the sandbox itself —
+ * this table lives in the host-side daemon, where unbounded means one
+ * sandbox writing files in a loop grows the host's memory. The buffer keeps
+ * the newest events (oldest dropped first); the per-sandbox watcher count
+ * refuses with resource_exhausted.
+ */
+export const MAX_EVENTS_PER_WATCHER = 8192;
+export const MAX_WATCHERS_PER_SANDBOX = 128;
+
+/** Refused watcher creation: the per-sandbox ceiling. */
+export class WatcherLimitError extends Error {}
+
+interface WatcherRecord {
+  watcherId: string;
+  sandboxId: string;
+  events: WatchEvent[];
+  handle: WatchDirHandle;
+}
+
+export class WatcherTable {
+  private readonly records = new Map<string, WatcherRecord>();
+
+  /**
+   * Starts a watcher and parks it. Path errors (missing, not a directory)
+   * surface as the executor's typed errors, exactly like the streaming face.
+   */
+  async create(args: {
+    executor: Executor;
+    sandboxId: string;
+    path: string;
+    recursive: boolean;
+  }): Promise<string> {
+    const { executor, sandboxId, path, recursive } = args;
+    let count = 0;
+    for (const record of this.records.values()) {
+      if (record.sandboxId === sandboxId) count++;
+    }
+    if (count >= MAX_WATCHERS_PER_SANDBOX) {
+      throw new WatcherLimitError(
+        `sandbox ${sandboxId} already has ${MAX_WATCHERS_PER_SANDBOX} watchers — remove some before creating more`,
+      );
+    }
+    const watcherId = randomUUID();
+    const events: WatchEvent[] = [];
+    const handle = await executor.watchDir(sandboxId, {
+      path,
+      recursive,
+      onEvent: (event) => {
+        events.push(event);
+        if (events.length > MAX_EVENTS_PER_WATCHER) events.shift();
+      },
+      // The watcher died with its container: the record goes with it, so
+      // the next poll answers not_found — the closest honest translation
+      // of "the envd you were polling is gone".
+      onEnd: () => {
+        this.records.delete(watcherId);
+      },
+    });
+    this.records.set(watcherId, { watcherId, sandboxId, events, handle });
+    return watcherId;
+  }
+
+  /**
+   * Drains and returns the buffered events — real envd's read-and-reset.
+   * undefined when the watcher does not exist for this sandbox; ids are
+   * sandbox-scoped like pids, so one sandbox cannot poll another's watcher.
+   */
+  drain(sandboxId: string, watcherId: string): WatchEvent[] | undefined {
+    const record = this.records.get(watcherId);
+    if (!record || record.sandboxId !== sandboxId) return undefined;
+    return record.events.splice(0, record.events.length);
+  }
+
+  /** Stops and forgets a watcher. False when there is nothing to remove. */
+  async remove(sandboxId: string, watcherId: string): Promise<boolean> {
+    const record = this.records.get(watcherId);
+    if (!record || record.sandboxId !== sandboxId) return false;
+    this.records.delete(watcherId);
+    await record.handle.stop();
+    return true;
+  }
+}
diff --git a/packages/server/src/executor/contract.ts b/packages/server/src/executor/contract.ts
index 0b68985..3c74848 100644
--- a/packages/server/src/executor/contract.ts
+++ b/packages/server/src/executor/contract.ts
@@ -1187,5 +1187,235 @@ export function describeExecutorContract(
       },
       timeoutMs,
     );
+
+    // ---- watchDir ------------------------------------------------------
+    // Assertions are inclusion, never counts: one real write can surface as
+    // several MODIFY lines, and event multiplicity is the kernel's business,
+    // not the contract's.
+
+    /** Collects events; watch() must be awaited before the change is made. */
+    function eventLog() {
+      const events: Array<{ name: string; type: string }> = [];
+      return {
+        events,
+        onEvent: (e: { name: string; type: string }) => {
+          events.push({ ...e });
+        },
+        has: (name: string, type: string) =>
+          events.some((e) => e.name === name && e.type === type),
+      };
+    }
+
+    it(
+      'a watcher sees a new file as create and write, an overwrite as write',
+      async () => {
+        const id = await fresh();
+        const log = eventLog();
+        const watch = await executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: log.onEvent,
+          onEnd: () => {},
+        });
+        await executor.writeFiles(id, [
+          { path: 'seen.txt', content: Buffer.from('one') },
+        ]);
+        await until(() => log.has('seen.txt', 'create'));
+        await until(() => log.has('seen.txt', 'write'));
+
+        log.events.length = 0;
+        await executor.writeFiles(id, [
+          { path: 'seen.txt', content: Buffer.from('two') },
+        ]);
+        await until(() => log.has('seen.txt', 'write'));
+        expect(log.has('seen.txt', 'create')).toBe(false);
+        await watch.stop();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a watcher sees removals, and a move as rename plus create',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: 'old.txt', content: Buffer.from('x') },
+          { path: 'doomed.txt', content: Buffer.from('y') },
+        ]);
+        const log = eventLog();
+        const watch = await executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: log.onEvent,
+          onEnd: () => {},
+        });
+        await executor.remove(id, 'doomed.txt');
+        await until(() => log.has('doomed.txt', 'remove'));
+
+        await executor.move(id, 'old.txt', 'new.txt');
+        await until(() => log.has('old.txt', 'rename'));
+        await until(() => log.has('new.txt', 'create'));
+        await watch.stop();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'subtree events reach a recursive watcher only, with subdir-relative names',
+      async () => {
+        const id = await fresh();
+        await executor.makeDir(id, '/home/user/sub');
+        const flat = eventLog();
+        const deep = eventLog();
+        const flatWatch = await executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: flat.onEvent,
+          onEnd: () => {},
+        });
+        const deepWatch = await executor.watchDir(id, {
+          path: '/home/user',
+          recursive: true,
+          onEvent: deep.onEvent,
+          onEnd: () => {},
+        });
+        await executor.writeFiles(id, [
+          { path: 'sub/inner.txt', content: Buffer.from('deep') },
+        ]);
+        await until(() => deep.has('sub/inner.txt', 'create'));
+        expect(flat.events).toEqual([]);
+        await flatWatch.stop();
+        await deepWatch.stop();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a recursive watcher follows directories created after it started',
+      async () => {
+        // Measured under gVisor 2026-07-10: inotifywait -r adds watches for
+        // directories born while it is running; the fake's prefix matching
+        // gives the same answer.
+        const id = await fresh();
+        const log = eventLog();
+        const watch = await executor.watchDir(id, {
+          path: '/home/user',
+          recursive: true,
+          onEvent: log.onEvent,
+          onEnd: () => {},
+        });
+        await executor.makeDir(id, '/home/user/born-later');
+        await until(() => log.has('born-later', 'create'));
+        await executor.writeFiles(id, [
+          { path: 'born-later/inside.txt', content: Buffer.from('!') },
+        ]);
+        await until(() => log.has('born-later/inside.txt', 'create'));
+        await watch.stop();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'stop() ends delivery; the watcher does not call onEnd for its own stop',
+      async () => {
+        const id = await fresh();
+        const log = eventLog();
+        let ended = false;
+        const watch = await executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: log.onEvent,
+          onEnd: () => {
+            ended = true;
+          },
+        });
+        await watch.stop();
+        await executor.writeFiles(id, [
+          { path: 'after-stop.txt', content: Buffer.from('x') },
+        ]);
+        // Bounded quiet: nothing arrives for a change made after stop().
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        expect(log.events).toEqual([]);
+        expect(ended).toBe(false);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'watchDir refuses a missing path and a file path with the typed errors',
+      async () => {
+        const id = await fresh();
+        const missing = await executor
+          .watchDir(id, {
+            path: '/home/user/nowhere',
+            recursive: false,
+            onEvent: () => {},
+            onEnd: () => {},
+          })
+          .catch((e) => e);
+        expect(missing).toBeInstanceOf(FileNotFoundError);
+        expect(missing.message).toBe('no such file: /home/user/nowhere');
+
+        await executor.writeFiles(id, [
+          { path: 'plain.txt', content: Buffer.from('x') },
+        ]);
+        const onFile = await executor
+          .watchDir(id, {
+            path: 'plain.txt',
+            recursive: false,
+            onEvent: () => {},
+            onEnd: () => {},
+          })
+          .catch((e) => e);
+        expect(onFile).toBeInstanceOf(NotADirectoryError);
+        expect(onFile.message).toBe('not a directory: /home/user/plain.txt');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'the container stopping ends the watcher through onEnd',
+      async () => {
+        const id = await fresh();
+        let ended: Error | undefined;
+        const watch = await executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: () => {},
+          onEnd: (error) => {
+            ended = error ?? new Error('ended without error');
+          },
+        });
+        await executor.freeze(id);
+        await executor.stop(id);
+        await until(() => ended !== undefined);
+        // Ending was the container's doing, not stop()'s — which now finds
+        // nothing left to do and must still resolve.
+        await watch.stop();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a watcher survives freeze/unfreeze and reports changes made after',
+      async () => {
+        const id = await fresh();
+        const log = eventLog();
+        const watch = await executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: log.onEvent,
+          onEnd: () => {},
+        });
+        await executor.freeze(id);
+        await executor.unfreeze(id);
+        await executor.writeFiles(id, [
+          { path: 'thawed.txt', content: Buffer.from('back') },
+        ]);
+        await until(() => log.has('thawed.txt', 'create'));
+        await watch.stop();
+      },
+      timeoutMs,
+    );
   });
 }
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 7a47ba7..9e5da94 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -33,6 +33,9 @@ import {
   NotAFileError,
   type PtySize,
   type SandboxEntry,
+  type WatchDirHandle,
+  type WatchDirOptions,
+  type WatchEvent,
 } from './executor';
 
 /**
@@ -154,6 +157,62 @@ const REMOVE_SCRIPT = [
   'exec rm -rf -- "$1"',
 ].join('\n');
 
+/**
+ * A watcher may outlive any one request, but not the sandbox's day — the
+ * same backstop as e2b-surface execs, physical cleanup only.
+ */
+const WATCH_BACKSTOP_SECONDS = 24 * 60 * 60;
+
+/**
+ * $1 = pidfile, $2 = recursive flag (`-r` or empty), $3 = watched dir.
+ * The existence checks run in-script: one round trip, no gap for the path
+ * to change under a separate stat. Readiness is inotifywait's own
+ * "Watches established." on stderr — measured under gVisor 2026-07-10,
+ * along with -r picking up directories created after the watch began.
+ */
+const WATCH_SCRIPT = [
+  'echo "$$" > "$1"',
+  `[ -e "$3" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  `[ -d "$3" ] || exit ${NOT_A_DIR_EXIT}`,
+  // $2 rides unquoted on purpose: empty must vanish, not become an argument.
+  `exec timeout --signal=KILL ${WATCH_BACKSTOP_SECONDS} inotifywait -m $2 -e create,modify,delete,move,attrib --format '%e|%w%f' -- "$3"`,
+].join('\n');
+
+/**
+ * One inotifywait line -> wire events. A line reads `OPS|/abs/path` with
+ * OPS comma-separated; `ISDIR` and anything unmapped fall through silently.
+ * MOVED_FROM/MOVED_TO land as rename/create — fsnotify's reading, which is
+ * what the E2B wire speaks. Events on the watched directory itself (empty
+ * name) are dropped, like real envd's "." edge.
+ */
+export function parseInotifyLine(line: string, base: string): WatchEvent[] {
+  const cut = line.indexOf('|');
+  if (cut === -1) return [];
+  const eventPath = line.slice(cut + 1);
+  const prefix = base === '/' ? '/' : `${base}/`;
+  if (!eventPath.startsWith(prefix) || eventPath.length === prefix.length) {
+    return [];
+  }
+  const name = eventPath.slice(prefix.length);
+  const events: WatchEvent[] = [];
+  for (const op of line.slice(0, cut).split(',')) {
+    const type =
+      op === 'CREATE' || op === 'MOVED_TO'
+        ? ('create' as const)
+        : op === 'MODIFY'
+          ? ('write' as const)
+          : op === 'DELETE'
+            ? ('remove' as const)
+            : op === 'MOVED_FROM'
+              ? ('rename' as const)
+              : op === 'ATTRIB'
+                ? ('chmod' as const)
+                : undefined;
+    if (type) events.push({ name, type });
+  }
+  return events;
+}
+
 /**
  * Wrapper every execStream command runs under, so the handle can signal it
  * later. $1 = pidfile, $2 = timeout seconds, $3 = the user's command.
@@ -1046,6 +1105,108 @@ export class DockerExecutor implements Executor {
     }
   }
 
+  async watchDir(
+    sandboxId: string,
+    opts: WatchDirOptions,
+  ): Promise<WatchDirHandle> {
+    const resolved = resolveSandboxPath(opts.path);
+    const containerId = await this.expectState(sandboxId, 'running');
+    const container = this.docker.getContainer(containerId);
+    const pidfile = `/tmp/.dormice-exec-${randomUUID()}.pid`;
+
+    // Once true, arriving lines drain and drop — after stop() nothing is
+    // delivered, even the pipe's stragglers.
+    let stopped = false;
+    let pending = '';
+    const onStdout = async (chunk: Buffer) => {
+      pending += chunk.toString('utf8');
+      while (true) {
+        const eol = pending.indexOf('\n');
+        if (eol === -1) return;
+        const line = pending.slice(0, eol);
+        pending = pending.slice(eol + 1);
+        for (const event of parseInotifyLine(line, resolved)) {
+          // Awaited: backpressure travels through to inotifywait's pipe.
+          if (!stopped) await opts.onEvent(event);
+        }
+      }
+    };
+    let stderrText = '';
+    let markReady = () => {};
+    const ready = new Promise<'ready'>((resolve) => {
+      markReady = () => resolve('ready');
+    });
+    const onStderr = (chunk: Buffer) => {
+      stderrText += chunk.toString('utf8');
+      if (stderrText.includes('Watches established.')) markReady();
+    };
+
+    const started = await this.startInContainer(container, sandboxId, {
+      cmd: [
+        'bash',
+        '-c',
+        WATCH_SCRIPT,
+        'bash',
+        pidfile,
+        opts.recursive ? '-r' : '',
+        resolved,
+      ],
+      stdout: new CallbackSink(onStdout),
+      stderr: new CallbackSink(onStderr),
+    });
+    const exitInfo = started.wait().then(
+      (exitCode) => ({ exitCode, error: undefined as Error | undefined }),
+      (error) => ({
+        exitCode: -1,
+        error: error instanceof Error ? error : new Error(String(error)),
+      }),
+    );
+
+    const outcome = await Promise.race([ready, exitInfo]);
+    if (outcome !== 'ready') {
+      // The script spoke through its exit code before the watch stood up.
+      if (outcome.exitCode === NO_SUCH_FILE_EXIT) {
+        throw new FileNotFoundError(`no such file: ${resolved}`);
+      }
+      if (outcome.exitCode === NOT_A_DIR_EXIT) {
+        throw new NotADirectoryError(`not a directory: ${resolved}`);
+      }
+      if (outcome.exitCode === 127) {
+        throw new Error(
+          `inotifywait is not in this sandbox's image — rebuild it from images/Dockerfile (it installs inotify-tools) to enable watch`,
+        );
+      }
+      throw new Error(
+        `starting watcher on ${resolved} in ${sandboxId} failed (exit ${outcome.exitCode}): ${stderrText.trim()}`,
+      );
+    }
+
+    void exitInfo.then(({ exitCode, error }) => {
+      if (stopped) return;
+      stopped = true;
+      opts.onEnd(
+        error ?? new Error(`watcher on ${resolved} exited with ${exitCode}`),
+      );
+    });
+
+    return {
+      stop: async () => {
+        if (stopped) return;
+        stopped = true;
+        try {
+          await this.signalProcess(container, sandboxId, pidfile, 'SIGKILL');
+        } catch {
+          // The container is paused or gone: the signal cannot land, so
+          // waiting for the exit would hang. The stopped flag already
+          // silences the watcher; the process itself is reaped by the
+          // container's own death or the 24h backstop.
+          return;
+        }
+        await exitInfo;
+      },
+    };
+  }
+
   /** The buffered face of the exec pipeline: capped sinks, awaited to the end. */
   private async runInContainer(
     container: Docker.Container,
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index d9aa96e..57f8804 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -118,6 +118,36 @@ export interface FileToWrite {
   content: Buffer;
 }
 
+/**
+ * One filesystem change under a watched directory — fsnotify's vocabulary,
+ * because that is what the E2B wire speaks. A move fires 'rename' on the
+ * old path and 'create' on the new one; 'name' is relative to the watched
+ * directory ('sub/x.txt' under a recursive watch).
+ */
+export interface WatchEvent {
+  name: string;
+  type: 'create' | 'write' | 'remove' | 'rename' | 'chmod';
+}
+
+export interface WatchDirOptions {
+  /** Absolute, or relative to /home/user — resolveSandboxPath's rules. */
+  path: string;
+  /** Watch the whole subtree; directories created later are picked up too. */
+  recursive: boolean;
+  /** A returned promise is awaited before the next event: backpressure. */
+  onEvent: (event: WatchEvent) => void | Promise<void>;
+  /**
+   * The watcher died without stop() being called — its container stopped,
+   * or the watching process failed. Never fires after stop().
+   */
+  onEnd: (error?: Error) => void;
+}
+
+export interface WatchDirHandle {
+  /** Stops watching; no events or onEnd are delivered after this resolves. */
+  stop(): Promise<void>;
+}
+
 /** What the filesystem says about one path — the shape stat and listDir speak. */
 export interface SandboxEntry {
   /** Basename; '/' for the root itself. */
@@ -304,4 +334,15 @@ export interface Executor {
    * state (unlike removeDisk, whose caller is reconciliation).
    */
   remove(sandboxId: string, path: string): Promise<void>;
+  /**
+   * Starts watching a directory for filesystem events. The path must exist
+   * (FileNotFoundError) and be a directory (NotADirectoryError) — checked
+   * before the returned promise resolves; resolution means the watch is
+   * established, so a change made right after is seen. Requires state
+   * `running`; a freeze suspends the watcher with everything else, and
+   * events cannot be missed while frozen — the disk only changes from
+   * inside, and anything that reaches inside wakes the sandbox first.
+   * Lifetime is bounded by the sandbox's own 24h exec backstop.
+   */
+  watchDir(sandboxId: string, opts: WatchDirOptions): Promise<WatchDirHandle>;
 }
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index e0fbb9c..2025afc 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -19,6 +19,9 @@ import {
   NotAFileError,
   type PtySize,
   type SandboxEntry,
+  type WatchDirHandle,
+  type WatchDirOptions,
+  type WatchEvent,
 } from './executor';
 
 /**
@@ -79,6 +82,21 @@ function entryFor(path: string, node: FakeNode): SandboxEntry {
   };
 }
 
+/**
+ * One live fake watcher: a subscription on the fake disk's mutation funnels.
+ * Events chain through `queue` so a slow onEvent (backpressure) never
+ * reorders deliveries — the same serialization the real executor gets from
+ * reading inotifywait's pipe line by line.
+ */
+interface FakeWatcher {
+  base: string;
+  recursive: boolean;
+  onEvent: (event: WatchEvent) => void | Promise<void>;
+  onEnd: (error?: Error) => void;
+  stopped: boolean;
+  queue: Promise<void>;
+}
+
 /**
  * The live half of a fake process: a stdin mailbox and a kill switch. The
  * interpreter reads the mailbox (cat), sleeps interruptibly against the
@@ -178,6 +196,12 @@ export class FakeExecutor implements Executor {
    * modeled where it physically lives.
    */
   private readonly fs = new Map<string, Map<string, FakeNode>>();
+  /**
+   * Live watchers per sandbox. Keyed like processes, not disks: a watcher
+   * is a running inotifywait on the real executor, so the container's death
+   * ends it even though the files it watched survive.
+   */
+  private readonly watchers = new Map<string, Set<FakeWatcher>>();
 
   /** Test hook: what does "reality" say about this sandbox? */
   stateOf(sandboxId: string): ContainerState | undefined {
@@ -437,8 +461,74 @@ export class FakeExecutor implements Executor {
 
   private killProcesses(sandboxId: string): void {
     const set = this.procs.get(sandboxId);
+    if (set) for (const io of set) io.kill('SIGKILL');
+    this.endWatchers(sandboxId);
+  }
+
+  /** The container died under the watchers — conduct it, like processes. */
+  private endWatchers(sandboxId: string): void {
+    const set = this.watchers.get(sandboxId);
+    if (!set) return;
+    this.watchers.delete(sandboxId);
+    for (const watcher of set) {
+      if (watcher.stopped) continue;
+      watcher.stopped = true;
+      watcher.onEnd(new Error('watcher stopped: its container died'));
+    }
+  }
+
+  /** The mutation funnels report here; each watcher filters and enqueues. */
+  private emitWatch(
+    sandboxId: string,
+    path: string,
+    type: WatchEvent['type'],
+  ): void {
+    const set = this.watchers.get(sandboxId);
     if (!set) return;
-    for (const io of set) io.kill('SIGKILL');
+    for (const watcher of set) {
+      if (watcher.stopped) continue;
+      const prefix = watcher.base === '/' ? '/' : `${watcher.base}/`;
+      if (!path.startsWith(prefix)) continue;
+      const name = path.slice(prefix.length);
+      if (!watcher.recursive && name.includes('/')) continue;
+      watcher.queue = watcher.queue.then(async () => {
+        if (watcher.stopped) return;
+        await watcher.onEvent({ name, type });
+      });
+      // A throwing onEvent must not silence the watcher or crash anything;
+      // the real pipe reader shrugs the same way.
+      watcher.queue = watcher.queue.catch(() => {});
+    }
+  }
+
+  async watchDir(
+    sandboxId: string,
+    opts: WatchDirOptions,
+  ): Promise<WatchDirHandle> {
+    this.expect(sandboxId, 'running');
+    const base = resolveSandboxPath(opts.path);
+    const node = this.disk(sandboxId).get(base);
+    if (!node) throw new FileNotFoundError(`no such file: ${base}`);
+    if (node.type !== 'dir') {
+      throw new NotADirectoryError(`not a directory: ${base}`);
+    }
+    const watcher: FakeWatcher = {
+      base,
+      recursive: opts.recursive,
+      onEvent: opts.onEvent,
+      onEnd: opts.onEnd,
+      stopped: false,
+      queue: Promise.resolve(),
+    };
+    const set = this.watchers.get(sandboxId) ?? new Set();
+    set.add(watcher);
+    this.watchers.set(sandboxId, set);
+    return {
+      stop: async () => {
+        watcher.stopped = true;
+        set.delete(watcher);
+      },
+    };
   }
 
   async writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void> {
@@ -532,6 +622,7 @@ export class FakeExecutor implements Executor {
     const now = new Date().toISOString();
     this.ensureParents(sandboxId, disk, resolved);
     disk.set(resolved, { type: 'dir', modifiedTime: now });
+    this.emitWatch(sandboxId, resolved, 'create');
     return true;
   }
 
@@ -564,6 +655,11 @@ export class FakeExecutor implements Executor {
       disk.delete(p);
       disk.set(destination + p.slice(source.length), n);
     }
+    // inotify's move pair: RENAME fires on the old path, CREATE on the new
+    // one (fsnotify's reading of MOVED_FROM/MOVED_TO); children move along
+    // silently, exactly like the kernel's.
+    this.emitWatch(sandboxId, source, 'rename');
+    this.emitWatch(sandboxId, destination, 'create');
     return entryFor(destination, node);
   }
 
@@ -579,9 +675,17 @@ export class FakeExecutor implements Executor {
       throw new Error(`removing ${resolved} failed: built-in directory`);
     }
     const prefix = `${resolved}/`;
+    const deleted: string[] = [];
     for (const p of [...disk.keys()]) {
-      if (p === resolved || p.startsWith(prefix)) disk.delete(p);
+      if (p === resolved || p.startsWith(prefix)) {
+        disk.delete(p);
+        deleted.push(p);
+      }
     }
+    // rm -rf works depth-first, so inotify reports children before their
+    // directory; deepest-first reproduces that order.
+    deleted.sort((a, b) => b.length - a.length);
+    for (const p of deleted) this.emitWatch(sandboxId, p, 'remove');
   }
 
   private disk(sandboxId: string): Map<string, FakeNode> {
@@ -607,6 +711,10 @@ export class FakeExecutor implements Executor {
       content,
       modifiedTime: new Date().toISOString(),
     });
+    // A new file is CREATE then MODIFY through inotify; an overwrite is
+    // MODIFY only (the real cat > truncates in place).
+    if (!existing) this.emitWatch(sandboxId, resolved, 'create');
+    this.emitWatch(sandboxId, resolved, 'write');
   }
 
   /** mkdir -p leaves real directories behind; so does the fake. */
@@ -625,6 +733,7 @@ export class FakeExecutor implements Executor {
           type: 'dir',
           modifiedTime: new Date().toISOString(),
         });
+        this.emitWatch(sandboxId, parent, 'create');
       } else if (node.type !== 'dir') {
         // mkdir -p over a file fails on the real executor too (its stderr
         // wording differs; the contract does not pin this path).

From a31c06739301c360530a45884b9450ccd80eeec1 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 03:56:43 +0800
Subject: [PATCH 021/133] A terminal in the console: the browser speaks the
 envd wire itself
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The detail page grows an interactive bash behind an explicit click —
opening a terminal wakes a sleeping sandbox, so merely looking at a page
must never thaw anything. There is no console-only terminal endpoint:
output is the same Process/Start PTY stream the e2b SDK reads (plain
fetch, no WebSocket), keystrokes go through SendInput on a client-side
serial chain (the browser may spread POSTs across connections, and
reordered keystrokes corrupt input), resize is Update, and closing the
terminal SIGKILLs the shell so no orphan bash outlives its tab. The one
new server piece is POST /ui/envdToken: envd auth is the per-sandbox
HMAC only an API-token holder can compute, and the browser deliberately
is not one — the session cookie trades for exactly one sandbox's token,
through the same requireApiAuth arbiter as every native route.
---
 packages/server/src/routes/ui.test.ts         |  40 +++
 packages/server/src/routes/ui.ts              |  28 ++
 packages/web/package.json                     |   2 +
 .../sandboxes/components/SandboxTerminal.tsx  | 137 ++++++++++
 .../web/src/features/sandboxes/envd-pty.ts    | 241 ++++++++++++++++++
 .../sandboxes/pages/SandboxDetailPage.tsx     |   5 +
 packages/web/src/lib/api.ts                   |   5 +
 packages/web/vite.config.ts                   |   3 +
 pnpm-lock.yaml                                |  16 ++
 9 files changed, 477 insertions(+)
 create mode 100644 packages/web/src/features/sandboxes/components/SandboxTerminal.tsx
 create mode 100644 packages/web/src/features/sandboxes/envd-pty.ts

diff --git a/packages/server/src/routes/ui.test.ts b/packages/server/src/routes/ui.test.ts
index c99d36d..b150c28 100644
--- a/packages/server/src/routes/ui.test.ts
+++ b/packages/server/src/routes/ui.test.ts
@@ -13,6 +13,7 @@ import {
 } from '../auth';
 import { loadConfig } from '../config';
 import { migrateDb, openDb } from '../db/db';
+import { verifyEnvdToken } from '../e2b/protocol';
 import { FakeExecutor } from '../executor/fake';
 import { KeyedQueue } from '../keyed-queue';
 
@@ -159,6 +160,45 @@ describe('cookie-authenticated API access', () => {
   });
 });
 
+describe('POST /ui/envdToken', () => {
+  async function mint(
+    app: ReturnType<typeof testApp>,
+    cookieValue: string,
+    headers: Record<string, string> = { [CONSOLE_HEADER]: '1' },
+  ) {
+    return app.inject({
+      method: 'POST',
+      url: '/ui/envdToken',
+      cookies: { [SESSION_COOKIE]: cookieValue },
+      headers,
+      payload: { sandboxId: 'sb-terminal' },
+    });
+  }
+
+  it('a session cookie mints the exact token the envd surface verifies', async () => {
+    const app = testApp();
+    const cookie = sessionCookie(await login(app));
+    const res = await mint(app, cookie.value);
+    expect(res.statusCode).toBe(200);
+    const { envdAccessToken } = res.json() as { envdAccessToken: string };
+    expect(verifyEnvdToken(TOKEN, 'sb-terminal', envdAccessToken)).toBe(true);
+    // Per-sandbox: the same token opens no other sandbox.
+    expect(verifyEnvdToken(TOKEN, 'sb-other', envdAccessToken)).toBe(false);
+  });
+
+  it('goes through the API-wide arbiter: no console header, no token', async () => {
+    const app = testApp();
+    const cookie = sessionCookie(await login(app));
+    const res = await mint(app, cookie.value, {});
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('rejects a tampered cookie', async () => {
+    const res = await mint(testApp(), `${mintSession(TOKEN)}ff`);
+    expect(res.statusCode).toBe(401);
+  });
+});
+
 describe('POST /ui/auth/logout', () => {
   it('clears the session cookie', async () => {
     const res = await testApp().inject({
diff --git a/packages/server/src/routes/ui.ts b/packages/server/src/routes/ui.ts
index 34a2157..de0c9f0 100644
--- a/packages/server/src/routes/ui.ts
+++ b/packages/server/src/routes/ui.ts
@@ -3,11 +3,13 @@ import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import { z } from 'zod';
 import {
   mintSession,
+  requireApiAuth,
   SESSION_COOKIE,
   SESSION_TTL_SECONDS,
   tokensEqual,
 } from '../auth';
 import type { Config } from '../config';
+import { mintEnvdToken } from '../e2b/protocol';
 
 export interface UiRoutesOptions {
   config: Config;
@@ -73,6 +75,32 @@ export const uiRoutes: FastifyPluginAsyncZod<UiRoutesOptions> = async (
     },
   );
 
+  // The console's terminal speaks to the envd surface directly — the same
+  // wire the e2b SDK uses — but envd auth is the per-sandbox HMAC, which
+  // only an API-token holder can compute and the browser deliberately is
+  // not one. This trades the session for exactly one sandbox's token; the
+  // API-wide arbiter guards it, so the cookie path also needs the console
+  // header. Minting is stateless on purpose (like the token itself): a
+  // made-up sandboxId yields a token that opens nothing.
+  app.post(
+    '/ui/envdToken',
+    {
+      onRequest: requireApiAuth(config.DORMICE_API_TOKEN),
+      schema: {
+        body: z.object({ sandboxId: z.string().min(1) }),
+        response: {
+          200: z.object({ envdAccessToken: z.string() }),
+        },
+      },
+    },
+    async (request) => ({
+      envdAccessToken: mintEnvdToken(
+        config.DORMICE_API_TOKEN,
+        request.body.sandboxId,
+      ),
+    }),
+  );
+
   if (webDistDir) {
     await app.register(
       async (ui) => {
diff --git a/packages/web/package.json b/packages/web/package.json
index ae33ed1..26320fa 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -18,6 +18,8 @@
     "@shadcn/react": "^0.2.1",
     "@tanstack/react-query": "^5.101.2",
     "@tanstack/react-router": "^1.170.17",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
diff --git a/packages/web/src/features/sandboxes/components/SandboxTerminal.tsx b/packages/web/src/features/sandboxes/components/SandboxTerminal.tsx
new file mode 100644
index 0000000..6f2f09f
--- /dev/null
+++ b/packages/web/src/features/sandboxes/components/SandboxTerminal.tsx
@@ -0,0 +1,137 @@
+import { FitAddon } from '@xterm/addon-fit';
+import { Terminal } from '@xterm/xterm';
+import { useEffect, useRef, useState } from 'react';
+import { Button } from '@/components/ui/button';
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import { mintEnvdToken } from '@/lib/api';
+import { openPty, type PtySession } from '../envd-pty';
+import '@xterm/xterm/css/xterm.css';
+
+/**
+ * One live terminal: an xterm bound to a PTY session in the sandbox. The
+ * whole session lives inside the effect — unmounting kills the shell, so
+ * navigating away never strands a bash in the process table.
+ */
+function LiveTerminal({ sandboxId }: { sandboxId: string }) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const [closedReason, setClosedReason] = useState<string | null>(null);
+  const [generation, setGeneration] = useState(0);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: generation is unused inside on purpose — bumping it is how Reconnect re-runs the whole session effect
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const term = new Terminal({ cursorBlink: true, fontSize: 13 });
+    const fit = new FitAddon();
+    term.loadAddon(fit);
+    term.open(container);
+    fit.fit();
+    // Waking a stopped sandbox is a cold start — seconds, not ms. Say so
+    // in the terminal itself instead of leaving a dead black box.
+    term.writeln('\x1b[2mconnecting — a sleeping sandbox wakes first…\x1b[0m');
+
+    let session: PtySession | undefined;
+    let cancelled = false;
+    (async () => {
+      const { envdAccessToken } = await mintEnvdToken(sandboxId);
+      if (cancelled) return;
+      session = await openPty({
+        sandboxId,
+        envdAccessToken,
+        size: { cols: term.cols, rows: term.rows },
+        callbacks: {
+          onData: (bytes) => term.write(bytes),
+          onClose: (reason) => {
+            if (!cancelled) setClosedReason(reason);
+          },
+        },
+      });
+      if (cancelled) {
+        void session.close();
+        return;
+      }
+      term.onData((data) => session?.write(data));
+      term.onResize(({ cols, rows }) => session?.resize({ cols, rows }));
+      term.focus();
+    })().catch((error: unknown) => {
+      if (!cancelled) {
+        setClosedReason(error instanceof Error ? error.message : String(error));
+      }
+    });
+
+    const observer = new ResizeObserver(() => fit.fit());
+    observer.observe(container);
+    return () => {
+      cancelled = true;
+      observer.disconnect();
+      void session?.close();
+      term.dispose();
+    };
+  }, [sandboxId, generation]);
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div
+        ref={containerRef}
+        className="h-80 w-full overflow-hidden rounded-md bg-black p-2"
+      />
+      {closedReason && (
+        <div className="flex items-center justify-between rounded-md border px-3 py-2 text-sm text-muted-foreground">
+          <span>{closedReason}</span>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => {
+              setClosedReason(null);
+              setGeneration((n) => n + 1);
+            }}
+          >
+            Reconnect
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The terminal lives behind an explicit click: opening one starts a bash,
+ * which wakes a frozen sandbox — and merely looking at a detail page must
+ * never thaw anything.
+ */
+export function SandboxTerminalCard({ sandboxId }: { sandboxId: string }) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Terminal</CardTitle>
+        <CardDescription>
+          An interactive bash inside the sandbox — opening it wakes a sleeping
+          sandbox, closing it lets the idle countdown resume.
+        </CardDescription>
+        <CardAction>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => setOpen((value) => !value)}
+          >
+            {open ? 'Close terminal' : 'Open terminal'}
+          </Button>
+        </CardAction>
+      </CardHeader>
+      {open && (
+        <CardContent>
+          <LiveTerminal sandboxId={sandboxId} />
+        </CardContent>
+      )}
+    </Card>
+  );
+}
diff --git a/packages/web/src/features/sandboxes/envd-pty.ts b/packages/web/src/features/sandboxes/envd-pty.ts
new file mode 100644
index 0000000..cad153b
--- /dev/null
+++ b/packages/web/src/features/sandboxes/envd-pty.ts
@@ -0,0 +1,241 @@
+/**
+ * A browser-side client for the daemon's envd PTY surface — the exact wire
+ * the official e2b SDK speaks, reused instead of inventing a console-only
+ * terminal endpoint (a second protocol would be a second truth). Output is
+ * one streaming Connect RPC (Process/Start with a pty block); keystrokes,
+ * resizes and the kill are plain unary calls. All of it is fetch — no
+ * WebSocket, so it works through any proxy plain HTTP works through.
+ */
+
+const ENVD = '/e2b/envd';
+
+/** Connect streaming envelope flags, mirrored from the server's protocol.ts. */
+const FLAG_END_STREAM = 0x02;
+
+export interface PtySize {
+  cols: number;
+  rows: number;
+}
+
+export interface PtyCallbacks {
+  /** Raw terminal output — bytes for xterm.write, straight off the wire. */
+  onData: (bytes: Uint8Array) => void;
+  /**
+   * The session is over, whichever way: the shell exited, the stream
+   * errored, or the sandbox died under it. Fires exactly once.
+   */
+  onClose: (reason: string) => void;
+}
+
+export interface PtySession {
+  /** Keyboard input, exactly as xterm's onData hands it over. */
+  write(data: string): void;
+  resize(size: PtySize): void;
+  /** Kill the shell and drop the stream. Safe to call more than once. */
+  close(): Promise<void>;
+}
+
+/** 1 flag byte + 4-byte big-endian length + JSON — the Connect JSON codec. */
+function envelope(json: unknown): Uint8Array<ArrayBuffer> {
+  const payload = new TextEncoder().encode(JSON.stringify(json));
+  const buf = new Uint8Array(5 + payload.length);
+  new DataView(buf.buffer).setUint32(1, payload.length);
+  buf.set(payload, 5);
+  return buf;
+}
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function fromBase64(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** What a data/end/error frame can carry — the slice of the stream we read. */
+interface StreamFrame {
+  event?: {
+    start?: { pid?: number };
+    data?: { pty?: string };
+    end?: { exitCode?: number; status?: string };
+  };
+  error?: { code?: string; message?: string };
+}
+
+/**
+ * Opens an interactive bash in the sandbox and resolves once the shell has
+ * actually started (the stream's start frame carries the pid the unary
+ * calls need). Opening wakes a frozen sandbox — callers gate this behind an
+ * explicit user action, because merely looking at a sandbox must not thaw it.
+ */
+export async function openPty(options: {
+  sandboxId: string;
+  envdAccessToken: string;
+  size: PtySize;
+  callbacks: PtyCallbacks;
+}): Promise<PtySession> {
+  const { sandboxId, envdAccessToken, size, callbacks } = options;
+  const headers = {
+    'e2b-sandbox-id': sandboxId,
+    'x-access-token': envdAccessToken,
+  };
+
+  async function unary(rpc: string, body: unknown): Promise<void> {
+    const res = await fetch(`${ENVD}/process.Process/${rpc}`, {
+      method: 'POST',
+      headers: { ...headers, 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const detail = (await res.json().catch(() => undefined)) as
+        | { message?: string }
+        | undefined;
+      throw new Error(detail?.message ?? `${rpc} failed with ${res.status}`);
+    }
+  }
+
+  const abort = new AbortController();
+  const res = await fetch(`${ENVD}/process.Process/Start`, {
+    method: 'POST',
+    headers: { ...headers, 'content-type': 'application/connect+json' },
+    // The shape the e2b SDK sends for a terminal; the daemon accepts no
+    // other. TERM travels as an env because there is no tty inheritance.
+    body: envelope({
+      process: {
+        cmd: '/bin/bash',
+        args: ['-i', '-l'],
+        envs: { TERM: 'xterm-256color' },
+      },
+      pty: { size },
+    }),
+    signal: abort.signal,
+  });
+  if (!res.ok || !res.body) {
+    const detail = (await res.json().catch(() => undefined)) as
+      | { message?: string }
+      | undefined;
+    throw new Error(detail?.message ?? `terminal failed with ${res.status}`);
+  }
+
+  let closed = false;
+  const closeOnce = (reason: string) => {
+    if (closed) return;
+    closed = true;
+    abort.abort();
+    callbacks.onClose(reason);
+  };
+
+  // Frames arrive fragmented and coalesced at TCP's whim; buffer and slice.
+  let buffer = new Uint8Array(0);
+  const handleFrame = (
+    flags: number,
+    frame: StreamFrame,
+  ): number | undefined => {
+    if (flags & FLAG_END_STREAM) {
+      closeOnce(frame.error?.message ?? 'connection closed');
+      return;
+    }
+    if (frame.event?.data?.pty) {
+      callbacks.onData(fromBase64(frame.event.data.pty));
+    }
+    if (frame.event?.end) {
+      closeOnce(`shell exited (code ${frame.event.end.exitCode ?? '?'})`);
+    }
+    return frame.event?.start?.pid;
+  };
+
+  const reader = res.body.getReader();
+  const pumpFrames = async (until?: 'start'): Promise<number | undefined> => {
+    for (;;) {
+      while (buffer.length >= 5) {
+        const view = new DataView(
+          buffer.buffer,
+          buffer.byteOffset,
+          buffer.byteLength,
+        );
+        const length = view.getUint32(1);
+        if (buffer.length < 5 + length) break;
+        const json = JSON.parse(
+          new TextDecoder().decode(buffer.subarray(5, 5 + length)),
+        ) as StreamFrame;
+        const flags = view.getUint8(0);
+        buffer = buffer.slice(5 + length);
+        const pid = handleFrame(flags, json);
+        if (closed) return undefined;
+        if (until === 'start' && typeof pid === 'number') return pid;
+      }
+      const { done, value } = await reader.read();
+      if (done) {
+        closeOnce('connection closed');
+        return undefined;
+      }
+      const grown = new Uint8Array(buffer.length + value.length);
+      grown.set(buffer);
+      grown.set(value, buffer.length);
+      buffer = grown;
+    }
+  };
+
+  // The start frame is the daemon's promise that bash is running; anything
+  // else first (an in-stream error, an early close) fails the open.
+  let pid: number | undefined;
+  try {
+    pid = await pumpFrames('start');
+  } catch (error) {
+    closeOnce(error instanceof Error ? error.message : String(error));
+  }
+  if (pid === undefined) {
+    throw new Error('terminal did not start');
+  }
+  const startedPid = pid;
+
+  // Keep draining in the background for the life of the session.
+  pumpFrames().catch((error: unknown) => {
+    // An aborted fetch rejects; that is close() doing its job, not news.
+    if (!closed) {
+      closeOnce(error instanceof Error ? error.message : String(error));
+    }
+  });
+
+  // Keystrokes are separate POSTs, and the browser may spread them over
+  // several connections — chained here so they cannot arrive reordered.
+  let inputChain: Promise<void> = Promise.resolve();
+
+  return {
+    write(data: string) {
+      const input = toBase64(new TextEncoder().encode(data));
+      inputChain = inputChain
+        .then(() =>
+          unary('SendInput', {
+            process: { pid: startedPid },
+            input: { pty: input },
+          }),
+        )
+        .catch(() => {
+          // A failed keystroke on a dying session; the stream's own close
+          // tells the story.
+        });
+    },
+    resize(next: PtySize) {
+      void unary('Update', {
+        process: { pid: startedPid },
+        pty: { size: next },
+      }).catch(() => undefined);
+    },
+    async close() {
+      if (closed) return;
+      // Kill first, then drop the stream: an abandoned bash would otherwise
+      // sit in the process table until the sandbox stops.
+      await unary('SendSignal', {
+        process: { pid: startedPid },
+        signal: 'SIGNAL_SIGKILL',
+      }).catch(() => undefined);
+      closeOnce('terminal closed');
+    },
+  };
+}
diff --git a/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx
index dfdd7b1..98b71b5 100644
--- a/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -13,6 +13,7 @@ import {
 } from '@/components/ui/empty';
 import { ReleaseSandboxButton } from '../components/ReleaseSandboxButton';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
+import { SandboxTerminalCard } from '../components/SandboxTerminal';
 import { formatDuration, since } from '../format';
 import { useSandbox } from '../hooks/useSandboxes';
 
@@ -77,6 +78,10 @@ export function SandboxDetailPage() {
         />
       </header>
 
+      <div className="mb-6">
+        <SandboxTerminalCard sandboxId={sandbox.sandboxId} />
+      </div>
+
       <Card>
         <CardContent>
           <dl>
diff --git a/packages/web/src/lib/api.ts b/packages/web/src/lib/api.ts
index f48bfc0..7ae4a06 100644
--- a/packages/web/src/lib/api.ts
+++ b/packages/web/src/lib/api.ts
@@ -77,3 +77,8 @@ export const acquireSandbox = (request: AcquireRequest) =>
 
 export const releaseSandbox = (userKey: string) =>
   rpc<{ released: boolean }>('/releaseSandbox', { userKey });
+
+// The terminal's key: trades the session cookie for one sandbox's envd
+// access token, so the browser can speak to the envd surface directly.
+export const mintEnvdToken = (sandboxId: string) =>
+  rpc<{ envdAccessToken: string }>('/ui/envdToken', { sandboxId });
diff --git a/packages/web/vite.config.ts b/packages/web/vite.config.ts
index 4ab13df..7b5fa05 100644
--- a/packages/web/vite.config.ts
+++ b/packages/web/vite.config.ts
@@ -21,9 +21,12 @@ export default defineConfig({
     // API — same paths the browser uses in production, so no API base knob.
     proxy: {
       '/ui/auth': 'http://127.0.0.1:3676',
+      '/ui/envdToken': 'http://127.0.0.1:3676',
       '/listSandboxes': 'http://127.0.0.1:3676',
       '/releaseSandbox': 'http://127.0.0.1:3676',
       '/acquireSandbox': 'http://127.0.0.1:3676',
+      // The terminal speaks the envd surface directly, like the e2b SDK.
+      '/e2b': 'http://127.0.0.1:3676',
     },
   },
 });
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d4e7df7..e0d87ec 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -137,6 +137,12 @@ importers:
       '@tanstack/react-router':
         specifier: ^1.170.17
         version: 1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@xterm/addon-fit':
+        specifier: ^0.11.0
+        version: 0.11.0
+      '@xterm/xterm':
+        specifier: ^6.0.0
+        version: 6.0.0
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
@@ -1965,6 +1971,12 @@ packages:
   '@vitest/utils@4.1.10':
     resolution: {integrity: sha512-fy9am/HWxbaGt/Sawrp90vt6Y6jQwf1RX77cz3uwoJwJVMli/e1IEwRPnMNJ7vKfPTwo0diXifkpPvwH9v7nGA==}
 
+  '@xterm/addon-fit@0.11.0':
+    resolution: {integrity: sha512-jYcgT6xtVYhnhgxh3QgYDnnNMYTcf8ElbxxFzX0IZo+vabQqSPAjC3c1wJrKB5E19VwQei89QCiZZP86DCPF7g==}
+
+  '@xterm/xterm@6.0.0':
+    resolution: {integrity: sha512-TQwDdQGtwwDt+2cgKDLn0IRaSxYu1tSUjgKarSDkUM0ZNiSRXFpjxEsvc/Zgc5kq5omJ+V0a8/kIM2WD3sMOYg==}
+
   abstract-logging@2.0.1:
     resolution: {integrity: sha512-2BjRTZxTPvheOvGbBslFSYOUkr+SjPtOnrLP33f+VIWLzezQpZcqVg7ja3L4dBXmzzgwT+a029jRx5PCi3JuiA==}
 
@@ -5679,6 +5691,10 @@ snapshots:
       convert-source-map: 2.0.0
       tinyrainbow: 3.1.0
 
+  '@xterm/addon-fit@0.11.0': {}
+
+  '@xterm/xterm@6.0.0': {}
+
   abstract-logging@2.0.1: {}
 
   accepts@2.0.0:

From 9960dc5a6ff5d5d2aa4ba0500229202b07e3de0a Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 03:59:59 +0800
Subject: [PATCH 022/133] e2e exam disks evaporate with the exam: default
 DORMICE_DATA_DIR to the temp dir
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A docker-mode e2e run without an exported DORMICE_DATA_DIR dropped its
sandbox disks into /var/lib/dormice — the resident daemon's data dir,
whose startup guard then refused to start over 14 foreign disks
(measured 2026-07-10). An exported value still wins.
---
 e2e/src/setup/daemon.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/e2e/src/setup/daemon.ts b/e2e/src/setup/daemon.ts
index 6a0f5bd..9521bd4 100644
--- a/e2e/src/setup/daemon.ts
+++ b/e2e/src/setup/daemon.ts
@@ -56,6 +56,12 @@ export default async function setup(project: TestProject) {
   }
   const child = spawn('node', [MAIN], {
     env: {
+      // Exam disks evaporate with the exam: without this default, a docker
+      // run without an exported DORMICE_DATA_DIR drops its sandbox disks
+      // into /var/lib/dormice — the resident daemon's data dir, whose
+      // startup guard then refuses to start (measured 2026-07-10). An
+      // exported value still wins through `inherited` below.
+      DORMICE_DATA_DIR: dataDir,
       ...inherited,
       DORMICE_PORT: String(port),
       DORMICE_DB_PATH: join(dataDir, 'dormice.db'),

From c036635c1ff5fa60d989b62609cd43b190eba39c Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 04:18:38 +0800
Subject: [PATCH 023/133] Claude Code joins the base image, pinned at 2.1.200

---
 images/Dockerfile | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/images/Dockerfile b/images/Dockerfile
index a729d8f..0c52cfa 100644
--- a/images/Dockerfile
+++ b/images/Dockerfile
@@ -1,4 +1,5 @@
-# Dormice sandbox base image: Ubuntu 24.04 + Python 3.12 + Node.js 24 LTS.
+# Dormice sandbox base image: Ubuntu 24.04 + Python 3.12 + Node.js 24 LTS
+# + Claude Code.
 #
 # Three rules this file lives by:
 #   1. Layers are ordered by change frequency: system packages at the bottom,
@@ -58,7 +59,16 @@ RUN if [ -n "$PIP_INDEX" ]; then \
       && printf 'registry=%s\n' "$NPM_REGISTRY" > "/opt/node-$NODE_VERSION-linux-x64/etc/npmrc"; \
     fi
 
-# ---- Layer 4: non-root user (top layer) ----
+# ---- Layer 4: Claude Code, version-pinned ----
+# Placed after the registry layer on purpose: `npm install -g` reads the
+# global npmrc written above, so a mirror configured for the sandbox also
+# speeds up this build step. Installs into the Node prefix under /opt
+# (never /home/user — rule 2), with the usual /usr/local/bin symlink.
+ARG CLAUDE_CODE_VERSION=2.1.200
+RUN npm install -g "@anthropic-ai/claude-code@$CLAUDE_CODE_VERSION" \
+ && ln -s "/opt/node-$NODE_VERSION-linux-x64/bin/claude" /usr/local/bin/claude
+
+# ---- Layer 5: non-root user (top layer) ----
 # ubuntu:24.04 ships an "ubuntu" user at uid 1000; replace it with "user" so
 # the uid the executor chowns sandbox disks to always maps to the same name.
 RUN userdel -r ubuntu 2>/dev/null; useradd -m -u 1000 -s /bin/bash user

From 9eca60272aa9c9d29b01e36e4eca6d0a0197ada6 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 14:11:54 +0800
Subject: [PATCH 024/133] rebuildSandbox: swap the container, keep the disk

The disk is the sandbox's body; the container is a shell built from the
daemon's base image at creation time. Removing the shell and letting the
next wake rebuild it is how an existing sandbox picks up a new base image
without losing a byte of /home/user. New executor verb removeContainer
(any state, keeps the disk, contract-pinned), POST /rebuildSandbox
(404 unknown key, leaves the row stopped), SDK method, dor sandbox
rebuild, and a Rebuild button on the console's detail page. The one new
legal two-rung transition: active -> stopped.
---
 e2e/src/native.test.ts                        | 48 +++++++++++++
 packages/cli/src/commands.test.ts             | 13 ++++
 packages/cli/src/commands.ts                  | 16 +++++
 packages/cli/src/main.ts                      | 11 +++
 packages/sdk/src/client.test.ts               | 21 ++++++
 packages/sdk/src/client.ts                    | 15 ++++
 packages/server/src/app.test.ts               | 68 +++++++++++++++++++
 packages/server/src/db/ledger.test.ts         |  8 +--
 packages/server/src/db/ledger.ts              | 12 ++--
 packages/server/src/executor/contract.ts      | 54 +++++++++++++++
 packages/server/src/executor/docker.ts        | 35 ++++++++--
 packages/server/src/executor/executor.ts      |  9 +++
 packages/server/src/executor/fake.ts          | 14 ++++
 packages/server/src/lifecycle.ts              | 21 ++++++
 packages/server/src/routes/sandboxes.ts       | 41 ++++++++++-
 packages/shared/src/index.ts                  |  1 +
 packages/shared/src/rebuild.ts                | 32 +++++++++
 .../components/RebuildSandboxButton.tsx       | 60 ++++++++++++++++
 .../features/sandboxes/hooks/useSandboxes.ts  | 15 +++-
 .../sandboxes/pages/SandboxDetailPage.tsx     | 12 ++--
 packages/web/src/lib/api.ts                   |  5 ++
 21 files changed, 490 insertions(+), 21 deletions(-)
 create mode 100644 packages/shared/src/rebuild.ts
 create mode 100644 packages/web/src/features/sandboxes/components/RebuildSandboxButton.tsx

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index 173e215..f5c403a 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -96,6 +96,54 @@ describe('native API over a real daemon', () => {
     expect(again.sandbox.sandboxId).not.toBe(created.sandbox.sandboxId);
   });
 
+  it('rebuilds a sandbox: shell swapped, /home/user kept, same key wakes it', async () => {
+    const created = await client().acquireSandbox('rebuild-key');
+    await client().writeFiles('rebuild-key', [
+      { path: 'keep.txt', content: 'still here' },
+    ]);
+
+    const { sandbox } = await client().rebuildSandbox('rebuild-key');
+    expect(sandbox.sandboxId).toBe(created.sandbox.sandboxId);
+    expect(sandbox.state).toBe('stopped');
+
+    // The wake after a rebuild is a cold start into a fresh container; the
+    // disk — and with it the file — must have survived the swap.
+    const again = await client().acquireSandbox('rebuild-key');
+    expect(again.sandbox.sandboxId).toBe(created.sandbox.sandboxId);
+    const read = await client().readFile('rebuild-key', 'keep.txt');
+    expect(new TextDecoder().decode(read.content)).toBe('still here');
+
+    await expect(client().rebuildSandbox('nobody-key')).rejects.toMatchObject({
+      name: 'DormiceApiError',
+      status: 404,
+    });
+    await client().releaseSandbox('rebuild-key');
+  });
+
+  // The fake's files hang off the disk, so only a real container can show
+  // the other half of rebuild's promise: the container layer resets.
+  it.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
+    'rebuild resets the container layer: /tmp evaporates, /home/user stays',
+    async () => {
+      await client().acquireSandbox('rebuild-layers-key');
+      await client().execCommand(
+        'rebuild-layers-key',
+        'touch /tmp/ephemeral && echo kept > ~/kept.txt',
+      );
+
+      await client().rebuildSandbox('rebuild-layers-key');
+
+      const check = await client().execCommand(
+        'rebuild-layers-key',
+        'ls /tmp/ephemeral; cat ~/kept.txt',
+      );
+      expect(check.stdout).toContain('kept');
+      expect(check.stdout).not.toContain('ephemeral');
+      expect(check.stderr).toMatch(/No such file/);
+      await client().releaseSandbox('rebuild-layers-key');
+    },
+  );
+
   it('runs a command in the sandbox and returns the buffered result', async () => {
     await client().acquireSandbox('exec-key');
     const result = await client().execCommand('exec-key', 'echo hi');
diff --git a/packages/cli/src/commands.test.ts b/packages/cli/src/commands.test.ts
index e95794f..c129022 100644
--- a/packages/cli/src/commands.test.ts
+++ b/packages/cli/src/commands.test.ts
@@ -16,6 +16,7 @@ import {
   sandboxLs,
   sandboxPull,
   sandboxPush,
+  sandboxRebuild,
   sandboxRelease,
 } from './commands';
 
@@ -154,6 +155,18 @@ describe('sandbox commands over real HTTP', () => {
     await client.releaseSandbox('puller');
   });
 
+  it('rebuild reports the swap and surfaces the 404 for an unknown key', async () => {
+    await client.acquireSandbox('rebuilder');
+    expect(await sandboxRebuild(client, 'rebuilder')).toBe(
+      'Rebuilt the sandbox for key "rebuilder" — /home/user kept, now stopped; ' +
+        'its next use starts on the current base image.',
+    );
+    await expect(sandboxRebuild(client, 'nobody')).rejects.toThrow(
+      /acquire it first/,
+    );
+    await client.releaseSandbox('rebuilder');
+  });
+
   it('release reports both outcomes of the idempotent destroy', async () => {
     await client.acquireSandbox('carol');
     expect(await sandboxRelease(client, 'carol')).toBe(
diff --git a/packages/cli/src/commands.ts b/packages/cli/src/commands.ts
index 36d3210..6dad8f2 100644
--- a/packages/cli/src/commands.ts
+++ b/packages/cli/src/commands.ts
@@ -137,6 +137,22 @@ export function pullSavedMessage(
   return `Pulled ${printable(result.path)} -> ${localPath} (${result.content.length} bytes).`;
 }
 
+/**
+ * `dor sandbox rebuild <userKey>`: swap the sandbox's container, keep its
+ * disk. /home/user survives; everything else resets onto the daemon's
+ * current base image at the next use.
+ */
+export async function sandboxRebuild(
+  client: Dormice,
+  userKey: string,
+): Promise<string> {
+  const { sandbox } = await client.rebuildSandbox(userKey);
+  return (
+    `Rebuilt the sandbox for key "${printable(userKey)}" — /home/user kept, ` +
+    `now ${sandbox.state}; its next use starts on the current base image.`
+  );
+}
+
 /** `dor sandbox release <userKey>`: destroy the sandbox behind a key, idempotently. */
 export async function sandboxRelease(
   client: Dormice,
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index 6375798..261cf3f 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -13,6 +13,7 @@ import {
   sandboxLs,
   sandboxPull,
   sandboxPush,
+  sandboxRebuild,
   sandboxRelease,
 } from './commands';
 import { realDoctorContext, runDoctor } from './doctor';
@@ -117,6 +118,16 @@ sandbox
     console.log(pullSavedMessage(result, localPath));
   });
 
+sandbox
+  .command('rebuild')
+  .description(
+    'Swap the container, keep /home/user — next use starts on the current base image',
+  )
+  .argument('<userKey>', 'the user key whose sandbox to rebuild')
+  .action(async (userKey: string) => {
+    console.log(await sandboxRebuild(clientFromEnv(process.env), userKey));
+  });
+
 sandbox
   .command('release')
   .description('Destroy the sandbox behind a user key (idempotent)')
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 994a502..68eedc8 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -246,6 +246,27 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
     });
   });
 
+  it('rebuilds a sandbox: same id, state stopped, data intact after re-acquire', async () => {
+    const created = await client.acquireSandbox('grace');
+    const id = created.sandbox.sandboxId;
+    await client.writeFiles('grace', [{ path: 'keep.txt', content: 'body' }]);
+
+    const { sandbox } = await client.rebuildSandbox('grace');
+    expect(sandbox.sandboxId).toBe(id);
+    expect(sandbox.state).toBe('stopped');
+    expect(executor.stateOf(id)).toBeUndefined();
+
+    const again = await client.acquireSandbox('grace');
+    expect(again.sandbox.sandboxId).toBe(id);
+    const read = await client.readFile('grace', 'keep.txt');
+    expect(new TextDecoder().decode(read.content)).toBe('body');
+
+    await expect(client.rebuildSandbox('no-such-key')).rejects.toMatchObject({
+      name: 'DormiceApiError',
+      status: 404,
+    });
+  });
+
   it('releases a sandbox and reports idempotently', async () => {
     const created = await client.acquireSandbox('frank');
     expect(await client.releaseSandbox('frank')).toEqual({ released: true });
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 4346046..ec9f10b 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -6,8 +6,10 @@ import {
   execCommandResponseSchema,
   type LifecyclePolicyOverride,
   listSandboxesResponseSchema,
+  type RebuildSandboxResponse,
   type ReleaseSandboxResponse,
   readFileResponseSchema,
+  rebuildSandboxResponseSchema,
   releaseSandboxResponseSchema,
   type Sandbox,
   type WriteFilesResponse,
@@ -101,6 +103,19 @@ export class Dormice {
     return listSandboxesResponseSchema.parse(data).sandboxes;
   }
 
+  /**
+   * Swaps the sandbox's container while keeping its disk: /home/user is
+   * untouched, and the next use builds a fresh container from the daemon's
+   * current base image — how an existing sandbox picks up new shared layers
+   * (anything outside /home/user is reset). The sandbox is left `stopped`;
+   * the next acquire or exec wakes it, paying one cold start. Unknown key:
+   * 404 — rebuild is not a creator.
+   */
+  async rebuildSandbox(userKey: string): Promise<RebuildSandboxResponse> {
+    const data = await this.rpc('rebuildSandbox', { userKey });
+    return rebuildSandboxResponseSchema.parse(data);
+  }
+
   /**
    * Destroys the sandbox behind a user key — container and disk are gone
    * for good. Idempotent like acquire: a key that has no sandbox is not an
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index 853c99b..4826518 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -749,6 +749,74 @@ describe('POST /listSandboxes', () => {
   });
 });
 
+describe('POST /rebuildSandbox', () => {
+  it('swaps the container, keeps the disk, and the same key wakes with its data', async () => {
+    const { app, executor } = testApp();
+    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const id = created.sandbox.sandboxId;
+    await rpc(app, '/writeFiles', {
+      userKey: 'alice',
+      files: [
+        {
+          path: 'keep.txt',
+          contentBase64: Buffer.from('survives').toString('base64'),
+        },
+      ],
+    });
+
+    const res = await rpc(app, '/rebuildSandbox', { userKey: 'alice' });
+    expect(res.statusCode).toBe(200);
+    // The shell is gone, the row stays, the state says so honestly.
+    expect(res.json().sandbox).toMatchObject({
+      sandboxId: id,
+      state: 'stopped',
+    });
+    expect(executor.stateOf(id)).toBeUndefined();
+
+    // The same key comes back to the same sandbox — rebuilt shell, same body.
+    const again = (await acquire(app, { userKey: 'alice' })).json();
+    expect(again.sandbox.sandboxId).toBe(id);
+    const read = await rpc(app, '/readFile', {
+      userKey: 'alice',
+      path: 'keep.txt',
+    });
+    expect(Buffer.from(read.json().contentBase64, 'base64').toString()).toBe(
+      'survives',
+    );
+  });
+
+  it('rebuilds a frozen sandbox too, and again while already stopped', async () => {
+    const { app, db, executor, locks } = testApp();
+    const created = (await acquire(app, { userKey: 'alice' })).json();
+    await scanOnce(
+      db,
+      executor,
+      locks,
+      after(
+        created.sandbox.lastActiveAt,
+        DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
+      ),
+    );
+    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+
+    const res = await rpc(app, '/rebuildSandbox', { userKey: 'alice' });
+    expect(res.json().sandbox.state).toBe('stopped');
+
+    // A second rebuild finds no container — the goal state, not an error.
+    const again = await rpc(app, '/rebuildSandbox', { userKey: 'alice' });
+    expect(again.statusCode).toBe(200);
+    expect(again.json().sandbox.state).toBe('stopped');
+  });
+
+  it('answers 404 for an unknown key — rebuild is not a creator', async () => {
+    const res = await rpc(testApp().app, '/rebuildSandbox', {
+      userKey: 'nobody',
+    });
+    expect(res.statusCode).toBe(404);
+    expect(res.json().message).toMatch(/acquire it first/);
+  });
+});
+
 describe('POST /releaseSandbox', () => {
   it('destroys the container and forgets the key', async () => {
     const { app, executor } = testApp();
diff --git a/packages/server/src/db/ledger.test.ts b/packages/server/src/db/ledger.test.ts
index 4b4396a..e5d38aa 100644
--- a/packages/server/src/db/ledger.test.ts
+++ b/packages/server/src/db/ledger.test.ts
@@ -59,15 +59,15 @@ describe('ledger', () => {
     expect(transition(db, sandboxId, 'active').state).toBe('active');
   });
 
-  it('rejects skipping rungs on the way down', () => {
+  it('rejects skipping rungs on the way down, except rebuild', () => {
     const db = testDb();
     const { sandboxId } = create(db);
-    expect(() => transition(db, sandboxId, 'stopped')).toThrow(
-      /illegal transition/,
-    );
     expect(() => transition(db, sandboxId, 'archived')).toThrow(
       /illegal transition/,
     );
+    // The one legal two-rung move: rebuild removes a running container
+    // outright, with no paused moment in between to record.
+    expect(transition(db, sandboxId, 'stopped').state).toBe('stopped');
   });
 
   it('rejects waking an archived sandbox without going through restoring', () => {
diff --git a/packages/server/src/db/ledger.ts b/packages/server/src/db/ledger.ts
index af12a2a..a92fb24 100644
--- a/packages/server/src/db/ledger.ts
+++ b/packages/server/src/db/ledger.ts
@@ -4,16 +4,18 @@ import type { Db } from './db';
 import { type SandboxRow, sandboxes } from './schema';
 
 /**
- * The lifecycle state machine. A sandbox only ever moves one rung colder at
- * a time; waking up is a single jump back to active. Everything the idle
- * scanner and acquire() are allowed to do is this table — it is the single
- * arbiter for state changes, enforced in transition().
+ * The lifecycle state machine. The idle scanner only ever moves one rung
+ * colder at a time; waking up is a single jump back to active. The one
+ * two-rung move is active -> stopped: rebuild removes a running container
+ * outright (the shell is swapped, the disk stays), and there is no paused
+ * moment in between to record. This table is the single arbiter for state
+ * changes, enforced in transition().
  */
 export const ALLOWED_TRANSITIONS: Record<
   SandboxState,
   readonly SandboxState[]
 > = {
-  active: ['frozen'],
+  active: ['frozen', 'stopped'],
   frozen: ['active', 'stopped'],
   stopped: ['active', 'archived'],
   archived: ['restoring'],
diff --git a/packages/server/src/executor/contract.ts b/packages/server/src/executor/contract.ts
index 3c74848..e55a329 100644
--- a/packages/server/src/executor/contract.ts
+++ b/packages/server/src/executor/contract.ts
@@ -206,6 +206,60 @@ export function describeExecutorContract(
       timeoutMs,
     );
 
+    it(
+      'removeContainer swaps the shell: container gone, disk kept, start rebuilds with data intact',
+      async () => {
+        const id = await fresh();
+        await executor.writeFiles(id, [
+          { path: 'keep.txt', content: Buffer.from('survives the rebuild') },
+        ]);
+
+        await executor.removeContainer(id);
+        expect(await stateOf(id)).toBeUndefined();
+        expect(await executor.listDisks()).toContain(id);
+
+        await executor.start(id);
+        expect(await stateOf(id)).toBe('running');
+        expect((await executor.readFile(id, 'keep.txt')).toString()).toBe(
+          'survives the rebuild',
+        );
+      },
+      timeoutMs,
+    );
+
+    it(
+      'removeContainer takes the container down from any state',
+      async () => {
+        const paused = await fresh();
+        await executor.freeze(paused);
+        await executor.removeContainer(paused);
+        expect(await stateOf(paused)).toBeUndefined();
+        expect(await executor.listDisks()).toContain(paused);
+
+        const stopped = await freshStopped();
+        await executor.removeContainer(stopped);
+        expect(await stateOf(stopped)).toBeUndefined();
+        expect(await executor.listDisks()).toContain(stopped);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'removeContainer: an absent container is the goal state beside a disk, a complaint without one',
+      async () => {
+        const id = await freshStopped();
+        await subject.vanishContainer(id);
+        // Pruned behind the daemon's back — removing it again is a no-op.
+        await executor.removeContainer(id);
+        expect(await executor.listDisks()).toContain(id);
+
+        await expect(executor.removeContainer(randomUUID())).rejects.toThrow(
+          /absent, cannot remove/,
+        );
+      },
+      timeoutMs,
+    );
+
     it(
       'the disk lives with the container: born on create, kept through stop, gone on destroy',
       async () => {
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 9e5da94..912139d 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -489,12 +489,36 @@ export class DockerExecutor implements Executor {
       await this.teardownDisk(sandboxId);
       return;
     }
+    await this.takeContainerDown(found);
+    await this.teardownDisk(sandboxId);
+  }
+
+  async removeContainer(sandboxId: string): Promise<void> {
+    const found = await this.inspect(sandboxId);
+    if (found === null) {
+      // Already gone is the goal state — but only alongside a surviving
+      // disk. Both absent means the ledger points at nothing, worth hearing
+      // (destroy's contract, same message shape).
+      if (!(await this.diskExists(sandboxId))) {
+        throw new Error(`container ${sandboxId} is absent, cannot remove`);
+      }
+      return;
+    }
+    await this.takeContainerDown(found);
+  }
+
+  /**
+   * Walks a container down from any state and removes it, ourselves instead
+   * of leaning on remove's force-kill: dockerd cannot deliver a signal into
+   * a paused gVisor sandbox and burns a hard-coded 10s wait before
+   * escalating (measured 2026-07-09, sometimes erroring "PID is zombie").
+   * Unpause so the kill lands, then wait for the actual exit before removing.
+   */
+  private async takeContainerDown(found: {
+    id: string;
+    status: string;
+  }): Promise<void> {
     const container = this.docker.getContainer(found.id);
-    // Walk the container down ourselves instead of leaning on remove's
-    // force-kill: dockerd cannot deliver a signal into a paused gVisor
-    // sandbox and burns a hard-coded 10s wait before escalating (measured
-    // 2026-07-09, sometimes erroring "PID is zombie"). Unpause so the kill
-    // lands, then wait for the actual exit before removing.
     if (found.status === 'paused') {
       await container.unpause();
     }
@@ -508,7 +532,6 @@ export class DockerExecutor implements Executor {
       await container.wait({ condition: 'not-running' });
     }
     await container.remove({ force: true });
-    await this.teardownDisk(sandboxId);
   }
 
   async listContainers(): Promise<Map<string, ContainerState>> {
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index 57f8804..8e9566f 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -213,6 +213,15 @@ export interface Executor {
    * already gone: that means the ledger and reality disagree.
    */
   destroy(sandboxId: string): Promise<void>;
+  /**
+   * Removes the container object, whatever state, and keeps the disk —
+   * rebuild's physical half. The next start() builds a fresh container from
+   * the surviving disk (and thus from the daemon's *current* base image);
+   * this is how a sandbox upgrades its shared layers without losing data.
+   * A container already gone is the goal state as long as the disk remains;
+   * both absent throws, like destroy — the ledger and reality disagree.
+   */
+  removeContainer(sandboxId: string): Promise<void>;
   /**
    * Every container this executor knows about, with its observed state.
    * The reconciler's window into reality — the read the ledger is checked
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index 2025afc..bac0a1a 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -285,6 +285,20 @@ export class FakeExecutor implements Executor {
     }
   }
 
+  async removeContainer(sandboxId: string): Promise<void> {
+    // Any state goes; an already-gone container is the goal state as long
+    // as the disk remains. Both absent is destroy's same complaint: the
+    // ledger points at nothing. The disk — and with it the files — stays
+    // untouched: that is the entire point of the verb.
+    const hadContainer = this.containers.delete(sandboxId);
+    if (!hadContainer && !this.disks.has(sandboxId)) {
+      throw new Error(`container ${sandboxId} is absent, cannot remove`);
+    }
+    // The container's death takes every process and watcher with it, same
+    // physics as stop and vanish.
+    this.killProcesses(sandboxId);
+  }
+
   async listContainers(): Promise<Map<string, ContainerState>> {
     // A copy: reality is observed, not handed out by reference.
     return new Map(this.containers);
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index 419da29..b25f805 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -47,6 +47,27 @@ export async function releaseSandbox(
   deleteSandbox(db, sandboxId);
 }
 
+/**
+ * Swap the shell, keep the body: the container is removed (whatever state),
+ * the disk stays, and the ledger records `stopped` — the state whose wake
+ * path builds a fresh container from the surviving disk, and therefore from
+ * the daemon's *current* base image. This is how an existing sandbox picks
+ * up new shared layers without losing a byte of /home/user. Already-stopped
+ * rows skip the ledger write: removing a pruned-away container is a no-op
+ * and stopped -> stopped is not a transition.
+ */
+export async function rebuildSandbox(
+  db: Db,
+  executor: Executor,
+  row: SandboxRow,
+): Promise<SandboxRow> {
+  await executor.removeContainer(row.sandboxId);
+  if (row.state === 'stopped') {
+    return row;
+  }
+  return transition(db, row.sandboxId, 'stopped');
+}
+
 /** Brings a sandbox in any cold state back to active. No-op when already active. */
 export async function wakeSandbox(
   db: Db,
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index 25fea15..99dd677 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -8,6 +8,8 @@ import {
   listSandboxesResponseSchema,
   readFileRequestSchema,
   readFileResponseSchema,
+  rebuildSandboxRequestSchema,
+  rebuildSandboxResponseSchema,
   releaseSandboxRequestSchema,
   releaseSandboxResponseSchema,
   resolveSandboxPath,
@@ -37,7 +39,7 @@ import {
 } from '../executor/executor';
 import { httpError } from '../http-error';
 import type { KeyedQueue } from '../keyed-queue';
-import { releaseSandbox, wakeSandbox } from '../lifecycle';
+import { rebuildSandbox, releaseSandbox, wakeSandbox } from '../lifecycle';
 import { resolvePolicy } from '../policy';
 
 export interface SandboxRoutesOptions {
@@ -313,6 +315,43 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     },
   );
 
+  app.post(
+    '/rebuildSandbox',
+    {
+      schema: {
+        body: rebuildSandboxRequestSchema,
+        response: { 200: rebuildSandboxResponseSchema },
+      },
+    },
+    async (request) => {
+      const { userKey } = request.body;
+      // The whole verb holds the key's slot, like the file verbs: seconds of
+      // executor work at worst, and the slot keeps the scanner and a
+      // concurrent release from moving the sandbox under our feet.
+      return locks.run(userKey, async () => {
+        const existing = findByUserKey(db, userKey);
+        if (!existing) {
+          // Not a creator and not a destroyer: an unknown key is a typo,
+          // not a goal state — same manners as exec.
+          throw httpError(
+            404,
+            `no sandbox for key "${userKey}" — acquire it first`,
+          );
+        }
+        if (existing.state === 'archived' || existing.state === 'restoring') {
+          // An archived sandbox has no container to swap; it already meets
+          // rebuild's promise (its next wake builds from the current image).
+          throw httpError(
+            409,
+            `sandbox for key "${userKey}" is ${existing.state} — it has no container to rebuild`,
+          );
+        }
+        const row = await rebuildSandbox(db, executor, existing);
+        return { sandbox: toSandbox(row, endpoint) };
+      });
+    },
+  );
+
   app.post(
     '/releaseSandbox',
     {
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 914d925..b0638d2 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -3,6 +3,7 @@ export * from './exec';
 export * from './files';
 export * from './list';
 export * from './policy';
+export * from './rebuild';
 export * from './release';
 export * from './sandbox';
 export * from './states';
diff --git a/packages/shared/src/rebuild.ts b/packages/shared/src/rebuild.ts
new file mode 100644
index 0000000..f75cb03
--- /dev/null
+++ b/packages/shared/src/rebuild.ts
@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { sandboxSchema, userKeySchema } from './sandbox';
+
+/**
+ * rebuildSandbox(userKey) — swap the container, keep the disk. The disk is
+ * the sandbox's body; the container is a replaceable shell built from the
+ * daemon's current base image. Removing the shell and letting the next wake
+ * rebuild it is how an existing sandbox picks up a new base image without
+ * losing a byte of /home/user.
+ *
+ * Not idempotent-forgiving like release: rebuilding a key that has no
+ * sandbox is a caller's confusion (a typo, not a goal state) and answers 404.
+ */
+export const rebuildSandboxRequestSchema = z.object({
+  userKey: userKeySchema,
+});
+
+export type RebuildSandboxRequest = z.infer<typeof rebuildSandboxRequestSchema>;
+
+/**
+ * The sandbox as it stands after the rebuild: always `stopped` — the old
+ * container is gone, the disk waits. The next acquire (or any verb that
+ * wakes) builds the new container; rebuild itself does not, so callers pay
+ * the cold start only when they actually come back.
+ */
+export const rebuildSandboxResponseSchema = z.object({
+  sandbox: sandboxSchema,
+});
+
+export type RebuildSandboxResponse = z.infer<
+  typeof rebuildSandboxResponseSchema
+>;
diff --git a/packages/web/src/features/sandboxes/components/RebuildSandboxButton.tsx b/packages/web/src/features/sandboxes/components/RebuildSandboxButton.tsx
new file mode 100644
index 0000000..939d47d
--- /dev/null
+++ b/packages/web/src/features/sandboxes/components/RebuildSandboxButton.tsx
@@ -0,0 +1,60 @@
+import { toast } from 'sonner';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@/components/ui/alert-dialog';
+import { Button } from '@/components/ui/button';
+import { Spinner } from '@/components/ui/spinner';
+import { useRebuildSandbox } from '../hooks/useSandboxes';
+
+/**
+ * Rebuild swaps the container and keeps /home/user — not destructive, but it
+ * does kill everything running inside and resets anything installed outside
+ * the home directory, so it still asks first.
+ */
+export function RebuildSandboxButton({ userKey }: { userKey: string }) {
+  const mutation = useRebuildSandbox();
+
+  const rebuild = () =>
+    mutation.mutate(userKey, {
+      onSuccess: () =>
+        toast.success(
+          `Rebuilt ${userKey} — /home/user kept; its next use starts on the current base image`,
+        ),
+      onError: (error) => toast.error(error.message),
+    });
+
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger
+        render={
+          <Button variant="outline" size="sm" disabled={mutation.isPending}>
+            {mutation.isPending && <Spinner />}
+            Rebuild
+          </Button>
+        }
+      />
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Rebuild “{userKey}”?</AlertDialogTitle>
+          <AlertDialogDescription>
+            Swaps the container so the next use starts on the daemon’s current
+            base image. Everything in /home/user is kept; running processes and
+            changes outside it are gone.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Keep it</AlertDialogCancel>
+          <AlertDialogAction onClick={rebuild}>Rebuild</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
diff --git a/packages/web/src/features/sandboxes/hooks/useSandboxes.ts b/packages/web/src/features/sandboxes/hooks/useSandboxes.ts
index 1437fe0..e10c19f 100644
--- a/packages/web/src/features/sandboxes/hooks/useSandboxes.ts
+++ b/packages/web/src/features/sandboxes/hooks/useSandboxes.ts
@@ -1,6 +1,11 @@
 import type { AcquireRequest } from '@dormice/shared';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { acquireSandbox, listSandboxes, releaseSandbox } from '@/lib/api';
+import {
+  acquireSandbox,
+  listSandboxes,
+  rebuildSandbox,
+  releaseSandbox,
+} from '@/lib/api';
 
 /**
  * One entity, one file: every sandbox query and mutation lives here.
@@ -35,6 +40,14 @@ export function useAcquireSandbox() {
   });
 }
 
+export function useRebuildSandbox() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (userKey: string) => rebuildSandbox(userKey),
+    onSettled: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
+  });
+}
+
 export function useReleaseSandbox() {
   const queryClient = useQueryClient();
   return useMutation({
diff --git a/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx
index 98b71b5..0dfbe26 100644
--- a/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -11,6 +11,7 @@ import {
   EmptyHeader,
   EmptyTitle,
 } from '@/components/ui/empty';
+import { RebuildSandboxButton } from '../components/RebuildSandboxButton';
 import { ReleaseSandboxButton } from '../components/ReleaseSandboxButton';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
 import { SandboxTerminalCard } from '../components/SandboxTerminal';
@@ -72,10 +73,13 @@ export function SandboxDetailPage() {
           <h1 className="font-mono text-lg font-semibold">{sandbox.userKey}</h1>
           <SandboxStateBadge state={sandbox.state} />
         </div>
-        <ReleaseSandboxButton
-          userKey={sandbox.userKey}
-          onReleased={() => navigate({ to: '/' })}
-        />
+        <div className="flex items-center gap-2">
+          <RebuildSandboxButton userKey={sandbox.userKey} />
+          <ReleaseSandboxButton
+            userKey={sandbox.userKey}
+            onReleased={() => navigate({ to: '/' })}
+          />
+        </div>
       </header>
 
       <div className="mb-6">
diff --git a/packages/web/src/lib/api.ts b/packages/web/src/lib/api.ts
index 7ae4a06..e279efd 100644
--- a/packages/web/src/lib/api.ts
+++ b/packages/web/src/lib/api.ts
@@ -78,6 +78,11 @@ export const acquireSandbox = (request: AcquireRequest) =>
 export const releaseSandbox = (userKey: string) =>
   rpc<{ released: boolean }>('/releaseSandbox', { userKey });
 
+// Swap the container, keep /home/user: the next use starts on the daemon's
+// current base image.
+export const rebuildSandbox = (userKey: string) =>
+  rpc<{ sandbox: Sandbox }>('/rebuildSandbox', { userKey });
+
 // The terminal's key: trades the session cookie for one sandbox's envd
 // access token, so the browser can speak to the envd surface directly.
 export const mintEnvdToken = (sandboxId: string) =>

From 3d102f27b0e625627ea52b5a1dc9a6fd4c23dd86 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 14:39:25 +0800
Subject: [PATCH 025/133] The envd plugin splits into one file per protocol
 face
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

envd.ts had grown to 1165 lines carrying four independent surfaces (plain-
HTTP files, the unary Filesystem service, directory watching, the Process
service) plus a set of closure-shared helpers, and it grows with every new
E2B feature. The helpers only ever needed E2bDeps, so they move to
envd/shared.ts — pure ones as module functions, the liveness/wake
adjudicators built once by createEnvdContext — and each face registers its
routes from its own file. The plugin entry keeps the surface-wide machinery:
parsers, auth hook, error dialect, /health. Wire behavior is untouched;
compat, contract and e2e suites all pass unchanged.
---
 packages/server/src/e2b/envd.ts            | 1165 --------------------
 packages/server/src/e2b/envd/files.ts      |  153 +++
 packages/server/src/e2b/envd/filesystem.ts |  114 ++
 packages/server/src/e2b/envd/index.ts      |  114 ++
 packages/server/src/e2b/envd/process.ts    |  477 ++++++++
 packages/server/src/e2b/envd/shared.ts     |  183 +++
 packages/server/src/e2b/envd/watch.ts      |  236 ++++
 7 files changed, 1277 insertions(+), 1165 deletions(-)
 delete mode 100644 packages/server/src/e2b/envd.ts
 create mode 100644 packages/server/src/e2b/envd/files.ts
 create mode 100644 packages/server/src/e2b/envd/filesystem.ts
 create mode 100644 packages/server/src/e2b/envd/index.ts
 create mode 100644 packages/server/src/e2b/envd/process.ts
 create mode 100644 packages/server/src/e2b/envd/shared.ts
 create mode 100644 packages/server/src/e2b/envd/watch.ts

diff --git a/packages/server/src/e2b/envd.ts b/packages/server/src/e2b/envd.ts
deleted file mode 100644
index 58ae088..0000000
--- a/packages/server/src/e2b/envd.ts
+++ /dev/null
@@ -1,1165 +0,0 @@
-import { Buffer } from 'node:buffer';
-import { resolveSandboxPath } from '@dormice/shared';
-import multipart from '@fastify/multipart';
-import type { FastifyReply, FastifyRequest } from 'fastify';
-import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
-import { findBySandboxId, touch } from '../db/ledger';
-import type { SandboxRow } from '../db/schema';
-import { startExecHeartbeat } from '../exec-heartbeat';
-import {
-  DiskFullError,
-  FileNotFoundError,
-  NotADirectoryError,
-  NotAFileError,
-  type SandboxEntry,
-  type WatchEvent,
-} from '../executor/executor';
-import { wakeSandbox } from '../lifecycle';
-import type { E2bDeps } from './deps';
-import type { ProcessRecord, ProcessSubscriber } from './process-table';
-import {
-  connectError,
-  E2bError,
-  envelope,
-  FLAG_END_STREAM,
-  FLAG_MESSAGE,
-  readFirstMessage,
-  verifyEnvdToken,
-} from './protocol';
-import { e2bView } from './view';
-import { WatcherLimitError } from './watcher-table';
-
-/**
- * The envd surface: what the official SDK reaches through its `sandboxUrl`
- * option. One origin serves every sandbox — the SDK attaches an
- * E2b-Sandbox-Id header to every request, so no wildcard DNS is needed.
- * Connect RPC rides the JSON codec (the SDK sets useBinaryFormat: false);
- * files ride plain HTTP. The daemon itself plays the role of envd — there
- * is no agent inside the container.
- */
-
-/**
- * In-container cleanup backstop for e2b-surface processes. Deliberately not
- * the wire deadline: connect-timeout-ms only ever closes the stream — the
- * process lives until it exits, is signaled, or its sandbox dies (E2B's
- * semantics; the native /execCommand keeps its own kill-at-timeout contract).
- */
-const MAX_EXEC_SECONDS = 24 * 60 * 60;
-
-/** The SDK asks for keepalives via this header; we honor it, capped. */
-const MAX_KEEPALIVE_SECONDS = 30;
-
-/** Effectively unbounded route body: the disk quota is the real gate. */
-const UNLIMITED_BODY_BYTES = Number.MAX_SAFE_INTEGER;
-
-interface StartRequest {
-  process?: {
-    cmd?: string;
-    args?: string[];
-    envs?: Record<string, string>;
-    cwd?: string;
-  };
-  stdin?: boolean;
-  pty?: { size?: { cols?: number; rows?: number } };
-}
-
-/** SandboxEntry -> proto3-JSON EntryInfo (int64 size travels as a string). */
-function entryInfoJson(entry: SandboxEntry) {
-  return {
-    name: entry.name,
-    type:
-      entry.type === 'file'
-        ? 'FILE_TYPE_FILE'
-        : entry.type === 'dir'
-          ? 'FILE_TYPE_DIRECTORY'
-          : 'FILE_TYPE_UNSPECIFIED',
-    path: entry.path,
-    size: String(entry.sizeBytes),
-    mode: entry.mode,
-    permissions: permissionString(entry),
-    owner: entry.owner,
-    group: entry.group,
-    modifiedTime: entry.modifiedTime,
-  };
-}
-
-/** Go fs.FileMode style: type char + rwx triplets, display only. */
-function permissionString(entry: SandboxEntry): string {
-  const chars =
-    entry.type === 'dir' ? ['d'] : entry.type === 'file' ? ['-'] : ['?'];
-  for (let shift = 6; shift >= 0; shift -= 3) {
-    const bits = (entry.mode >> shift) & 0o7;
-    chars.push(
-      bits & 4 ? 'r' : '-',
-      bits & 2 ? 'w' : '-',
-      bits & 1 ? 'x' : '-',
-    );
-  }
-  return chars.join('');
-}
-
-/** Executor file errors -> the Connect codes the SDK maps back to its own taxonomy. */
-function toConnectError(error: unknown): unknown {
-  if (error instanceof FileNotFoundError) {
-    return connectError('not_found', error.message);
-  }
-  if (error instanceof NotAFileError || error instanceof NotADirectoryError) {
-    return connectError('invalid_argument', error.message);
-  }
-  if (error instanceof DiskFullError) {
-    return connectError('resource_exhausted', error.message);
-  }
-  return error;
-}
-
-export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
-  app,
-  { config, db, executor, locks, processes, watchers },
-) => {
-  await app.register(multipart, {
-    limits: {
-      // The disk quota is the ceiling; a route-level cap would just be a
-      // second, dishonest one. parts/files stay bounded so a hostile form
-      // cannot spray unlimited entries.
-      fileSize: UNLIMITED_BODY_BYTES,
-      files: 1000,
-      parts: 2000,
-      fieldSize: 1024 * 1024,
-    },
-    // busboy strips filenames to their basename by default (a browser-form
-    // safety net); here the filename IS the destination path — 'notes/x.txt'
-    // must keep its directory. Traversal is not a concern this opens:
-    // resolveSandboxPath clamps '..' at the container's own root anyway.
-    preservePath: true,
-  });
-
-  // Connect streaming requests arrive enveloped; keep the raw bytes.
-  app.addContentTypeParser(
-    'application/connect+json',
-    { parseAs: 'buffer' },
-    (_request, payload, done) => done(null, payload),
-  );
-  // Octet-stream uploads pass through as a stream: nothing materializes.
-  app.addContentTypeParser(
-    'application/octet-stream',
-    (_request, payload, done) => done(null, payload),
-  );
-
-  app.setErrorHandler((error, request, reply) => {
-    if (error instanceof E2bError) {
-      return reply
-        .code(error.statusCode)
-        .send({ code: error.code, message: error.message });
-    }
-    const status = (error as { statusCode?: number }).statusCode ?? 500;
-    if (status >= 500) {
-      request.log.error(error, 'e2b envd request failed');
-    }
-    return reply.code(status).send({
-      code: status === 400 ? 'invalid_argument' : 'internal',
-      message: (error as Error).message,
-    });
-  });
-  app.setNotFoundHandler((request, reply) => {
-    reply.code(404).send({
-      code: 'not_found',
-      message: `route ${request.method} ${request.url} not found`,
-    });
-  });
-
-  /** Every envd request names its sandbox in this header. */
-  function sandboxIdOf(request: FastifyRequest): string {
-    const header = request.headers['e2b-sandbox-id'];
-    const id = Array.isArray(header) ? header[0] : header;
-    if (!id) {
-      throw new E2bError(
-        401,
-        'unauthenticated',
-        'missing E2b-Sandbox-Id header',
-      );
-    }
-    return id;
-  }
-
-  // Auth: X-Access-Token must be the HMAC minted for exactly this sandbox.
-  // /health stays open like real envd's — it is how isRunning() probes.
-  app.addHook('onRequest', async (request) => {
-    if (request.method === 'GET' && request.url.endsWith('/health')) return;
-    const sandboxId = sandboxIdOf(request);
-    const header = request.headers['x-access-token'];
-    const token = Array.isArray(header) ? header[0] : header;
-    if (
-      !token ||
-      !verifyEnvdToken(config.DORMICE_API_TOKEN, sandboxId, token)
-    ) {
-      throw new E2bError(401, 'unauthenticated', 'invalid envd access token');
-    }
-  });
-
-  /**
-   * The protocol-liveness gate. Only a logically-running sandbox serves
-   * envd traffic: paused and dead answer 502, which the SDK triages into
-   * its "sandbox timed out / not running" errors — exactly what talking to
-   * a paused or killed E2B sandbox feels like.
-   */
-  function requireRunningRow(sandboxId: string): SandboxRow {
-    const row = findBySandboxId(db, sandboxId);
-    if (!row) {
-      throw new E2bError(502, 'unavailable', 'sandbox not found');
-    }
-    const state = e2bView(row, new Date());
-    if (state !== 'running') {
-      throw new E2bError(
-        502,
-        'unavailable',
-        state === 'paused' ? 'sandbox is paused' : 'sandbox not found',
-      );
-    }
-    return row;
-  }
-
-  /**
-   * Wake under the key's slot, like every native verb: physical wake-ups
-   * take seconds and must not race the scanner or a release.
-   */
-  async function wakeForUse(sandboxId: string): Promise<SandboxRow> {
-    const before = requireRunningRow(sandboxId);
-    return locks.run(before.userKey, async () => {
-      const fresh = requireRunningRow(sandboxId);
-      const awake = await wakeSandbox(db, executor, fresh);
-      return touch(db, awake.sandboxId);
-    });
-  }
-
-  app.get('/health', async (request, reply) => {
-    // No auth, no wake — a probe must stay cheap and honest. 502 = not
-    // running, the exact signal isRunning() keys on.
-    const header = request.headers['e2b-sandbox-id'];
-    const id = Array.isArray(header) ? header[0] : header;
-    const row = id ? findBySandboxId(db, id) : undefined;
-    if (!row || e2bView(row, new Date()) !== 'running') {
-      return reply
-        .code(502)
-        .send({ code: 'unavailable', message: 'sandbox is not running' });
-    }
-    return reply.code(204).send();
-  });
-
-  // ---- files over plain HTTP ------------------------------------------
-
-  app.get('/files', async (request, reply) => {
-    const query = request.query as { path?: string };
-    if (!query.path) {
-      throw new E2bError(400, 'invalid_argument', 'missing path query');
-    }
-    const row = await wakeForUse(sandboxIdOf(request));
-    const stopHeartbeat = startExecHeartbeat(
-      db,
-      row.sandboxId,
-      row.freezeAfterSeconds,
-    );
-    try {
-      let entry: SandboxEntry;
-      try {
-        entry = await executor.statEntry(row.sandboxId, query.path);
-        if (entry.type !== 'file') {
-          throw new NotAFileError(`not a regular file: ${entry.path}`);
-        }
-      } catch (error) {
-        if (error instanceof FileNotFoundError) {
-          throw new E2bError(404, 'not_found', error.message);
-        }
-        if (error instanceof NotAFileError) {
-          throw new E2bError(400, 'invalid_argument', error.message);
-        }
-        throw error;
-      }
-      // Size first, then stream: the SDK needs content-length (an empty
-      // file is detected by `content-length: 0`), and nothing buffers here.
-      reply.hijack();
-      reply.raw.writeHead(200, {
-        'content-type': 'application/octet-stream',
-        'content-length': String(entry.sizeBytes),
-      });
-      await executor.readFileStream(row.sandboxId, query.path, (chunk) => {
-        if (!reply.raw.write(chunk)) {
-          // Backpressure: the promise pauses the pipe all the way into the
-          // container until the client drains.
-          return new Promise<void>((resolve) =>
-            reply.raw.once('drain', resolve),
-          );
-        }
-      });
-      reply.raw.end();
-    } catch (error) {
-      if (reply.raw.headersSent) {
-        // Mid-stream failure: the body length will not match the announced
-        // content-length — the client sees a broken transfer, honestly.
-        request.log.error(error, 'file download broke mid-stream');
-        reply.raw.destroy();
-        return;
-      }
-      throw error;
-    } finally {
-      stopHeartbeat();
-      try {
-        touch(db, row.sandboxId);
-      } catch {
-        // Released mid-transfer; the transfer's own error tells the story.
-      }
-    }
-  });
-
-  app.post(
-    '/files',
-    { bodyLimit: UNLIMITED_BODY_BYTES },
-    async (request, reply) => {
-      const query = request.query as { path?: string };
-      const row = await wakeForUse(sandboxIdOf(request));
-      const stopHeartbeat = startExecHeartbeat(
-        db,
-        row.sandboxId,
-        row.freezeAfterSeconds,
-      );
-      try {
-        const written: Array<{ name: string; type: 'file'; path: string }> = [];
-        const writeOne = async (
-          path: string,
-          content: NodeJS.ReadableStream,
-        ) => {
-          try {
-            await executor.writeFileStream(row.sandboxId, path, content);
-          } catch (error) {
-            if (error instanceof NotAFileError) {
-              throw new E2bError(400, 'invalid_argument', error.message);
-            }
-            if (error instanceof DiskFullError) {
-              throw new E2bError(507, 'not_enough_space', error.message);
-            }
-            throw error;
-          }
-          const resolved = resolveSandboxPath(path);
-          written.push({
-            name: resolved.slice(resolved.lastIndexOf('/') + 1),
-            type: 'file',
-            path: resolved,
-          });
-        };
-
-        if (request.isMultipart()) {
-          // The SDK's default upload shape: one part per file, field name
-          // `file`, the part's filename carrying the destination path.
-          for await (const part of request.parts()) {
-            if (part.type !== 'file') continue;
-            const destination = part.filename || query.path;
-            if (!destination) {
-              throw new E2bError(
-                400,
-                'invalid_argument',
-                'multipart file part has no filename and no ?path= fallback',
-              );
-            }
-            await writeOne(destination, part.file);
-          }
-        } else {
-          // Octet-stream (the SDK's streaming/gzip shape): path in the query.
-          if (!query.path) {
-            throw new E2bError(400, 'invalid_argument', 'missing path query');
-          }
-          await writeOne(query.path, request.body as NodeJS.ReadableStream);
-        }
-        return await reply.code(200).send(written);
-      } finally {
-        stopHeartbeat();
-        try {
-          touch(db, row.sandboxId);
-        } catch {
-          // Released mid-upload; the upload's own result tells the story.
-        }
-      }
-    },
-  );
-
-  // ---- filesystem service (Connect RPC, unary, JSON codec) ------------
-
-  /** Unary filesystem RPCs run entirely in the key's slot, like native file verbs. */
-  async function inSlot<T>(
-    sandboxId: string,
-    work: (row: SandboxRow) => Promise<T>,
-  ): Promise<T> {
-    const before = requireRunningRow(sandboxId);
-    return locks.run(before.userKey, async () => {
-      const fresh = requireRunningRow(sandboxId);
-      const awake = await wakeSandbox(db, executor, fresh);
-      const row = touch(db, awake.sandboxId);
-      try {
-        return await work(row);
-      } catch (error) {
-        throw toConnectError(error);
-      }
-    });
-  }
-
-  app.post('/filesystem.Filesystem/Stat', async (request) => {
-    const body = request.body as { path?: string };
-    if (!body.path) throw connectError('invalid_argument', 'missing path');
-    const entry = await inSlot(sandboxIdOf(request), (row) =>
-      executor.statEntry(row.sandboxId, body.path as string),
-    );
-    return { entry: entryInfoJson(entry) };
-  });
-
-  app.post('/filesystem.Filesystem/ListDir', async (request) => {
-    const body = request.body as { path?: string; depth?: number };
-    if (!body.path) throw connectError('invalid_argument', 'missing path');
-    const depth = body.depth ?? 1;
-    if (depth < 1) {
-      throw connectError('invalid_argument', 'depth should be at least one');
-    }
-    const entries = await inSlot(sandboxIdOf(request), (row) =>
-      executor.listDir(row.sandboxId, body.path as string, depth),
-    );
-    return { entries: entries.map(entryInfoJson) };
-  });
-
-  app.post('/filesystem.Filesystem/MakeDir', async (request) => {
-    const body = request.body as { path?: string };
-    if (!body.path) throw connectError('invalid_argument', 'missing path');
-    const entry = await inSlot(sandboxIdOf(request), async (row) => {
-      const created = await executor.makeDir(
-        row.sandboxId,
-        body.path as string,
-      );
-      if (!created) {
-        // The SDK reads already_exists as makeDir() === false.
-        throw connectError(
-          'already_exists',
-          `already exists: ${resolveSandboxPath(body.path as string)}`,
-        );
-      }
-      return executor.statEntry(row.sandboxId, body.path as string);
-    });
-    return { entry: entryInfoJson(entry) };
-  });
-
-  app.post('/filesystem.Filesystem/Move', async (request) => {
-    const body = request.body as { source?: string; destination?: string };
-    if (!body.source || !body.destination) {
-      throw connectError('invalid_argument', 'missing source or destination');
-    }
-    const entry = await inSlot(sandboxIdOf(request), (row) =>
-      executor.move(
-        row.sandboxId,
-        body.source as string,
-        body.destination as string,
-      ),
-    );
-    return { entry: entryInfoJson(entry) };
-  });
-
-  app.post('/filesystem.Filesystem/Remove', async (request) => {
-    const body = request.body as { path?: string };
-    if (!body.path) throw connectError('invalid_argument', 'missing path');
-    await inSlot(sandboxIdOf(request), (row) =>
-      executor.remove(row.sandboxId, body.path as string),
-    );
-    return {};
-  });
-
-  // ---- directory watching ----------------------------------------------
-
-  /** Executor event types -> the proto enum names proto3-JSON speaks. */
-  const WATCH_EVENT_WIRE: Record<WatchEvent['type'], string> = {
-    create: 'EVENT_TYPE_CREATE',
-    write: 'EVENT_TYPE_WRITE',
-    remove: 'EVENT_TYPE_REMOVE',
-    rename: 'EVENT_TYPE_RENAME',
-    chmod: 'EVENT_TYPE_CHMOD',
-  };
-
-  /**
-   * Path validation errors travel differently on the two watch surfaces
-   * (in-stream frame vs unary throw), but the codes and messages are one
-   * decision: not_found for a missing path, invalid_argument for a file —
-   * real envd's answers, with this codebase's own wording.
-   */
-  function watchStartError(error: unknown): { code: string; message: string } {
-    if (error instanceof FileNotFoundError) {
-      return { code: 'not_found', message: error.message };
-    }
-    if (error instanceof NotADirectoryError) {
-      return { code: 'invalid_argument', message: error.message };
-    }
-    return {
-      code: 'internal',
-      message: error instanceof Error ? error.message : String(error),
-    };
-  }
-
-  /**
-   * The streaming watch: unlike a process stream, the watcher IS the stream
-   * — real envd runs the whole watch inside one handler, so the deadline,
-   * the client hanging up, or any ending stops the watcher itself (the SDK's
-   * WatchHandle.stop() is exactly an abort of this request). Frames are the
-   * WatchDirResponse oneof at the top level: {start:{}}, {filesystem:{...}},
-   * {keepalive:{}} — no `event` wrapper, unlike the process face.
-   *
-   * Deliberately no exec heartbeat: watching is passive observation, so an
-   * attached watch lets the idle scanner freeze the sandbox. No events can
-   * be missed frozen — the disk only changes from inside, and everything
-   * that reaches inside wakes the sandbox first.
-   */
-  app.post('/filesystem.Filesystem/WatchDir', async (request, reply) => {
-    const message = readFirstMessage(request.body as Buffer) as {
-      path?: string;
-      recursive?: boolean;
-    };
-    if (!message.path) {
-      return streamError(reply, 'invalid_argument', 'missing path');
-    }
-    const row = await wakeForStream(request, reply);
-    if (!row) return;
-
-    const write = rawWriter(reply);
-    // Events hold at this gate until the start frame is on the wire — the
-    // SDK requires the stream to open with it, and a change made in the
-    // sliver between watcher start and hijack would otherwise race ahead.
-    let openGate = () => {};
-    const opened = new Promise<void>((resolve) => {
-      openGate = resolve;
-    });
-    let settleEnd: (error: Error) => void = () => {};
-    const ended = new Promise<Error>((resolve) => {
-      settleEnd = resolve;
-    });
-    let watcher: Awaited<ReturnType<typeof executor.watchDir>>;
-    try {
-      watcher = await executor.watchDir(row.sandboxId, {
-        path: message.path,
-        recursive: message.recursive === true,
-        onEvent: async (event) => {
-          await opened;
-          await write(
-            envelope(FLAG_MESSAGE, {
-              filesystem: {
-                name: event.name,
-                type: WATCH_EVENT_WIRE[event.type],
-              },
-            }),
-          );
-        },
-        onEnd: (error) =>
-          settleEnd(error ?? new Error('watcher ended unexpectedly')),
-      });
-    } catch (error) {
-      const { code, message: text } = watchStartError(error);
-      return streamError(reply, code, text);
-    }
-
-    reply.hijack();
-    reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
-    await write(envelope(FLAG_MESSAGE, { start: {} }));
-    openGate();
-
-    const keepaliveSeconds = Math.min(
-      Number(request.headers['keepalive-ping-interval']) ||
-        MAX_KEEPALIVE_SECONDS,
-      MAX_KEEPALIVE_SECONDS,
-    );
-    const keepalive = setInterval(() => {
-      reply.raw.write(envelope(FLAG_MESSAGE, { keepalive: {} }));
-    }, keepaliveSeconds * 1000);
-    const deadlineMs = wireDeadlineMs(request);
-    let deadlineTimer: NodeJS.Timeout | undefined;
-    const deadline = new Promise<'deadline'>((resolve) => {
-      deadlineTimer = setTimeout(() => resolve('deadline'), deadlineMs);
-    });
-    const clientGone = new Promise<'gone'>((resolve) => {
-      reply.raw.once('close', () => resolve('gone'));
-    });
-    try {
-      const outcome = await Promise.race([ended, deadline, clientGone]);
-      if (outcome === 'deadline') {
-        // The SDK's watch default is 60s: a blown deadline is the normal
-        // ending of most watches, answered like real envd's ctx expiry.
-        await write(
-          envelope(FLAG_END_STREAM, {
-            error: {
-              code: 'deadline_exceeded',
-              message: `watch timed out after ${deadlineMs}ms`,
-            },
-          }),
-        );
-      } else if (outcome instanceof Error) {
-        await write(
-          envelope(FLAG_END_STREAM, {
-            error: { code: 'internal', message: outcome.message },
-          }),
-        );
-      }
-    } finally {
-      clearInterval(keepalive);
-      clearTimeout(deadlineTimer);
-      try {
-        await watcher.stop();
-      } catch {
-        // The sandbox died under the watcher; its ending already spoke.
-      }
-      reply.raw.end();
-    }
-  });
-
-  // The polling trio — what the sync SDKs use instead of the WatchDir
-  // stream. Same watcher engine, parked in the daemon-memory watcher table.
-
-  app.post('/filesystem.Filesystem/CreateWatcher', async (request) => {
-    const body = request.body as { path?: string; recursive?: boolean };
-    if (!body.path) throw connectError('invalid_argument', 'missing path');
-    const row = await wakeForUse(sandboxIdOf(request));
-    try {
-      const watcherId = await watchers.create({
-        executor,
-        sandboxId: row.sandboxId,
-        path: body.path,
-        recursive: body.recursive === true,
-      });
-      return { watcherId };
-    } catch (error) {
-      if (error instanceof WatcherLimitError) {
-        throw connectError('resource_exhausted', error.message);
-      }
-      const { code, message } = watchStartError(error);
-      throw connectError(code, message);
-    }
-  });
-
-  app.post('/filesystem.Filesystem/GetWatcherEvents', async (request) => {
-    const body = request.body as { watcherId?: string };
-    if (!body.watcherId) {
-      throw connectError('invalid_argument', 'missing watcher id');
-    }
-    // No wake: this reads daemon memory. A frozen sandbox has no new events
-    // to report anyway — the disk cannot change while it is frozen.
-    const row = requireRunningRow(sandboxIdOf(request));
-    const events = watchers.drain(row.sandboxId, body.watcherId);
-    if (events === undefined) {
-      throw connectError(
-        'not_found',
-        `watcher with id ${body.watcherId} not found`,
-      );
-    }
-    return {
-      events: events.map((event) => ({
-        name: event.name,
-        type: WATCH_EVENT_WIRE[event.type],
-      })),
-    };
-  });
-
-  app.post('/filesystem.Filesystem/RemoveWatcher', async (request) => {
-    const body = request.body as { watcherId?: string };
-    if (!body.watcherId) {
-      throw connectError('invalid_argument', 'missing watcher id');
-    }
-    // Wakes: stopping the in-container inotifywait needs the container up.
-    const row = await wakeForUse(sandboxIdOf(request));
-    const removed = await watchers.remove(row.sandboxId, body.watcherId);
-    if (!removed) {
-      throw connectError(
-        'not_found',
-        `watcher with id ${body.watcherId} not found`,
-      );
-    }
-    return {};
-  });
-
-  // ---- process service -------------------------------------------------
-
-  /**
-   * The wire face of one attached stream, shared by Start and Connect: data
-   * frames with backpressure, and the end frames written by the process's
-   * finalize. `done` settles once the ending — end event or in-stream error
-   * — is fully on the wire. The write closure touches reply.raw lazily: it
-   * is never called before the caller has hijacked (the executor emits
-   * nothing before execStream resolves, and subscription follows the
-   * hijack synchronously).
-   */
-  function streamSubscriber(write: (buf: Buffer) => Promise<void>): {
-    subscriber: ProcessSubscriber;
-    done: Promise<'ended'>;
-  } {
-    let resolveDone!: (outcome: 'ended') => void;
-    const done = new Promise<'ended'>((resolve) => {
-      resolveDone = resolve;
-    });
-    const subscriber: ProcessSubscriber = {
-      onOutput: (channel, chunk) =>
-        write(
-          envelope(FLAG_MESSAGE, {
-            event: { data: { [channel]: chunk.toString('base64') } },
-          }),
-        ),
-      onEnd: (end) => {
-        const frames =
-          end.kind === 'exit'
-            ? [
-                envelope(FLAG_MESSAGE, {
-                  event: {
-                    end: {
-                      exitCode: end.exitCode,
-                      exited: true,
-                      status: end.exitCode === 137 ? 'killed' : 'exited',
-                      ...(end.exitCode === 137
-                        ? { error: 'command killed (exit 137)' }
-                        : {}),
-                    },
-                  },
-                }),
-                envelope(FLAG_END_STREAM, {}),
-              ]
-            : [
-                // The container died under the process (a kill, a release):
-                // an in-stream internal error, which the SDK triages via its
-                // health check — the same feel as a killed E2B sandbox.
-                envelope(FLAG_END_STREAM, {
-                  error: { code: 'internal', message: end.message },
-                }),
-              ];
-        void (async () => {
-          for (const frame of frames) await write(frame);
-          resolveDone('ended');
-        })();
-      },
-    };
-    return { subscriber, done };
-  }
-
-  /** The SDK's connect-timeout-ms header, absent meaning "effectively never". */
-  function wireDeadlineMs(request: FastifyRequest): number {
-    const headerMs = Number(request.headers['connect-timeout-ms']);
-    return Number.isFinite(headerMs) && headerMs > 0
-      ? headerMs
-      : MAX_EXEC_SECONDS * 1000;
-  }
-
-  /**
-   * The attached half of a process stream: keepalives, the wire deadline,
-   * the client hanging up. The deadline and the hang-up both merely detach
-   * this stream — the process keeps running (real envd's semantics: nothing
-   * kills a process except its own exit, SendSignal, or the sandbox dying);
-   * the exec heartbeat lives exactly as long as someone is attached, so a
-   * background process nobody watches lets the sandbox freeze honestly.
-   */
-  async function pumpProcessStream(args: {
-    request: FastifyRequest;
-    reply: FastifyReply;
-    row: SandboxRow;
-    write: (buf: Buffer) => Promise<void>;
-    done: Promise<'ended'>;
-    detach: () => void;
-  }): Promise<void> {
-    const { request, reply, row, write, done, detach } = args;
-    const stopHeartbeat = startExecHeartbeat(
-      db,
-      row.sandboxId,
-      row.freezeAfterSeconds,
-    );
-    // Keepalive events on the interval the SDK asked for — what keeps
-    // proxies from cutting a silent long command.
-    const keepaliveSeconds = Math.min(
-      Number(request.headers['keepalive-ping-interval']) ||
-        MAX_KEEPALIVE_SECONDS,
-      MAX_KEEPALIVE_SECONDS,
-    );
-    const keepalive = setInterval(() => {
-      reply.raw.write(envelope(FLAG_MESSAGE, { event: { keepalive: {} } }));
-    }, keepaliveSeconds * 1000);
-    const deadlineMs = wireDeadlineMs(request);
-    let deadlineTimer: NodeJS.Timeout | undefined;
-    const deadline = new Promise<'deadline'>((resolve) => {
-      deadlineTimer = setTimeout(() => resolve('deadline'), deadlineMs);
-    });
-    const clientGone = new Promise<'gone'>((resolve) => {
-      reply.raw.once('close', () => resolve('gone'));
-    });
-    try {
-      const outcome = await Promise.race([done, deadline, clientGone]);
-      if (outcome === 'deadline') {
-        // Real envd answers a blown deadline with the Connect error, not an
-        // end event; the SDK turns it into its TimeoutError. The process
-        // stays alive — only this stream ends.
-        await write(
-          envelope(FLAG_END_STREAM, {
-            error: {
-              code: 'deadline_exceeded',
-              message: `command timed out after ${deadlineMs}ms`,
-            },
-          }),
-        );
-      }
-    } finally {
-      clearInterval(keepalive);
-      clearTimeout(deadlineTimer);
-      detach();
-      stopHeartbeat();
-      try {
-        // Watching the command was the activity: the idle countdown starts
-        // when the stream detaches, not when it attached.
-        touch(db, row.sandboxId);
-      } catch {
-        // Released mid-stream; the stream's own ending tells the story.
-      }
-      reply.raw.end();
-    }
-  }
-
-  /** Wake-for-use with streaming-dialect errors: streamError, not thrown JSON. */
-  async function wakeForStream(
-    request: FastifyRequest,
-    reply: FastifyReply,
-  ): Promise<SandboxRow | undefined> {
-    try {
-      return await wakeForUse(sandboxIdOf(request));
-    } catch (error) {
-      if (error instanceof E2bError) {
-        // Everything this surface throws carries a Connect string code; a
-        // numeric one would be a control-plane error that leaked — treat it
-        // as the sandbox being unreachable.
-        streamError(
-          reply,
-          typeof error.code === 'string' ? error.code : 'unavailable',
-          error.message,
-        );
-        return undefined;
-      }
-      throw error;
-    }
-  }
-
-  /** The backpressured raw write every process stream shares. */
-  function rawWriter(reply: FastifyReply): (buf: Buffer) => Promise<void> {
-    return (buf) =>
-      new Promise<void>((resolve) => {
-        if (!reply.raw.write(buf)) reply.raw.once('drain', resolve);
-        else resolve();
-      });
-  }
-
-  app.post('/process.Process/List', async (request) => {
-    // Read-only: no wake — looking at the table must not thaw a sandbox.
-    const row = requireRunningRow(sandboxIdOf(request));
-    return {
-      processes: processes.list(row.sandboxId).map((record) => ({
-        pid: record.pid,
-        // config is echoed verbatim and always complete: the SDK
-        // dereferences processes[].config.args unconditionally.
-        config: {
-          cmd: record.config.cmd,
-          args: record.config.args,
-          envs: record.config.envs,
-          ...(record.config.cwd ? { cwd: record.config.cwd } : {}),
-        },
-      })),
-    };
-  });
-
-  app.post('/process.Process/Start', async (request, reply) => {
-    const message = readFirstMessage(request.body as Buffer) as StartRequest;
-    const proc = message.process ?? {};
-    const args = proc.args ?? [];
-    // A pty block makes this a terminal session (the SDK sends
-    // /bin/bash -i -l; the executor hardcodes that shape anyway). Sizes
-    // default defensively — a 0x0 terminal misbehaves quietly.
-    const ptySize = message.pty
-      ? {
-          cols: message.pty.size?.cols || 80,
-          rows: message.pty.size?.rows || 24,
-        }
-      : undefined;
-    // Without a pty, the SDK always sends /bin/bash [-l] -c <command>;
-    // anything else is a shape this layer does not speak yet.
-    let command: string | undefined;
-    let loginShell = false;
-    if (args.length === 3 && args[0] === '-l' && args[1] === '-c') {
-      command = args[2];
-      loginShell = true;
-    } else if (args.length === 2 && args[0] === '-c') {
-      command = args[1];
-    }
-    if (!proc.cmd?.endsWith('bash') || (!ptySize && command === undefined)) {
-      return streamError(
-        reply,
-        'invalid_argument',
-        ptySize
-          ? 'only bash PTY sessions are supported'
-          : 'only shell commands are supported: expected /bin/bash [-l] -c <command>',
-      );
-    }
-    const row = await wakeForStream(request, reply);
-    if (!row) return;
-
-    const sandboxEnvs: Record<string, string> = row.envs
-      ? JSON.parse(row.envs)
-      : {};
-    const write = rawWriter(reply);
-    const { subscriber, done } = streamSubscriber(write);
-    let record: ProcessRecord;
-    try {
-      record = await processes.start({
-        executor,
-        sandboxId: row.sandboxId,
-        options: {
-          command,
-          loginShell,
-          pty: ptySize,
-          // The in-container timeout is a pathological-cleanup backstop
-          // only; the wire deadline lives in pumpProcessStream and never
-          // kills the process — E2B's semantics, adopted deliberately.
-          timeoutSeconds: MAX_EXEC_SECONDS,
-          stdin: message.stdin === true,
-          cwd: proc.cwd,
-          // Sandbox-level envs underneath, per-command envs on top.
-          env: { ...sandboxEnvs, ...(proc.envs ?? {}) },
-        },
-        config: {
-          cmd: proc.cmd,
-          args,
-          envs: proc.envs ?? {},
-          cwd: proc.cwd,
-        },
-        subscriber,
-      });
-    } catch (error) {
-      // Start order is deliberate: the start frame goes out only for a
-      // process that actually started.
-      const messageText =
-        error instanceof Error ? error.message : String(error);
-      return streamError(reply, 'internal', messageText);
-    }
-    reply.hijack();
-    reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
-    await write(
-      envelope(FLAG_MESSAGE, { event: { start: { pid: record.pid } } }),
-    );
-    await pumpProcessStream({
-      request,
-      reply,
-      row,
-      write,
-      done,
-      detach: () => processes.unsubscribe(record.pid, subscriber),
-    });
-  });
-
-  app.post('/process.Process/Connect', async (request, reply) => {
-    const message = readFirstMessage(request.body as Buffer) as {
-      process?: { pid?: number };
-    };
-    const pid = message.process?.pid;
-    if (typeof pid !== 'number') {
-      return streamError(reply, 'invalid_argument', 'missing process pid');
-    }
-    const row = await wakeForStream(request, reply);
-    if (!row) return;
-    const record = processes.get(row.sandboxId, pid);
-    if (!record) {
-      return streamError(reply, 'not_found', `process not found: ${pid}`);
-    }
-    const write = rawWriter(reply);
-    const { subscriber, done } = streamSubscriber(write);
-    reply.hijack();
-    reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
-    // The SDK requires a Connect stream to open with a start frame, exactly
-    // like Start's. Initiated before subscribing so no data frame can slip
-    // ahead of it (raw writes keep call order). No replay of past output —
-    // real envd's semantics.
-    const startFrame = write(
-      envelope(FLAG_MESSAGE, { event: { start: { pid: record.pid } } }),
-    );
-    const unsubscribe = processes.subscribe(pid, subscriber);
-    await startFrame;
-    if (!unsubscribe) {
-      // Finished between get and subscribe: report it rather than hold a
-      // stream that would never end.
-      await write(
-        envelope(FLAG_END_STREAM, {
-          error: { code: 'not_found', message: `process not found: ${pid}` },
-        }),
-      );
-      reply.raw.end();
-      return;
-    }
-    await pumpProcessStream({
-      request,
-      reply,
-      row,
-      write,
-      done,
-      detach: unsubscribe,
-    });
-  });
-
-  /** {process:{pid}} — the proto3-JSON flattening of the selector oneof. */
-  function requirePid(body: unknown): number {
-    const pid = (body as { process?: { pid?: unknown } })?.process?.pid;
-    if (typeof pid !== 'number') {
-      throw connectError('invalid_argument', 'missing process pid');
-    }
-    return pid;
-  }
-
-  /** A living process for this sandbox, or the not_found the SDK expects. */
-  function requireProcess(sandboxId: string, pid: number): ProcessRecord {
-    const record = processes.get(sandboxId, pid);
-    if (!record) {
-      throw connectError('not_found', `process not found: ${pid}`);
-    }
-    return record;
-  }
-
-  app.post('/process.Process/SendInput', async (request) => {
-    const body = request.body as {
-      process?: { pid?: number };
-      input?: { stdin?: string; pty?: string };
-    };
-    const pid = requirePid(body);
-    const row = await wakeForUse(sandboxIdOf(request));
-    const record = requireProcess(row.sandboxId, pid);
-    const stdinB64 = body.input?.stdin;
-    const ptyB64 = body.input?.pty;
-    if (typeof stdinB64 !== 'string' && typeof ptyB64 !== 'string') {
-      throw connectError('invalid_argument', 'missing input');
-    }
-    // Channel and promise must match: stdin input needs a stdin:true start,
-    // pty input needs a PTY session — a mismatch is the caller's confusion.
-    if (typeof stdinB64 === 'string' && !record.stdin) {
-      throw connectError(
-        'invalid_argument',
-        'process was started without stdin',
-      );
-    }
-    if (typeof ptyB64 === 'string' && !record.pty) {
-      throw connectError('invalid_argument', 'process has no PTY');
-    }
-    const data = Buffer.from((stdinB64 ?? ptyB64) as string, 'base64');
-    try {
-      await record.handle.sendStdin(data);
-    } catch (error) {
-      throw connectError(
-        'invalid_argument',
-        error instanceof Error ? error.message : String(error),
-      );
-    }
-    return {};
-  });
-
-  app.post('/process.Process/CloseStdin', async (request) => {
-    const pid = requirePid(request.body);
-    const row = await wakeForUse(sandboxIdOf(request));
-    const record = requireProcess(row.sandboxId, pid);
-    if (!record.stdin) {
-      throw connectError(
-        'invalid_argument',
-        'process was started without stdin',
-      );
-    }
-    try {
-      await record.handle.closeStdin();
-    } catch (error) {
-      throw connectError(
-        'invalid_argument',
-        error instanceof Error ? error.message : String(error),
-      );
-    }
-    return {};
-  });
-
-  app.post('/process.Process/SendSignal', async (request) => {
-    const body = request.body as {
-      process?: { pid?: number };
-      signal?: string | number;
-    };
-    const pid = requirePid(body);
-    // proto3-JSON enums travel as their names; a numeric fallback costs
-    // nothing and covers a client that emits raw values.
-    const sig =
-      body.signal === 'SIGNAL_SIGKILL' || body.signal === 9
-        ? ('SIGKILL' as const)
-        : body.signal === 'SIGNAL_SIGTERM' || body.signal === 15
-          ? ('SIGTERM' as const)
-          : undefined;
-    if (!sig) {
-      throw connectError(
-        'invalid_argument',
-        `unsupported signal: ${String(body.signal)} — only SIGKILL and SIGTERM are supported`,
-      );
-    }
-    const row = await wakeForUse(sandboxIdOf(request));
-    const record = requireProcess(row.sandboxId, pid);
-    try {
-      await record.handle.signal(sig);
-    } catch {
-      // The process ended between lookup and signal: protocol-wise it does
-      // not exist — the SDK turns not_found into kill() === false.
-      throw connectError('not_found', `process not found: ${pid}`);
-    }
-    return {};
-  });
-
-  app.post('/process.Process/Update', async (request) => {
-    const body = request.body as {
-      process?: { pid?: number };
-      pty?: { size?: { cols?: number; rows?: number } };
-    };
-    const pid = requirePid(body);
-    const row = await wakeForUse(sandboxIdOf(request));
-    const record = requireProcess(row.sandboxId, pid);
-    if (!record.pty) {
-      throw connectError('invalid_argument', 'process has no PTY');
-    }
-    const size = body.pty?.size;
-    if (
-      typeof size?.cols !== 'number' ||
-      typeof size?.rows !== 'number' ||
-      size.cols <= 0 ||
-      size.rows <= 0
-    ) {
-      throw connectError('invalid_argument', 'missing pty size');
-    }
-    try {
-      await record.handle.resizePty({ cols: size.cols, rows: size.rows });
-    } catch (error) {
-      throw connectError(
-        'invalid_argument',
-        error instanceof Error ? error.message : String(error),
-      );
-    }
-    return {};
-  });
-
-  /** Streaming endpoints answer errors inside the stream: 200 + end-stream frame. */
-  function streamError(
-    reply: FastifyReply,
-    code: string,
-    message: string,
-  ): void {
-    reply.hijack();
-    reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
-    reply.raw.write(envelope(FLAG_END_STREAM, { error: { code, message } }));
-    reply.raw.end();
-  }
-
-  // ---- honest unimplemented stubs --------------------------------------
-
-  const unimplemented: Array<[string, string]> = [
-    [
-      '/process.Process/StreamInput',
-      'streamed stdin is not supported — the SDK sends stdin via SendInput',
-    ],
-  ];
-  for (const [path, hint] of unimplemented) {
-    app.post(path, async () => {
-      throw connectError('unimplemented', hint);
-    });
-  }
-};
diff --git a/packages/server/src/e2b/envd/files.ts b/packages/server/src/e2b/envd/files.ts
new file mode 100644
index 0000000..4ee20a4
--- /dev/null
+++ b/packages/server/src/e2b/envd/files.ts
@@ -0,0 +1,153 @@
+import { resolveSandboxPath } from '@dormice/shared';
+import type { FastifyInstance } from 'fastify';
+import { touch } from '../../db/ledger';
+import { startExecHeartbeat } from '../../exec-heartbeat';
+import {
+  DiskFullError,
+  FileNotFoundError,
+  NotAFileError,
+  type SandboxEntry,
+} from '../../executor/executor';
+import { E2bError } from '../protocol';
+import { type EnvdContext, sandboxIdOf, UNLIMITED_BODY_BYTES } from './shared';
+
+/** The plain-HTTP file faces: GET /files streams out, POST /files streams in. */
+export function registerFileRoutes(
+  app: FastifyInstance,
+  ctx: EnvdContext,
+): void {
+  const { db, executor } = ctx;
+
+  app.get('/files', async (request, reply) => {
+    const query = request.query as { path?: string };
+    if (!query.path) {
+      throw new E2bError(400, 'invalid_argument', 'missing path query');
+    }
+    const row = await ctx.wakeForUse(sandboxIdOf(request));
+    const stopHeartbeat = startExecHeartbeat(
+      db,
+      row.sandboxId,
+      row.freezeAfterSeconds,
+    );
+    try {
+      let entry: SandboxEntry;
+      try {
+        entry = await executor.statEntry(row.sandboxId, query.path);
+        if (entry.type !== 'file') {
+          throw new NotAFileError(`not a regular file: ${entry.path}`);
+        }
+      } catch (error) {
+        if (error instanceof FileNotFoundError) {
+          throw new E2bError(404, 'not_found', error.message);
+        }
+        if (error instanceof NotAFileError) {
+          throw new E2bError(400, 'invalid_argument', error.message);
+        }
+        throw error;
+      }
+      // Size first, then stream: the SDK needs content-length (an empty
+      // file is detected by `content-length: 0`), and nothing buffers here.
+      reply.hijack();
+      reply.raw.writeHead(200, {
+        'content-type': 'application/octet-stream',
+        'content-length': String(entry.sizeBytes),
+      });
+      await executor.readFileStream(row.sandboxId, query.path, (chunk) => {
+        if (!reply.raw.write(chunk)) {
+          // Backpressure: the promise pauses the pipe all the way into the
+          // container until the client drains.
+          return new Promise<void>((resolve) =>
+            reply.raw.once('drain', resolve),
+          );
+        }
+      });
+      reply.raw.end();
+    } catch (error) {
+      if (reply.raw.headersSent) {
+        // Mid-stream failure: the body length will not match the announced
+        // content-length — the client sees a broken transfer, honestly.
+        request.log.error(error, 'file download broke mid-stream');
+        reply.raw.destroy();
+        return;
+      }
+      throw error;
+    } finally {
+      stopHeartbeat();
+      try {
+        touch(db, row.sandboxId);
+      } catch {
+        // Released mid-transfer; the transfer's own error tells the story.
+      }
+    }
+  });
+
+  app.post(
+    '/files',
+    { bodyLimit: UNLIMITED_BODY_BYTES },
+    async (request, reply) => {
+      const query = request.query as { path?: string };
+      const row = await ctx.wakeForUse(sandboxIdOf(request));
+      const stopHeartbeat = startExecHeartbeat(
+        db,
+        row.sandboxId,
+        row.freezeAfterSeconds,
+      );
+      try {
+        const written: Array<{ name: string; type: 'file'; path: string }> = [];
+        const writeOne = async (
+          path: string,
+          content: NodeJS.ReadableStream,
+        ) => {
+          try {
+            await executor.writeFileStream(row.sandboxId, path, content);
+          } catch (error) {
+            if (error instanceof NotAFileError) {
+              throw new E2bError(400, 'invalid_argument', error.message);
+            }
+            if (error instanceof DiskFullError) {
+              throw new E2bError(507, 'not_enough_space', error.message);
+            }
+            throw error;
+          }
+          const resolved = resolveSandboxPath(path);
+          written.push({
+            name: resolved.slice(resolved.lastIndexOf('/') + 1),
+            type: 'file',
+            path: resolved,
+          });
+        };
+
+        if (request.isMultipart()) {
+          // The SDK's default upload shape: one part per file, field name
+          // `file`, the part's filename carrying the destination path.
+          for await (const part of request.parts()) {
+            if (part.type !== 'file') continue;
+            const destination = part.filename || query.path;
+            if (!destination) {
+              throw new E2bError(
+                400,
+                'invalid_argument',
+                'multipart file part has no filename and no ?path= fallback',
+              );
+            }
+            await writeOne(destination, part.file);
+          }
+        } else {
+          // Octet-stream (the SDK's streaming/gzip shape): path in the query.
+          if (!query.path) {
+            throw new E2bError(400, 'invalid_argument', 'missing path query');
+          }
+          await writeOne(query.path, request.body as NodeJS.ReadableStream);
+        }
+        return await reply.code(200).send(written);
+      } finally {
+        stopHeartbeat();
+        try {
+          touch(db, row.sandboxId);
+        } catch {
+          // Released mid-upload; the upload's own result tells the story.
+        }
+      }
+    },
+  );
+}
diff --git a/packages/server/src/e2b/envd/filesystem.ts b/packages/server/src/e2b/envd/filesystem.ts
new file mode 100644
index 0000000..3057882
--- /dev/null
+++ b/packages/server/src/e2b/envd/filesystem.ts
@@ -0,0 +1,114 @@
+import { resolveSandboxPath } from '@dormice/shared';
+import type { FastifyInstance } from 'fastify';
+import type { SandboxEntry } from '../../executor/executor';
+import { connectError } from '../protocol';
+import { type EnvdContext, sandboxIdOf } from './shared';
+
+/** SandboxEntry -> proto3-JSON EntryInfo (int64 size travels as a string). */
+export function entryInfoJson(entry: SandboxEntry) {
+  return {
+    name: entry.name,
+    type:
+      entry.type === 'file'
+        ? 'FILE_TYPE_FILE'
+        : entry.type === 'dir'
+          ? 'FILE_TYPE_DIRECTORY'
+          : 'FILE_TYPE_UNSPECIFIED',
+    path: entry.path,
+    size: String(entry.sizeBytes),
+    mode: entry.mode,
+    permissions: permissionString(entry),
+    owner: entry.owner,
+    group: entry.group,
+    modifiedTime: entry.modifiedTime,
+  };
+}
+
+/** Go fs.FileMode style: type char + rwx triplets, display only. */
+function permissionString(entry: SandboxEntry): string {
+  const chars =
+    entry.type === 'dir' ? ['d'] : entry.type === 'file' ? ['-'] : ['?'];
+  for (let shift = 6; shift >= 0; shift -= 3) {
+    const bits = (entry.mode >> shift) & 0o7;
+    chars.push(
+      bits & 4 ? 'r' : '-',
+      bits & 2 ? 'w' : '-',
+      bits & 1 ? 'x' : '-',
+    );
+  }
+  return chars.join('');
+}
+
+/** The unary half of the Filesystem service: Connect RPC, JSON codec. */
+export function registerFilesystemRoutes(
+  app: FastifyInstance,
+  ctx: EnvdContext,
+): void {
+  const { executor } = ctx;
+
+  app.post('/filesystem.Filesystem/Stat', async (request) => {
+    const body = request.body as { path?: string };
+    if (!body.path) throw connectError('invalid_argument', 'missing path');
+    const entry = await ctx.inSlot(sandboxIdOf(request), (row) =>
+      executor.statEntry(row.sandboxId, body.path as string),
+    );
+    return { entry: entryInfoJson(entry) };
+  });
+
+  app.post('/filesystem.Filesystem/ListDir', async (request) => {
+    const body = request.body as { path?: string; depth?: number };
+    if (!body.path) throw connectError('invalid_argument', 'missing path');
+    const depth = body.depth ?? 1;
+    if (depth < 1) {
+      throw connectError('invalid_argument', 'depth should be at least one');
+    }
+    const entries = await ctx.inSlot(sandboxIdOf(request), (row) =>
+      executor.listDir(row.sandboxId, body.path as string, depth),
+    );
+    return { entries: entries.map(entryInfoJson) };
+  });
+
+  app.post('/filesystem.Filesystem/MakeDir', async (request) => {
+    const body = request.body as { path?: string };
+    if (!body.path) throw connectError('invalid_argument', 'missing path');
+    const entry = await ctx.inSlot(sandboxIdOf(request), async (row) => {
+      const created = await executor.makeDir(
+        row.sandboxId,
+        body.path as string,
+      );
+      if (!created) {
+        // The SDK reads already_exists as makeDir() === false.
+        throw connectError(
+          'already_exists',
+          `already exists: ${resolveSandboxPath(body.path as string)}`,
+        );
+      }
+      return executor.statEntry(row.sandboxId, body.path as string);
+    });
+    return { entry: entryInfoJson(entry) };
+  });
+
+  app.post('/filesystem.Filesystem/Move', async (request) => {
+    const body = request.body as { source?: string; destination?: string };
+    if (!body.source || !body.destination) {
+      throw connectError('invalid_argument', 'missing source or destination');
+    }
+    const entry = await ctx.inSlot(sandboxIdOf(request), (row) =>
+      executor.move(
+        row.sandboxId,
+        body.source as string,
+        body.destination as string,
+      ),
+    );
+    return { entry: entryInfoJson(entry) };
+  });
+
+  app.post('/filesystem.Filesystem/Remove', async (request) => {
+    const body = request.body as { path?: string };
+    if (!body.path) throw connectError('invalid_argument', 'missing path');
+    await ctx.inSlot(sandboxIdOf(request), (row) =>
+      executor.remove(row.sandboxId, body.path as string),
+    );
+    return {};
+  });
+}
diff --git a/packages/server/src/e2b/envd/index.ts b/packages/server/src/e2b/envd/index.ts
new file mode 100644
index 0000000..c339e0e
--- /dev/null
+++ b/packages/server/src/e2b/envd/index.ts
@@ -0,0 +1,114 @@
+import multipart from '@fastify/multipart';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import { findBySandboxId } from '../../db/ledger';
+import type { E2bDeps } from '../deps';
+import { E2bError, verifyEnvdToken } from '../protocol';
+import { e2bView } from '../view';
+import { registerFileRoutes } from './files';
+import { registerFilesystemRoutes } from './filesystem';
+import { registerProcessRoutes } from './process';
+import { createEnvdContext, sandboxIdOf, UNLIMITED_BODY_BYTES } from './shared';
+import { registerWatchRoutes } from './watch';
+
+/**
+ * The envd surface: what the official SDK reaches through its `sandboxUrl`
+ * option. One origin serves every sandbox — the SDK attaches an
+ * E2b-Sandbox-Id header to every request, so no wildcard DNS is needed.
+ * Connect RPC rides the JSON codec (the SDK sets useBinaryFormat: false);
+ * files ride plain HTTP. The daemon itself plays the role of envd — there
+ * is no agent inside the container.
+ *
+ * This file owns the surface-wide machinery (parsers, auth, error dialect,
+ * /health); each protocol face lives in its own route file.
+ */
+export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
+  app,
+  deps,
+) => {
+  const { config, db } = deps;
+  await app.register(multipart, {
+    limits: {
+      // The disk quota is the ceiling; a route-level cap would just be a
+      // second, dishonest one. parts/files stay bounded so a hostile form
+      // cannot spray unlimited entries.
+      fileSize: UNLIMITED_BODY_BYTES,
+      files: 1000,
+      parts: 2000,
+      fieldSize: 1024 * 1024,
+    },
+    // busboy strips filenames to their basename by default (a browser-form
+    // safety net); here the filename IS the destination path — 'notes/x.txt'
+    // must keep its directory. Traversal is not a concern this opens:
+    // resolveSandboxPath clamps '..' at the container's own root anyway.
+    preservePath: true,
+  });
+
+  // Connect streaming requests arrive enveloped; keep the raw bytes.
+  app.addContentTypeParser(
+    'application/connect+json',
+    { parseAs: 'buffer' },
+    (_request, payload, done) => done(null, payload),
+  );
+  // Octet-stream uploads pass through as a stream: nothing materializes.
+  app.addContentTypeParser(
+    'application/octet-stream',
+    (_request, payload, done) => done(null, payload),
+  );
+
+  app.setErrorHandler((error, request, reply) => {
+    if (error instanceof E2bError) {
+      return reply
+        .code(error.statusCode)
+        .send({ code: error.code, message: error.message });
+    }
+    const status = (error as { statusCode?: number }).statusCode ?? 500;
+    if (status >= 500) {
+      request.log.error(error, 'e2b envd request failed');
+    }
+    return reply.code(status).send({
+      code: status === 400 ? 'invalid_argument' : 'internal',
+      message: (error as Error).message,
+    });
+  });
+  app.setNotFoundHandler((request, reply) => {
+    reply.code(404).send({
+      code: 'not_found',
+      message: `route ${request.method} ${request.url} not found`,
+    });
+  });
+
+  // Auth: X-Access-Token must be the HMAC minted for exactly this sandbox.
+  // /health stays open like real envd's — it is how isRunning() probes.
+  app.addHook('onRequest', async (request) => {
+    if (request.method === 'GET' && request.url.endsWith('/health')) return;
+    const sandboxId = sandboxIdOf(request);
+    const header = request.headers['x-access-token'];
+    const token = Array.isArray(header) ? header[0] : header;
+    if (
+      !token ||
+      !verifyEnvdToken(config.DORMICE_API_TOKEN, sandboxId, token)
+    ) {
+      throw new E2bError(401, 'unauthenticated', 'invalid envd access token');
+    }
+  });
+
+  app.get('/health', async (request, reply) => {
+    // No auth, no wake — a probe must stay cheap and honest. 502 = not
+    // running, the exact signal isRunning() keys on.
+    const header = request.headers['e2b-sandbox-id'];
+    const id = Array.isArray(header) ? header[0] : header;
+    const row = id ? findBySandboxId(db, id) : undefined;
+    if (!row || e2bView(row, new Date()) !== 'running') {
+      return reply
+        .code(502)
+        .send({ code: 'unavailable', message: 'sandbox is not running' });
+    }
+    return reply.code(204).send();
+  });
+
+  const ctx = createEnvdContext(deps);
+  registerFileRoutes(app, ctx);
+  registerFilesystemRoutes(app, ctx);
+  registerWatchRoutes(app, ctx);
+  registerProcessRoutes(app, ctx);
+};
diff --git a/packages/server/src/e2b/envd/process.ts b/packages/server/src/e2b/envd/process.ts
new file mode 100644
index 0000000..dba8176
--- /dev/null
+++ b/packages/server/src/e2b/envd/process.ts
@@ -0,0 +1,477 @@
+import { Buffer } from 'node:buffer';
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import { touch } from '../../db/ledger';
+import type { SandboxRow } from '../../db/schema';
+import { startExecHeartbeat } from '../../exec-heartbeat';
+import type { ProcessRecord, ProcessSubscriber } from '../process-table';
+import {
+  connectError,
+  envelope,
+  FLAG_END_STREAM,
+  FLAG_MESSAGE,
+  readFirstMessage,
+} from '../protocol';
+import {
+  type EnvdContext,
+  MAX_EXEC_SECONDS,
+  MAX_KEEPALIVE_SECONDS,
+  rawWriter,
+  sandboxIdOf,
+  streamError,
+  wireDeadlineMs,
+} from './shared';
+
+interface StartRequest {
+  process?: {
+    cmd?: string;
+    args?: string[];
+    envs?: Record<string, string>;
+    cwd?: string;
+  };
+  stdin?: boolean;
+  pty?: { size?: { cols?: number; rows?: number } };
+}
+
+/**
+ * The wire face of one attached stream, shared by Start and Connect: data
+ * frames with backpressure, and the end frames written by the process's
+ * finalize. `done` settles once the ending — end event or in-stream error
+ * — is fully on the wire. The write closure touches reply.raw lazily: it
+ * is never called before the caller has hijacked (the executor emits
+ * nothing before execStream resolves, and subscription follows the
+ * hijack synchronously).
+ */
+function streamSubscriber(write: (buf: Buffer) => Promise<void>): {
+  subscriber: ProcessSubscriber;
+  done: Promise<'ended'>;
+} {
+  let resolveDone!: (outcome: 'ended') => void;
+  const done = new Promise<'ended'>((resolve) => {
+    resolveDone = resolve;
+  });
+  const subscriber: ProcessSubscriber = {
+    onOutput: (channel, chunk) =>
+      write(
+        envelope(FLAG_MESSAGE, {
+          event: { data: { [channel]: chunk.toString('base64') } },
+        }),
+      ),
+    onEnd: (end) => {
+      const frames =
+        end.kind === 'exit'
+          ? [
+              envelope(FLAG_MESSAGE, {
+                event: {
+                  end: {
+                    exitCode: end.exitCode,
+                    exited: true,
+                    status: end.exitCode === 137 ? 'killed' : 'exited',
+                    ...(end.exitCode === 137
+                      ? { error: 'command killed (exit 137)' }
+                      : {}),
+                  },
+                },
+              }),
+              envelope(FLAG_END_STREAM, {}),
+            ]
+          : [
+              // The container died under the process (a kill, a release):
+              // an in-stream internal error, which the SDK triages via its
+              // health check — the same feel as a killed E2B sandbox.
+              envelope(FLAG_END_STREAM, {
+                error: { code: 'internal', message: end.message },
+              }),
+            ];
+      void (async () => {
+        for (const frame of frames) await write(frame);
+        resolveDone('ended');
+      })();
+    },
+  };
+  return { subscriber, done };
+}
+
+/** {process:{pid}} — the proto3-JSON flattening of the selector oneof. */
+function requirePid(body: unknown): number {
+  const pid = (body as { process?: { pid?: unknown } })?.process?.pid;
+  if (typeof pid !== 'number') {
+    throw connectError('invalid_argument', 'missing process pid');
+  }
+  return pid;
+}
+
+/** The Process service: streams, input, signals, resize — E2B's process model. */
+export function registerProcessRoutes(
+  app: FastifyInstance,
+  ctx: EnvdContext,
+): void {
+  const { db, executor, processes } = ctx;
+
+  /**
+   * The attached half of a process stream: keepalives, the wire deadline,
+   * the client hanging up. The deadline and the hang-up both merely detach
+   * this stream — the process keeps running (real envd's semantics: nothing
+   * kills a process except its own exit, SendSignal, or the sandbox dying);
+   * the exec heartbeat lives exactly as long as someone is attached, so a
+   * background process nobody watches lets the sandbox freeze honestly.
+   */
+  async function pumpProcessStream(args: {
+    request: FastifyRequest;
+    reply: FastifyReply;
+    row: SandboxRow;
+    write: (buf: Buffer) => Promise<void>;
+    done: Promise<'ended'>;
+    detach: () => void;
+  }): Promise<void> {
+    const { request, reply, row, write, done, detach } = args;
+    const stopHeartbeat = startExecHeartbeat(
+      db,
+      row.sandboxId,
+      row.freezeAfterSeconds,
+    );
+    // Keepalive events on the interval the SDK asked for — what keeps
+    // proxies from cutting a silent long command.
+    const keepaliveSeconds = Math.min(
+      Number(request.headers['keepalive-ping-interval']) ||
+        MAX_KEEPALIVE_SECONDS,
+      MAX_KEEPALIVE_SECONDS,
+    );
+    const keepalive = setInterval(() => {
+      reply.raw.write(envelope(FLAG_MESSAGE, { event: { keepalive: {} } }));
+    }, keepaliveSeconds * 1000);
+    const deadlineMs = wireDeadlineMs(request);
+    let deadlineTimer: NodeJS.Timeout | undefined;
+    const deadline = new Promise<'deadline'>((resolve) => {
+      deadlineTimer = setTimeout(() => resolve('deadline'), deadlineMs);
+    });
+    const clientGone = new Promise<'gone'>((resolve) => {
+      reply.raw.once('close', () => resolve('gone'));
+    });
+    try {
+      const outcome = await Promise.race([done, deadline, clientGone]);
+      if (outcome === 'deadline') {
+        // Real envd answers a blown deadline with the Connect error, not an
+        // end event; the SDK turns it into its TimeoutError. The process
+        // stays alive — only this stream ends.
+        await write(
+          envelope(FLAG_END_STREAM, {
+            error: {
+              code: 'deadline_exceeded',
+              message: `command timed out after ${deadlineMs}ms`,
+            },
+          }),
+        );
+      }
+    } finally {
+      clearInterval(keepalive);
+      clearTimeout(deadlineTimer);
+      detach();
+      stopHeartbeat();
+      try {
+        // Watching the command was the activity: the idle countdown starts
+        // when the stream detaches, not when it attached.
+        touch(db, row.sandboxId);
+      } catch {
+        // Released mid-stream; the stream's own ending tells the story.
+      }
+      reply.raw.end();
+    }
+  }
+
+  /** A living process for this sandbox, or the not_found the SDK expects. */
+  function requireProcess(sandboxId: string, pid: number): ProcessRecord {
+    const record = processes.get(sandboxId, pid);
+    if (!record) {
+      throw connectError('not_found', `process not found: ${pid}`);
+    }
+    return record;
+  }
+
+  app.post('/process.Process/List', async (request) => {
+    // Read-only: no wake — looking at the table must not thaw a sandbox.
+    const row = ctx.requireRunningRow(sandboxIdOf(request));
+    return {
+      processes: processes.list(row.sandboxId).map((record) => ({
+        pid: record.pid,
+        // config is echoed verbatim and always complete: the SDK
+        // dereferences processes[].config.args unconditionally.
+        config: {
+          cmd: record.config.cmd,
+          args: record.config.args,
+          envs: record.config.envs,
+          ...(record.config.cwd ? { cwd: record.config.cwd } : {}),
+        },
+      })),
+    };
+  });
+
+  app.post('/process.Process/Start', async (request, reply) => {
+    const message = readFirstMessage(request.body as Buffer) as StartRequest;
+    const proc = message.process ?? {};
+    const args = proc.args ?? [];
+    // A pty block makes this a terminal session (the SDK sends
+    // /bin/bash -i -l; the executor hardcodes that shape anyway). Sizes
+    // default defensively — a 0x0 terminal misbehaves quietly.
+    const ptySize = message.pty
+      ? {
+          cols: message.pty.size?.cols || 80,
+          rows: message.pty.size?.rows || 24,
+        }
+      : undefined;
+    // Without a pty, the SDK always sends /bin/bash [-l] -c <command>;
+    // anything else is a shape this layer does not speak yet.
+    let command: string | undefined;
+    let loginShell = false;
+    if (args.length === 3 && args[0] === '-l' && args[1] === '-c') {
+      command = args[2];
+      loginShell = true;
+    } else if (args.length === 2 && args[0] === '-c') {
+      command = args[1];
+    }
+    if (!proc.cmd?.endsWith('bash') || (!ptySize && command === undefined)) {
+      return streamError(
+        reply,
+        'invalid_argument',
+        ptySize
+          ? 'only bash PTY sessions are supported'
+          : 'only shell commands are supported: expected /bin/bash [-l] -c <command>',
+      );
+    }
+    const row = await ctx.wakeForStream(request, reply);
+    if (!row) return;
+
+    const sandboxEnvs: Record<string, string> = row.envs
+      ? JSON.parse(row.envs)
+      : {};
+    const write = rawWriter(reply);
+    const { subscriber, done } = streamSubscriber(write);
+    let record: ProcessRecord;
+    try {
+      record = await processes.start({
+        executor,
+        sandboxId: row.sandboxId,
+        options: {
+          command,
+          loginShell,
+          pty: ptySize,
+          // The in-container timeout is a pathological-cleanup backstop
+          // only; the wire deadline lives in pumpProcessStream and never
+          // kills the process — E2B's semantics, adopted deliberately.
+          timeoutSeconds: MAX_EXEC_SECONDS,
+          stdin: message.stdin === true,
+          cwd: proc.cwd,
+          // Sandbox-level envs underneath, per-command envs on top.
+          env: { ...sandboxEnvs, ...(proc.envs ?? {}) },
+        },
+        config: {
+          cmd: proc.cmd,
+          args,
+          envs: proc.envs ?? {},
+          cwd: proc.cwd,
+        },
+        subscriber,
+      });
+    } catch (error) {
+      // Start order is deliberate: the start frame goes out only for a
+      // process that actually started.
+      const messageText =
+        error instanceof Error ? error.message : String(error);
+      return streamError(reply, 'internal', messageText);
+    }
+    reply.hijack();
+    reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
+    await write(
+      envelope(FLAG_MESSAGE, { event: { start: { pid: record.pid } } }),
+    );
+    await pumpProcessStream({
+      request,
+      reply,
+      row,
+      write,
+      done,
+      detach: () => processes.unsubscribe(record.pid, subscriber),
+    });
+  });
+
+  app.post('/process.Process/Connect', async (request, reply) => {
+    const message = readFirstMessage(request.body as Buffer) as {
+      process?: { pid?: number };
+    };
+    const pid = message.process?.pid;
+    if (typeof pid !== 'number') {
+      return streamError(reply, 'invalid_argument', 'missing process pid');
+    }
+    const row = await ctx.wakeForStream(request, reply);
+    if (!row) return;
+    const record = processes.get(row.sandboxId, pid);
+    if (!record) {
+      return streamError(reply, 'not_found', `process not found: ${pid}`);
+    }
+    const write = rawWriter(reply);
+    const { subscriber, done } = streamSubscriber(write);
+    reply.hijack();
+    reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
+    // The SDK requires a Connect stream to open with a start frame, exactly
+    // like Start's. Initiated before subscribing so no data frame can slip
+    // ahead of it (raw writes keep call order). No replay of past output —
+    // real envd's semantics.
+    const startFrame = write(
+      envelope(FLAG_MESSAGE, { event: { start: { pid: record.pid } } }),
+    );
+    const unsubscribe = processes.subscribe(pid, subscriber);
+    await startFrame;
+    if (!unsubscribe) {
+      // Finished between get and subscribe: report it rather than hold a
+      // stream that would never end.
+      await write(
+        envelope(FLAG_END_STREAM, {
+          error: { code: 'not_found', message: `process not found: ${pid}` },
+        }),
+      );
+      reply.raw.end();
+      return;
+    }
+    await pumpProcessStream({
+      request,
+      reply,
+      row,
+      write,
+      done,
+      detach: unsubscribe,
+    });
+  });
+
+  app.post('/process.Process/SendInput', async (request) => {
+    const body = request.body as {
+      process?: { pid?: number };
+      input?: { stdin?: string; pty?: string };
+    };
+    const pid = requirePid(body);
+    const row = await ctx.wakeForUse(sandboxIdOf(request));
+    const record = requireProcess(row.sandboxId, pid);
+    const stdinB64 = body.input?.stdin;
+    const ptyB64 = body.input?.pty;
+    if (typeof stdinB64 !== 'string' && typeof ptyB64 !== 'string') {
+      throw connectError('invalid_argument', 'missing input');
+    }
+    // Channel and promise must match: stdin input needs a stdin:true start,
+    // pty input needs a PTY session — a mismatch is the caller's confusion.
+    if (typeof stdinB64 === 'string' && !record.stdin) {
+      throw connectError(
+        'invalid_argument',
+        'process was started without stdin',
+      );
+    }
+    if (typeof ptyB64 === 'string' && !record.pty) {
+      throw connectError('invalid_argument', 'process has no PTY');
+    }
+    const data = Buffer.from((stdinB64 ?? ptyB64) as string, 'base64');
+    try {
+      await record.handle.sendStdin(data);
+    } catch (error) {
+      throw connectError(
+        'invalid_argument',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    return {};
+  });
+
+  app.post('/process.Process/CloseStdin', async (request) => {
+    const pid = requirePid(request.body);
+    const row = await ctx.wakeForUse(sandboxIdOf(request));
+    const record = requireProcess(row.sandboxId, pid);
+    if (!record.stdin) {
+      throw connectError(
+        'invalid_argument',
+        'process was started without stdin',
+      );
+    }
+    try {
+      await record.handle.closeStdin();
+    } catch (error) {
+      throw connectError(
+        'invalid_argument',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    return {};
+  });
+
+  app.post('/process.Process/SendSignal', async (request) => {
+    const body = request.body as {
+      process?: { pid?: number };
+      signal?: string | number;
+    };
+    const pid = requirePid(body);
+    // proto3-JSON enums travel as their names; a numeric fallback costs
+    // nothing and covers a client that emits raw values.
+    const sig =
+      body.signal === 'SIGNAL_SIGKILL' || body.signal === 9
+        ? ('SIGKILL' as const)
+        : body.signal === 'SIGNAL_SIGTERM' || body.signal === 15
+          ? ('SIGTERM' as const)
+          : undefined;
+    if (!sig) {
+      throw connectError(
+        'invalid_argument',
+        `unsupported signal: ${String(body.signal)} — only SIGKILL and SIGTERM are supported`,
+      );
+    }
+    const row = await ctx.wakeForUse(sandboxIdOf(request));
+    const record = requireProcess(row.sandboxId, pid);
+    try {
+      await record.handle.signal(sig);
+    } catch {
+      // The process ended between lookup and signal: protocol-wise it does
+      // not exist — the SDK turns not_found into kill() === false.
+      throw connectError('not_found', `process not found: ${pid}`);
+    }
+    return {};
+  });
+
+  app.post('/process.Process/Update', async (request) => {
+    const body = request.body as {
+      process?: { pid?: number };
+      pty?: { size?: { cols?: number; rows?: number } };
+    };
+    const pid = requirePid(body);
+    const row = await ctx.wakeForUse(sandboxIdOf(request));
+    const record = requireProcess(row.sandboxId, pid);
+    if (!record.pty) {
+      throw connectError('invalid_argument', 'process has no PTY');
+    }
+    const size = body.pty?.size;
+    if (
+      typeof size?.cols !== 'number' ||
+      typeof size?.rows !== 'number' ||
+      size.cols <= 0 ||
+      size.rows <= 0
+    ) {
+      throw connectError('invalid_argument', 'missing pty size');
+    }
+    try {
+      await record.handle.resizePty({ cols: size.cols, rows: size.rows });
+    } catch (error) {
+      throw connectError(
+        'invalid_argument',
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+    return {};
+  });
+
+  // ---- honest unimplemented stubs --------------------------------------
+
+  const unimplemented: Array<[string, string]> = [
+    [
+      '/process.Process/StreamInput',
+      'streamed stdin is not supported — the SDK sends stdin via SendInput',
+    ],
+  ];
+  for (const [path, hint] of unimplemented) {
+    app.post(path, async () => {
+      throw connectError('unimplemented', hint);
+    });
+  }
+}
diff --git a/packages/server/src/e2b/envd/shared.ts b/packages/server/src/e2b/envd/shared.ts
new file mode 100644
index 0000000..c3f3c21
--- /dev/null
+++ b/packages/server/src/e2b/envd/shared.ts
@@ -0,0 +1,183 @@
+import type { Buffer } from 'node:buffer';
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import { findBySandboxId, touch } from '../../db/ledger';
+import type { SandboxRow } from '../../db/schema';
+import {
+  DiskFullError,
+  FileNotFoundError,
+  NotADirectoryError,
+  NotAFileError,
+} from '../../executor/executor';
+import { wakeSandbox } from '../../lifecycle';
+import type { E2bDeps } from '../deps';
+import { connectError, E2bError, envelope, FLAG_END_STREAM } from '../protocol';
+import { e2bView } from '../view';
+
+/**
+ * In-container cleanup backstop for e2b-surface processes. Deliberately not
+ * the wire deadline: connect-timeout-ms only ever closes the stream — the
+ * process lives until it exits, is signaled, or its sandbox dies (E2B's
+ * semantics; the native /execCommand keeps its own kill-at-timeout contract).
+ */
+export const MAX_EXEC_SECONDS = 24 * 60 * 60;
+
+/** The SDK asks for keepalives via this header; we honor it, capped. */
+export const MAX_KEEPALIVE_SECONDS = 30;
+
+/** Effectively unbounded route body: the disk quota is the real gate. */
+export const UNLIMITED_BODY_BYTES = Number.MAX_SAFE_INTEGER;
+
+/** Executor file errors -> the Connect codes the SDK maps back to its own taxonomy. */
+export function toConnectError(error: unknown): unknown {
+  if (error instanceof FileNotFoundError) {
+    return connectError('not_found', error.message);
+  }
+  if (error instanceof NotAFileError || error instanceof NotADirectoryError) {
+    return connectError('invalid_argument', error.message);
+  }
+  if (error instanceof DiskFullError) {
+    return connectError('resource_exhausted', error.message);
+  }
+  return error;
+}
+
+/** Every envd request names its sandbox in this header. */
+export function sandboxIdOf(request: FastifyRequest): string {
+  const header = request.headers['e2b-sandbox-id'];
+  const id = Array.isArray(header) ? header[0] : header;
+  if (!id) {
+    throw new E2bError(401, 'unauthenticated', 'missing E2b-Sandbox-Id header');
+  }
+  return id;
+}
+
+/** The SDK's connect-timeout-ms header, absent meaning "effectively never". */
+export function wireDeadlineMs(request: FastifyRequest): number {
+  const headerMs = Number(request.headers['connect-timeout-ms']);
+  return Number.isFinite(headerMs) && headerMs > 0
+    ? headerMs
+    : MAX_EXEC_SECONDS * 1000;
+}
+
+/** The backpressured raw write every process stream shares. */
+export function rawWriter(reply: FastifyReply): (buf: Buffer) => Promise<void> {
+  return (buf) =>
+    new Promise<void>((resolve) => {
+      if (!reply.raw.write(buf)) reply.raw.once('drain', resolve);
+      else resolve();
+    });
+}
+
+/** Streaming endpoints answer errors inside the stream: 200 + end-stream frame. */
+export function streamError(
+  reply: FastifyReply,
+  code: string,
+  message: string,
+): void {
+  reply.hijack();
+  reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
+  reply.raw.write(envelope(FLAG_END_STREAM, { error: { code, message } }));
+  reply.raw.end();
+}
+
+/**
+ * The deps plus the liveness/wake adjudicators every envd face shares.
+ * Built once per plugin registration; the route files receive it instead
+ * of closing over the plugin body.
+ */
+export interface EnvdContext extends E2bDeps {
+  /** The protocol-liveness gate: only a logically-running sandbox serves envd traffic. */
+  requireRunningRow(sandboxId: string): SandboxRow;
+  /** Wake under the key's slot, like every native verb. */
+  wakeForUse(sandboxId: string): Promise<SandboxRow>;
+  /** Unary filesystem RPCs run entirely in the key's slot, like native file verbs. */
+  inSlot<T>(
+    sandboxId: string,
+    work: (row: SandboxRow) => Promise<T>,
+  ): Promise<T>;
+  /** Wake-for-use with streaming-dialect errors: streamError, not thrown JSON. */
+  wakeForStream(
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ): Promise<SandboxRow | undefined>;
+}
+
+export function createEnvdContext(deps: E2bDeps): EnvdContext {
+  const { db, executor, locks } = deps;
+
+  /**
+   * Only a logically-running sandbox serves envd traffic: paused and dead
+   * answer 502, which the SDK triages into its "sandbox timed out / not
+   * running" errors — exactly what talking to a paused or killed E2B
+   * sandbox feels like.
+   */
+  function requireRunningRow(sandboxId: string): SandboxRow {
+    const row = findBySandboxId(db, sandboxId);
+    if (!row) {
+      throw new E2bError(502, 'unavailable', 'sandbox not found');
+    }
+    const state = e2bView(row, new Date());
+    if (state !== 'running') {
+      throw new E2bError(
+        502,
+        'unavailable',
+        state === 'paused' ? 'sandbox is paused' : 'sandbox not found',
+      );
+    }
+    return row;
+  }
+
+  /**
+   * Wake under the key's slot, like every native verb: physical wake-ups
+   * take seconds and must not race the scanner or a release.
+   */
+  async function wakeForUse(sandboxId: string): Promise<SandboxRow> {
+    const before = requireRunningRow(sandboxId);
+    return locks.run(before.userKey, async () => {
+      const fresh = requireRunningRow(sandboxId);
+      const awake = await wakeSandbox(db, executor, fresh);
+      return touch(db, awake.sandboxId);
+    });
+  }
+
+  async function inSlot<T>(
+    sandboxId: string,
+    work: (row: SandboxRow) => Promise<T>,
+  ): Promise<T> {
+    const before = requireRunningRow(sandboxId);
+    return locks.run(before.userKey, async () => {
+      const fresh = requireRunningRow(sandboxId);
+      const awake = await wakeSandbox(db, executor, fresh);
+      const row = touch(db, awake.sandboxId);
+      try {
+        return await work(row);
+      } catch (error) {
+        throw toConnectError(error);
+      }
+    });
+  }
+
+  async function wakeForStream(
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ): Promise<SandboxRow | undefined> {
+    try {
+      return await wakeForUse(sandboxIdOf(request));
+    } catch (error) {
+      if (error instanceof E2bError) {
+        // Everything this surface throws carries a Connect string code; a
+        // numeric one would be a control-plane error that leaked — treat it
+        // as the sandbox being unreachable.
+        streamError(
+          reply,
+          typeof error.code === 'string' ? error.code : 'unavailable',
+          error.message,
+        );
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  return { ...deps, requireRunningRow, wakeForUse, inSlot, wakeForStream };
+}
diff --git a/packages/server/src/e2b/envd/watch.ts b/packages/server/src/e2b/envd/watch.ts
new file mode 100644
index 0000000..1d9c842
--- /dev/null
+++ b/packages/server/src/e2b/envd/watch.ts
@@ -0,0 +1,236 @@
+import type { Buffer } from 'node:buffer';
+import type { FastifyInstance } from 'fastify';
+import {
+  FileNotFoundError,
+  NotADirectoryError,
+  type WatchEvent,
+} from '../../executor/executor';
+import {
+  connectError,
+  envelope,
+  FLAG_END_STREAM,
+  FLAG_MESSAGE,
+  readFirstMessage,
+} from '../protocol';
+import { WatcherLimitError } from '../watcher-table';
+import {
+  type EnvdContext,
+  MAX_KEEPALIVE_SECONDS,
+  rawWriter,
+  sandboxIdOf,
+  streamError,
+  wireDeadlineMs,
+} from './shared';
+
+/** Executor event types -> the proto enum names proto3-JSON speaks. */
+const WATCH_EVENT_WIRE: Record<WatchEvent['type'], string> = {
+  create: 'EVENT_TYPE_CREATE',
+  write: 'EVENT_TYPE_WRITE',
+  remove: 'EVENT_TYPE_REMOVE',
+  rename: 'EVENT_TYPE_RENAME',
+  chmod: 'EVENT_TYPE_CHMOD',
+};
+
+/**
+ * Path validation errors travel differently on the two watch surfaces
+ * (in-stream frame vs unary throw), but the codes and messages are one
+ * decision: not_found for a missing path, invalid_argument for a file —
+ * real envd's answers, with this codebase's own wording.
+ */
+function watchStartError(error: unknown): { code: string; message: string } {
+  if (error instanceof FileNotFoundError) {
+    return { code: 'not_found', message: error.message };
+  }
+  if (error instanceof NotADirectoryError) {
+    return { code: 'invalid_argument', message: error.message };
+  }
+  return {
+    code: 'internal',
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+/** The watch faces: the streaming WatchDir plus the sync SDKs' polling trio. */
+export function registerWatchRoutes(
+  app: FastifyInstance,
+  ctx: EnvdContext,
+): void {
+  const { executor, watchers } = ctx;
+
+  /**
+   * The streaming watch: unlike a process stream, the watcher IS the stream
+   * — real envd runs the whole watch inside one handler, so the deadline,
+   * the client hanging up, or any ending stops the watcher itself (the SDK's
+   * WatchHandle.stop() is exactly an abort of this request). Frames are the
+   * WatchDirResponse oneof at the top level: {start:{}}, {filesystem:{...}},
+   * {keepalive:{}} — no `event` wrapper, unlike the process face.
+   *
+   * Deliberately no exec heartbeat: watching is passive observation, so an
+   * attached watch lets the idle scanner freeze the sandbox. No events can
+   * be missed frozen — the disk only changes from inside, and everything
+   * that reaches inside wakes the sandbox first.
+   */
+  app.post('/filesystem.Filesystem/WatchDir', async (request, reply) => {
+    const message = readFirstMessage(request.body as Buffer) as {
+      path?: string;
+      recursive?: boolean;
+    };
+    if (!message.path) {
+      return streamError(reply, 'invalid_argument', 'missing path');
+    }
+    const row = await ctx.wakeForStream(request, reply);
+    if (!row) return;
+
+    const write = rawWriter(reply);
+    // Events hold at this gate until the start frame is on the wire — the
+    // SDK requires the stream to open with it, and a change made in the
+    // sliver between watcher start and hijack would otherwise race ahead.
+    let openGate = () => {};
+    const opened = new Promise<void>((resolve) => {
+      openGate = resolve;
+    });
+    let settleEnd: (error: Error) => void = () => {};
+    const ended = new Promise<Error>((resolve) => {
+      settleEnd = resolve;
+    });
+    let watcher: Awaited<ReturnType<typeof executor.watchDir>>;
+    try {
+      watcher = await executor.watchDir(row.sandboxId, {
+        path: message.path,
+        recursive: message.recursive === true,
+        onEvent: async (event) => {
+          await opened;
+          await write(
+            envelope(FLAG_MESSAGE, {
+              filesystem: {
+                name: event.name,
+                type: WATCH_EVENT_WIRE[event.type],
+              },
+            }),
+          );
+        },
+        onEnd: (error) =>
+          settleEnd(error ?? new Error('watcher ended unexpectedly')),
+      });
+    } catch (error) {
+      const { code, message: text } = watchStartError(error);
+      return streamError(reply, code, text);
+    }
+
+    reply.hijack();
+    reply.raw.writeHead(200, { 'content-type': 'application/connect+json' });
+    await write(envelope(FLAG_MESSAGE, { start: {} }));
+    openGate();
+
+    const keepaliveSeconds = Math.min(
+      Number(request.headers['keepalive-ping-interval']) ||
+        MAX_KEEPALIVE_SECONDS,
+      MAX_KEEPALIVE_SECONDS,
+    );
+    const keepalive = setInterval(() => {
+      reply.raw.write(envelope(FLAG_MESSAGE, { keepalive: {} }));
+    }, keepaliveSeconds * 1000);
+    const deadlineMs = wireDeadlineMs(request);
+    let deadlineTimer: NodeJS.Timeout | undefined;
+    const deadline = new Promise<'deadline'>((resolve) => {
+      deadlineTimer = setTimeout(() => resolve('deadline'), deadlineMs);
+    });
+    const clientGone = new Promise<'gone'>((resolve) => {
+      reply.raw.once('close', () => resolve('gone'));
+    });
+    try {
+      const outcome = await Promise.race([ended, deadline, clientGone]);
+      if (outcome === 'deadline') {
+        // The SDK's watch default is 60s: a blown deadline is the normal
+        // ending of most watches, answered like real envd's ctx expiry.
+        await write(
+          envelope(FLAG_END_STREAM, {
+            error: {
+              code: 'deadline_exceeded',
+              message: `watch timed out after ${deadlineMs}ms`,
+            },
+          }),
+        );
+      } else if (outcome instanceof Error) {
+        await write(
+          envelope(FLAG_END_STREAM, {
+            error: { code: 'internal', message: outcome.message },
+          }),
+        );
+      }
+    } finally {
+      clearInterval(keepalive);
+      clearTimeout(deadlineTimer);
+      try {
+        await watcher.stop();
+      } catch {
+        // The sandbox died under the watcher; its ending already spoke.
+      }
+      reply.raw.end();
+    }
+  });
+
+  // The polling trio — what the sync SDKs use instead of the WatchDir
+  // stream. Same watcher engine, parked in the daemon-memory watcher table.
+
+  app.post('/filesystem.Filesystem/CreateWatcher', async (request) => {
+    const body = request.body as { path?: string; recursive?: boolean };
+    if (!body.path) throw connectError('invalid_argument', 'missing path');
+    const row = await ctx.wakeForUse(sandboxIdOf(request));
+    try {
+      const watcherId = await watchers.create({
+        executor,
+        sandboxId: row.sandboxId,
+        path: body.path,
+        recursive: body.recursive === true,
+      });
+      return { watcherId };
+    } catch (error) {
+      if (error instanceof WatcherLimitError) {
+        throw connectError('resource_exhausted', error.message);
+      }
+      const { code, message } = watchStartError(error);
+      throw connectError(code, message);
+    }
+  });
+
+  app.post('/filesystem.Filesystem/GetWatcherEvents', async (request) => {
+    const body = request.body as { watcherId?: string };
+    if (!body.watcherId) {
+      throw connectError('invalid_argument', 'missing watcher id');
+    }
+    // No wake: this reads daemon memory. A frozen sandbox has no new events
+    // to report anyway — the disk cannot change while it is frozen.
+    const row = ctx.requireRunningRow(sandboxIdOf(request));
+    const events = watchers.drain(row.sandboxId, body.watcherId);
+    if (events === undefined) {
+      throw connectError(
+        'not_found',
+        `watcher with id ${body.watcherId} not found`,
+      );
+    }
+    return {
+      events: events.map((event) => ({
+        name: event.name,
+        type: WATCH_EVENT_WIRE[event.type],
+      })),
+    };
+  });
+
+  app.post('/filesystem.Filesystem/RemoveWatcher', async (request) => {
+    const body = request.body as { watcherId?: string };
+    if (!body.watcherId) {
+      throw connectError('invalid_argument', 'missing watcher id');
+    }
+    // Wakes: stopping the in-container inotifywait needs the container up.
+    const row = await ctx.wakeForUse(sandboxIdOf(request));
+    const removed = await watchers.remove(row.sandboxId, body.watcherId);
+    if (!removed) {
+      throw connectError(
+        'not_found',
+        `watcher with id ${body.watcherId} not found`,
+      );
+    }
+    return {};
+  });
+}

From 049372c596e2420033de6b808579c1c46fed838c Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 14:45:22 +0800
Subject: [PATCH 026/133] The executor contract splits into chapters, one file
 per verb family
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

68 tests sat flat in one 1475-line describe; the exam now reads as six
chapters — lifecycle and disks, exec, execStream and PTY, files, directory
entries, watchDir — each a nested describe in its own file, so a real-machine
run reports failures by chapter. The harness (fresh sandboxes, cleanup,
polling) moves into a ContractContext with live getters, since beforeEach
rebuilds the subject per test. describeExecutorContract stays the single
entry point: one exam, both executors, same error messages — nothing about
the contract's meaning changes, and the suite count is untouched.
---
 packages/server/src/executor/contract.ts      | 1475 -----------------
 .../server/src/executor/contract/entries.ts   |  187 +++
 packages/server/src/executor/contract/exec.ts |  154 ++
 .../src/executor/contract/execStream.ts       |  359 ++++
 .../server/src/executor/contract/files.ts     |  274 +++
 .../server/src/executor/contract/index.ts     |  126 ++
 .../server/src/executor/contract/lifecycle.ts |  247 +++
 .../server/src/executor/contract/watch.ts     |  239 +++
 8 files changed, 1586 insertions(+), 1475 deletions(-)
 delete mode 100644 packages/server/src/executor/contract.ts
 create mode 100644 packages/server/src/executor/contract/entries.ts
 create mode 100644 packages/server/src/executor/contract/exec.ts
 create mode 100644 packages/server/src/executor/contract/execStream.ts
 create mode 100644 packages/server/src/executor/contract/files.ts
 create mode 100644 packages/server/src/executor/contract/index.ts
 create mode 100644 packages/server/src/executor/contract/lifecycle.ts
 create mode 100644 packages/server/src/executor/contract/watch.ts

diff --git a/packages/server/src/executor/contract.ts b/packages/server/src/executor/contract.ts
deleted file mode 100644
index e55a329..0000000
--- a/packages/server/src/executor/contract.ts
+++ /dev/null
@@ -1,1475 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { Readable } from 'node:stream';
-import {
-  EXEC_OUTPUT_LIMIT_BYTES,
-  FILE_SIZE_LIMIT_BYTES,
-} from '@dormice/shared';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import {
-  type ContainerState,
-  type Executor,
-  FileNotFoundError,
-  FileTooLargeError,
-  NotADirectoryError,
-  NotAFileError,
-} from './executor';
-
-/**
- * What a contract run needs beyond the executor itself: a way to stage the
- * one drift an executor cannot produce through its own verbs.
- */
-export interface ContractSubject {
-  executor: Executor;
-  /**
-   * Removes the container object while the disk stays — the drift a
-   * `docker container prune` (or any removal behind the daemon's back)
-   * leaves. The fake flips its map; the docker subject asks the engine
-   * directly. Part of the contract because "start rebuilds from the disk"
-   * and "destroy takes the leftover disk" must hold on both implementations.
-   */
-  vanishContainer(sandboxId: string): Promise<void>;
-}
-
-/**
- * The executor contract: one test suite both implementations must pass,
- * down to the error messages. Unit tests run it against FakeExecutor
- * everywhere; on a Linux docker host the same suite runs against
- * DockerExecutor — that is what makes the fake a trustworthy stand-in.
- *
- * Observations go through listContainers() and listDisks() only, because
- * together they are the whole public window into reality; sandbox ids are
- * random so runs never collide on a real machine, and everything created
- * is destroyed afterwards.
- */
-export function describeExecutorContract(
-  name: string,
-  makeSubject: () => ContractSubject | Promise<ContractSubject>,
-  { timeoutMs = 5_000 }: { timeoutMs?: number } = {},
-) {
-  describe(`executor contract: ${name}`, () => {
-    let executor: Executor;
-    let subject: ContractSubject;
-    let created: string[] = [];
-
-    beforeEach(async () => {
-      subject = await makeSubject();
-      executor = subject.executor;
-      created = [];
-    });
-
-    afterEach(async () => {
-      for (const sandboxId of created) {
-        try {
-          await executor.destroy(sandboxId);
-        } catch {
-          // Already gone — the test destroyed it itself.
-        }
-      }
-    }, timeoutMs);
-
-    async function fresh(): Promise<string> {
-      const sandboxId = randomUUID();
-      created.push(sandboxId);
-      await executor.create(sandboxId);
-      return sandboxId;
-    }
-
-    /** Walks a fresh sandbox down to stopped: exited container plus disk. */
-    async function freshStopped(): Promise<string> {
-      const sandboxId = await fresh();
-      await executor.freeze(sandboxId);
-      await executor.stop(sandboxId);
-      return sandboxId;
-    }
-
-    async function stateOf(
-      sandboxId: string,
-    ): Promise<ContainerState | undefined> {
-      return (await executor.listContainers()).get(sandboxId);
-    }
-
-    it(
-      'walks the full container lifecycle',
-      async () => {
-        const id = await fresh();
-        expect(await stateOf(id)).toBe('running');
-        await executor.freeze(id);
-        expect(await stateOf(id)).toBe('paused');
-        await executor.unfreeze(id);
-        expect(await stateOf(id)).toBe('running');
-        await executor.freeze(id);
-        await executor.stop(id);
-        expect(await stateOf(id)).toBe('stopped');
-        await executor.start(id);
-        expect(await stateOf(id)).toBe('running');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'rejects creating the same container twice',
-      async () => {
-        const id = await fresh();
-        await expect(executor.create(id)).rejects.toThrow(/already exists/);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'rejects operations from the wrong state',
-      async () => {
-        const id = await fresh();
-        await expect(executor.unfreeze(id)).rejects.toThrow(/expected paused/);
-        await expect(executor.stop(id)).rejects.toThrow(/expected paused/);
-        await expect(executor.start(id)).rejects.toThrow(/expected stopped/);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'rejects operations on absent containers',
-      async () => {
-        await expect(executor.freeze(randomUUID())).rejects.toThrow(/absent/);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'destroys a container from any state',
-      async () => {
-        const running = await fresh();
-        await executor.destroy(running);
-        expect(await stateOf(running)).toBeUndefined();
-
-        const paused = await fresh();
-        await executor.freeze(paused);
-        await executor.destroy(paused);
-        expect(await stateOf(paused)).toBeUndefined();
-
-        const stopped = await fresh();
-        await executor.freeze(stopped);
-        await executor.stop(stopped);
-        await executor.destroy(stopped);
-        expect(await stateOf(stopped)).toBeUndefined();
-      },
-      timeoutMs,
-    );
-
-    it(
-      'rejects destroying an absent container',
-      async () => {
-        // The ledger says it exists, reality disagrees: worth hearing, not
-        // a silent success — vanished containers are the reconciler's case.
-        await expect(executor.destroy(randomUUID())).rejects.toThrow(/absent/);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'start rebuilds the container from a surviving disk',
-      async () => {
-        const id = await freshStopped();
-        // The exited container object is removed behind the daemon's back —
-        // exactly what a routine `docker container prune` does. The disk,
-        // which is the sandbox's actual data, stays.
-        await subject.vanishContainer(id);
-        expect(await stateOf(id)).toBeUndefined();
-        expect(await executor.listDisks()).toContain(id);
-
-        await executor.start(id);
-        expect(await stateOf(id)).toBe('running');
-        expect(await executor.listDisks()).toContain(id);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'destroy of a vanished container still takes the leftover disk',
-      async () => {
-        const id = await freshStopped();
-        await subject.vanishContainer(id);
-
-        await executor.destroy(id);
-        expect(await executor.listDisks()).not.toContain(id);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'rejects starting a sandbox that has no disk',
-      async () => {
-        // No container AND no disk: there is nothing to rebuild from.
-        await expect(executor.start(randomUUID())).rejects.toThrow(
-          /disk .+ is absent, cannot start/,
-        );
-      },
-      timeoutMs,
-    );
-
-    it(
-      'removeContainer swaps the shell: container gone, disk kept, start rebuilds with data intact',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: 'keep.txt', content: Buffer.from('survives the rebuild') },
-        ]);
-
-        await executor.removeContainer(id);
-        expect(await stateOf(id)).toBeUndefined();
-        expect(await executor.listDisks()).toContain(id);
-
-        await executor.start(id);
-        expect(await stateOf(id)).toBe('running');
-        expect((await executor.readFile(id, 'keep.txt')).toString()).toBe(
-          'survives the rebuild',
-        );
-      },
-      timeoutMs,
-    );
-
-    it(
-      'removeContainer takes the container down from any state',
-      async () => {
-        const paused = await fresh();
-        await executor.freeze(paused);
-        await executor.removeContainer(paused);
-        expect(await stateOf(paused)).toBeUndefined();
-        expect(await executor.listDisks()).toContain(paused);
-
-        const stopped = await freshStopped();
-        await executor.removeContainer(stopped);
-        expect(await stateOf(stopped)).toBeUndefined();
-        expect(await executor.listDisks()).toContain(stopped);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'removeContainer: an absent container is the goal state beside a disk, a complaint without one',
-      async () => {
-        const id = await freshStopped();
-        await subject.vanishContainer(id);
-        // Pruned behind the daemon's back — removing it again is a no-op.
-        await executor.removeContainer(id);
-        expect(await executor.listDisks()).toContain(id);
-
-        await expect(executor.removeContainer(randomUUID())).rejects.toThrow(
-          /absent, cannot remove/,
-        );
-      },
-      timeoutMs,
-    );
-
-    it(
-      'the disk lives with the container: born on create, kept through stop, gone on destroy',
-      async () => {
-        const id = await fresh();
-        expect(await executor.listDisks()).toContain(id);
-        await executor.freeze(id);
-        await executor.stop(id);
-        // "The processes die, the disk stays."
-        expect(await executor.listDisks()).toContain(id);
-        await executor.destroy(id);
-        expect(await executor.listDisks()).not.toContain(id);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'removeDisk is idempotent: an absent disk already is the goal state',
-      async () => {
-        await expect(
-          executor.removeDisk(randomUUID()),
-        ).resolves.toBeUndefined();
-      },
-      timeoutMs,
-    );
-
-    it(
-      'lists every container as an observation, not a live reference',
-      async () => {
-        const a = await fresh();
-        const b = await fresh();
-        await executor.freeze(b);
-
-        const observed = await executor.listContainers();
-        expect(observed.get(a)).toBe('running');
-        expect(observed.get(b)).toBe('paused');
-        // Mutating the observation must not mutate reality.
-        observed.delete(a);
-        expect(await stateOf(a)).toBe('running');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'exec runs a command and returns its buffered result',
-      async () => {
-        const id = await fresh();
-        const result = await executor.exec(id, {
-          command: 'echo hi',
-          timeoutSeconds: 30,
-        });
-        expect(result).toEqual({
-          exitCode: 0,
-          stdout: 'hi\n',
-          stderr: '',
-          stdoutTruncated: false,
-          stderrTruncated: false,
-        });
-      },
-      timeoutMs,
-    );
-
-    it(
-      'exec reports a nonzero exit code as a result, not an error',
-      async () => {
-        const id = await fresh();
-        const result = await executor.exec(id, {
-          command: 'exit 3',
-          timeoutSeconds: 30,
-        });
-        expect(result.exitCode).toBe(3);
-      },
-      timeoutMs,
-    );
-
-    it(
-      "exec answers an unknown command with bash's own 127",
-      async () => {
-        const id = await fresh();
-        const result = await executor.exec(id, {
-          command: 'no-such-command-xyz',
-          timeoutSeconds: 30,
-        });
-        expect(result.exitCode).toBe(127);
-        expect(result.stderr).toMatch(/command not found/);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'exec honors cwd and defaults to /home/user',
-      async () => {
-        const id = await fresh();
-        const inTmp = await executor.exec(id, {
-          command: 'pwd',
-          cwd: '/tmp',
-          timeoutSeconds: 30,
-        });
-        expect(inTmp.stdout).toBe('/tmp\n');
-        const inHome = await executor.exec(id, {
-          command: 'pwd',
-          timeoutSeconds: 30,
-        });
-        expect(inHome.stdout).toBe('/home/user\n');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'exec passes env vars through',
-      async () => {
-        const id = await fresh();
-        const result = await executor.exec(id, {
-          command: 'printenv DORMICE_CONTRACT_PROBE',
-          env: { DORMICE_CONTRACT_PROBE: '42' },
-          timeoutSeconds: 30,
-        });
-        expect(result.exitCode).toBe(0);
-        expect(result.stdout).toBe('42\n');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'rejects exec on a container that is not running',
-      async () => {
-        const paused = await fresh();
-        await executor.freeze(paused);
-        await expect(
-          executor.exec(paused, { command: 'echo hi', timeoutSeconds: 30 }),
-        ).rejects.toThrow(/is paused, expected running/);
-
-        const stopped = await freshStopped();
-        await expect(
-          executor.exec(stopped, { command: 'echo hi', timeoutSeconds: 30 }),
-        ).rejects.toThrow(/is stopped, expected running/);
-
-        await expect(
-          executor.exec(randomUUID(), {
-            command: 'echo hi',
-            timeoutSeconds: 30,
-          }),
-        ).rejects.toThrow(/is absent, expected running/);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'the timeout kills the command in-container: exit 137',
-      async () => {
-        const id = await fresh();
-        const before = Date.now();
-        const result = await executor.exec(id, {
-          command: 'sleep 5',
-          timeoutSeconds: 1,
-        });
-        // Well under the 5s sleep proves the kill actually landed; the
-        // slack above 1s absorbs a loaded docker host.
-        expect(Date.now() - before).toBeLessThan(4_000);
-        expect(result.exitCode).toBe(137);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'exec caps each stream and reports the truncation',
-      async () => {
-        const id = await fresh();
-        // seq, not a giant echo literal: MAX_ARG_STRLEN caps one argv
-        // element at 128 KiB, so an over-cap echo argument would die in
-        // execve on the real executor instead of testing the cap.
-        const result = await executor.exec(id, {
-          command: 'seq 1 300000',
-          timeoutSeconds: 60,
-        });
-        expect(result.exitCode).toBe(0);
-        expect(result.stdoutTruncated).toBe(true);
-        expect(result.stdout.length).toBe(EXEC_OUTPUT_LIMIT_BYTES);
-        expect(result.stderrTruncated).toBe(false);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'execStream delivers output live, chunk by chunk',
-      async () => {
-        const id = await fresh();
-        const chunks: Array<{ text: string; at: number }> = [];
-        const handle = await executor.execStream(id, {
-          command: 'echo first; sleep 1; echo second',
-          timeoutSeconds: 30,
-          onStdout: (c) => {
-            chunks.push({ text: c.toString('utf8'), at: Date.now() });
-          },
-          onStderr: () => {},
-        });
-        const { exitCode } = await handle.wait();
-        expect(exitCode).toBe(0);
-        expect(chunks.map((c) => c.text).join('')).toBe('first\nsecond\n');
-        // The anti-buffering assertion: with the sleep between the echoes,
-        // live delivery shows a real gap between the first and last chunk.
-        // A buffered implementation delivers everything at once — gap zero.
-        const at = chunks.map((c) => c.at);
-        expect(Math.max(...at) - Math.min(...at)).toBeGreaterThanOrEqual(500);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'execStream reports a nonzero exit through wait, not an error',
-      async () => {
-        const id = await fresh();
-        const handle = await executor.execStream(id, {
-          command: 'exit 7',
-          timeoutSeconds: 30,
-          onStdout: () => {},
-          onStderr: () => {},
-        });
-        await expect(handle.wait()).resolves.toEqual({ exitCode: 7 });
-      },
-      timeoutMs,
-    );
-
-    it(
-      'execStream timeout kills in-container; chunks already delivered stay delivered',
-      async () => {
-        const id = await fresh();
-        const seen: string[] = [];
-        const before = Date.now();
-        const handle = await executor.execStream(id, {
-          command: 'echo early; sleep 5',
-          timeoutSeconds: 1,
-          onStdout: (c) => {
-            seen.push(c.toString('utf8'));
-          },
-          onStderr: () => {},
-        });
-        const { exitCode } = await handle.wait();
-        expect(Date.now() - before).toBeLessThan(4_000);
-        expect(exitCode).toBe(137);
-        expect(seen.join('')).toBe('early\n');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'execStream stdin round-trips: sendStdin chunks echo back, closeStdin is EOF',
-      async () => {
-        const id = await fresh();
-        const seen: string[] = [];
-        const handle = await executor.execStream(id, {
-          command: 'cat',
-          timeoutSeconds: 30,
-          stdin: true,
-          onStdout: (c) => {
-            seen.push(c.toString('utf8'));
-          },
-          onStderr: () => {},
-        });
-        await handle.sendStdin(Buffer.from('hello '));
-        await handle.sendStdin(Buffer.from('world'));
-        await handle.closeStdin();
-        const { exitCode } = await handle.wait();
-        expect(exitCode).toBe(0);
-        expect(seen.join('')).toBe('hello world');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'execStream closeStdin with nothing written ends the command cleanly',
-      async () => {
-        const id = await fresh();
-        const seen: string[] = [];
-        const handle = await executor.execStream(id, {
-          command: 'cat',
-          timeoutSeconds: 30,
-          stdin: true,
-          onStdout: (c) => {
-            seen.push(c.toString('utf8'));
-          },
-          onStderr: () => {},
-        });
-        await handle.closeStdin();
-        const { exitCode } = await handle.wait();
-        expect(exitCode).toBe(0);
-        expect(seen.join('')).toBe('');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'sendStdin on a command started without stdin refuses honestly',
-      async () => {
-        const id = await fresh();
-        const handle = await executor.execStream(id, {
-          command: 'sleep 5',
-          timeoutSeconds: 30,
-          onStdout: () => {},
-          onStderr: () => {},
-        });
-        await expect(handle.sendStdin(Buffer.from('x'))).rejects.toThrow(
-          'process was started without stdin',
-        );
-        await expect(handle.closeStdin()).rejects.toThrow(
-          'process was started without stdin',
-        );
-        await handle.signal('SIGKILL');
-        await handle.wait();
-      },
-      timeoutMs,
-    );
-
-    it(
-      'sendStdin after closeStdin refuses: stdin is closed',
-      async () => {
-        const id = await fresh();
-        const handle = await executor.execStream(id, {
-          command: 'cat',
-          timeoutSeconds: 30,
-          stdin: true,
-          onStdout: () => {},
-          onStderr: () => {},
-        });
-        await handle.closeStdin();
-        await expect(handle.sendStdin(Buffer.from('late'))).rejects.toThrow(
-          'stdin is closed',
-        );
-        await handle.wait();
-      },
-      timeoutMs,
-    );
-
-    it(
-      'signal SIGKILL lands as exit 137; delivered chunks stay delivered',
-      async () => {
-        const id = await fresh();
-        const seen: string[] = [];
-        const handle = await executor.execStream(id, {
-          command: 'echo early; sleep 30',
-          timeoutSeconds: 60,
-          onStdout: (c) => {
-            seen.push(c.toString('utf8'));
-          },
-          onStderr: () => {},
-        });
-        // Wait for the first chunk so the kill provably interrupts, not races.
-        const before = Date.now();
-        while (seen.length === 0 && Date.now() - before < 5_000) {
-          await new Promise((resolve) => setTimeout(resolve, 50));
-        }
-        await handle.signal('SIGKILL');
-        const { exitCode } = await handle.wait();
-        expect(exitCode).toBe(137);
-        expect(seen.join('')).toBe('early\n');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'signal SIGTERM lands as exit 143',
-      async () => {
-        const id = await fresh();
-        const handle = await executor.execStream(id, {
-          command: 'sleep 30',
-          timeoutSeconds: 60,
-          onStdout: () => {},
-          onStderr: () => {},
-        });
-        await handle.signal('SIGTERM');
-        const { exitCode } = await handle.wait();
-        expect(exitCode).toBe(143);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'execStream emits nothing before it resolves',
-      async () => {
-        const id = await fresh();
-        let resolved = false;
-        let leaked = false;
-        const handle = await executor.execStream(id, {
-          command: 'echo eager',
-          timeoutSeconds: 30,
-          onStdout: () => {
-            if (!resolved) leaked = true;
-          },
-          onStderr: () => {},
-        });
-        resolved = true;
-        await handle.wait();
-        expect(leaked).toBe(false);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'a running command survives freeze/unfreeze and completes afterwards',
-      async () => {
-        const id = await fresh();
-        const seen: string[] = [];
-        const handle = await executor.execStream(id, {
-          command: 'echo started; sleep 1; echo woke',
-          timeoutSeconds: 30,
-          onStdout: (c) => {
-            seen.push(c.toString('utf8'));
-          },
-          onStderr: () => {},
-        });
-        // Wait for proof the command is actually running before freezing:
-        // dockerd acknowledges exec start before the process has spawned
-        // (measured 2026-07-10 — a zero-gap pause wins that race and the
-        // exec dies 128 "cannot exec in a paused state"). The contract's
-        // claim is about running commands, so observe one first.
-        const before = Date.now();
-        while (seen.length === 0 && Date.now() - before < 5_000) {
-          await new Promise((resolve) => setTimeout(resolve, 50));
-        }
-        await executor.freeze(id);
-        await executor.unfreeze(id);
-        const { exitCode } = await handle.wait();
-        expect(exitCode).toBe(0);
-        expect(seen.join('')).toContain('woke');
-      },
-      timeoutMs,
-    );
-
-    /** Polls until the observation holds — PTY output has no fixed schedule. */
-    async function until(check: () => boolean): Promise<void> {
-      const before = Date.now();
-      while (!check()) {
-        if (Date.now() - before > timeoutMs - 1_000) {
-          throw new Error('condition never became true');
-        }
-        await new Promise((resolve) => setTimeout(resolve, 50));
-      }
-    }
-
-    it(
-      'a PTY session echoes input and runs what is typed',
-      async () => {
-        const id = await fresh();
-        const seen: string[] = [];
-        const handle = await executor.execStream(id, {
-          timeoutSeconds: 60,
-          pty: { cols: 80, rows: 24 },
-          env: { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' },
-          onStdout: (c) => {
-            seen.push(c.toString('utf8'));
-          },
-          onStderr: () => {},
-        });
-        await handle.sendStdin(Buffer.from('echo pty-marker\r'));
-        // contains, never equals: a real bash brings PS1 and escape codes.
-        await until(() => seen.join('').includes('pty-marker'));
-        await handle.sendStdin(Buffer.from('exit\r'));
-        const { exitCode } = await handle.wait();
-        expect(exitCode).toBe(0);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'resizePty changes what stty size reports',
-      async () => {
-        const id = await fresh();
-        const seen: string[] = [];
-        const handle = await executor.execStream(id, {
-          timeoutSeconds: 60,
-          pty: { cols: 80, rows: 24 },
-          env: { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' },
-          onStdout: (c) => {
-            seen.push(c.toString('utf8'));
-          },
-          onStderr: () => {},
-        });
-        await handle.resizePty({ cols: 123, rows: 45 });
-        await handle.sendStdin(Buffer.from('stty size\r'));
-        await until(() => seen.join('').includes('45 123'));
-        await handle.sendStdin(Buffer.from('exit\r'));
-        await handle.wait();
-      },
-      timeoutMs,
-    );
-
-    it(
-      'a PTY dies to SIGKILL as 137; a plain command has no PTY to resize',
-      async () => {
-        const id = await fresh();
-        const pty = await executor.execStream(id, {
-          timeoutSeconds: 60,
-          pty: { cols: 80, rows: 24 },
-          env: { TERM: 'xterm-256color' },
-          onStdout: () => {},
-          onStderr: () => {},
-        });
-        await pty.signal('SIGKILL');
-        expect((await pty.wait()).exitCode).toBe(137);
-
-        const plain = await executor.execStream(id, {
-          command: 'sleep 5',
-          timeoutSeconds: 30,
-          onStdout: () => {},
-          onStderr: () => {},
-        });
-        await expect(plain.resizePty({ cols: 1, rows: 1 })).rejects.toThrow(
-          'process has no PTY',
-        );
-        await plain.signal('SIGKILL');
-        await plain.wait();
-      },
-      timeoutMs,
-    );
-
-    it(
-      'resolvePortTarget answers for a running sandbox and refuses the wrong state',
-      async () => {
-        const id = await fresh();
-        const target = await executor.resolvePortTarget(id, 8000);
-        expect(target.host).not.toBe('');
-        expect(target.port).toBeGreaterThan(0);
-        await executor.freeze(id);
-        await expect(executor.resolvePortTarget(id, 8000)).rejects.toThrow(
-          `container ${id} is paused, expected running`,
-        );
-      },
-      timeoutMs,
-    );
-
-    it(
-      'stopping the sandbox settles a running command in bounded time',
-      async () => {
-        // The shape of the ending is not pinned — the real engine may report
-        // 137 or lose the exit code entirely; settling at all is the contract
-        // (a dangling wait would strand every process-table subscriber).
-        const id = await fresh();
-        const handle = await executor.execStream(id, {
-          command: 'sleep 30',
-          timeoutSeconds: 60,
-          onStdout: () => {},
-          onStderr: () => {},
-        });
-        await executor.freeze(id);
-        await executor.stop(id);
-        const outcome = await Promise.race([
-          handle.wait().then(
-            () => 'settled',
-            () => 'settled',
-          ),
-          new Promise((resolve) =>
-            setTimeout(() => resolve('hung'), timeoutMs - 1_000),
-          ),
-        ]);
-        expect(outcome).toBe('settled');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'writeFiles then readFile round-trips text',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: '/home/user/hello.txt', content: Buffer.from('hello\n') },
-        ]);
-        const read = await executor.readFile(id, '/home/user/hello.txt');
-        expect(read.toString('utf8')).toBe('hello\n');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'file content round-trips byte-exact, binary included',
-      async () => {
-        const id = await fresh();
-        // Every byte value, repeated — any encoding sloppiness (utf8 coercion,
-        // base64 mangling, CR/LF translation) breaks the exact comparison.
-        const bytes = Buffer.alloc(256 * 64);
-        for (let i = 0; i < bytes.length; i++) bytes[i] = i % 256;
-        await executor.writeFiles(id, [
-          { path: '/home/user/blob.bin', content: bytes },
-        ]);
-        const read = await executor.readFile(id, '/home/user/blob.bin');
-        expect(read.equals(bytes)).toBe(true);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'writeFiles writes the whole batch',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: '/home/user/a.txt', content: Buffer.from('a') },
-          { path: '/home/user/b.txt', content: Buffer.from('b') },
-          { path: '/home/user/c.txt', content: Buffer.from('c') },
-        ]);
-        expect(
-          (await executor.readFile(id, '/home/user/a.txt')).toString(),
-        ).toBe('a');
-        expect(
-          (await executor.readFile(id, '/home/user/b.txt')).toString(),
-        ).toBe('b');
-        expect(
-          (await executor.readFile(id, '/home/user/c.txt')).toString(),
-        ).toBe('c');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'relative paths resolve against /home/user',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: 'rel.txt', content: Buffer.from('via relative') },
-        ]);
-        const read = await executor.readFile(id, '/home/user/rel.txt');
-        expect(read.toString('utf8')).toBe('via relative');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'writeFiles creates missing parent directories',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          {
-            path: '/home/user/deep/er/nested.txt',
-            content: Buffer.from('deep'),
-          },
-        ]);
-        const read = await executor.readFile(
-          id,
-          '/home/user/deep/er/nested.txt',
-        );
-        expect(read.toString('utf8')).toBe('deep');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'writing an existing path overwrites it',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: '/home/user/v.txt', content: Buffer.from('first') },
-        ]);
-        await executor.writeFiles(id, [
-          { path: '/home/user/v.txt', content: Buffer.from('second') },
-        ]);
-        const read = await executor.readFile(id, '/home/user/v.txt');
-        expect(read.toString('utf8')).toBe('second');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'files live on the disk: they survive stop, start, even a vanished container',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: '/home/user/keep.txt', content: Buffer.from('still here') },
-        ]);
-        await executor.freeze(id);
-        await executor.stop(id);
-        // The container object itself is lost (a prune) — the disk, which
-        // holds the files, is the sandbox's actual body.
-        await subject.vanishContainer(id);
-        await executor.start(id);
-        const read = await executor.readFile(id, '/home/user/keep.txt');
-        expect(read.toString('utf8')).toBe('still here');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'readFile on a missing path throws FileNotFoundError',
-      async () => {
-        const id = await fresh();
-        const missing = '/home/user/absent.txt';
-        const error = await executor.readFile(id, missing).catch((e) => e);
-        expect(error).toBeInstanceOf(FileNotFoundError);
-        expect(error.message).toBe(`no such file: ${missing}`);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'readFile on a directory throws NotAFileError',
-      async () => {
-        const id = await fresh();
-        // /home/user exists as a directory in every sandbox by construction.
-        const error = await executor.readFile(id, '/home/user').catch((e) => e);
-        expect(error).toBeInstanceOf(NotAFileError);
-        expect(error.message).toBe('not a regular file: /home/user');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'writeFiles onto a directory throws NotAFileError',
-      async () => {
-        const id = await fresh();
-        const error = await executor
-          .writeFiles(id, [{ path: '/home/user', content: Buffer.from('x') }])
-          .catch((e) => e);
-        expect(error).toBeInstanceOf(NotAFileError);
-        expect(error.message).toBe('not a regular file: /home/user');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'readFile refuses an over-limit file with its actual size, never truncates',
-      async () => {
-        const id = await fresh();
-        // One byte over the line. The executor's write path is deliberately
-        // uncapped (the protocol schema is the write-cap adjudicator), which
-        // is exactly what lets the exam stage an over-limit file to read.
-        const size = FILE_SIZE_LIMIT_BYTES + 1;
-        await executor.writeFiles(id, [
-          { path: '/home/user/big.bin', content: Buffer.alloc(size) },
-        ]);
-        const error = await executor
-          .readFile(id, '/home/user/big.bin')
-          .catch((e) => e);
-        expect(error).toBeInstanceOf(FileTooLargeError);
-        expect(error.message).toBe(
-          `file too large: /home/user/big.bin is ${size} bytes, limit ${FILE_SIZE_LIMIT_BYTES}`,
-        );
-      },
-      timeoutMs * 4,
-    );
-
-    it(
-      'rejects file operations on a container that is not running',
-      async () => {
-        const paused = await fresh();
-        await executor.freeze(paused);
-        await expect(
-          executor.writeFiles(paused, [
-            { path: 'x.txt', content: Buffer.from('x') },
-          ]),
-        ).rejects.toThrow(/is paused, expected running/);
-        await expect(executor.readFile(paused, 'x.txt')).rejects.toThrow(
-          /is paused, expected running/,
-        );
-
-        await expect(executor.readFile(randomUUID(), 'x.txt')).rejects.toThrow(
-          /is absent, expected running/,
-        );
-      },
-      timeoutMs,
-    );
-
-    it(
-      'statEntry reports a file with its real metadata',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: '/home/user/s.txt', content: Buffer.from('12345') },
-        ]);
-        // Relative path resolves like every other file verb.
-        const entry = await executor.statEntry(id, 's.txt');
-        expect(entry).toMatchObject({
-          name: 's.txt',
-          path: '/home/user/s.txt',
-          type: 'file',
-          sizeBytes: 5,
-          mode: 0o644,
-          owner: 'user',
-          group: 'user',
-        });
-        // Written moments ago; both executors report a live clock.
-        expect(
-          Math.abs(Date.parse(entry.modifiedTime) - Date.now()),
-        ).toBeLessThan(60_000);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'statEntry reports directories and refuses missing paths',
-      async () => {
-        const id = await fresh();
-        const home = await executor.statEntry(id, '/home/user');
-        expect(home).toMatchObject({
-          name: 'user',
-          path: '/home/user',
-          type: 'dir',
-          mode: 0o755,
-          owner: 'user',
-        });
-
-        const missing = '/home/user/nope';
-        const error = await executor.statEntry(id, missing).catch((e) => e);
-        expect(error).toBeInstanceOf(FileNotFoundError);
-        expect(error.message).toBe(`no such file: ${missing}`);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'listDir walks exactly as deep as asked, sorted by path',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: '/home/user/a.txt', content: Buffer.from('a') },
-          { path: '/home/user/sub/b.txt', content: Buffer.from('b') },
-        ]);
-        // Depth 1: the file, the created dir — and lost+found, the mkfs
-        // artifact every real disk root carries; the listing shows reality.
-        const one = await executor.listDir(id, '/home/user', 1);
-        expect(one.map((e) => [e.path, e.type])).toEqual([
-          ['/home/user/a.txt', 'file'],
-          ['/home/user/lost+found', 'dir'],
-          ['/home/user/sub', 'dir'],
-        ]);
-        const two = await executor.listDir(id, '/home/user', 2);
-        expect(two.map((e) => e.path)).toEqual([
-          '/home/user/a.txt',
-          '/home/user/lost+found',
-          '/home/user/sub',
-          '/home/user/sub/b.txt',
-        ]);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'listDir refuses files and missing paths with the right errors',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: '/home/user/plain.txt', content: Buffer.from('x') },
-        ]);
-        const onFile = await executor
-          .listDir(id, '/home/user/plain.txt', 1)
-          .catch((e) => e);
-        expect(onFile).toBeInstanceOf(NotADirectoryError);
-        expect(onFile.message).toBe('not a directory: /home/user/plain.txt');
-
-        const onMissing = await executor
-          .listDir(id, '/home/user/void', 1)
-          .catch((e) => e);
-        expect(onMissing).toBeInstanceOf(FileNotFoundError);
-        expect(onMissing.message).toBe('no such file: /home/user/void');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'makeDir creates with parents, and reports "already there" as false',
-      async () => {
-        const id = await fresh();
-        expect(await executor.makeDir(id, '/home/user/mk/deep')).toBe(true);
-        expect(
-          await executor.statEntry(id, '/home/user/mk/deep'),
-        ).toMatchObject({ type: 'dir', owner: 'user' });
-        // Again: already exists — false, not an error, whatever is there.
-        expect(await executor.makeDir(id, '/home/user/mk/deep')).toBe(false);
-        await executor.writeFiles(id, [
-          { path: '/home/user/mk/file.txt', content: Buffer.from('f') },
-        ]);
-        expect(await executor.makeDir(id, '/home/user/mk/file.txt')).toBe(
-          false,
-        );
-      },
-      timeoutMs,
-    );
-
-    it(
-      'move renames a file and refuses a missing source',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: '/home/user/m1.txt', content: Buffer.from('payload') },
-        ]);
-        const moved = await executor.move(
-          id,
-          '/home/user/m1.txt',
-          '/home/user/m2.txt',
-        );
-        expect(moved).toMatchObject({
-          path: '/home/user/m2.txt',
-          type: 'file',
-          sizeBytes: 7,
-        });
-        const gone = await executor
-          .readFile(id, '/home/user/m1.txt')
-          .catch((e) => e);
-        expect(gone).toBeInstanceOf(FileNotFoundError);
-        expect(
-          (await executor.readFile(id, '/home/user/m2.txt')).toString(),
-        ).toBe('payload');
-
-        const missing = await executor
-          .move(id, '/home/user/void.txt', '/home/user/x.txt')
-          .catch((e) => e);
-        expect(missing).toBeInstanceOf(FileNotFoundError);
-        expect(missing.message).toBe('no such file: /home/user/void.txt');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'remove takes a file, takes a tree, refuses what is not there',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: '/home/user/r/a.txt', content: Buffer.from('a') },
-          { path: '/home/user/r/sub/b.txt', content: Buffer.from('b') },
-          { path: '/home/user/single.txt', content: Buffer.from('s') },
-        ]);
-        await executor.remove(id, '/home/user/single.txt');
-        await executor.remove(id, '/home/user/r');
-        const statR = await executor
-          .statEntry(id, '/home/user/r')
-          .catch((e) => e);
-        expect(statR).toBeInstanceOf(FileNotFoundError);
-
-        const again = await executor.remove(id, '/home/user/r').catch((e) => e);
-        expect(again).toBeInstanceOf(FileNotFoundError);
-        expect(again.message).toBe('no such file: /home/user/r');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'the streaming file path is the uncapped one: over-limit content round-trips byte-exact',
-      async () => {
-        const id = await fresh();
-        // Past the buffered API's 16 MiB line — only the stream may carry it.
-        const size = FILE_SIZE_LIMIT_BYTES + 5;
-        const big = Buffer.alloc(size);
-        for (let i = 0; i < size; i += 4096) big[i] = i % 251;
-        const half = Math.floor(size / 2);
-        await executor.writeFileStream(
-          id,
-          '/home/user/big-stream.bin',
-          Readable.from([big.subarray(0, half), big.subarray(half)]),
-        );
-        const chunks: Buffer[] = [];
-        await executor.readFileStream(id, '/home/user/big-stream.bin', (c) => {
-          chunks.push(Buffer.from(c));
-        });
-        expect(Buffer.concat(chunks).equals(big)).toBe(true);
-        // The buffered read still refuses it: two paths, two contracts.
-        await expect(
-          executor.readFile(id, '/home/user/big-stream.bin'),
-        ).rejects.toThrow(FileTooLargeError);
-      },
-      timeoutMs * 4,
-    );
-
-    it(
-      'streaming file verbs throw the same typed errors as the buffered ones',
-      async () => {
-        const id = await fresh();
-        const missing = await executor
-          .readFileStream(id, '/home/user/void.bin', () => {})
-          .catch((e) => e);
-        expect(missing).toBeInstanceOf(FileNotFoundError);
-        expect(missing.message).toBe('no such file: /home/user/void.bin');
-
-        const onDir = await executor
-          .readFileStream(id, '/home/user', () => {})
-          .catch((e) => e);
-        expect(onDir).toBeInstanceOf(NotAFileError);
-        expect(onDir.message).toBe('not a regular file: /home/user');
-
-        const writeDir = await executor
-          .writeFileStream(id, '/home/user', Readable.from([Buffer.from('x')]))
-          .catch((e) => e);
-        expect(writeDir).toBeInstanceOf(NotAFileError);
-        expect(writeDir.message).toBe('not a regular file: /home/user');
-      },
-      timeoutMs,
-    );
-
-    // ---- watchDir ------------------------------------------------------
-    // Assertions are inclusion, never counts: one real write can surface as
-    // several MODIFY lines, and event multiplicity is the kernel's business,
-    // not the contract's.
-
-    /** Collects events; watch() must be awaited before the change is made. */
-    function eventLog() {
-      const events: Array<{ name: string; type: string }> = [];
-      return {
-        events,
-        onEvent: (e: { name: string; type: string }) => {
-          events.push({ ...e });
-        },
-        has: (name: string, type: string) =>
-          events.some((e) => e.name === name && e.type === type),
-      };
-    }
-
-    it(
-      'a watcher sees a new file as create and write, an overwrite as write',
-      async () => {
-        const id = await fresh();
-        const log = eventLog();
-        const watch = await executor.watchDir(id, {
-          path: '/home/user',
-          recursive: false,
-          onEvent: log.onEvent,
-          onEnd: () => {},
-        });
-        await executor.writeFiles(id, [
-          { path: 'seen.txt', content: Buffer.from('one') },
-        ]);
-        await until(() => log.has('seen.txt', 'create'));
-        await until(() => log.has('seen.txt', 'write'));
-
-        log.events.length = 0;
-        await executor.writeFiles(id, [
-          { path: 'seen.txt', content: Buffer.from('two') },
-        ]);
-        await until(() => log.has('seen.txt', 'write'));
-        expect(log.has('seen.txt', 'create')).toBe(false);
-        await watch.stop();
-      },
-      timeoutMs,
-    );
-
-    it(
-      'a watcher sees removals, and a move as rename plus create',
-      async () => {
-        const id = await fresh();
-        await executor.writeFiles(id, [
-          { path: 'old.txt', content: Buffer.from('x') },
-          { path: 'doomed.txt', content: Buffer.from('y') },
-        ]);
-        const log = eventLog();
-        const watch = await executor.watchDir(id, {
-          path: '/home/user',
-          recursive: false,
-          onEvent: log.onEvent,
-          onEnd: () => {},
-        });
-        await executor.remove(id, 'doomed.txt');
-        await until(() => log.has('doomed.txt', 'remove'));
-
-        await executor.move(id, 'old.txt', 'new.txt');
-        await until(() => log.has('old.txt', 'rename'));
-        await until(() => log.has('new.txt', 'create'));
-        await watch.stop();
-      },
-      timeoutMs,
-    );
-
-    it(
-      'subtree events reach a recursive watcher only, with subdir-relative names',
-      async () => {
-        const id = await fresh();
-        await executor.makeDir(id, '/home/user/sub');
-        const flat = eventLog();
-        const deep = eventLog();
-        const flatWatch = await executor.watchDir(id, {
-          path: '/home/user',
-          recursive: false,
-          onEvent: flat.onEvent,
-          onEnd: () => {},
-        });
-        const deepWatch = await executor.watchDir(id, {
-          path: '/home/user',
-          recursive: true,
-          onEvent: deep.onEvent,
-          onEnd: () => {},
-        });
-        await executor.writeFiles(id, [
-          { path: 'sub/inner.txt', content: Buffer.from('deep') },
-        ]);
-        await until(() => deep.has('sub/inner.txt', 'create'));
-        expect(flat.events).toEqual([]);
-        await flatWatch.stop();
-        await deepWatch.stop();
-      },
-      timeoutMs,
-    );
-
-    it(
-      'a recursive watcher follows directories created after it started',
-      async () => {
-        // Measured under gVisor 2026-07-10: inotifywait -r adds watches for
-        // directories born while it is running; the fake's prefix matching
-        // gives the same answer.
-        const id = await fresh();
-        const log = eventLog();
-        const watch = await executor.watchDir(id, {
-          path: '/home/user',
-          recursive: true,
-          onEvent: log.onEvent,
-          onEnd: () => {},
-        });
-        await executor.makeDir(id, '/home/user/born-later');
-        await until(() => log.has('born-later', 'create'));
-        await executor.writeFiles(id, [
-          { path: 'born-later/inside.txt', content: Buffer.from('!') },
-        ]);
-        await until(() => log.has('born-later/inside.txt', 'create'));
-        await watch.stop();
-      },
-      timeoutMs,
-    );
-
-    it(
-      'stop() ends delivery; the watcher does not call onEnd for its own stop',
-      async () => {
-        const id = await fresh();
-        const log = eventLog();
-        let ended = false;
-        const watch = await executor.watchDir(id, {
-          path: '/home/user',
-          recursive: false,
-          onEvent: log.onEvent,
-          onEnd: () => {
-            ended = true;
-          },
-        });
-        await watch.stop();
-        await executor.writeFiles(id, [
-          { path: 'after-stop.txt', content: Buffer.from('x') },
-        ]);
-        // Bounded quiet: nothing arrives for a change made after stop().
-        await new Promise((resolve) => setTimeout(resolve, 300));
-        expect(log.events).toEqual([]);
-        expect(ended).toBe(false);
-      },
-      timeoutMs,
-    );
-
-    it(
-      'watchDir refuses a missing path and a file path with the typed errors',
-      async () => {
-        const id = await fresh();
-        const missing = await executor
-          .watchDir(id, {
-            path: '/home/user/nowhere',
-            recursive: false,
-            onEvent: () => {},
-            onEnd: () => {},
-          })
-          .catch((e) => e);
-        expect(missing).toBeInstanceOf(FileNotFoundError);
-        expect(missing.message).toBe('no such file: /home/user/nowhere');
-
-        await executor.writeFiles(id, [
-          { path: 'plain.txt', content: Buffer.from('x') },
-        ]);
-        const onFile = await executor
-          .watchDir(id, {
-            path: 'plain.txt',
-            recursive: false,
-            onEvent: () => {},
-            onEnd: () => {},
-          })
-          .catch((e) => e);
-        expect(onFile).toBeInstanceOf(NotADirectoryError);
-        expect(onFile.message).toBe('not a directory: /home/user/plain.txt');
-      },
-      timeoutMs,
-    );
-
-    it(
-      'the container stopping ends the watcher through onEnd',
-      async () => {
-        const id = await fresh();
-        let ended: Error | undefined;
-        const watch = await executor.watchDir(id, {
-          path: '/home/user',
-          recursive: false,
-          onEvent: () => {},
-          onEnd: (error) => {
-            ended = error ?? new Error('ended without error');
-          },
-        });
-        await executor.freeze(id);
-        await executor.stop(id);
-        await until(() => ended !== undefined);
-        // Ending was the container's doing, not stop()'s — which now finds
-        // nothing left to do and must still resolve.
-        await watch.stop();
-      },
-      timeoutMs,
-    );
-
-    it(
-      'a watcher survives freeze/unfreeze and reports changes made after',
-      async () => {
-        const id = await fresh();
-        const log = eventLog();
-        const watch = await executor.watchDir(id, {
-          path: '/home/user',
-          recursive: false,
-          onEvent: log.onEvent,
-          onEnd: () => {},
-        });
-        await executor.freeze(id);
-        await executor.unfreeze(id);
-        await executor.writeFiles(id, [
-          { path: 'thawed.txt', content: Buffer.from('back') },
-        ]);
-        await until(() => log.has('thawed.txt', 'create'));
-        await watch.stop();
-      },
-      timeoutMs,
-    );
-  });
-}
diff --git a/packages/server/src/executor/contract/entries.ts b/packages/server/src/executor/contract/entries.ts
new file mode 100644
index 0000000..c4a4ae4
--- /dev/null
+++ b/packages/server/src/executor/contract/entries.ts
@@ -0,0 +1,187 @@
+import { describe, expect, it } from 'vitest';
+import { FileNotFoundError, NotADirectoryError } from '../executor';
+import type { ContractContext } from './index';
+
+/** The directory-entry verbs: stat, list, mkdir, move, remove. */
+export function entryTests(ctx: ContractContext) {
+  const { timeoutMs } = ctx;
+
+  describe('directory entries', () => {
+    it(
+      'statEntry reports a file with its real metadata',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/s.txt', content: Buffer.from('12345') },
+        ]);
+        // Relative path resolves like every other file verb.
+        const entry = await ctx.executor.statEntry(id, 's.txt');
+        expect(entry).toMatchObject({
+          name: 's.txt',
+          path: '/home/user/s.txt',
+          type: 'file',
+          sizeBytes: 5,
+          mode: 0o644,
+          owner: 'user',
+          group: 'user',
+        });
+        // Written moments ago; both executors report a live clock.
+        expect(
+          Math.abs(Date.parse(entry.modifiedTime) - Date.now()),
+        ).toBeLessThan(60_000);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'statEntry reports directories and refuses missing paths',
+      async () => {
+        const id = await ctx.fresh();
+        const home = await ctx.executor.statEntry(id, '/home/user');
+        expect(home).toMatchObject({
+          name: 'user',
+          path: '/home/user',
+          type: 'dir',
+          mode: 0o755,
+          owner: 'user',
+        });
+
+        const missing = '/home/user/nope';
+        const error = await ctx.executor.statEntry(id, missing).catch((e) => e);
+        expect(error).toBeInstanceOf(FileNotFoundError);
+        expect(error.message).toBe(`no such file: ${missing}`);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'listDir walks exactly as deep as asked, sorted by path',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/a.txt', content: Buffer.from('a') },
+          { path: '/home/user/sub/b.txt', content: Buffer.from('b') },
+        ]);
+        // Depth 1: the file, the created dir — and lost+found, the mkfs
+        // artifact every real disk root carries; the listing shows reality.
+        const one = await ctx.executor.listDir(id, '/home/user', 1);
+        expect(one.map((e) => [e.path, e.type])).toEqual([
+          ['/home/user/a.txt', 'file'],
+          ['/home/user/lost+found', 'dir'],
+          ['/home/user/sub', 'dir'],
+        ]);
+        const two = await ctx.executor.listDir(id, '/home/user', 2);
+        expect(two.map((e) => e.path)).toEqual([
+          '/home/user/a.txt',
+          '/home/user/lost+found',
+          '/home/user/sub',
+          '/home/user/sub/b.txt',
+        ]);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'listDir refuses files and missing paths with the right errors',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/plain.txt', content: Buffer.from('x') },
+        ]);
+        const onFile = await ctx.executor
+          .listDir(id, '/home/user/plain.txt', 1)
+          .catch((e) => e);
+        expect(onFile).toBeInstanceOf(NotADirectoryError);
+        expect(onFile.message).toBe('not a directory: /home/user/plain.txt');
+
+        const onMissing = await ctx.executor
+          .listDir(id, '/home/user/void', 1)
+          .catch((e) => e);
+        expect(onMissing).toBeInstanceOf(FileNotFoundError);
+        expect(onMissing.message).toBe('no such file: /home/user/void');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'makeDir creates with parents, and reports "already there" as false',
+      async () => {
+        const id = await ctx.fresh();
+        expect(await ctx.executor.makeDir(id, '/home/user/mk/deep')).toBe(true);
+        expect(
+          await ctx.executor.statEntry(id, '/home/user/mk/deep'),
+        ).toMatchObject({ type: 'dir', owner: 'user' });
+        // Again: already exists — false, not an error, whatever is there.
+        expect(await ctx.executor.makeDir(id, '/home/user/mk/deep')).toBe(
+          false,
+        );
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/mk/file.txt', content: Buffer.from('f') },
+        ]);
+        expect(await ctx.executor.makeDir(id, '/home/user/mk/file.txt')).toBe(
+          false,
+        );
+      },
+      timeoutMs,
+    );
+
+    it(
+      'move renames a file and refuses a missing source',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/m1.txt', content: Buffer.from('payload') },
+        ]);
+        const moved = await ctx.executor.move(
+          id,
+          '/home/user/m1.txt',
+          '/home/user/m2.txt',
+        );
+        expect(moved).toMatchObject({
+          path: '/home/user/m2.txt',
+          type: 'file',
+          sizeBytes: 7,
+        });
+        const gone = await ctx.executor
+          .readFile(id, '/home/user/m1.txt')
+          .catch((e) => e);
+        expect(gone).toBeInstanceOf(FileNotFoundError);
+        expect(
+          (await ctx.executor.readFile(id, '/home/user/m2.txt')).toString(),
+        ).toBe('payload');
+
+        const missing = await ctx.executor
+          .move(id, '/home/user/void.txt', '/home/user/x.txt')
+          .catch((e) => e);
+        expect(missing).toBeInstanceOf(FileNotFoundError);
+        expect(missing.message).toBe('no such file: /home/user/void.txt');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'remove takes a file, takes a tree, refuses what is not there',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/r/a.txt', content: Buffer.from('a') },
+          { path: '/home/user/r/sub/b.txt', content: Buffer.from('b') },
+          { path: '/home/user/single.txt', content: Buffer.from('s') },
+        ]);
+        await ctx.executor.remove(id, '/home/user/single.txt');
+        await ctx.executor.remove(id, '/home/user/r');
+        const statR = await ctx.executor
+          .statEntry(id, '/home/user/r')
+          .catch((e) => e);
+        expect(statR).toBeInstanceOf(FileNotFoundError);
+
+        const again = await ctx.executor
+          .remove(id, '/home/user/r')
+          .catch((e) => e);
+        expect(again).toBeInstanceOf(FileNotFoundError);
+        expect(again.message).toBe('no such file: /home/user/r');
+      },
+      timeoutMs,
+    );
+  });
+}
diff --git a/packages/server/src/executor/contract/exec.ts b/packages/server/src/executor/contract/exec.ts
new file mode 100644
index 0000000..75d2d07
--- /dev/null
+++ b/packages/server/src/executor/contract/exec.ts
@@ -0,0 +1,154 @@
+import { randomUUID } from 'node:crypto';
+import { EXEC_OUTPUT_LIMIT_BYTES } from '@dormice/shared';
+import { describe, expect, it } from 'vitest';
+import type { ContractContext } from './index';
+
+/** The buffered exec verb: run to completion, one result object back. */
+export function execTests(ctx: ContractContext) {
+  const { timeoutMs } = ctx;
+
+  describe('exec', () => {
+    it(
+      'exec runs a command and returns its buffered result',
+      async () => {
+        const id = await ctx.fresh();
+        const result = await ctx.executor.exec(id, {
+          command: 'echo hi',
+          timeoutSeconds: 30,
+        });
+        expect(result).toEqual({
+          exitCode: 0,
+          stdout: 'hi\n',
+          stderr: '',
+          stdoutTruncated: false,
+          stderrTruncated: false,
+        });
+      },
+      timeoutMs,
+    );
+
+    it(
+      'exec reports a nonzero exit code as a result, not an error',
+      async () => {
+        const id = await ctx.fresh();
+        const result = await ctx.executor.exec(id, {
+          command: 'exit 3',
+          timeoutSeconds: 30,
+        });
+        expect(result.exitCode).toBe(3);
+      },
+      timeoutMs,
+    );
+
+    it(
+      "exec answers an unknown command with bash's own 127",
+      async () => {
+        const id = await ctx.fresh();
+        const result = await ctx.executor.exec(id, {
+          command: 'no-such-command-xyz',
+          timeoutSeconds: 30,
+        });
+        expect(result.exitCode).toBe(127);
+        expect(result.stderr).toMatch(/command not found/);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'exec honors cwd and defaults to /home/user',
+      async () => {
+        const id = await ctx.fresh();
+        const inTmp = await ctx.executor.exec(id, {
+          command: 'pwd',
+          cwd: '/tmp',
+          timeoutSeconds: 30,
+        });
+        expect(inTmp.stdout).toBe('/tmp\n');
+        const inHome = await ctx.executor.exec(id, {
+          command: 'pwd',
+          timeoutSeconds: 30,
+        });
+        expect(inHome.stdout).toBe('/home/user\n');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'exec passes env vars through',
+      async () => {
+        const id = await ctx.fresh();
+        const result = await ctx.executor.exec(id, {
+          command: 'printenv DORMICE_CONTRACT_PROBE',
+          env: { DORMICE_CONTRACT_PROBE: '42' },
+          timeoutSeconds: 30,
+        });
+        expect(result.exitCode).toBe(0);
+        expect(result.stdout).toBe('42\n');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'rejects exec on a container that is not running',
+      async () => {
+        const paused = await ctx.fresh();
+        await ctx.executor.freeze(paused);
+        await expect(
+          ctx.executor.exec(paused, { command: 'echo hi', timeoutSeconds: 30 }),
+        ).rejects.toThrow(/is paused, expected running/);
+
+        const stopped = await ctx.freshStopped();
+        await expect(
+          ctx.executor.exec(stopped, {
+            command: 'echo hi',
+            timeoutSeconds: 30,
+          }),
+        ).rejects.toThrow(/is stopped, expected running/);
+
+        await expect(
+          ctx.executor.exec(randomUUID(), {
+            command: 'echo hi',
+            timeoutSeconds: 30,
+          }),
+        ).rejects.toThrow(/is absent, expected running/);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'the timeout kills the command in-container: exit 137',
+      async () => {
+        const id = await ctx.fresh();
+        const before = Date.now();
+        const result = await ctx.executor.exec(id, {
+          command: 'sleep 5',
+          timeoutSeconds: 1,
+        });
+        // Well under the 5s sleep proves the kill actually landed; the
+        // slack above 1s absorbs a loaded docker host.
+        expect(Date.now() - before).toBeLessThan(4_000);
+        expect(result.exitCode).toBe(137);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'exec caps each stream and reports the truncation',
+      async () => {
+        const id = await ctx.fresh();
+        // seq, not a giant echo literal: MAX_ARG_STRLEN caps one argv
+        // element at 128 KiB, so an over-cap echo argument would die in
+        // execve on the real executor instead of testing the cap.
+        const result = await ctx.executor.exec(id, {
+          command: 'seq 1 300000',
+          timeoutSeconds: 60,
+        });
+        expect(result.exitCode).toBe(0);
+        expect(result.stdoutTruncated).toBe(true);
+        expect(result.stdout.length).toBe(EXEC_OUTPUT_LIMIT_BYTES);
+        expect(result.stderrTruncated).toBe(false);
+      },
+      timeoutMs,
+    );
+  });
+}
diff --git a/packages/server/src/executor/contract/execStream.ts b/packages/server/src/executor/contract/execStream.ts
new file mode 100644
index 0000000..358ce8f
--- /dev/null
+++ b/packages/server/src/executor/contract/execStream.ts
@@ -0,0 +1,359 @@
+import { describe, expect, it } from 'vitest';
+import type { ContractContext } from './index';
+
+/** The streaming exec verb: live output, stdin, signals, PTY sessions. */
+export function execStreamTests(ctx: ContractContext) {
+  const { timeoutMs } = ctx;
+
+  describe('execStream and PTY', () => {
+    it(
+      'execStream delivers output live, chunk by chunk',
+      async () => {
+        const id = await ctx.fresh();
+        const chunks: Array<{ text: string; at: number }> = [];
+        const handle = await ctx.executor.execStream(id, {
+          command: 'echo first; sleep 1; echo second',
+          timeoutSeconds: 30,
+          onStdout: (c) => {
+            chunks.push({ text: c.toString('utf8'), at: Date.now() });
+          },
+          onStderr: () => {},
+        });
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(0);
+        expect(chunks.map((c) => c.text).join('')).toBe('first\nsecond\n');
+        // The anti-buffering assertion: with the sleep between the echoes,
+        // live delivery shows a real gap between the first and last chunk.
+        // A buffered implementation delivers everything at once — gap zero.
+        const at = chunks.map((c) => c.at);
+        expect(Math.max(...at) - Math.min(...at)).toBeGreaterThanOrEqual(500);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'execStream reports a nonzero exit through wait, not an error',
+      async () => {
+        const id = await ctx.fresh();
+        const handle = await ctx.executor.execStream(id, {
+          command: 'exit 7',
+          timeoutSeconds: 30,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await expect(handle.wait()).resolves.toEqual({ exitCode: 7 });
+      },
+      timeoutMs,
+    );
+
+    it(
+      'execStream timeout kills in-container; chunks already delivered stay delivered',
+      async () => {
+        const id = await ctx.fresh();
+        const seen: string[] = [];
+        const before = Date.now();
+        const handle = await ctx.executor.execStream(id, {
+          command: 'echo early; sleep 5',
+          timeoutSeconds: 1,
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        const { exitCode } = await handle.wait();
+        expect(Date.now() - before).toBeLessThan(4_000);
+        expect(exitCode).toBe(137);
+        expect(seen.join('')).toBe('early\n');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'execStream stdin round-trips: sendStdin chunks echo back, closeStdin is EOF',
+      async () => {
+        const id = await ctx.fresh();
+        const seen: string[] = [];
+        const handle = await ctx.executor.execStream(id, {
+          command: 'cat',
+          timeoutSeconds: 30,
+          stdin: true,
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        await handle.sendStdin(Buffer.from('hello '));
+        await handle.sendStdin(Buffer.from('world'));
+        await handle.closeStdin();
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(0);
+        expect(seen.join('')).toBe('hello world');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'execStream closeStdin with nothing written ends the command cleanly',
+      async () => {
+        const id = await ctx.fresh();
+        const seen: string[] = [];
+        const handle = await ctx.executor.execStream(id, {
+          command: 'cat',
+          timeoutSeconds: 30,
+          stdin: true,
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        await handle.closeStdin();
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(0);
+        expect(seen.join('')).toBe('');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'sendStdin on a command started without stdin refuses honestly',
+      async () => {
+        const id = await ctx.fresh();
+        const handle = await ctx.executor.execStream(id, {
+          command: 'sleep 5',
+          timeoutSeconds: 30,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await expect(handle.sendStdin(Buffer.from('x'))).rejects.toThrow(
+          'process was started without stdin',
+        );
+        await expect(handle.closeStdin()).rejects.toThrow(
+          'process was started without stdin',
+        );
+        await handle.signal('SIGKILL');
+        await handle.wait();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'sendStdin after closeStdin refuses: stdin is closed',
+      async () => {
+        const id = await ctx.fresh();
+        const handle = await ctx.executor.execStream(id, {
+          command: 'cat',
+          timeoutSeconds: 30,
+          stdin: true,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await handle.closeStdin();
+        await expect(handle.sendStdin(Buffer.from('late'))).rejects.toThrow(
+          'stdin is closed',
+        );
+        await handle.wait();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'signal SIGKILL lands as exit 137; delivered chunks stay delivered',
+      async () => {
+        const id = await ctx.fresh();
+        const seen: string[] = [];
+        const handle = await ctx.executor.execStream(id, {
+          command: 'echo early; sleep 30',
+          timeoutSeconds: 60,
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        // Wait for the first chunk so the kill provably interrupts, not races.
+        const before = Date.now();
+        while (seen.length === 0 && Date.now() - before < 5_000) {
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        await handle.signal('SIGKILL');
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(137);
+        expect(seen.join('')).toBe('early\n');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'signal SIGTERM lands as exit 143',
+      async () => {
+        const id = await ctx.fresh();
+        const handle = await ctx.executor.execStream(id, {
+          command: 'sleep 30',
+          timeoutSeconds: 60,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await handle.signal('SIGTERM');
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(143);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'execStream emits nothing before it resolves',
+      async () => {
+        const id = await ctx.fresh();
+        let resolved = false;
+        let leaked = false;
+        const handle = await ctx.executor.execStream(id, {
+          command: 'echo eager',
+          timeoutSeconds: 30,
+          onStdout: () => {
+            if (!resolved) leaked = true;
+          },
+          onStderr: () => {},
+        });
+        resolved = true;
+        await handle.wait();
+        expect(leaked).toBe(false);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a running command survives freeze/unfreeze and completes afterwards',
+      async () => {
+        const id = await ctx.fresh();
+        const seen: string[] = [];
+        const handle = await ctx.executor.execStream(id, {
+          command: 'echo started; sleep 1; echo woke',
+          timeoutSeconds: 30,
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        // Wait for proof the command is actually running before freezing:
+        // dockerd acknowledges exec start before the process has spawned
+        // (measured 2026-07-10 — a zero-gap pause wins that race and the
+        // exec dies 128 "cannot exec in a paused state"). The contract's
+        // claim is about running commands, so observe one first.
+        const before = Date.now();
+        while (seen.length === 0 && Date.now() - before < 5_000) {
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        await ctx.executor.freeze(id);
+        await ctx.executor.unfreeze(id);
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(0);
+        expect(seen.join('')).toContain('woke');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a PTY session echoes input and runs what is typed',
+      async () => {
+        const id = await ctx.fresh();
+        const seen: string[] = [];
+        const handle = await ctx.executor.execStream(id, {
+          timeoutSeconds: 60,
+          pty: { cols: 80, rows: 24 },
+          env: { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' },
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        await handle.sendStdin(Buffer.from('echo pty-marker\r'));
+        // contains, never equals: a real bash brings PS1 and escape codes.
+        await ctx.until(() => seen.join('').includes('pty-marker'));
+        await handle.sendStdin(Buffer.from('exit\r'));
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(0);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'resizePty changes what stty size reports',
+      async () => {
+        const id = await ctx.fresh();
+        const seen: string[] = [];
+        const handle = await ctx.executor.execStream(id, {
+          timeoutSeconds: 60,
+          pty: { cols: 80, rows: 24 },
+          env: { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' },
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        await handle.resizePty({ cols: 123, rows: 45 });
+        await handle.sendStdin(Buffer.from('stty size\r'));
+        await ctx.until(() => seen.join('').includes('45 123'));
+        await handle.sendStdin(Buffer.from('exit\r'));
+        await handle.wait();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a PTY dies to SIGKILL as 137; a plain command has no PTY to resize',
+      async () => {
+        const id = await ctx.fresh();
+        const pty = await ctx.executor.execStream(id, {
+          timeoutSeconds: 60,
+          pty: { cols: 80, rows: 24 },
+          env: { TERM: 'xterm-256color' },
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await pty.signal('SIGKILL');
+        expect((await pty.wait()).exitCode).toBe(137);
+
+        const plain = await ctx.executor.execStream(id, {
+          command: 'sleep 5',
+          timeoutSeconds: 30,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await expect(plain.resizePty({ cols: 1, rows: 1 })).rejects.toThrow(
+          'process has no PTY',
+        );
+        await plain.signal('SIGKILL');
+        await plain.wait();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'stopping the sandbox settles a running command in bounded time',
+      async () => {
+        // The shape of the ending is not pinned — the real engine may report
+        // 137 or lose the exit code entirely; settling at all is the contract
+        // (a dangling wait would strand every process-table subscriber).
+        const id = await ctx.fresh();
+        const handle = await ctx.executor.execStream(id, {
+          command: 'sleep 30',
+          timeoutSeconds: 60,
+          onStdout: () => {},
+          onStderr: () => {},
+        });
+        await ctx.executor.freeze(id);
+        await ctx.executor.stop(id);
+        const outcome = await Promise.race([
+          handle.wait().then(
+            () => 'settled',
+            () => 'settled',
+          ),
+          new Promise((resolve) =>
+            setTimeout(() => resolve('hung'), timeoutMs - 1_000),
+          ),
+        ]);
+        expect(outcome).toBe('settled');
+      },
+      timeoutMs,
+    );
+  });
+}
diff --git a/packages/server/src/executor/contract/files.ts b/packages/server/src/executor/contract/files.ts
new file mode 100644
index 0000000..a64d955
--- /dev/null
+++ b/packages/server/src/executor/contract/files.ts
@@ -0,0 +1,274 @@
+import { randomUUID } from 'node:crypto';
+import { Readable } from 'node:stream';
+import { FILE_SIZE_LIMIT_BYTES } from '@dormice/shared';
+import { describe, expect, it } from 'vitest';
+import {
+  FileNotFoundError,
+  FileTooLargeError,
+  NotAFileError,
+} from '../executor';
+import type { ContractContext } from './index';
+
+/** File content in and out: the buffered pair and the uncapped streams. */
+export function fileTests(ctx: ContractContext) {
+  const { timeoutMs } = ctx;
+
+  describe('files', () => {
+    it(
+      'writeFiles then readFile round-trips text',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/hello.txt', content: Buffer.from('hello\n') },
+        ]);
+        const read = await ctx.executor.readFile(id, '/home/user/hello.txt');
+        expect(read.toString('utf8')).toBe('hello\n');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'file content round-trips byte-exact, binary included',
+      async () => {
+        const id = await ctx.fresh();
+        // Every byte value, repeated — any encoding sloppiness (utf8 coercion,
+        // base64 mangling, CR/LF translation) breaks the exact comparison.
+        const bytes = Buffer.alloc(256 * 64);
+        for (let i = 0; i < bytes.length; i++) bytes[i] = i % 256;
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/blob.bin', content: bytes },
+        ]);
+        const read = await ctx.executor.readFile(id, '/home/user/blob.bin');
+        expect(read.equals(bytes)).toBe(true);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'writeFiles writes the whole batch',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/a.txt', content: Buffer.from('a') },
+          { path: '/home/user/b.txt', content: Buffer.from('b') },
+          { path: '/home/user/c.txt', content: Buffer.from('c') },
+        ]);
+        expect(
+          (await ctx.executor.readFile(id, '/home/user/a.txt')).toString(),
+        ).toBe('a');
+        expect(
+          (await ctx.executor.readFile(id, '/home/user/b.txt')).toString(),
+        ).toBe('b');
+        expect(
+          (await ctx.executor.readFile(id, '/home/user/c.txt')).toString(),
+        ).toBe('c');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'relative paths resolve against /home/user',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: 'rel.txt', content: Buffer.from('via relative') },
+        ]);
+        const read = await ctx.executor.readFile(id, '/home/user/rel.txt');
+        expect(read.toString('utf8')).toBe('via relative');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'writeFiles creates missing parent directories',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          {
+            path: '/home/user/deep/er/nested.txt',
+            content: Buffer.from('deep'),
+          },
+        ]);
+        const read = await ctx.executor.readFile(
+          id,
+          '/home/user/deep/er/nested.txt',
+        );
+        expect(read.toString('utf8')).toBe('deep');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'writing an existing path overwrites it',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/v.txt', content: Buffer.from('first') },
+        ]);
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/v.txt', content: Buffer.from('second') },
+        ]);
+        const read = await ctx.executor.readFile(id, '/home/user/v.txt');
+        expect(read.toString('utf8')).toBe('second');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'files live on the disk: they survive stop, start, even a vanished container',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/keep.txt', content: Buffer.from('still here') },
+        ]);
+        await ctx.executor.freeze(id);
+        await ctx.executor.stop(id);
+        // The container object itself is lost (a prune) — the disk, which
+        // holds the files, is the sandbox's actual body.
+        await ctx.subject.vanishContainer(id);
+        await ctx.executor.start(id);
+        const read = await ctx.executor.readFile(id, '/home/user/keep.txt');
+        expect(read.toString('utf8')).toBe('still here');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'readFile on a missing path throws FileNotFoundError',
+      async () => {
+        const id = await ctx.fresh();
+        const missing = '/home/user/absent.txt';
+        const error = await ctx.executor.readFile(id, missing).catch((e) => e);
+        expect(error).toBeInstanceOf(FileNotFoundError);
+        expect(error.message).toBe(`no such file: ${missing}`);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'readFile on a directory throws NotAFileError',
+      async () => {
+        const id = await ctx.fresh();
+        // /home/user exists as a directory in every sandbox by construction.
+        const error = await ctx.executor
+          .readFile(id, '/home/user')
+          .catch((e) => e);
+        expect(error).toBeInstanceOf(NotAFileError);
+        expect(error.message).toBe('not a regular file: /home/user');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'writeFiles onto a directory throws NotAFileError',
+      async () => {
+        const id = await ctx.fresh();
+        const error = await ctx.executor
+          .writeFiles(id, [{ path: '/home/user', content: Buffer.from('x') }])
+          .catch((e) => e);
+        expect(error).toBeInstanceOf(NotAFileError);
+        expect(error.message).toBe('not a regular file: /home/user');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'readFile refuses an over-limit file with its actual size, never truncates',
+      async () => {
+        const id = await ctx.fresh();
+        // One byte over the line. The executor's write path is deliberately
+        // uncapped (the protocol schema is the write-cap adjudicator), which
+        // is exactly what lets the exam stage an over-limit file to read.
+        const size = FILE_SIZE_LIMIT_BYTES + 1;
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/big.bin', content: Buffer.alloc(size) },
+        ]);
+        const error = await ctx.executor
+          .readFile(id, '/home/user/big.bin')
+          .catch((e) => e);
+        expect(error).toBeInstanceOf(FileTooLargeError);
+        expect(error.message).toBe(
+          `file too large: /home/user/big.bin is ${size} bytes, limit ${FILE_SIZE_LIMIT_BYTES}`,
+        );
+      },
+      timeoutMs * 4,
+    );
+
+    it(
+      'rejects file operations on a container that is not running',
+      async () => {
+        const paused = await ctx.fresh();
+        await ctx.executor.freeze(paused);
+        await expect(
+          ctx.executor.writeFiles(paused, [
+            { path: 'x.txt', content: Buffer.from('x') },
+          ]),
+        ).rejects.toThrow(/is paused, expected running/);
+        await expect(ctx.executor.readFile(paused, 'x.txt')).rejects.toThrow(
+          /is paused, expected running/,
+        );
+
+        await expect(
+          ctx.executor.readFile(randomUUID(), 'x.txt'),
+        ).rejects.toThrow(/is absent, expected running/);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'the streaming file path is the uncapped one: over-limit content round-trips byte-exact',
+      async () => {
+        const id = await ctx.fresh();
+        // Past the buffered API's 16 MiB line — only the stream may carry it.
+        const size = FILE_SIZE_LIMIT_BYTES + 5;
+        const big = Buffer.alloc(size);
+        for (let i = 0; i < size; i += 4096) big[i] = i % 251;
+        const half = Math.floor(size / 2);
+        await ctx.executor.writeFileStream(
+          id,
+          '/home/user/big-stream.bin',
+          Readable.from([big.subarray(0, half), big.subarray(half)]),
+        );
+        const chunks: Buffer[] = [];
+        await ctx.executor.readFileStream(
+          id,
+          '/home/user/big-stream.bin',
+          (c) => {
+            chunks.push(Buffer.from(c));
+          },
+        );
+        expect(Buffer.concat(chunks).equals(big)).toBe(true);
+        // The buffered read still refuses it: two paths, two contracts.
+        await expect(
+          ctx.executor.readFile(id, '/home/user/big-stream.bin'),
+        ).rejects.toThrow(FileTooLargeError);
+      },
+      timeoutMs * 4,
+    );
+
+    it(
+      'streaming file verbs throw the same typed errors as the buffered ones',
+      async () => {
+        const id = await ctx.fresh();
+        const missing = await ctx.executor
+          .readFileStream(id, '/home/user/void.bin', () => {})
+          .catch((e) => e);
+        expect(missing).toBeInstanceOf(FileNotFoundError);
+        expect(missing.message).toBe('no such file: /home/user/void.bin');
+
+        const onDir = await ctx.executor
+          .readFileStream(id, '/home/user', () => {})
+          .catch((e) => e);
+        expect(onDir).toBeInstanceOf(NotAFileError);
+        expect(onDir.message).toBe('not a regular file: /home/user');
+
+        const writeDir = await ctx.executor
+          .writeFileStream(id, '/home/user', Readable.from([Buffer.from('x')]))
+          .catch((e) => e);
+        expect(writeDir).toBeInstanceOf(NotAFileError);
+        expect(writeDir.message).toBe('not a regular file: /home/user');
+      },
+      timeoutMs,
+    );
+  });
+}
diff --git a/packages/server/src/executor/contract/index.ts b/packages/server/src/executor/contract/index.ts
new file mode 100644
index 0000000..90fca19
--- /dev/null
+++ b/packages/server/src/executor/contract/index.ts
@@ -0,0 +1,126 @@
+import { randomUUID } from 'node:crypto';
+import { afterEach, beforeEach, describe } from 'vitest';
+import type { ContainerState, Executor } from '../executor';
+import { entryTests } from './entries';
+import { execTests } from './exec';
+import { execStreamTests } from './execStream';
+import { fileTests } from './files';
+import { lifecycleTests } from './lifecycle';
+import { watchTests } from './watch';
+
+/**
+ * What a contract run needs beyond the executor itself: a way to stage the
+ * one drift an executor cannot produce through its own verbs.
+ */
+export interface ContractSubject {
+  executor: Executor;
+  /**
+   * Removes the container object while the disk stays — the drift a
+   * `docker container prune` (or any removal behind the daemon's back)
+   * leaves. The fake flips its map; the docker subject asks the engine
+   * directly. Part of the contract because "start rebuilds from the disk"
+   * and "destroy takes the leftover disk" must hold on both implementations.
+   */
+  vanishContainer(sandboxId: string): Promise<void>;
+}
+
+/**
+ * The exam harness each section receives: live views of the subject under
+ * test (rebuilt per test by beforeEach — hence getters, not snapshots) and
+ * the helpers every section leans on.
+ */
+export interface ContractContext {
+  readonly executor: Executor;
+  readonly subject: ContractSubject;
+  timeoutMs: number;
+  /** A fresh running sandbox, registered for after-test destruction. */
+  fresh(): Promise<string>;
+  /** Walks a fresh sandbox down to stopped: exited container plus disk. */
+  freshStopped(): Promise<string>;
+  stateOf(sandboxId: string): Promise<ContainerState | undefined>;
+  /** Polls until the observation holds — real output has no fixed schedule. */
+  until(check: () => boolean): Promise<void>;
+}
+
+/**
+ * The executor contract: one test suite both implementations must pass,
+ * down to the error messages. Unit tests run it against FakeExecutor
+ * everywhere; on a Linux docker host the same suite runs against
+ * DockerExecutor — that is what makes the fake a trustworthy stand-in.
+ *
+ * Observations go through listContainers() and listDisks() only, because
+ * together they are the whole public window into reality; sandbox ids are
+ * random so runs never collide on a real machine, and everything created
+ * is destroyed afterwards.
+ *
+ * One exam, one entry point: the sections under ./contract/ are chapters
+ * of this suite, never run on their own.
+ */
+export function describeExecutorContract(
+  name: string,
+  makeSubject: () => ContractSubject | Promise<ContractSubject>,
+  { timeoutMs = 5_000 }: { timeoutMs?: number } = {},
+) {
+  describe(`executor contract: ${name}`, () => {
+    let executor: Executor;
+    let subject: ContractSubject;
+    let created: string[] = [];
+
+    beforeEach(async () => {
+      subject = await makeSubject();
+      executor = subject.executor;
+      created = [];
+    });
+
+    afterEach(async () => {
+      for (const sandboxId of created) {
+        try {
+          await executor.destroy(sandboxId);
+        } catch {
+          // Already gone — the test destroyed it itself.
+        }
+      }
+    }, timeoutMs);
+
+    const ctx: ContractContext = {
+      get executor() {
+        return executor;
+      },
+      get subject() {
+        return subject;
+      },
+      timeoutMs,
+      async fresh() {
+        const sandboxId = randomUUID();
+        created.push(sandboxId);
+        await executor.create(sandboxId);
+        return sandboxId;
+      },
+      async freshStopped() {
+        const sandboxId = await ctx.fresh();
+        await executor.freeze(sandboxId);
+        await executor.stop(sandboxId);
+        return sandboxId;
+      },
+      async stateOf(sandboxId) {
+        return (await executor.listContainers()).get(sandboxId);
+      },
+      async until(check) {
+        const before = Date.now();
+        while (!check()) {
+          if (Date.now() - before > timeoutMs - 1_000) {
+            throw new Error('condition never became true');
+          }
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+      },
+    };
+
+    lifecycleTests(ctx);
+    execTests(ctx);
+    execStreamTests(ctx);
+    fileTests(ctx);
+    entryTests(ctx);
+    watchTests(ctx);
+  });
+}
diff --git a/packages/server/src/executor/contract/lifecycle.ts b/packages/server/src/executor/contract/lifecycle.ts
new file mode 100644
index 0000000..77f180e
--- /dev/null
+++ b/packages/server/src/executor/contract/lifecycle.ts
@@ -0,0 +1,247 @@
+import { randomUUID } from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+import type { ContractContext } from './index';
+
+/** Container lifecycle, the disk as the sandbox's body, and state gates. */
+export function lifecycleTests(ctx: ContractContext) {
+  const { timeoutMs } = ctx;
+
+  describe('lifecycle and disks', () => {
+    it(
+      'walks the full container lifecycle',
+      async () => {
+        const id = await ctx.fresh();
+        expect(await ctx.stateOf(id)).toBe('running');
+        await ctx.executor.freeze(id);
+        expect(await ctx.stateOf(id)).toBe('paused');
+        await ctx.executor.unfreeze(id);
+        expect(await ctx.stateOf(id)).toBe('running');
+        await ctx.executor.freeze(id);
+        await ctx.executor.stop(id);
+        expect(await ctx.stateOf(id)).toBe('stopped');
+        await ctx.executor.start(id);
+        expect(await ctx.stateOf(id)).toBe('running');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'rejects creating the same container twice',
+      async () => {
+        const id = await ctx.fresh();
+        await expect(ctx.executor.create(id)).rejects.toThrow(/already exists/);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'rejects operations from the wrong state',
+      async () => {
+        const id = await ctx.fresh();
+        await expect(ctx.executor.unfreeze(id)).rejects.toThrow(
+          /expected paused/,
+        );
+        await expect(ctx.executor.stop(id)).rejects.toThrow(/expected paused/);
+        await expect(ctx.executor.start(id)).rejects.toThrow(
+          /expected stopped/,
+        );
+      },
+      timeoutMs,
+    );
+
+    it(
+      'rejects operations on absent containers',
+      async () => {
+        await expect(ctx.executor.freeze(randomUUID())).rejects.toThrow(
+          /absent/,
+        );
+      },
+      timeoutMs,
+    );
+
+    it(
+      'destroys a container from any state',
+      async () => {
+        const running = await ctx.fresh();
+        await ctx.executor.destroy(running);
+        expect(await ctx.stateOf(running)).toBeUndefined();
+
+        const paused = await ctx.fresh();
+        await ctx.executor.freeze(paused);
+        await ctx.executor.destroy(paused);
+        expect(await ctx.stateOf(paused)).toBeUndefined();
+
+        const stopped = await ctx.fresh();
+        await ctx.executor.freeze(stopped);
+        await ctx.executor.stop(stopped);
+        await ctx.executor.destroy(stopped);
+        expect(await ctx.stateOf(stopped)).toBeUndefined();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'rejects destroying an absent container',
+      async () => {
+        // The ledger says it exists, reality disagrees: worth hearing, not
+        // a silent success — vanished containers are the reconciler's case.
+        await expect(ctx.executor.destroy(randomUUID())).rejects.toThrow(
+          /absent/,
+        );
+      },
+      timeoutMs,
+    );
+
+    it(
+      'start rebuilds the container from a surviving disk',
+      async () => {
+        const id = await ctx.freshStopped();
+        // The exited container object is removed behind the daemon's back —
+        // exactly what a routine `docker container prune` does. The disk,
+        // which is the sandbox's actual data, stays.
+        await ctx.subject.vanishContainer(id);
+        expect(await ctx.stateOf(id)).toBeUndefined();
+        expect(await ctx.executor.listDisks()).toContain(id);
+
+        await ctx.executor.start(id);
+        expect(await ctx.stateOf(id)).toBe('running');
+        expect(await ctx.executor.listDisks()).toContain(id);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'destroy of a vanished container still takes the leftover disk',
+      async () => {
+        const id = await ctx.freshStopped();
+        await ctx.subject.vanishContainer(id);
+
+        await ctx.executor.destroy(id);
+        expect(await ctx.executor.listDisks()).not.toContain(id);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'rejects starting a sandbox that has no disk',
+      async () => {
+        // No container AND no disk: there is nothing to rebuild from.
+        await expect(ctx.executor.start(randomUUID())).rejects.toThrow(
+          /disk .+ is absent, cannot start/,
+        );
+      },
+      timeoutMs,
+    );
+
+    it(
+      'removeContainer swaps the shell: container gone, disk kept, start rebuilds with data intact',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: 'keep.txt', content: Buffer.from('survives the rebuild') },
+        ]);
+
+        await ctx.executor.removeContainer(id);
+        expect(await ctx.stateOf(id)).toBeUndefined();
+        expect(await ctx.executor.listDisks()).toContain(id);
+
+        await ctx.executor.start(id);
+        expect(await ctx.stateOf(id)).toBe('running');
+        expect((await ctx.executor.readFile(id, 'keep.txt')).toString()).toBe(
+          'survives the rebuild',
+        );
+      },
+      timeoutMs,
+    );
+
+    it(
+      'removeContainer takes the container down from any state',
+      async () => {
+        const paused = await ctx.fresh();
+        await ctx.executor.freeze(paused);
+        await ctx.executor.removeContainer(paused);
+        expect(await ctx.stateOf(paused)).toBeUndefined();
+        expect(await ctx.executor.listDisks()).toContain(paused);
+
+        const stopped = await ctx.freshStopped();
+        await ctx.executor.removeContainer(stopped);
+        expect(await ctx.stateOf(stopped)).toBeUndefined();
+        expect(await ctx.executor.listDisks()).toContain(stopped);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'removeContainer: an absent container is the goal state beside a disk, a complaint without one',
+      async () => {
+        const id = await ctx.freshStopped();
+        await ctx.subject.vanishContainer(id);
+        // Pruned behind the daemon's back — removing it again is a no-op.
+        await ctx.executor.removeContainer(id);
+        expect(await ctx.executor.listDisks()).toContain(id);
+
+        await expect(
+          ctx.executor.removeContainer(randomUUID()),
+        ).rejects.toThrow(/absent, cannot remove/);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'the disk lives with the container: born on create, kept through stop, gone on destroy',
+      async () => {
+        const id = await ctx.fresh();
+        expect(await ctx.executor.listDisks()).toContain(id);
+        await ctx.executor.freeze(id);
+        await ctx.executor.stop(id);
+        // "The processes die, the disk stays."
+        expect(await ctx.executor.listDisks()).toContain(id);
+        await ctx.executor.destroy(id);
+        expect(await ctx.executor.listDisks()).not.toContain(id);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'removeDisk is idempotent: an absent disk already is the goal state',
+      async () => {
+        await expect(
+          ctx.executor.removeDisk(randomUUID()),
+        ).resolves.toBeUndefined();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'lists every container as an observation, not a live reference',
+      async () => {
+        const a = await ctx.fresh();
+        const b = await ctx.fresh();
+        await ctx.executor.freeze(b);
+
+        const observed = await ctx.executor.listContainers();
+        expect(observed.get(a)).toBe('running');
+        expect(observed.get(b)).toBe('paused');
+        // Mutating the observation must not mutate reality.
+        observed.delete(a);
+        expect(await ctx.stateOf(a)).toBe('running');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'resolvePortTarget answers for a running sandbox and refuses the wrong state',
+      async () => {
+        const id = await ctx.fresh();
+        const target = await ctx.executor.resolvePortTarget(id, 8000);
+        expect(target.host).not.toBe('');
+        expect(target.port).toBeGreaterThan(0);
+        await ctx.executor.freeze(id);
+        await expect(ctx.executor.resolvePortTarget(id, 8000)).rejects.toThrow(
+          `container ${id} is paused, expected running`,
+        );
+      },
+      timeoutMs,
+    );
+  });
+}
diff --git a/packages/server/src/executor/contract/watch.ts b/packages/server/src/executor/contract/watch.ts
new file mode 100644
index 0000000..80c5142
--- /dev/null
+++ b/packages/server/src/executor/contract/watch.ts
@@ -0,0 +1,239 @@
+import { describe, expect, it } from 'vitest';
+import { FileNotFoundError, NotADirectoryError } from '../executor';
+import type { ContractContext } from './index';
+
+/**
+ * watchDir. Assertions are inclusion, never counts: one real write can
+ * surface as several MODIFY lines, and event multiplicity is the kernel's
+ * business, not the contract's.
+ */
+export function watchTests(ctx: ContractContext) {
+  const { timeoutMs } = ctx;
+
+  /** Collects events; watch() must be awaited before the change is made. */
+  function eventLog() {
+    const events: Array<{ name: string; type: string }> = [];
+    return {
+      events,
+      onEvent: (e: { name: string; type: string }) => {
+        events.push({ ...e });
+      },
+      has: (name: string, type: string) =>
+        events.some((e) => e.name === name && e.type === type),
+    };
+  }
+
+  describe('watchDir', () => {
+    it(
+      'a watcher sees a new file as create and write, an overwrite as write',
+      async () => {
+        const id = await ctx.fresh();
+        const log = eventLog();
+        const watch = await ctx.executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: log.onEvent,
+          onEnd: () => {},
+        });
+        await ctx.executor.writeFiles(id, [
+          { path: 'seen.txt', content: Buffer.from('one') },
+        ]);
+        await ctx.until(() => log.has('seen.txt', 'create'));
+        await ctx.until(() => log.has('seen.txt', 'write'));
+
+        log.events.length = 0;
+        await ctx.executor.writeFiles(id, [
+          { path: 'seen.txt', content: Buffer.from('two') },
+        ]);
+        await ctx.until(() => log.has('seen.txt', 'write'));
+        expect(log.has('seen.txt', 'create')).toBe(false);
+        await watch.stop();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a watcher sees removals, and a move as rename plus create',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: 'old.txt', content: Buffer.from('x') },
+          { path: 'doomed.txt', content: Buffer.from('y') },
+        ]);
+        const log = eventLog();
+        const watch = await ctx.executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: log.onEvent,
+          onEnd: () => {},
+        });
+        await ctx.executor.remove(id, 'doomed.txt');
+        await ctx.until(() => log.has('doomed.txt', 'remove'));
+
+        await ctx.executor.move(id, 'old.txt', 'new.txt');
+        await ctx.until(() => log.has('old.txt', 'rename'));
+        await ctx.until(() => log.has('new.txt', 'create'));
+        await watch.stop();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'subtree events reach a recursive watcher only, with subdir-relative names',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.makeDir(id, '/home/user/sub');
+        const flat = eventLog();
+        const deep = eventLog();
+        const flatWatch = await ctx.executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: flat.onEvent,
+          onEnd: () => {},
+        });
+        const deepWatch = await ctx.executor.watchDir(id, {
+          path: '/home/user',
+          recursive: true,
+          onEvent: deep.onEvent,
+          onEnd: () => {},
+        });
+        await ctx.executor.writeFiles(id, [
+          { path: 'sub/inner.txt', content: Buffer.from('deep') },
+        ]);
+        await ctx.until(() => deep.has('sub/inner.txt', 'create'));
+        expect(flat.events).toEqual([]);
+        await flatWatch.stop();
+        await deepWatch.stop();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a recursive watcher follows directories created after it started',
+      async () => {
+        // Measured under gVisor 2026-07-10: inotifywait -r adds watches for
+        // directories born while it is running; the fake's prefix matching
+        // gives the same answer.
+        const id = await ctx.fresh();
+        const log = eventLog();
+        const watch = await ctx.executor.watchDir(id, {
+          path: '/home/user',
+          recursive: true,
+          onEvent: log.onEvent,
+          onEnd: () => {},
+        });
+        await ctx.executor.makeDir(id, '/home/user/born-later');
+        await ctx.until(() => log.has('born-later', 'create'));
+        await ctx.executor.writeFiles(id, [
+          { path: 'born-later/inside.txt', content: Buffer.from('!') },
+        ]);
+        await ctx.until(() => log.has('born-later/inside.txt', 'create'));
+        await watch.stop();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'stop() ends delivery; the watcher does not call onEnd for its own stop',
+      async () => {
+        const id = await ctx.fresh();
+        const log = eventLog();
+        let ended = false;
+        const watch = await ctx.executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: log.onEvent,
+          onEnd: () => {
+            ended = true;
+          },
+        });
+        await watch.stop();
+        await ctx.executor.writeFiles(id, [
+          { path: 'after-stop.txt', content: Buffer.from('x') },
+        ]);
+        // Bounded quiet: nothing arrives for a change made after stop().
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        expect(log.events).toEqual([]);
+        expect(ended).toBe(false);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'watchDir refuses a missing path and a file path with the typed errors',
+      async () => {
+        const id = await ctx.fresh();
+        const missing = await ctx.executor
+          .watchDir(id, {
+            path: '/home/user/nowhere',
+            recursive: false,
+            onEvent: () => {},
+            onEnd: () => {},
+          })
+          .catch((e) => e);
+        expect(missing).toBeInstanceOf(FileNotFoundError);
+        expect(missing.message).toBe('no such file: /home/user/nowhere');
+
+        await ctx.executor.writeFiles(id, [
+          { path: 'plain.txt', content: Buffer.from('x') },
+        ]);
+        const onFile = await ctx.executor
+          .watchDir(id, {
+            path: 'plain.txt',
+            recursive: false,
+            onEvent: () => {},
+            onEnd: () => {},
+          })
+          .catch((e) => e);
+        expect(onFile).toBeInstanceOf(NotADirectoryError);
+        expect(onFile.message).toBe('not a directory: /home/user/plain.txt');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'the container stopping ends the watcher through onEnd',
+      async () => {
+        const id = await ctx.fresh();
+        let ended: Error | undefined;
+        const watch = await ctx.executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: () => {},
+          onEnd: (error) => {
+            ended = error ?? new Error('ended without error');
+          },
+        });
+        await ctx.executor.freeze(id);
+        await ctx.executor.stop(id);
+        await ctx.until(() => ended !== undefined);
+        // Ending was the container's doing, not stop()'s — which now finds
+        // nothing left to do and must still resolve.
+        await watch.stop();
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a watcher survives freeze/unfreeze and reports changes made after',
+      async () => {
+        const id = await ctx.fresh();
+        const log = eventLog();
+        const watch = await ctx.executor.watchDir(id, {
+          path: '/home/user',
+          recursive: false,
+          onEvent: log.onEvent,
+          onEnd: () => {},
+        });
+        await ctx.executor.freeze(id);
+        await ctx.executor.unfreeze(id);
+        await ctx.executor.writeFiles(id, [
+          { path: 'thawed.txt', content: Buffer.from('back') },
+        ]);
+        await ctx.until(() => log.has('thawed.txt', 'create'));
+        await watch.stop();
+      },
+      timeoutMs,
+    );
+  });
+}

From 234a837d9843ff74a396ce84c54617c054286725 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 14:52:00 +0800
Subject: [PATCH 027/133] The in-container scripts move out of docker.ts,
 parsers riding along
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docker.ts opened with 330 lines of shell-script constants and stream
helpers before the executor class began, and reading a method meant
scrolling far away from the script it runs. docker-scripts.ts now holds
every in-container script together with the parser of its output — a
script and its parser are one wire format, so they change together;
docker-streams.ts takes the two Writable sinks. The class, its options,
and the docker-facing helpers stay in docker.ts. Pure movement: no script
byte or error message changes, contract suite untouched.
---
 .../server/src/executor/docker-scripts.ts     | 244 +++++++++++++
 .../server/src/executor/docker-streams.ts     |  66 ++++
 packages/server/src/executor/docker.ts        | 328 ++----------------
 3 files changed, 337 insertions(+), 301 deletions(-)
 create mode 100644 packages/server/src/executor/docker-scripts.ts
 create mode 100644 packages/server/src/executor/docker-streams.ts

diff --git a/packages/server/src/executor/docker-scripts.ts b/packages/server/src/executor/docker-scripts.ts
new file mode 100644
index 0000000..da1c4e7
--- /dev/null
+++ b/packages/server/src/executor/docker-scripts.ts
@@ -0,0 +1,244 @@
+import type { SandboxEntry, WatchEvent } from './executor';
+
+/**
+ * Every script the DockerExecutor runs inside a sandbox, with the parsers
+ * for their output. A script and its parser are one wire format — they
+ * change together, which is why they share this file. No user input is
+ * ever spliced into a script: arguments travel as positional shell
+ * parameters ($1, $2, ...), set by the exec's argv.
+ */
+
+/**
+ * In-container deadline for file operations, same mechanism as exec's
+ * (host-side disconnects cannot kill an in-container process). Not a user
+ * knob: 16 MiB on a local ext4 is subsecond work — this guard only exists
+ * so a pathological target cannot hang the daemon's request forever.
+ */
+export const FILE_OP_TIMEOUT_SECONDS = 60;
+
+/**
+ * The file-op scripts talk back through exit codes of our choosing — private
+ * numbers between the daemon and its own script, no user command runs inside.
+ * They map 1:1 onto the typed file errors both executors must throw.
+ */
+export const NO_SUCH_FILE_EXIT = 44;
+export const NOT_A_FILE_EXIT = 45;
+export const TOO_LARGE_EXIT = 46;
+export const NOT_A_DIR_EXIT = 47;
+export const ALREADY_EXISTS_EXIT = 48;
+
+/**
+ * $1 = absolute path. Refuses a target that exists but is not a regular
+ * file (directory, FIFO — `cat >` into a FIFO would block forever), creates
+ * the parents, then streams stdin into the file. Runs as uid 1000, so
+ * in-sandbox permissions apply honestly, and path resolution — symlinks
+ * included — happens inside the container, where there is no host to
+ * escape to.
+ */
+export const WRITE_FILE_SCRIPT = [
+  `[ ! -e "$1" ] || [ -f "$1" ] || exit ${NOT_A_FILE_EXIT}`,
+  'mkdir -p -- "$(dirname -- "$1")" && exec cat > "$1"',
+].join('\n');
+
+/** $1 = absolute path, $2 = size limit in bytes. Size gate before content: an over-limit file is refused, never truncated. */
+export const READ_FILE_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  `[ -f "$1" ] || exit ${NOT_A_FILE_EXIT}`,
+  'size=$(stat -c %s -- "$1") || exit 1',
+  `[ "$size" -le "$2" ] || { echo "$size" >&2; exit ${TOO_LARGE_EXIT}; }`,
+  'exec cat -- "$1"',
+].join('\n');
+
+/**
+ * Streaming file transfers have no size cap, so their in-container deadline
+ * must fit a quota-sized file crawling to a slow client — generous, but
+ * still a bound so a wedged transfer cannot hold an exec forever.
+ */
+export const STREAM_FILE_OP_TIMEOUT_SECONDS = 3600;
+
+/** Ceiling for one directory listing; past it the listing errors instead of silently losing entries. */
+export const LIST_OUTPUT_LIMIT_BYTES = 8 * 1024 * 1024;
+
+/** $1 = absolute path. READ_FILE_SCRIPT without the size gate — the streaming read is the uncapped path. */
+export const READ_FILE_STREAM_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  `[ -f "$1" ] || exit ${NOT_A_FILE_EXIT}`,
+  'exec cat -- "$1"',
+].join('\n');
+
+/**
+ * $1 = absolute dir, $2 = depth. One NUL-terminated record per entry, tab
+ * separated with the path last, so a path containing tabs still parses
+ * (nothing else can contain a tab, and a path cannot contain a NUL).
+ */
+export const LIST_DIR_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  `[ -d "$1" ] || exit ${NOT_A_DIR_EXIT}`,
+  `exec find "$1" -mindepth 1 -maxdepth "$2" -printf '%y\\t%s\\t%T@\\t%m\\t%u\\t%g\\t%p\\0'`,
+].join('\n');
+
+/** $1 = absolute path. --printf, not -c: only --printf interprets \t. */
+export const STAT_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  `exec stat --printf '%F\\t%s\\t%Y\\t%a\\t%U\\t%G' -- "$1"`,
+].join('\n');
+
+/** $1 = absolute path. Exists (whatever it is) -> "already there", else mkdir -p. */
+export const MAKE_DIR_SCRIPT = [
+  `[ ! -e "$1" ] || exit ${ALREADY_EXISTS_EXIT}`,
+  'exec mkdir -p -- "$1"',
+].join('\n');
+
+/** $1 = source, $2 = destination. -T = rename(2) semantics: never "move into". */
+export const MOVE_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  'exec mv -T -- "$1" "$2"',
+].join('\n');
+
+export const REMOVE_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  'exec rm -rf -- "$1"',
+].join('\n');
+
+/**
+ * A watcher may outlive any one request, but not the sandbox's day — the
+ * same backstop as e2b-surface execs, physical cleanup only.
+ */
+export const WATCH_BACKSTOP_SECONDS = 24 * 60 * 60;
+
+/**
+ * $1 = pidfile, $2 = recursive flag (`-r` or empty), $3 = watched dir.
+ * The existence checks run in-script: one round trip, no gap for the path
+ * to change under a separate stat. Readiness is inotifywait's own
+ * "Watches established." on stderr — measured under gVisor 2026-07-10,
+ * along with -r picking up directories created after the watch began.
+ */
+export const WATCH_SCRIPT = [
+  'echo "$$" > "$1"',
+  `[ -e "$3" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  `[ -d "$3" ] || exit ${NOT_A_DIR_EXIT}`,
+  // $2 rides unquoted on purpose: empty must vanish, not become an argument.
+  `exec timeout --signal=KILL ${WATCH_BACKSTOP_SECONDS} inotifywait -m $2 -e create,modify,delete,move,attrib --format '%e|%w%f' -- "$3"`,
+].join('\n');
+
+/**
+ * One inotifywait line -> wire events. A line reads `OPS|/abs/path` with
+ * OPS comma-separated; `ISDIR` and anything unmapped fall through silently.
+ * MOVED_FROM/MOVED_TO land as rename/create — fsnotify's reading, which is
+ * what the E2B wire speaks. Events on the watched directory itself (empty
+ * name) are dropped, like real envd's "." edge.
+ */
+export function parseInotifyLine(line: string, base: string): WatchEvent[] {
+  const cut = line.indexOf('|');
+  if (cut === -1) return [];
+  const eventPath = line.slice(cut + 1);
+  const prefix = base === '/' ? '/' : `${base}/`;
+  if (!eventPath.startsWith(prefix) || eventPath.length === prefix.length) {
+    return [];
+  }
+  const name = eventPath.slice(prefix.length);
+  const events: WatchEvent[] = [];
+  for (const op of line.slice(0, cut).split(',')) {
+    const type =
+      op === 'CREATE' || op === 'MOVED_TO'
+        ? ('create' as const)
+        : op === 'MODIFY'
+          ? ('write' as const)
+          : op === 'DELETE'
+            ? ('remove' as const)
+            : op === 'MOVED_FROM'
+              ? ('rename' as const)
+              : op === 'ATTRIB'
+                ? ('chmod' as const)
+                : undefined;
+    if (type) events.push({ name, type });
+  }
+  return events;
+}
+
+/**
+ * Wrapper every execStream command runs under, so the handle can signal it
+ * later. $1 = pidfile, $2 = timeout seconds, $3 = the user's command.
+ * The exec chain keeps the pid stable: the recorded $$ is the bash that
+ * becomes `timeout`, and GNU timeout itself (without --foreground) calls
+ * setpgid(0,0) — that same pid becomes a fresh process-group leader, so
+ * one `kill -- -pid` reaps the command and all its descendants.
+ * Deliberately NOT setsid --wait for the group: measured 2026-07-10,
+ * setsid reports a signal-killed child as the raw signal number (9/15)
+ * where the shell convention — and E2B — speak 128+N; timeout's own
+ * signal propagation (it re-raises on itself) preserves 137/143.
+ */
+export function execStreamWrapper(loginShell: boolean): string {
+  const shell = loginShell ? 'bash -l -c' : 'bash -c';
+  return [
+    'echo "$$" > "$1"',
+    `exec timeout --signal=KILL "$2" ${shell} "$3"`,
+  ].join('\n');
+}
+
+/**
+ * $1 = pidfile, $2 = signal name (SIGKILL/SIGTERM). The brief wait covers
+ * the honest race of a signal arriving before the wrapper's first line has
+ * written the pidfile. Group kill first; a leader that already died with
+ * children lingering still gets the single-pid fallback.
+ */
+export const SIGNAL_SCRIPT = [
+  'for _ in $(seq 1 40); do [ -s "$1" ] && break; sleep 0.05; done',
+  'p=$(cat "$1") || exit 1',
+  '[ -n "$p" ] || exit 1',
+  'kill -s "$2" -- "-$p" 2>/dev/null || exec kill -s "$2" "$p"',
+].join('\n');
+
+/**
+ * $1 = pidfile. The PTY session: an interactive login shell, nothing else.
+ * Deliberately no timeout wrapper (GNU timeout puts the child in its own
+ * process group, which wrecks interactive job control with SIGTTIN) and no
+ * setsid (a Tty exec is born session leader holding the controlling
+ * terminal; setsid would take the terminal away). The shell's own group is
+ * what the pidfile kill reaps; foreground jobs follow the closing pty
+ * master via SIGHUP. Lifetime is bounded by the sandbox's own.
+ */
+export const PTY_WRAPPER = ['echo "$$" > "$1"', 'exec bash -i -l'].join('\n');
+
+/** One `find -printf` record (see LIST_DIR_SCRIPT) -> entry. */
+export function entryFromFindRecord(record: string): SandboxEntry {
+  const fields = record.split('\t');
+  const [kind = '', size = '', mtime = '', mode = '', owner = '', group = ''] =
+    fields;
+  // The path is everything after the sixth tab — its own tabs survive.
+  const path = fields.slice(6).join('\t');
+  return {
+    name: path.slice(path.lastIndexOf('/') + 1) || '/',
+    path,
+    type: kind === 'f' ? 'file' : kind === 'd' ? 'dir' : 'other',
+    sizeBytes: Number(size),
+    modifiedTime: new Date(Number(mtime) * 1000).toISOString(),
+    mode: Number.parseInt(mode, 8),
+    owner,
+    group,
+  };
+}
+
+/** One `stat --printf` line (see STAT_SCRIPT) -> entry. */
+export function entryFromStatLine(
+  resolved: string,
+  line: string,
+): SandboxEntry {
+  const [kind = '', size = '', mtime = '', mode = '', owner = '', group = ''] =
+    line.split('\t');
+  return {
+    name: resolved.slice(resolved.lastIndexOf('/') + 1) || '/',
+    path: resolved,
+    // %F says "regular file" or "regular empty file" — both are files.
+    type: kind.startsWith('regular')
+      ? 'file'
+      : kind === 'directory'
+        ? 'dir'
+        : 'other',
+    sizeBytes: Number(size),
+    modifiedTime: new Date(Number(mtime) * 1000).toISOString(),
+    mode: Number.parseInt(mode, 8),
+    owner,
+    group,
+  };
+}
diff --git a/packages/server/src/executor/docker-streams.ts b/packages/server/src/executor/docker-streams.ts
new file mode 100644
index 0000000..6a1a36a
--- /dev/null
+++ b/packages/server/src/executor/docker-streams.ts
@@ -0,0 +1,66 @@
+import { Writable } from 'node:stream';
+
+/**
+ * A Writable that keeps the first `cap` bytes and drains the rest. Draining
+ * is the point: if the sink stopped acknowledging chunks past the cap,
+ * backpressure would wedge the exec stream and the command with it.
+ */
+export class CappedBuffer extends Writable {
+  private readonly chunks: Buffer[] = [];
+  private size = 0;
+  truncated = false;
+
+  constructor(private readonly cap: number) {
+    super();
+  }
+
+  override _write(
+    chunk: Buffer,
+    _encoding: BufferEncoding,
+    callback: () => void,
+  ): void {
+    const room = this.cap - this.size;
+    if (room > 0) {
+      const kept = chunk.length <= room ? chunk : chunk.subarray(0, room);
+      this.chunks.push(kept);
+      this.size += kept.length;
+    }
+    if (chunk.length > room) this.truncated = true;
+    callback();
+  }
+
+  bytes(): Buffer {
+    return Buffer.concat(this.chunks);
+  }
+
+  text(): string {
+    return this.bytes().toString('utf8');
+  }
+}
+
+/**
+ * A Writable that hands each chunk to a callback — the streaming sink for
+ * exec output and file downloads. When the callback returns a promise it is
+ * awaited before the next chunk is accepted: that is how a slow consumer's
+ * backpressure travels through demux all the way to the in-container writer.
+ */
+export class CallbackSink extends Writable {
+  constructor(
+    private readonly onChunk: (chunk: Buffer) => void | Promise<void>,
+  ) {
+    super();
+  }
+
+  override _write(
+    chunk: Buffer,
+    _encoding: BufferEncoding,
+    callback: (error?: Error | null) => void,
+  ): void {
+    Promise.resolve()
+      .then(() => this.onChunk(chunk))
+      .then(
+        () => callback(),
+        (err) => callback(err instanceof Error ? err : new Error(String(err))),
+      );
+  }
+}
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 912139d..f06b752 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -9,8 +9,7 @@ import {
   rm,
 } from 'node:fs/promises';
 import path from 'node:path';
-import type { Duplex } from 'node:stream';
-import { Writable } from 'node:stream';
+import type { Duplex, Writable } from 'node:stream';
 import {
   EXEC_OUTPUT_LIMIT_BYTES,
   FILE_SIZE_LIMIT_BYTES,
@@ -18,6 +17,32 @@ import {
 } from '@dormice/shared';
 import Docker from 'dockerode';
 import { execa } from 'execa';
+import {
+  ALREADY_EXISTS_EXIT,
+  entryFromFindRecord,
+  entryFromStatLine,
+  execStreamWrapper,
+  FILE_OP_TIMEOUT_SECONDS,
+  LIST_DIR_SCRIPT,
+  LIST_OUTPUT_LIMIT_BYTES,
+  MAKE_DIR_SCRIPT,
+  MOVE_SCRIPT,
+  NO_SUCH_FILE_EXIT,
+  NOT_A_DIR_EXIT,
+  NOT_A_FILE_EXIT,
+  PTY_WRAPPER,
+  parseInotifyLine,
+  READ_FILE_SCRIPT,
+  READ_FILE_STREAM_SCRIPT,
+  REMOVE_SCRIPT,
+  SIGNAL_SCRIPT,
+  STAT_SCRIPT,
+  STREAM_FILE_OP_TIMEOUT_SECONDS,
+  TOO_LARGE_EXIT,
+  WATCH_SCRIPT,
+  WRITE_FILE_SCRIPT,
+} from './docker-scripts';
+import { CallbackSink, CappedBuffer } from './docker-streams';
 import {
   type ContainerState,
   DiskFullError,
@@ -35,7 +60,6 @@ import {
   type SandboxEntry,
   type WatchDirHandle,
   type WatchDirOptions,
-  type WatchEvent,
 } from './executor';
 
 /**
@@ -64,239 +88,6 @@ export function containerName(sandboxId: string): string {
   return `sbx-${sandboxId}`;
 }
 
-/**
- * In-container deadline for file operations, same mechanism as exec's
- * (host-side disconnects cannot kill an in-container process). Not a user
- * knob: 16 MiB on a local ext4 is subsecond work — this guard only exists
- * so a pathological target cannot hang the daemon's request forever.
- */
-const FILE_OP_TIMEOUT_SECONDS = 60;
-
-/**
- * The file-op scripts talk back through exit codes of our choosing — private
- * numbers between the daemon and its own script, no user command runs inside.
- * They map 1:1 onto the typed file errors both executors must throw.
- */
-const NO_SUCH_FILE_EXIT = 44;
-const NOT_A_FILE_EXIT = 45;
-const TOO_LARGE_EXIT = 46;
-
-/**
- * $1 = absolute path. Refuses a target that exists but is not a regular
- * file (directory, FIFO — `cat >` into a FIFO would block forever), creates
- * the parents, then streams stdin into the file. Runs as uid 1000, so
- * in-sandbox permissions apply honestly, and path resolution — symlinks
- * included — happens inside the container, where there is no host to
- * escape to.
- */
-const WRITE_FILE_SCRIPT = [
-  `[ ! -e "$1" ] || [ -f "$1" ] || exit ${NOT_A_FILE_EXIT}`,
-  'mkdir -p -- "$(dirname -- "$1")" && exec cat > "$1"',
-].join('\n');
-
-/** $1 = absolute path, $2 = size limit in bytes. Size gate before content: an over-limit file is refused, never truncated. */
-const READ_FILE_SCRIPT = [
-  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
-  `[ -f "$1" ] || exit ${NOT_A_FILE_EXIT}`,
-  'size=$(stat -c %s -- "$1") || exit 1',
-  `[ "$size" -le "$2" ] || { echo "$size" >&2; exit ${TOO_LARGE_EXIT}; }`,
-  'exec cat -- "$1"',
-].join('\n');
-
-const NOT_A_DIR_EXIT = 47;
-const ALREADY_EXISTS_EXIT = 48;
-
-/**
- * Streaming file transfers have no size cap, so their in-container deadline
- * must fit a quota-sized file crawling to a slow client — generous, but
- * still a bound so a wedged transfer cannot hold an exec forever.
- */
-const STREAM_FILE_OP_TIMEOUT_SECONDS = 3600;
-
-/** Ceiling for one directory listing; past it the listing errors instead of silently losing entries. */
-const LIST_OUTPUT_LIMIT_BYTES = 8 * 1024 * 1024;
-
-/** $1 = absolute path. READ_FILE_SCRIPT without the size gate — the streaming read is the uncapped path. */
-const READ_FILE_STREAM_SCRIPT = [
-  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
-  `[ -f "$1" ] || exit ${NOT_A_FILE_EXIT}`,
-  'exec cat -- "$1"',
-].join('\n');
-
-/**
- * $1 = absolute dir, $2 = depth. One NUL-terminated record per entry, tab
- * separated with the path last, so a path containing tabs still parses
- * (nothing else can contain a tab, and a path cannot contain a NUL).
- */
-const LIST_DIR_SCRIPT = [
-  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
-  `[ -d "$1" ] || exit ${NOT_A_DIR_EXIT}`,
-  `exec find "$1" -mindepth 1 -maxdepth "$2" -printf '%y\\t%s\\t%T@\\t%m\\t%u\\t%g\\t%p\\0'`,
-].join('\n');
-
-/** $1 = absolute path. --printf, not -c: only --printf interprets \t. */
-const STAT_SCRIPT = [
-  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
-  `exec stat --printf '%F\\t%s\\t%Y\\t%a\\t%U\\t%G' -- "$1"`,
-].join('\n');
-
-/** $1 = absolute path. Exists (whatever it is) -> "already there", else mkdir -p. */
-const MAKE_DIR_SCRIPT = [
-  `[ ! -e "$1" ] || exit ${ALREADY_EXISTS_EXIT}`,
-  'exec mkdir -p -- "$1"',
-].join('\n');
-
-/** $1 = source, $2 = destination. -T = rename(2) semantics: never "move into". */
-const MOVE_SCRIPT = [
-  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
-  'exec mv -T -- "$1" "$2"',
-].join('\n');
-
-const REMOVE_SCRIPT = [
-  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
-  'exec rm -rf -- "$1"',
-].join('\n');
-
-/**
- * A watcher may outlive any one request, but not the sandbox's day — the
- * same backstop as e2b-surface execs, physical cleanup only.
- */
-const WATCH_BACKSTOP_SECONDS = 24 * 60 * 60;
-
-/**
- * $1 = pidfile, $2 = recursive flag (`-r` or empty), $3 = watched dir.
- * The existence checks run in-script: one round trip, no gap for the path
- * to change under a separate stat. Readiness is inotifywait's own
- * "Watches established." on stderr — measured under gVisor 2026-07-10,
- * along with -r picking up directories created after the watch began.
- */
-const WATCH_SCRIPT = [
-  'echo "$$" > "$1"',
-  `[ -e "$3" ] || exit ${NO_SUCH_FILE_EXIT}`,
-  `[ -d "$3" ] || exit ${NOT_A_DIR_EXIT}`,
-  // $2 rides unquoted on purpose: empty must vanish, not become an argument.
-  `exec timeout --signal=KILL ${WATCH_BACKSTOP_SECONDS} inotifywait -m $2 -e create,modify,delete,move,attrib --format '%e|%w%f' -- "$3"`,
-].join('\n');
-
-/**
- * One inotifywait line -> wire events. A line reads `OPS|/abs/path` with
- * OPS comma-separated; `ISDIR` and anything unmapped fall through silently.
- * MOVED_FROM/MOVED_TO land as rename/create — fsnotify's reading, which is
- * what the E2B wire speaks. Events on the watched directory itself (empty
- * name) are dropped, like real envd's "." edge.
- */
-export function parseInotifyLine(line: string, base: string): WatchEvent[] {
-  const cut = line.indexOf('|');
-  if (cut === -1) return [];
-  const eventPath = line.slice(cut + 1);
-  const prefix = base === '/' ? '/' : `${base}/`;
-  if (!eventPath.startsWith(prefix) || eventPath.length === prefix.length) {
-    return [];
-  }
-  const name = eventPath.slice(prefix.length);
-  const events: WatchEvent[] = [];
-  for (const op of line.slice(0, cut).split(',')) {
-    const type =
-      op === 'CREATE' || op === 'MOVED_TO'
-        ? ('create' as const)
-        : op === 'MODIFY'
-          ? ('write' as const)
-          : op === 'DELETE'
-            ? ('remove' as const)
-            : op === 'MOVED_FROM'
-              ? ('rename' as const)
-              : op === 'ATTRIB'
-                ? ('chmod' as const)
-                : undefined;
-    if (type) events.push({ name, type });
-  }
-  return events;
-}
-
-/**
- * Wrapper every execStream command runs under, so the handle can signal it
- * later. $1 = pidfile, $2 = timeout seconds, $3 = the user's command.
- * The exec chain keeps the pid stable: the recorded $$ is the bash that
- * becomes `timeout`, and GNU timeout itself (without --foreground) calls
- * setpgid(0,0) — that same pid becomes a fresh process-group leader, so
- * one `kill -- -pid` reaps the command and all its descendants.
- * Deliberately NOT setsid --wait for the group: measured 2026-07-10,
- * setsid reports a signal-killed child as the raw signal number (9/15)
- * where the shell convention — and E2B — speak 128+N; timeout's own
- * signal propagation (it re-raises on itself) preserves 137/143.
- */
-function execStreamWrapper(loginShell: boolean): string {
-  const shell = loginShell ? 'bash -l -c' : 'bash -c';
-  return [
-    'echo "$$" > "$1"',
-    `exec timeout --signal=KILL "$2" ${shell} "$3"`,
-  ].join('\n');
-}
-
-/**
- * $1 = pidfile, $2 = signal name (SIGKILL/SIGTERM). The brief wait covers
- * the honest race of a signal arriving before the wrapper's first line has
- * written the pidfile. Group kill first; a leader that already died with
- * children lingering still gets the single-pid fallback.
- */
-const SIGNAL_SCRIPT = [
-  'for _ in $(seq 1 40); do [ -s "$1" ] && break; sleep 0.05; done',
-  'p=$(cat "$1") || exit 1',
-  '[ -n "$p" ] || exit 1',
-  'kill -s "$2" -- "-$p" 2>/dev/null || exec kill -s "$2" "$p"',
-].join('\n');
-
-/**
- * $1 = pidfile. The PTY session: an interactive login shell, nothing else.
- * Deliberately no timeout wrapper (GNU timeout puts the child in its own
- * process group, which wrecks interactive job control with SIGTTIN) and no
- * setsid (a Tty exec is born session leader holding the controlling
- * terminal; setsid would take the terminal away). The shell's own group is
- * what the pidfile kill reaps; foreground jobs follow the closing pty
- * master via SIGHUP. Lifetime is bounded by the sandbox's own.
- */
-const PTY_WRAPPER = ['echo "$$" > "$1"', 'exec bash -i -l'].join('\n');
-
-/** One `find -printf` record (see LIST_DIR_SCRIPT) -> entry. */
-function entryFromFindRecord(record: string): SandboxEntry {
-  const fields = record.split('\t');
-  const [kind = '', size = '', mtime = '', mode = '', owner = '', group = ''] =
-    fields;
-  // The path is everything after the sixth tab — its own tabs survive.
-  const path = fields.slice(6).join('\t');
-  return {
-    name: path.slice(path.lastIndexOf('/') + 1) || '/',
-    path,
-    type: kind === 'f' ? 'file' : kind === 'd' ? 'dir' : 'other',
-    sizeBytes: Number(size),
-    modifiedTime: new Date(Number(mtime) * 1000).toISOString(),
-    mode: Number.parseInt(mode, 8),
-    owner,
-    group,
-  };
-}
-
-/** One `stat --printf` line (see STAT_SCRIPT) -> entry. */
-function entryFromStatLine(resolved: string, line: string): SandboxEntry {
-  const [kind = '', size = '', mtime = '', mode = '', owner = '', group = ''] =
-    line.split('\t');
-  return {
-    name: resolved.slice(resolved.lastIndexOf('/') + 1) || '/',
-    path: resolved,
-    // %F says "regular file" or "regular empty file" — both are files.
-    type: kind.startsWith('regular')
-      ? 'file'
-      : kind === 'directory'
-        ? 'dir'
-        : 'other',
-    sizeBytes: Number(size),
-    modifiedTime: new Date(Number(mtime) * 1000).toISOString(),
-    mode: Number.parseInt(mode, 8),
-    owner,
-    group,
-  };
-}
-
 /**
  * Docker reports seven statuses; the executor's contract knows three. With
  * RestartPolicy "no" a container never restarts on its own, so everything
@@ -317,71 +108,6 @@ export function assertInside(base: string, target: string): void {
   }
 }
 
-/**
- * A Writable that keeps the first `cap` bytes and drains the rest. Draining
- * is the point: if the sink stopped acknowledging chunks past the cap,
- * backpressure would wedge the exec stream and the command with it.
- */
-class CappedBuffer extends Writable {
-  private readonly chunks: Buffer[] = [];
-  private size = 0;
-  truncated = false;
-
-  constructor(private readonly cap: number) {
-    super();
-  }
-
-  override _write(
-    chunk: Buffer,
-    _encoding: BufferEncoding,
-    callback: () => void,
-  ): void {
-    const room = this.cap - this.size;
-    if (room > 0) {
-      const kept = chunk.length <= room ? chunk : chunk.subarray(0, room);
-      this.chunks.push(kept);
-      this.size += kept.length;
-    }
-    if (chunk.length > room) this.truncated = true;
-    callback();
-  }
-
-  bytes(): Buffer {
-    return Buffer.concat(this.chunks);
-  }
-
-  text(): string {
-    return this.bytes().toString('utf8');
-  }
-}
-
-/**
- * A Writable that hands each chunk to a callback — the streaming sink for
- * exec output and file downloads. When the callback returns a promise it is
- * awaited before the next chunk is accepted: that is how a slow consumer's
- * backpressure travels through demux all the way to the in-container writer.
- */
-class CallbackSink extends Writable {
-  constructor(
-    private readonly onChunk: (chunk: Buffer) => void | Promise<void>,
-  ) {
-    super();
-  }
-
-  override _write(
-    chunk: Buffer,
-    _encoding: BufferEncoding,
-    callback: (error?: Error | null) => void,
-  ): void {
-    Promise.resolve()
-      .then(() => this.onChunk(chunk))
-      .then(
-        () => callback(),
-        (err) => callback(err instanceof Error ? err : new Error(String(err))),
-      );
-  }
-}
-
 interface DockerApiError {
   statusCode: number;
 }

From e9f7776b4a10243421e86a4e98b8eec304184905 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 14:53:08 +0800
Subject: [PATCH 028/133] Multi-word file names settle on kebab-case

Every existing multi-word module in the server package is kebab-case
(keyed-queue, process-table, sandbox-proxy, exec-heartbeat, ...); the
one camelCase newcomer from the contract split now matches. The naming
rule in the internal code conventions is rewritten to describe this
reality.
---
 .../src/executor/contract/{execStream.ts => exec-stream.ts}     | 0
 packages/server/src/executor/contract/index.ts                  | 2 +-
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename packages/server/src/executor/contract/{execStream.ts => exec-stream.ts} (100%)

diff --git a/packages/server/src/executor/contract/execStream.ts b/packages/server/src/executor/contract/exec-stream.ts
similarity index 100%
rename from packages/server/src/executor/contract/execStream.ts
rename to packages/server/src/executor/contract/exec-stream.ts
diff --git a/packages/server/src/executor/contract/index.ts b/packages/server/src/executor/contract/index.ts
index 90fca19..43ad211 100644
--- a/packages/server/src/executor/contract/index.ts
+++ b/packages/server/src/executor/contract/index.ts
@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe } from 'vitest';
 import type { ContainerState, Executor } from '../executor';
 import { entryTests } from './entries';
 import { execTests } from './exec';
-import { execStreamTests } from './execStream';
+import { execStreamTests } from './exec-stream';
 import { fileTests } from './files';
 import { lifecycleTests } from './lifecycle';
 import { watchTests } from './watch';

From 85ec2a12d50a0e7215c2402839a2770b8e1a800a Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 17:25:23 +0800
Subject: [PATCH 029/133] getMetrics: one sample taken now, and observation
 never wakes

---
 e2e/src/e2b.test.ts                           | 44 ++++++++++
 packages/server/src/e2b/compat.test.ts        | 62 +++++++++++++
 packages/server/src/e2b/control.ts            | 33 +++++++
 .../server/src/executor/contract/index.ts     |  2 +
 .../server/src/executor/contract/metrics.ts   | 86 +++++++++++++++++++
 packages/server/src/executor/docker.ts        | 44 ++++++++++
 packages/server/src/executor/executor.ts      | 26 ++++++
 packages/server/src/executor/fake.ts          | 26 ++++++
 8 files changed, 323 insertions(+)
 create mode 100644 packages/server/src/executor/contract/metrics.ts

diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 51450eb..4add6f4 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -196,6 +196,26 @@ describe('official e2b SDK against the daemon', () => {
     }
   });
 
+  it('getMetrics answers one live sample; a killed sandbox refuses', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      const metrics = await sbx.getMetrics();
+      expect(metrics).toHaveLength(1);
+      const m = metrics[0];
+      if (!m) throw new Error('unreachable');
+      expect(m.timestamp).toBeInstanceOf(Date);
+      expect(Math.abs(m.timestamp.getTime() - Date.now())).toBeLessThan(60_000);
+      expect(m.cpuCount).toBeGreaterThanOrEqual(1);
+      expect(m.memTotal).toBeGreaterThan(0);
+      expect(m.memUsed).toBeLessThanOrEqual(m.memTotal);
+      expect(m.diskTotal).toBeGreaterThan(0);
+      expect(m.diskUsed).toBeLessThanOrEqual(m.diskTotal);
+    } finally {
+      await sbx.kill();
+    }
+    await expect(sbx.getMetrics()).rejects.toThrow(/not found/i);
+  });
+
   it('kill destroys for real: gone from list, connect refuses, second kill is false', async () => {
     const sbx = await Sandbox.create(connection());
     await sbx.files.write('doomed.txt', 'will not survive');
@@ -597,6 +617,30 @@ describe.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
       }
     });
 
+    it('metrics watch a real disk fill: dd 5 MiB and diskUsed grows', async () => {
+      const sbx = await Sandbox.create(connection());
+      try {
+        const before = (await sbx.getMetrics())[0];
+        if (!before) throw new Error('no baseline sample');
+        await sbx.commands.run(
+          'dd if=/dev/zero of=/home/user/fill.bin bs=1M count=5 conv=fsync',
+        );
+        // Re-read until the filesystem's accounting catches up.
+        let after = (await sbx.getMetrics())[0];
+        const deadline = Date.now() + 20_000;
+        while (
+          (after?.diskUsed ?? 0) <= before.diskUsed &&
+          Date.now() < deadline
+        ) {
+          await sleep(0.5);
+          after = (await sbx.getMetrics())[0];
+        }
+        expect(after?.diskUsed ?? 0).toBeGreaterThan(before.diskUsed);
+      } finally {
+        await sbx.kill();
+      }
+    });
+
     it('getHost reaches a real server started in the sandbox', async () => {
       const sbx = await Sandbox.create(connection());
       try {
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 9e1a84b..b05fe20 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -344,6 +344,68 @@ describe('E2B control plane', () => {
     expect(findBySandboxId(t.db, sandboxID)?.state).toBe('stopped');
   });
 
+  it('metrics answers one sample in SDK field names; start/end accepted, ignored', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    // start/end slice a history we do not keep — one sample, taken now.
+    const res = await control(
+      t,
+      'GET',
+      `/sandboxes/${sandboxID}/metrics?start=1&end=2`,
+    );
+    expect(res.statusCode).toBe(200);
+    const samples = res.json();
+    expect(samples).toHaveLength(1);
+    const m = samples[0];
+    expect(Date.parse(m.timestamp)).not.toBeNaN();
+    expect(
+      Math.abs(Date.parse(m.timestamp) / 1000 - m.timestampUnix),
+    ).toBeLessThanOrEqual(1);
+    expect(m.cpuCount).toBeGreaterThanOrEqual(1);
+    expect(m.cpuUsedPct).toBeGreaterThanOrEqual(0);
+    expect(m.memUsed).toBeGreaterThan(0);
+    expect(m.memTotal).toBeGreaterThan(0);
+    expect(m.memCache).toBeGreaterThanOrEqual(0);
+    expect(m.diskUsed).toBeGreaterThan(0);
+    expect(m.diskTotal).toBeGreaterThan(0);
+  });
+
+  it('metrics reads a frozen sandbox without waking it; a stopped one answers []', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t, { timeout: 86400 });
+    // Freeze through the idle scanner, exactly like production.
+    const row = findBySandboxId(t.db, sandboxID);
+    const later = new Date(
+      Date.now() + ((row?.freezeAfterSeconds ?? 0) + 60) * 1000,
+    );
+    await scanOnce(t.db, t.executor, t.locks, later);
+    expect(t.executor.stateOf(sandboxID)).toBe('paused');
+
+    const frozen = await control(t, 'GET', `/sandboxes/${sandboxID}/metrics`);
+    expect(frozen.statusCode).toBe(200);
+    expect(frozen.json()).toHaveLength(1);
+    // Observation is not activity: still paused afterwards.
+    expect(t.executor.stateOf(sandboxID)).toBe('paused');
+
+    // keepMemory:false parks it stopped — nothing runs, so no samples.
+    await control(t, 'POST', `/sandboxes/${sandboxID}/pause`, {
+      memory: false,
+    });
+    const stopped = await control(t, 'GET', `/sandboxes/${sandboxID}/metrics`);
+    expect(stopped.statusCode).toBe(200);
+    expect(stopped.json()).toEqual([]);
+  });
+
+  it('metrics 404s an unknown sandbox in the control-plane dialect', async () => {
+    const t = testApp();
+    const res = await control(t, 'GET', '/sandboxes/no-such/metrics');
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toEqual({
+      code: 404,
+      message: 'sandbox "no-such" not found',
+    });
+  });
+
   it('lists with metadata and state filters, paginating via x-next-token', async () => {
     const t = testApp();
     const blue1 = await createSandbox(t, { metadata: { team: 'blue' } });
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index e7d1303..c3bd47d 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -285,6 +285,39 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     return infoView(row, state);
   });
 
+  // The SDK sends start/end (unix seconds) to slice a metrics history; we
+  // keep none — the daemon is an observation window, not a monitoring
+  // system — so the answer is always one sample, taken now. loose() admits
+  // the query without acting on it.
+  app.get(
+    '/sandboxes/:id/metrics',
+    { schema: { querystring: z.object({}).loose() } },
+    async (request) => {
+      const { id } = request.params as { id: string };
+      const { row } = findLive(id);
+      // Physical stopped/archived: nothing is running to measure, and
+      // measuring must never wake a sandbox (observation is not activity —
+      // the same principle that keeps list from waking). [] is the honest
+      // answer, and a legal one to the SDK.
+      if (row.state !== 'active' && row.state !== 'frozen') return [];
+      const m = await executor.metrics(row.sandboxId);
+      const now = new Date();
+      return [
+        {
+          timestamp: now.toISOString(),
+          timestampUnix: Math.floor(now.getTime() / 1000),
+          cpuCount: m.cpuCount,
+          cpuUsedPct: m.cpuUsedPct,
+          memUsed: m.memUsedBytes,
+          memTotal: m.memTotalBytes,
+          memCache: m.memCacheBytes,
+          diskUsed: m.diskUsedBytes,
+          diskTotal: m.diskTotalBytes,
+        },
+      ];
+    },
+  );
+
   app.delete('/sandboxes/:id', async (request, reply) => {
     const { id } = request.params as { id: string };
     // kill = release, for real: container, disk and row gone. Persistence
diff --git a/packages/server/src/executor/contract/index.ts b/packages/server/src/executor/contract/index.ts
index 43ad211..0bb48df 100644
--- a/packages/server/src/executor/contract/index.ts
+++ b/packages/server/src/executor/contract/index.ts
@@ -6,6 +6,7 @@ import { execTests } from './exec';
 import { execStreamTests } from './exec-stream';
 import { fileTests } from './files';
 import { lifecycleTests } from './lifecycle';
+import { metricsTests } from './metrics';
 import { watchTests } from './watch';
 
 /**
@@ -122,5 +123,6 @@ export function describeExecutorContract(
     fileTests(ctx);
     entryTests(ctx);
     watchTests(ctx);
+    metricsTests(ctx);
   });
 }
diff --git a/packages/server/src/executor/contract/metrics.ts b/packages/server/src/executor/contract/metrics.ts
new file mode 100644
index 0000000..863f607
--- /dev/null
+++ b/packages/server/src/executor/contract/metrics.ts
@@ -0,0 +1,86 @@
+import { randomUUID } from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+import type { ContractContext } from './index';
+
+/**
+ * The metrics verb: a point-in-time reading. Numbers differ per runtime, so
+ * the exam checks invariants — proportions, growth, the state gate — never
+ * absolute values.
+ */
+export function metricsTests(ctx: ContractContext) {
+  const { timeoutMs } = ctx;
+
+  describe('metrics', () => {
+    it(
+      'metrics reports sane proportions on a fresh sandbox',
+      async () => {
+        const id = await ctx.fresh();
+        const m = await ctx.executor.metrics(id);
+        expect(Number.isInteger(m.cpuCount)).toBe(true);
+        expect(m.cpuCount).toBeGreaterThanOrEqual(1);
+        expect(m.cpuUsedPct).toBeGreaterThanOrEqual(0);
+        expect(m.memTotalBytes).toBeGreaterThan(0);
+        expect(m.memUsedBytes).toBeGreaterThanOrEqual(0);
+        expect(m.memUsedBytes).toBeLessThanOrEqual(m.memTotalBytes);
+        expect(m.memCacheBytes).toBeGreaterThanOrEqual(0);
+        expect(m.diskTotalBytes).toBeGreaterThan(0);
+        expect(m.diskUsedBytes).toBeGreaterThanOrEqual(0);
+        expect(m.diskUsedBytes).toBeLessThanOrEqual(m.diskTotalBytes);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'disk usage grows after writing a file',
+      async () => {
+        const id = await ctx.fresh();
+        const before = await ctx.executor.metrics(id);
+        await ctx.executor.writeFiles(id, [
+          { path: 'metrics-blob.bin', content: Buffer.alloc(2 * 1024 ** 2, 7) },
+        ]);
+        // Re-read until the filesystem's accounting catches up — ext4 may
+        // settle delayed allocations a beat after the write returns.
+        let after = await ctx.executor.metrics(id);
+        const deadline = Date.now() + timeoutMs - 1_000;
+        while (
+          after.diskUsedBytes <= before.diskUsedBytes &&
+          Date.now() < deadline
+        ) {
+          await new Promise((resolve) => setTimeout(resolve, 100));
+          after = await ctx.executor.metrics(id);
+        }
+        expect(after.diskUsedBytes).toBeGreaterThan(before.diskUsedBytes);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a paused sandbox still reports metrics — observation must not require waking',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.freeze(id);
+        const m = await ctx.executor.metrics(id);
+        expect(m.memTotalBytes).toBeGreaterThan(0);
+        expect(m.diskTotalBytes).toBeGreaterThan(0);
+        // Reading is not waking: the container is still paused afterwards.
+        expect(await ctx.stateOf(id)).toBe('paused');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'metrics refuses a stopped or absent sandbox',
+      async () => {
+        const stopped = await ctx.freshStopped();
+        await expect(ctx.executor.metrics(stopped)).rejects.toThrow(
+          `container ${stopped} is stopped, expected running or paused`,
+        );
+        const ghost = randomUUID();
+        await expect(ctx.executor.metrics(ghost)).rejects.toThrow(
+          `container ${ghost} is absent, expected running or paused`,
+        );
+      },
+      timeoutMs,
+    );
+  });
+}
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index f06b752..4ccdb38 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -7,6 +7,7 @@ import {
   readdir,
   readFile,
   rm,
+  statfs,
 } from 'node:fs/promises';
 import path from 'node:path';
 import type { Duplex, Writable } from 'node:stream';
@@ -58,6 +59,7 @@ import {
   NotAFileError,
   type PtySize,
   type SandboxEntry,
+  type SandboxMetrics,
   type WatchDirHandle,
   type WatchDirOptions,
 } from './executor';
@@ -313,6 +315,48 @@ export class DockerExecutor implements Executor {
     return { host: ip, port };
   }
 
+  async metrics(sandboxId: string): Promise<SandboxMetrics> {
+    const found = await this.inspect(sandboxId);
+    const actual =
+      found === null ? undefined : containerStateFromDocker(found.status);
+    if (found === null || (actual !== 'running' && actual !== 'paused')) {
+      throw new Error(
+        `container ${sandboxId} is ${actual ?? 'absent'}, expected running or paused`,
+      );
+    }
+    // stream:false makes the engine take two samples a beat apart so the
+    // CPU delta below has a denominator; one reading costs about a second.
+    const stats = await this.docker
+      .getContainer(found.id)
+      .stats({ stream: false });
+    const cpuDelta =
+      (stats.cpu_stats?.cpu_usage?.total_usage ?? 0) -
+      (stats.precpu_stats?.cpu_usage?.total_usage ?? 0);
+    const systemDelta =
+      (stats.cpu_stats?.system_cpu_usage ?? 0) -
+      (stats.precpu_stats?.system_cpu_usage ?? 0);
+    const onlineCpus = stats.cpu_stats?.online_cpus || this.opts.cpus;
+    // cgroup v2 calls the page cache inactive_file; v1 calls it cache.
+    const memStats = (stats.memory_stats?.stats ?? {}) as Record<
+      string,
+      number
+    >;
+    const disk = await statfs(this.mountDir(sandboxId));
+    return {
+      cpuCount: this.opts.cpus,
+      cpuUsedPct:
+        systemDelta > 0 && cpuDelta > 0
+          ? (cpuDelta / systemDelta) * onlineCpus * 100
+          : 0,
+      memUsedBytes: stats.memory_stats?.usage ?? 0,
+      memTotalBytes:
+        stats.memory_stats?.limit || Math.round(this.opts.memoryGb * 1024 ** 3),
+      memCacheBytes: memStats.cache ?? memStats.inactive_file ?? 0,
+      diskUsedBytes: (disk.blocks - disk.bfree) * disk.bsize,
+      diskTotalBytes: disk.blocks * disk.bsize,
+    };
+  }
+
   async exec(sandboxId: string, opts: ExecOptions): Promise<ExecResult> {
     const containerId = await this.expectState(sandboxId, 'running');
     const container = this.docker.getContainer(containerId);
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index 8e9566f..a63dc73 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -166,6 +166,23 @@ export interface SandboxEntry {
   group: string;
 }
 
+/**
+ * A point-in-time resource reading of one sandbox — what the E2B surface's
+ * getMetrics reports. Numbers are observations, not promises: a runtime
+ * that cannot account for something reports 0, honestly.
+ */
+export interface SandboxMetrics {
+  /** Configured CPU allowance, same source as the control plane's info. */
+  cpuCount: number;
+  /** Percent of one CPU; can exceed 100 on a multi-CPU sandbox. */
+  cpuUsedPct: number;
+  memUsedBytes: number;
+  memTotalBytes: number;
+  memCacheBytes: number;
+  diskUsedBytes: number;
+  diskTotalBytes: number;
+}
+
 /**
  * The file-op error taxonomy, shared by both executors down to the message
  * (the contract exam holds them to it) and mapped to HTTP statuses by the
@@ -252,6 +269,15 @@ export interface Executor {
     sandboxId: string,
     port: number,
   ): Promise<{ host: string; port: number }>;
+  /**
+   * A point-in-time resource reading. Unlike the exec verbs it accepts a
+   * paused container too — reading cgroup accounting does not require the
+   * guest to run, and metrics must never wake a sandbox (observation is
+   * not activity, the same principle as listing). A stopped or absent
+   * container throws (`expected running or paused`): there is nothing
+   * running to measure — the route above answers [] for those on its own.
+   */
+  metrics(sandboxId: string): Promise<SandboxMetrics>;
   /**
    * Runs a shell command inside a running container and returns the fully
    * buffered result. Requires state `running` — a paused container cannot
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index bac0a1a..2d0157e 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -19,6 +19,7 @@ import {
   NotAFileError,
   type PtySize,
   type SandboxEntry,
+  type SandboxMetrics,
   type WatchDirHandle,
   type WatchDirOptions,
   type WatchEvent,
@@ -356,6 +357,31 @@ export class FakeExecutor implements Executor {
     this.upstreams.delete(sandboxId);
   }
 
+  async metrics(sandboxId: string): Promise<SandboxMetrics> {
+    const actual = this.containers.get(sandboxId);
+    if (actual !== 'running' && actual !== 'paused') {
+      throw new Error(
+        `container ${sandboxId} is ${actual ?? 'absent'}, expected running or paused`,
+      );
+    }
+    // Disk usage is computed from the file table — the one number the
+    // contract can watch move (write a file, usage grows) on both
+    // executors; the rest are plausible constants in honest proportions.
+    let diskUsedBytes = 0;
+    for (const node of this.disk(sandboxId).values()) {
+      diskUsedBytes += node.type === 'file' ? node.content.length : 4096;
+    }
+    return {
+      cpuCount: 1,
+      cpuUsedPct: 0,
+      memUsedBytes: 64 * 1024 ** 2,
+      memTotalBytes: 2 * 1024 ** 3,
+      memCacheBytes: 0,
+      diskUsedBytes,
+      diskTotalBytes: 10 * 1024 ** 3,
+    };
+  }
+
   async exec(sandboxId: string, opts: ExecOptions): Promise<ExecResult> {
     const stdout = new CappedText(EXEC_OUTPUT_LIMIT_BYTES);
     const stderr = new CappedText(EXEC_OUTPUT_LIMIT_BYTES);

From 73c69a09ee5ba24430a7dbda26d36af97f38bd79 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 17:34:55 +0800
Subject: [PATCH 030/133] Signed file URLs land at the daemon root, the
 signature is auth and identity

---
 e2e/src/e2b.test.ts                     |  48 +++++
 packages/server/src/e2b/compat.test.ts  | 246 +++++++++++++++++++++++
 packages/server/src/e2b/envd/files.ts   | 255 +++++++++++++-----------
 packages/server/src/e2b/index.ts        |   6 +
 packages/server/src/e2b/signed-files.ts | 134 +++++++++++++
 packages/server/src/e2b/signing.ts      |  71 +++++++
 6 files changed, 640 insertions(+), 120 deletions(-)
 create mode 100644 packages/server/src/e2b/signed-files.ts
 create mode 100644 packages/server/src/e2b/signing.ts

diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 4add6f4..6268636 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -175,6 +175,54 @@ describe('official e2b SDK against the daemon', () => {
     }
   });
 
+  it('signed URLs from the SDK work bare over fetch: download, upload, refusals', async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      await sbx.files.write('signed/hello.txt', 'signed content\n');
+
+      // The URL the SDK actually builds (new URL('/files', sandboxUrl)
+      // strips the /e2b/envd prefix — this test is what pins that reality).
+      const url = await sbx.downloadUrl('signed/hello.txt', {
+        useSignatureExpiration: 300,
+      });
+      const res = await fetch(url);
+      expect(res.status).toBe(200);
+      expect(await res.text()).toBe('signed content\n');
+
+      // Tampering with the signature closes the door.
+      const forged = new URL(url);
+      forged.searchParams.set('signature', 'v1_forged');
+      expect((await fetch(forged)).status).toBe(401);
+
+      // An expired signature closes it too, by name.
+      const expiredUrl = await sbx.downloadUrl('signed/hello.txt', {
+        useSignatureExpiration: -10,
+      });
+      const expired = await fetch(expiredUrl);
+      expect(expired.status).toBe(401);
+      expect(((await expired.json()) as { message: string }).message).toBe(
+        'signature is already expired',
+      );
+
+      // Upload the way the docs show: FormData against uploadUrl, the
+      // part's filename carrying the destination path.
+      const uploadUrl = await sbx.uploadUrl();
+      const form = new FormData();
+      form.append(
+        'file',
+        new Blob(['uploaded via signed url\n']),
+        'signed/up.txt',
+      );
+      const up = await fetch(uploadUrl, { method: 'POST', body: form });
+      expect(up.status).toBe(200);
+      expect(await sbx.files.read('signed/up.txt')).toBe(
+        'uploaded via signed url\n',
+      );
+    } finally {
+      await sbx.kill();
+    }
+  });
+
   it('reports info, appears in list, and can be found by metadata', async () => {
     const sbx = await Sandbox.create({
       ...connection(),
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index b05fe20..7a9fa16 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 import { buildApp } from '../app';
@@ -1220,3 +1221,248 @@ describe('E2B envd surface', () => {
     });
   });
 });
+
+/**
+ * The signature exactly as the official SDK computes it (signature.ts in
+ * the e2b package) — deliberately re-implemented here instead of importing
+ * our signing.ts, so the test pins both ends of the wire independently.
+ */
+function sdkSignature(opts: {
+  path?: string;
+  operation: 'read' | 'write';
+  user?: string;
+  envdAccessToken: string;
+  expiration?: number;
+}): string {
+  const raw = [
+    opts.path ?? '',
+    opts.operation,
+    opts.user ?? '',
+    opts.envdAccessToken,
+    ...(opts.expiration === undefined ? [] : [String(opts.expiration)]),
+  ].join(':');
+  const hash = createHash('sha256').update(raw, 'utf8').digest('base64');
+  return `v1_${hash.replace(/=+$/, '')}`;
+}
+
+/** Writes a file through the envd surface — the signed tests' fixture pen. */
+async function putFile(
+  t: TestApp,
+  sandboxID: string,
+  path: string,
+  content: string,
+) {
+  const res = await t.app.inject({
+    method: 'POST',
+    url: `/e2b/envd/files?path=${encodeURIComponent(path)}`,
+    headers: {
+      ...envdHeaders(sandboxID),
+      'content-type': 'application/octet-stream',
+    },
+    payload: content,
+  });
+  expect(res.statusCode).toBe(200);
+}
+
+describe('signed file URLs at the daemon root', () => {
+  it('a bare signed GET /files downloads — the signature is auth AND identity', async () => {
+    const t = testApp();
+    const a = await createSandbox(t);
+    const b = await createSandbox(t);
+    // The same path in two sandboxes, different content: only the
+    // signature says which sandbox the URL speaks for.
+    await putFile(t, a.sandboxID, 'secret.txt', 'contents of A\n');
+    await putFile(t, b.sandboxID, 'secret.txt', 'contents of B\n');
+
+    const download = (token: string, expiration?: number) => {
+      const sig = sdkSignature({
+        path: 'secret.txt',
+        operation: 'read',
+        envdAccessToken: token,
+        ...(expiration === undefined ? {} : { expiration }),
+      });
+      const exp =
+        expiration === undefined ? '' : `&signature_expiration=${expiration}`;
+      // No headers at all — exactly what a browser hitting the URL sends.
+      return t.app.inject({
+        method: 'GET',
+        url: `/files?path=secret.txt&signature=${encodeURIComponent(sig)}${exp}`,
+      });
+    };
+
+    const fromA = await download(a.envdAccessToken);
+    expect(fromA.statusCode).toBe(200);
+    expect(fromA.body).toBe('contents of A\n');
+
+    // With a future expiration in the material — the second signing shape.
+    const exp = Math.floor(Date.now() / 1000) + 300;
+    const fromB = await download(b.envdAccessToken, exp);
+    expect(fromB.statusCode).toBe(200);
+    expect(fromB.body).toBe('contents of B\n');
+  });
+
+  it('signed uploads: multipart carries the path in the filename, octet-stream in the query', async () => {
+    const t = testApp();
+    const { sandboxID, envdAccessToken } = await createSandbox(t);
+
+    // uploadUrl without a path signs the empty string and sends no ?path=.
+    const multipartSig = sdkSignature({
+      operation: 'write',
+      envdAccessToken,
+    });
+    const boundary = 'dormice-signed-boundary';
+    const body = [
+      `--${boundary}`,
+      'Content-Disposition: form-data; name="file"; filename="signed/up.txt"',
+      'Content-Type: application/octet-stream',
+      '',
+      'through the signed door\n',
+      `--${boundary}--`,
+      '',
+    ].join('\r\n');
+    const up = await t.app.inject({
+      method: 'POST',
+      url: `/files?signature=${encodeURIComponent(multipartSig)}`,
+      headers: { 'content-type': `multipart/form-data; boundary=${boundary}` },
+      payload: body,
+    });
+    expect(up.statusCode).toBe(200);
+    expect(up.json()).toEqual([
+      { name: 'up.txt', type: 'file', path: '/home/user/signed/up.txt' },
+    ]);
+
+    const octetSig = sdkSignature({
+      path: 'signed/oct.txt',
+      operation: 'write',
+      envdAccessToken,
+    });
+    const oct = await t.app.inject({
+      method: 'POST',
+      url: `/files?path=${encodeURIComponent('signed/oct.txt')}&signature=${encodeURIComponent(octetSig)}`,
+      headers: { 'content-type': 'application/octet-stream' },
+      payload: 'octets through the signed door\n',
+    });
+    expect(oct.statusCode).toBe(200);
+
+    // Both landed in the sandbox, readable through the envd surface.
+    const back = await t.app.inject({
+      method: 'GET',
+      url: '/e2b/envd/files?path=signed/oct.txt',
+      headers: envdHeaders(sandboxID),
+    });
+    expect(back.body).toBe('octets through the signed door\n');
+  });
+
+  it("refuses in real envd's order and words", async () => {
+    const t = testApp();
+    const { envdAccessToken } = await createSandbox(t);
+
+    const missing = await t.app.inject({ method: 'GET', url: '/files?path=x' });
+    expect(missing.statusCode).toBe(401);
+    expect(missing.json()).toEqual({
+      code: 'unauthenticated',
+      message: 'missing signature query parameter',
+    });
+
+    const wrong = await t.app.inject({
+      method: 'GET',
+      url: '/files?path=x&signature=v1_forged',
+    });
+    expect(wrong.statusCode).toBe(401);
+    expect(wrong.json().message).toBe('invalid signature');
+
+    // A valid signature whose material includes a past expiration: the
+    // match succeeds, the clock refuses.
+    const past = Math.floor(Date.now() / 1000) - 10;
+    const expiredSig = sdkSignature({
+      path: 'x',
+      operation: 'read',
+      envdAccessToken,
+      expiration: past,
+    });
+    const expired = await t.app.inject({
+      method: 'GET',
+      url: `/files?path=x&signature=${encodeURIComponent(expiredSig)}&signature_expiration=${past}`,
+    });
+    expect(expired.statusCode).toBe(401);
+    expect(expired.json().message).toBe('signature is already expired');
+
+    // A wrong signature that also claims a past expiration must say
+    // "invalid signature" — the signature check comes first, so a forger
+    // never learns whether their expiry was the problem.
+    const forgedExpired = await t.app.inject({
+      method: 'GET',
+      url: `/files?path=x&signature=v1_forged&signature_expiration=${past}`,
+    });
+    expect(forgedExpired.json().message).toBe('invalid signature');
+
+    // A read signature opens no write door: the operation is in the material.
+    const readSig = sdkSignature({
+      path: 'x',
+      operation: 'read',
+      envdAccessToken,
+    });
+    const misused = await t.app.inject({
+      method: 'POST',
+      url: `/files?path=x&signature=${encodeURIComponent(readSig)}`,
+      headers: { 'content-type': 'application/octet-stream' },
+      payload: 'nope',
+    });
+    expect(misused.statusCode).toBe(401);
+    expect(misused.json().message).toBe('invalid signature');
+
+    // The root door is signature-only: a header token belongs to
+    // /e2b/envd/files and buys nothing here.
+    const headerOnly = await t.app.inject({
+      method: 'GET',
+      url: '/files?path=x',
+      headers: { 'x-access-token': envdAccessToken },
+    });
+    expect(headerOnly.statusCode).toBe(401);
+    expect(headerOnly.json().message).toBe('missing signature query parameter');
+  });
+
+  it('a signed download wakes a frozen sandbox — autoResume through the bare door', async () => {
+    const t = testApp();
+    const { sandboxID, envdAccessToken } = await createSandbox(t, {
+      timeout: 86400,
+    });
+    await putFile(t, sandboxID, 'frozen.txt', 'still here\n');
+    const row = findBySandboxId(t.db, sandboxID);
+    const later = new Date(
+      Date.now() + ((row?.freezeAfterSeconds ?? 0) + 60) * 1000,
+    );
+    await scanOnce(t.db, t.executor, t.locks, later);
+    expect(t.executor.stateOf(sandboxID)).toBe('paused');
+
+    const sig = sdkSignature({
+      path: 'frozen.txt',
+      operation: 'read',
+      envdAccessToken,
+    });
+    const res = await t.app.inject({
+      method: 'GET',
+      url: `/files?path=frozen.txt&signature=${encodeURIComponent(sig)}`,
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toBe('still here\n');
+    expect(t.executor.stateOf(sandboxID)).toBe('running');
+  });
+
+  it("vets the signed username: only the image's users exist", async () => {
+    const t = testApp();
+    const { envdAccessToken } = await createSandbox(t);
+    const sig = sdkSignature({
+      path: 'x',
+      operation: 'read',
+      user: 'nobody',
+      envdAccessToken,
+    });
+    const res = await t.app.inject({
+      method: 'GET',
+      url: `/files?path=x&username=nobody&signature=${encodeURIComponent(sig)}`,
+    });
+    expect(res.statusCode).toBe(401);
+    expect(res.json().message).toBe("invalid username: 'nobody'");
+  });
+});
diff --git a/packages/server/src/e2b/envd/files.ts b/packages/server/src/e2b/envd/files.ts
index 4ee20a4..475e5b3 100644
--- a/packages/server/src/e2b/envd/files.ts
+++ b/packages/server/src/e2b/envd/files.ts
@@ -1,5 +1,5 @@
 import { resolveSandboxPath } from '@dormice/shared';
-import type { FastifyInstance } from 'fastify';
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
 import { touch } from '../../db/ledger';
 import { startExecHeartbeat } from '../../exec-heartbeat';
 import {
@@ -11,143 +11,158 @@ import {
 import { E2bError } from '../protocol';
 import { type EnvdContext, sandboxIdOf, UNLIMITED_BODY_BYTES } from './shared';
 
-/** The plain-HTTP file faces: GET /files streams out, POST /files streams in. */
+/**
+ * The plain-HTTP file faces: GET /files streams out, POST /files streams in.
+ * The handler cores take the sandbox id as a parameter because two doors
+ * lead here — the envd surface (id in the E2b-Sandbox-Id header, token
+ * auth) and the signed-URL surface at the daemon root (id recovered from
+ * the signature itself, no headers at all).
+ */
 export function registerFileRoutes(
   app: FastifyInstance,
   ctx: EnvdContext,
 ): void {
-  const { db, executor } = ctx;
+  app.get('/files', async (request, reply) =>
+    serveFileDownload(ctx, sandboxIdOf(request), request, reply),
+  );
+
+  app.post('/files', { bodyLimit: UNLIMITED_BODY_BYTES }, (request, reply) =>
+    serveFileUpload(ctx, sandboxIdOf(request), request, reply),
+  );
+}
 
-  app.get('/files', async (request, reply) => {
-    const query = request.query as { path?: string };
-    if (!query.path) {
-      throw new E2bError(400, 'invalid_argument', 'missing path query');
+export async function serveFileDownload(
+  ctx: EnvdContext,
+  sandboxId: string,
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const { db, executor } = ctx;
+  const query = request.query as { path?: string };
+  if (!query.path) {
+    throw new E2bError(400, 'invalid_argument', 'missing path query');
+  }
+  const row = await ctx.wakeForUse(sandboxId);
+  const stopHeartbeat = startExecHeartbeat(
+    db,
+    row.sandboxId,
+    row.freezeAfterSeconds,
+  );
+  try {
+    let entry: SandboxEntry;
+    try {
+      entry = await executor.statEntry(row.sandboxId, query.path);
+      if (entry.type !== 'file') {
+        throw new NotAFileError(`not a regular file: ${entry.path}`);
+      }
+    } catch (error) {
+      if (error instanceof FileNotFoundError) {
+        throw new E2bError(404, 'not_found', error.message);
+      }
+      if (error instanceof NotAFileError) {
+        throw new E2bError(400, 'invalid_argument', error.message);
+      }
+      throw error;
+    }
+    // Size first, then stream: the SDK needs content-length (an empty
+    // file is detected by `content-length: 0`), and nothing buffers here.
+    reply.hijack();
+    reply.raw.writeHead(200, {
+      'content-type': 'application/octet-stream',
+      'content-length': String(entry.sizeBytes),
+    });
+    await executor.readFileStream(row.sandboxId, query.path, (chunk) => {
+      if (!reply.raw.write(chunk)) {
+        // Backpressure: the promise pauses the pipe all the way into the
+        // container until the client drains.
+        return new Promise<void>((resolve) => reply.raw.once('drain', resolve));
+      }
+    });
+    reply.raw.end();
+  } catch (error) {
+    if (reply.raw.headersSent) {
+      // Mid-stream failure: the body length will not match the announced
+      // content-length — the client sees a broken transfer, honestly.
+      request.log.error(error, 'file download broke mid-stream');
+      reply.raw.destroy();
+      return;
     }
-    const row = await ctx.wakeForUse(sandboxIdOf(request));
-    const stopHeartbeat = startExecHeartbeat(
-      db,
-      row.sandboxId,
-      row.freezeAfterSeconds,
-    );
+    throw error;
+  } finally {
+    stopHeartbeat();
     try {
-      let entry: SandboxEntry;
+      touch(db, row.sandboxId);
+    } catch {
+      // Released mid-transfer; the transfer's own error tells the story.
+    }
+  }
+}
+
+export async function serveFileUpload(
+  ctx: EnvdContext,
+  sandboxId: string,
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<unknown> {
+  const { db, executor } = ctx;
+  const query = request.query as { path?: string };
+  const row = await ctx.wakeForUse(sandboxId);
+  const stopHeartbeat = startExecHeartbeat(
+    db,
+    row.sandboxId,
+    row.freezeAfterSeconds,
+  );
+  try {
+    const written: Array<{ name: string; type: 'file'; path: string }> = [];
+    const writeOne = async (path: string, content: NodeJS.ReadableStream) => {
       try {
-        entry = await executor.statEntry(row.sandboxId, query.path);
-        if (entry.type !== 'file') {
-          throw new NotAFileError(`not a regular file: ${entry.path}`);
-        }
+        await executor.writeFileStream(row.sandboxId, path, content);
       } catch (error) {
-        if (error instanceof FileNotFoundError) {
-          throw new E2bError(404, 'not_found', error.message);
-        }
         if (error instanceof NotAFileError) {
           throw new E2bError(400, 'invalid_argument', error.message);
         }
+        if (error instanceof DiskFullError) {
+          throw new E2bError(507, 'not_enough_space', error.message);
+        }
         throw error;
       }
-      // Size first, then stream: the SDK needs content-length (an empty
-      // file is detected by `content-length: 0`), and nothing buffers here.
-      reply.hijack();
-      reply.raw.writeHead(200, {
-        'content-type': 'application/octet-stream',
-        'content-length': String(entry.sizeBytes),
+      const resolved = resolveSandboxPath(path);
+      written.push({
+        name: resolved.slice(resolved.lastIndexOf('/') + 1),
+        type: 'file',
+        path: resolved,
       });
-      await executor.readFileStream(row.sandboxId, query.path, (chunk) => {
-        if (!reply.raw.write(chunk)) {
-          // Backpressure: the promise pauses the pipe all the way into the
-          // container until the client drains.
-          return new Promise<void>((resolve) =>
-            reply.raw.once('drain', resolve),
+    };
+
+    if (request.isMultipart()) {
+      // The SDK's default upload shape: one part per file, field name
+      // `file`, the part's filename carrying the destination path.
+      for await (const part of request.parts()) {
+        if (part.type !== 'file') continue;
+        const destination = part.filename || query.path;
+        if (!destination) {
+          throw new E2bError(
+            400,
+            'invalid_argument',
+            'multipart file part has no filename and no ?path= fallback',
           );
         }
-      });
-      reply.raw.end();
-    } catch (error) {
-      if (reply.raw.headersSent) {
-        // Mid-stream failure: the body length will not match the announced
-        // content-length — the client sees a broken transfer, honestly.
-        request.log.error(error, 'file download broke mid-stream');
-        reply.raw.destroy();
-        return;
+        await writeOne(destination, part.file);
       }
-      throw error;
-    } finally {
-      stopHeartbeat();
-      try {
-        touch(db, row.sandboxId);
-      } catch {
-        // Released mid-transfer; the transfer's own error tells the story.
+    } else {
+      // Octet-stream (the SDK's streaming/gzip shape): path in the query.
+      if (!query.path) {
+        throw new E2bError(400, 'invalid_argument', 'missing path query');
       }
+      await writeOne(query.path, request.body as NodeJS.ReadableStream);
     }
-  });
-
-  app.post(
-    '/files',
-    { bodyLimit: UNLIMITED_BODY_BYTES },
-    async (request, reply) => {
-      const query = request.query as { path?: string };
-      const row = await ctx.wakeForUse(sandboxIdOf(request));
-      const stopHeartbeat = startExecHeartbeat(
-        db,
-        row.sandboxId,
-        row.freezeAfterSeconds,
-      );
-      try {
-        const written: Array<{ name: string; type: 'file'; path: string }> = [];
-        const writeOne = async (
-          path: string,
-          content: NodeJS.ReadableStream,
-        ) => {
-          try {
-            await executor.writeFileStream(row.sandboxId, path, content);
-          } catch (error) {
-            if (error instanceof NotAFileError) {
-              throw new E2bError(400, 'invalid_argument', error.message);
-            }
-            if (error instanceof DiskFullError) {
-              throw new E2bError(507, 'not_enough_space', error.message);
-            }
-            throw error;
-          }
-          const resolved = resolveSandboxPath(path);
-          written.push({
-            name: resolved.slice(resolved.lastIndexOf('/') + 1),
-            type: 'file',
-            path: resolved,
-          });
-        };
-
-        if (request.isMultipart()) {
-          // The SDK's default upload shape: one part per file, field name
-          // `file`, the part's filename carrying the destination path.
-          for await (const part of request.parts()) {
-            if (part.type !== 'file') continue;
-            const destination = part.filename || query.path;
-            if (!destination) {
-              throw new E2bError(
-                400,
-                'invalid_argument',
-                'multipart file part has no filename and no ?path= fallback',
-              );
-            }
-            await writeOne(destination, part.file);
-          }
-        } else {
-          // Octet-stream (the SDK's streaming/gzip shape): path in the query.
-          if (!query.path) {
-            throw new E2bError(400, 'invalid_argument', 'missing path query');
-          }
-          await writeOne(query.path, request.body as NodeJS.ReadableStream);
-        }
-        return await reply.code(200).send(written);
-      } finally {
-        stopHeartbeat();
-        try {
-          touch(db, row.sandboxId);
-        } catch {
-          // Released mid-upload; the upload's own result tells the story.
-        }
-      }
-    },
-  );
+    return await reply.code(200).send(written);
+  } finally {
+    stopHeartbeat();
+    try {
+      touch(db, row.sandboxId);
+    } catch {
+      // Released mid-upload; the upload's own result tells the story.
+    }
+  }
 }
diff --git a/packages/server/src/e2b/index.ts b/packages/server/src/e2b/index.ts
index 24ae927..4ddf02d 100644
--- a/packages/server/src/e2b/index.ts
+++ b/packages/server/src/e2b/index.ts
@@ -2,6 +2,7 @@ import type { FastifyInstance } from 'fastify';
 import { e2bControlRoutes } from './control';
 import type { E2bDeps } from './deps';
 import { e2bEnvdRoutes } from './envd';
+import { signedFileRoutes } from './signed-files';
 
 /**
  * The E2B compatibility layer: the official `e2b` package connects with two
@@ -9,6 +10,10 @@ import { e2bEnvdRoutes } from './envd';
  * `e2b_<DORMICE_API_TOKEN>` as its API key. Both scopes carry their own
  * auth and their own { code, message } error dialect; the native API's
  * Bearer auth and { message } dialect stay outside, untouched.
+ *
+ * The third registration has no prefix: signed file URLs land on
+ * `<daemon>/files` because the SDK's `new URL('/files', sandboxUrl)`
+ * replaces the whole path — see signed-files.ts.
  */
 export async function registerE2bCompat(
   app: FastifyInstance,
@@ -16,4 +21,5 @@ export async function registerE2bCompat(
 ): Promise<void> {
   await app.register(e2bControlRoutes, { ...deps, prefix: '/e2b/api' });
   await app.register(e2bEnvdRoutes, { ...deps, prefix: '/e2b/envd' });
+  await app.register(signedFileRoutes, deps);
 }
diff --git a/packages/server/src/e2b/signed-files.ts b/packages/server/src/e2b/signed-files.ts
new file mode 100644
index 0000000..aeda2e9
--- /dev/null
+++ b/packages/server/src/e2b/signed-files.ts
@@ -0,0 +1,134 @@
+import multipart from '@fastify/multipart';
+import type { FastifyRequest } from 'fastify';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import type { E2bDeps } from './deps';
+import { serveFileDownload, serveFileUpload } from './envd/files';
+import { createEnvdContext, UNLIMITED_BODY_BYTES } from './envd/shared';
+import { E2bError } from './protocol';
+import { findRowBySignature, type SigningOperation } from './signing';
+
+/**
+ * The signed-URL file surface, at the DAEMON ROOT — not under /e2b/envd.
+ * Not a stylistic choice: the SDK's uploadUrl/downloadUrl build their URL
+ * as `new URL('/files', sandboxUrl)`, and an absolute path replaces the
+ * whole path — the /e2b/envd prefix is stripped (verified against the SDK
+ * source). The consumer is a bare browser or curl: no E2b-Sandbox-Id
+ * header, no token, nothing but the query. The signature alone
+ * authenticates AND identifies the sandbox (see findRowBySignature).
+ *
+ * Deliberately signature-only: a header token here would be a second door
+ * to the same room — token-authenticated file traffic already has
+ * /e2b/envd/files. Real envd accepts both because it has only one door.
+ */
+export const signedFileRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
+  app,
+  deps,
+) => {
+  const { config } = deps;
+  // Same parser set as the envd surface: the upload shapes are identical.
+  await app.register(multipart, {
+    limits: {
+      fileSize: UNLIMITED_BODY_BYTES,
+      files: 1000,
+      parts: 2000,
+      fieldSize: 1024 * 1024,
+    },
+    preservePath: true,
+  });
+  app.addContentTypeParser(
+    'application/octet-stream',
+    (_request, payload, done) => done(null, payload),
+  );
+
+  // The envd error dialect ({ code: string, message }), scoped to these two
+  // routes; the daemon root's native { message } dialect stays untouched —
+  // and so does its 404 handler (no setNotFoundHandler here on purpose).
+  app.setErrorHandler((error, request, reply) => {
+    if (error instanceof E2bError) {
+      return reply
+        .code(error.statusCode)
+        .send({ code: error.code, message: error.message });
+    }
+    const status = (error as { statusCode?: number }).statusCode ?? 500;
+    if (status >= 500) {
+      request.log.error(error, 'signed file request failed');
+    }
+    return reply.code(status).send({
+      code: status === 400 ? 'invalid_argument' : 'internal',
+      message: (error as Error).message,
+    });
+  });
+
+  const ctx = createEnvdContext(deps);
+
+  /**
+   * Real envd's validateSigning, in its order: missing signature first,
+   * then the constant-time match (which here also recovers the sandbox),
+   * and only then the expiration — a wrong signature must never learn from
+   * the error whether it was also expired.
+   */
+  function authenticate(request: FastifyRequest, operation: SigningOperation) {
+    const query = request.query as {
+      path?: string;
+      username?: string;
+      signature?: string;
+      signature_expiration?: string;
+    };
+    if (!query.signature) {
+      throw new E2bError(
+        401,
+        'unauthenticated',
+        'missing signature query parameter',
+      );
+    }
+    const expirationUnix =
+      query.signature_expiration === undefined
+        ? undefined
+        : Number(query.signature_expiration);
+    const row = findRowBySignature(
+      deps.db,
+      config.DORMICE_API_TOKEN,
+      {
+        path: query.path ?? '',
+        operation,
+        username: query.username ?? '',
+        ...(expirationUnix === undefined ? {} : { expirationUnix }),
+      },
+      query.signature,
+    );
+    if (!row) {
+      throw new E2bError(401, 'unauthenticated', 'invalid signature');
+    }
+    if (
+      expirationUnix !== undefined &&
+      expirationUnix < Math.floor(Date.now() / 1000)
+    ) {
+      throw new E2bError(
+        401,
+        'unauthenticated',
+        'signature is already expired',
+      );
+    }
+    // The signed username also names the execution identity; only the
+    // image's own users exist. (The signature already covers it — a
+    // tampered username never gets this far.)
+    if (query.username !== undefined && query.username !== 'user') {
+      throw new E2bError(
+        401,
+        'unauthenticated',
+        `invalid username: '${query.username}'`,
+      );
+    }
+    return row;
+  }
+
+  app.get('/files', async (request, reply) => {
+    const row = authenticate(request, 'read');
+    return serveFileDownload(ctx, row.sandboxId, request, reply);
+  });
+
+  app.post('/files', { bodyLimit: UNLIMITED_BODY_BYTES }, (request, reply) => {
+    const row = authenticate(request, 'write');
+    return serveFileUpload(ctx, row.sandboxId, request, reply);
+  });
+};
diff --git a/packages/server/src/e2b/signing.ts b/packages/server/src/e2b/signing.ts
new file mode 100644
index 0000000..0a86e19
--- /dev/null
+++ b/packages/server/src/e2b/signing.ts
@@ -0,0 +1,71 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import type { Db } from '../db/db';
+import { listSandboxes } from '../db/ledger';
+import type { SandboxRow } from '../db/schema';
+import { mintEnvdToken } from './protocol';
+import { e2bView } from './view';
+
+/**
+ * The E2B file-URL signature, pinned against both ends of the official
+ * implementation (the SDK's getSignature and real envd's auth.go):
+ *
+ *   "v1_" + base64( sha256( path:operation:username:token[:expiration] ) )
+ *
+ * — standard base64 alphabet, '=' padding stripped. `path` and `username`
+ * are empty strings when absent (the SDK omits both by default against an
+ * envd >= 0.4.0, which we report); `expiration` is an absolute unix-seconds
+ * timestamp, present in the material exactly when the URL carries
+ * `signature_expiration`. The token is the sandbox's envd access token.
+ */
+export type SigningOperation = 'read' | 'write';
+
+export interface SignatureMaterial {
+  path: string;
+  operation: SigningOperation;
+  username: string;
+  expirationUnix?: number;
+}
+
+export function fileSignature(
+  envdAccessToken: string,
+  m: SignatureMaterial,
+): string {
+  const parts = [m.path, m.operation, m.username, envdAccessToken];
+  if (m.expirationUnix !== undefined) parts.push(String(m.expirationUnix));
+  const digest = createHash('sha256')
+    .update(parts.join(':'), 'utf8')
+    .digest('base64');
+  return `v1_${digest.replace(/=+$/, '')}`;
+}
+
+const sha256 = (value: string) => createHash('sha256').update(value).digest();
+
+/**
+ * Which sandbox does this signature speak for? A signed URL arrives bare —
+ * no headers, no sandbox id anywhere (the SDK's fileUrl builds
+ * `<origin>/files?...` and browsers add nothing) — but every sandbox's
+ * access token is different, so the signature itself binds the sandbox:
+ * compute the expected signature per live ledger row and take the match.
+ * At most DORMICE_MAX_SANDBOXES hashes per request — microseconds.
+ *
+ * This is the single-domain answer to what real E2B solves with one
+ * subdomain per sandbox; the deliberate divergence is documented in the
+ * protocol rules.
+ */
+export function findRowBySignature(
+  db: Db,
+  apiToken: string,
+  material: SignatureMaterial,
+  presented: string,
+): SandboxRow | undefined {
+  const now = new Date();
+  for (const row of listSandboxes(db)) {
+    if (e2bView(row, now) === 'dead') continue;
+    const expected = fileSignature(
+      mintEnvdToken(apiToken, row.sandboxId),
+      material,
+    );
+    if (timingSafeEqual(sha256(expected), sha256(presented))) return row;
+  }
+  return undefined;
+}

From da9c3ef31a94341f560688a65116713922038bdc Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 18:07:05 +0800
Subject: [PATCH 031/133] =?UTF-8?q?user:'root'=20=E2=80=94=20identity=20ri?=
 =?UTF-8?q?des=20Basic=20auth=20and=20the=20username=20query,=20decided=20?=
 =?UTF-8?q?at=20the=20two=20exec=20points?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 e2e/src/e2b.test.ts                           | 56 ++++++++++++
 packages/server/src/e2b/compat.test.ts        | 85 ++++++++++++++++++-
 packages/server/src/e2b/envd/files.ts         | 40 ++++++---
 packages/server/src/e2b/envd/filesystem.ts    | 22 +++--
 packages/server/src/e2b/envd/process.ts       | 12 +++
 packages/server/src/e2b/envd/shared.ts        | 29 ++++++-
 packages/server/src/e2b/signed-files.ts       | 13 +--
 .../src/executor/contract/exec-stream.ts      | 49 +++++++++++
 packages/server/src/executor/contract/exec.ts | 38 +++++++++
 packages/server/src/executor/docker.ts        | 66 +++++++++++---
 packages/server/src/executor/executor.ts      | 43 ++++++++--
 packages/server/src/executor/fake.ts          | 65 +++++++++++---
 12 files changed, 460 insertions(+), 58 deletions(-)

diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 6268636..42d8cb9 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -414,6 +414,41 @@ describe('official e2b SDK against the daemon', () => {
     }
   });
 
+  it("user:'root' changes who commands and PTYs run as; unknown names are refused", async () => {
+    const sbx = await Sandbox.create(connection());
+    try {
+      expect((await sbx.commands.run('whoami')).stdout).toBe('user\n');
+      expect((await sbx.commands.run('id -u')).stdout).toBe('1000\n');
+      expect((await sbx.commands.run('whoami', { user: 'root' })).stdout).toBe(
+        'root\n',
+      );
+      expect((await sbx.commands.run('id -u', { user: 'root' })).stdout).toBe(
+        '0\n',
+      );
+
+      await expect(
+        sbx.commands.run('whoami', { user: 'nobody' }),
+      ).rejects.toThrow(/invalid username: 'nobody'/);
+
+      // A root terminal: `id` because a root prompt already says "root",
+      // while uid=0 can only come from the shell itself.
+      const seen: string[] = [];
+      const term = await sbx.pty.create({
+        cols: 80,
+        rows: 24,
+        user: 'root',
+        onData: (data) => {
+          seen.push(Buffer.from(data).toString('utf8'));
+        },
+      });
+      await sbx.pty.sendInput(term.pid, new TextEncoder().encode('id\r'));
+      await until(() => seen.join('').includes('uid=0'));
+      await sbx.pty.kill(term.pid);
+    } finally {
+      await sbx.kill();
+    }
+  });
+
   it('pty.create: a live terminal — typed input runs, resize lands, kill ends it', async () => {
     const sbx = await Sandbox.create(connection());
     try {
@@ -665,6 +700,27 @@ describe.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
       }
     });
 
+    it("root has real powers: write and read under /root, where 'user' cannot", async () => {
+      const sbx = await Sandbox.create(connection());
+      try {
+        await sbx.files.write('/root/probe.txt', 'root wrote this\n', {
+          user: 'root',
+        });
+        expect(await sbx.files.read('/root/probe.txt', { user: 'root' })).toBe(
+          'root wrote this\n',
+        );
+        // /root is 0700: the default user cannot even stat inside it.
+        await expect(sbx.files.read('/root/probe.txt')).rejects.toThrow();
+        // Ownership followed the writer.
+        const owner = await sbx.commands.run('stat -c %U /root/probe.txt', {
+          user: 'root',
+        });
+        expect(owner.stdout).toBe('root\n');
+      } finally {
+        await sbx.kill();
+      }
+    });
+
     it('metrics watch a real disk fill: dd 5 MiB and diskUsed grows', async () => {
       const sbx = await Sandbox.create(connection());
       try {
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 7a9fa16..02265c8 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -705,6 +705,73 @@ describe('E2B envd surface', () => {
     ).toBe('over\n');
   });
 
+  it('user rides Basic auth: root runs as root, an unknown name is refused in both dialects', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const basic = (name: string) => ({
+      authorization: `Basic ${Buffer.from(`${name}:`).toString('base64')}`,
+    });
+
+    // Streaming face: Start with Basic root — whoami answers root.
+    const asRoot = await startCommand(t, sandboxID, 'whoami', {
+      headers: basic('root'),
+    });
+    const events = parseEnvelopes(asRoot.rawPayload)
+      .filter((f) => f.flags === 0)
+      .map((f) => f.json.event as Record<string, unknown>);
+    const data = events.find((e) => 'data' in e) as {
+      data: { stdout: string };
+    };
+    expect(Buffer.from(data.data.stdout, 'base64').toString('utf8')).toBe(
+      'root\n',
+    );
+
+    // Streaming face, unknown name: refused inside the stream, before start.
+    const refused = await startCommand(t, sandboxID, 'whoami', {
+      headers: basic('nobody'),
+    });
+    const frames = parseEnvelopes(refused.rawPayload);
+    expect(frames).toHaveLength(1);
+    expect(frames[0]).toEqual({
+      flags: 2,
+      json: {
+        error: {
+          code: 'unauthenticated',
+          message: "invalid username: 'nobody'",
+        },
+      },
+    });
+
+    // Unary face: same identity, same refusal, unary dialect.
+    const stat = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/filesystem.Filesystem/Stat',
+      headers: { ...envdHeaders(sandboxID), ...basic('root') },
+      payload: { path: '/home/user' },
+    });
+    expect(stat.statusCode).toBe(200);
+    const statRefused = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/filesystem.Filesystem/Stat',
+      headers: { ...envdHeaders(sandboxID), ...basic('nobody') },
+      payload: { path: '/home/user' },
+    });
+    expect(statRefused.statusCode).toBe(401);
+    expect(statRefused.json()).toEqual({
+      code: 'unauthenticated',
+      message: "invalid username: 'nobody'",
+    });
+
+    // Files face: username in the query, vetted the same way.
+    const filesRefused = await t.app.inject({
+      method: 'GET',
+      url: '/e2b/envd/files?path=x&username=nobody',
+      headers: envdHeaders(sandboxID),
+    });
+    expect(filesRefused.statusCode).toBe(401);
+    expect(filesRefused.json().message).toBe("invalid username: 'nobody'");
+  });
+
   it('answers a blown connect-timeout-ms deadline with deadline_exceeded, not an end event', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t);
@@ -1451,7 +1518,7 @@ describe('signed file URLs at the daemon root', () => {
 
   it("vets the signed username: only the image's users exist", async () => {
     const t = testApp();
-    const { envdAccessToken } = await createSandbox(t);
+    const { sandboxID, envdAccessToken } = await createSandbox(t);
     const sig = sdkSignature({
       path: 'x',
       operation: 'read',
@@ -1464,5 +1531,21 @@ describe('signed file URLs at the daemon root', () => {
     });
     expect(res.statusCode).toBe(401);
     expect(res.json().message).toBe("invalid username: 'nobody'");
+
+    // root exists: a root-signed download passes the vet (the fake has no
+    // permission model — root's real powers are the docker e2e's business).
+    await putFile(t, sandboxID, 'rooted.txt', 'root readable\n');
+    const rootSig = sdkSignature({
+      path: 'rooted.txt',
+      operation: 'read',
+      user: 'root',
+      envdAccessToken,
+    });
+    const asRoot = await t.app.inject({
+      method: 'GET',
+      url: `/files?path=rooted.txt&username=root&signature=${encodeURIComponent(rootSig)}`,
+    });
+    expect(asRoot.statusCode).toBe(200);
+    expect(asRoot.body).toBe('root readable\n');
   });
 });
diff --git a/packages/server/src/e2b/envd/files.ts b/packages/server/src/e2b/envd/files.ts
index 475e5b3..3f5c65e 100644
--- a/packages/server/src/e2b/envd/files.ts
+++ b/packages/server/src/e2b/envd/files.ts
@@ -9,7 +9,12 @@ import {
   type SandboxEntry,
 } from '../../executor/executor';
 import { E2bError } from '../protocol';
-import { type EnvdContext, sandboxIdOf, UNLIMITED_BODY_BYTES } from './shared';
+import {
+  type EnvdContext,
+  sandboxIdOf,
+  UNLIMITED_BODY_BYTES,
+  vetUsername,
+} from './shared';
 
 /**
  * The plain-HTTP file faces: GET /files streams out, POST /files streams in.
@@ -38,10 +43,13 @@ export async function serveFileDownload(
   reply: FastifyReply,
 ): Promise<void> {
   const { db, executor } = ctx;
-  const query = request.query as { path?: string };
+  const query = request.query as { path?: string; username?: string };
   if (!query.path) {
     throw new E2bError(400, 'invalid_argument', 'missing path query');
   }
+  // Identity rides the username query on this face (the SDK's user option);
+  // vetted before anything wakes.
+  const user = vetUsername(query.username);
   const row = await ctx.wakeForUse(sandboxId);
   const stopHeartbeat = startExecHeartbeat(
     db,
@@ -51,7 +59,7 @@ export async function serveFileDownload(
   try {
     let entry: SandboxEntry;
     try {
-      entry = await executor.statEntry(row.sandboxId, query.path);
+      entry = await executor.statEntry(row.sandboxId, query.path, user);
       if (entry.type !== 'file') {
         throw new NotAFileError(`not a regular file: ${entry.path}`);
       }
@@ -71,13 +79,20 @@ export async function serveFileDownload(
       'content-type': 'application/octet-stream',
       'content-length': String(entry.sizeBytes),
     });
-    await executor.readFileStream(row.sandboxId, query.path, (chunk) => {
-      if (!reply.raw.write(chunk)) {
-        // Backpressure: the promise pauses the pipe all the way into the
-        // container until the client drains.
-        return new Promise<void>((resolve) => reply.raw.once('drain', resolve));
-      }
-    });
+    await executor.readFileStream(
+      row.sandboxId,
+      query.path,
+      (chunk) => {
+        if (!reply.raw.write(chunk)) {
+          // Backpressure: the promise pauses the pipe all the way into the
+          // container until the client drains.
+          return new Promise<void>((resolve) =>
+            reply.raw.once('drain', resolve),
+          );
+        }
+      },
+      user,
+    );
     reply.raw.end();
   } catch (error) {
     if (reply.raw.headersSent) {
@@ -105,7 +120,8 @@ export async function serveFileUpload(
   reply: FastifyReply,
 ): Promise<unknown> {
   const { db, executor } = ctx;
-  const query = request.query as { path?: string };
+  const query = request.query as { path?: string; username?: string };
+  const user = vetUsername(query.username);
   const row = await ctx.wakeForUse(sandboxId);
   const stopHeartbeat = startExecHeartbeat(
     db,
@@ -116,7 +132,7 @@ export async function serveFileUpload(
     const written: Array<{ name: string; type: 'file'; path: string }> = [];
     const writeOne = async (path: string, content: NodeJS.ReadableStream) => {
       try {
-        await executor.writeFileStream(row.sandboxId, path, content);
+        await executor.writeFileStream(row.sandboxId, path, content, user);
       } catch (error) {
         if (error instanceof NotAFileError) {
           throw new E2bError(400, 'invalid_argument', error.message);
diff --git a/packages/server/src/e2b/envd/filesystem.ts b/packages/server/src/e2b/envd/filesystem.ts
index 3057882..c33e366 100644
--- a/packages/server/src/e2b/envd/filesystem.ts
+++ b/packages/server/src/e2b/envd/filesystem.ts
@@ -2,7 +2,12 @@ import { resolveSandboxPath } from '@dormice/shared';
 import type { FastifyInstance } from 'fastify';
 import type { SandboxEntry } from '../../executor/executor';
 import { connectError } from '../protocol';
-import { type EnvdContext, sandboxIdOf } from './shared';
+import {
+  type EnvdContext,
+  sandboxIdOf,
+  usernameOf,
+  vetUsername,
+} from './shared';
 
 /** SandboxEntry -> proto3-JSON EntryInfo (int64 size travels as a string). */
 export function entryInfoJson(entry: SandboxEntry) {
@@ -49,8 +54,9 @@ export function registerFilesystemRoutes(
   app.post('/filesystem.Filesystem/Stat', async (request) => {
     const body = request.body as { path?: string };
     if (!body.path) throw connectError('invalid_argument', 'missing path');
+    const user = vetUsername(usernameOf(request));
     const entry = await ctx.inSlot(sandboxIdOf(request), (row) =>
-      executor.statEntry(row.sandboxId, body.path as string),
+      executor.statEntry(row.sandboxId, body.path as string, user),
     );
     return { entry: entryInfoJson(entry) };
   });
@@ -62,8 +68,9 @@ export function registerFilesystemRoutes(
     if (depth < 1) {
       throw connectError('invalid_argument', 'depth should be at least one');
     }
+    const user = vetUsername(usernameOf(request));
     const entries = await ctx.inSlot(sandboxIdOf(request), (row) =>
-      executor.listDir(row.sandboxId, body.path as string, depth),
+      executor.listDir(row.sandboxId, body.path as string, depth, user),
     );
     return { entries: entries.map(entryInfoJson) };
   });
@@ -71,10 +78,12 @@ export function registerFilesystemRoutes(
   app.post('/filesystem.Filesystem/MakeDir', async (request) => {
     const body = request.body as { path?: string };
     if (!body.path) throw connectError('invalid_argument', 'missing path');
+    const user = vetUsername(usernameOf(request));
     const entry = await ctx.inSlot(sandboxIdOf(request), async (row) => {
       const created = await executor.makeDir(
         row.sandboxId,
         body.path as string,
+        user,
       );
       if (!created) {
         // The SDK reads already_exists as makeDir() === false.
@@ -83,7 +92,7 @@ export function registerFilesystemRoutes(
           `already exists: ${resolveSandboxPath(body.path as string)}`,
         );
       }
-      return executor.statEntry(row.sandboxId, body.path as string);
+      return executor.statEntry(row.sandboxId, body.path as string, user);
     });
     return { entry: entryInfoJson(entry) };
   });
@@ -93,11 +102,13 @@ export function registerFilesystemRoutes(
     if (!body.source || !body.destination) {
       throw connectError('invalid_argument', 'missing source or destination');
     }
+    const user = vetUsername(usernameOf(request));
     const entry = await ctx.inSlot(sandboxIdOf(request), (row) =>
       executor.move(
         row.sandboxId,
         body.source as string,
         body.destination as string,
+        user,
       ),
     );
     return { entry: entryInfoJson(entry) };
@@ -106,8 +117,9 @@ export function registerFilesystemRoutes(
   app.post('/filesystem.Filesystem/Remove', async (request) => {
     const body = request.body as { path?: string };
     if (!body.path) throw connectError('invalid_argument', 'missing path');
+    const user = vetUsername(usernameOf(request));
     await ctx.inSlot(sandboxIdOf(request), (row) =>
-      executor.remove(row.sandboxId, body.path as string),
+      executor.remove(row.sandboxId, body.path as string, user),
     );
     return {};
   });
diff --git a/packages/server/src/e2b/envd/process.ts b/packages/server/src/e2b/envd/process.ts
index dba8176..fa39ace 100644
--- a/packages/server/src/e2b/envd/process.ts
+++ b/packages/server/src/e2b/envd/process.ts
@@ -18,6 +18,8 @@ import {
   rawWriter,
   sandboxIdOf,
   streamError,
+  usernameOf,
+  vetUsername,
   wireDeadlineMs,
 } from './shared';
 
@@ -237,6 +239,15 @@ export function registerProcessRoutes(
           : 'only shell commands are supported: expected /bin/bash [-l] -c <command>',
       );
     }
+    // Identity rides the Basic auth header (SDK: user option); vetted here,
+    // in the streaming dialect, before anything wakes.
+    let user: string | undefined;
+    try {
+      user = vetUsername(usernameOf(request));
+    } catch (error) {
+      const e = error as { code: string | number; message: string };
+      return streamError(reply, String(e.code), e.message);
+    }
     const row = await ctx.wakeForStream(request, reply);
     if (!row) return;
 
@@ -260,6 +271,7 @@ export function registerProcessRoutes(
           timeoutSeconds: MAX_EXEC_SECONDS,
           stdin: message.stdin === true,
           cwd: proc.cwd,
+          user,
           // Sandbox-level envs underneath, per-command envs on top.
           env: { ...sandboxEnvs, ...(proc.envs ?? {}) },
         },
diff --git a/packages/server/src/e2b/envd/shared.ts b/packages/server/src/e2b/envd/shared.ts
index c3f3c21..496e152 100644
--- a/packages/server/src/e2b/envd/shared.ts
+++ b/packages/server/src/e2b/envd/shared.ts
@@ -1,4 +1,4 @@
-import type { Buffer } from 'node:buffer';
+import { Buffer } from 'node:buffer';
 import type { FastifyReply, FastifyRequest } from 'fastify';
 import { findBySandboxId, touch } from '../../db/ledger';
 import type { SandboxRow } from '../../db/schema';
@@ -51,6 +51,33 @@ export function sandboxIdOf(request: FastifyRequest): string {
   return id;
 }
 
+/**
+ * The SDK's `user` option travels as `Authorization: Basic base64("<u>:")`
+ * — username, empty password (real envd's authenticate.go reads BasicAuth
+ * the same way). Absent (the SDK sends nothing against envd >= 0.4.0, which
+ * we report) means the default user.
+ */
+export function usernameOf(request: FastifyRequest): string | undefined {
+  const header = request.headers.authorization;
+  const value = Array.isArray(header) ? header[0] : header;
+  if (!value?.startsWith('Basic ')) return undefined;
+  const decoded = Buffer.from(value.slice(6), 'base64').toString('utf8');
+  const colon = decoded.indexOf(':');
+  const username = colon === -1 ? decoded : decoded.slice(0, colon);
+  return username || undefined;
+}
+
+/**
+ * The single arbiter of which usernames exist: the base image has exactly
+ * `user` (uid 1000) and `root` — a deliberate narrowing of real envd's
+ * "any system user" (documented in the protocol rules). The message is real
+ * envd's own wording for an unknown user.
+ */
+export function vetUsername(name: string | undefined): string | undefined {
+  if (name === undefined || name === 'user' || name === 'root') return name;
+  throw connectError('unauthenticated', `invalid username: '${name}'`);
+}
+
 /** The SDK's connect-timeout-ms header, absent meaning "effectively never". */
 export function wireDeadlineMs(request: FastifyRequest): number {
   const headerMs = Number(request.headers['connect-timeout-ms']);
diff --git a/packages/server/src/e2b/signed-files.ts b/packages/server/src/e2b/signed-files.ts
index aeda2e9..b4f8929 100644
--- a/packages/server/src/e2b/signed-files.ts
+++ b/packages/server/src/e2b/signed-files.ts
@@ -109,16 +109,9 @@ export const signedFileRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         'signature is already expired',
       );
     }
-    // The signed username also names the execution identity; only the
-    // image's own users exist. (The signature already covers it — a
-    // tampered username never gets this far.)
-    if (query.username !== undefined && query.username !== 'user') {
-      throw new E2bError(
-        401,
-        'unauthenticated',
-        `invalid username: '${query.username}'`,
-      );
-    }
+    // The signed username also names the execution identity; the file
+    // handler cores vet it against the image's users (a tampered username
+    // never gets that far — the signature covers it).
     return row;
   }
 
diff --git a/packages/server/src/executor/contract/exec-stream.ts b/packages/server/src/executor/contract/exec-stream.ts
index 358ce8f..74d8f1a 100644
--- a/packages/server/src/executor/contract/exec-stream.ts
+++ b/packages/server/src/executor/contract/exec-stream.ts
@@ -275,6 +275,55 @@ export function execStreamTests(ctx: ContractContext) {
       timeoutMs,
     );
 
+    it(
+      "execStream with user:'root' streams as root; a root process can be signaled",
+      async () => {
+        const id = await ctx.fresh();
+        const seen: string[] = [];
+        const handle = await ctx.executor.execStream(id, {
+          command: 'whoami; sleep 30',
+          timeoutSeconds: 60,
+          user: 'root',
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        await ctx.until(() => seen.join('').includes('root\n'));
+        // The signal path must run as the process's own user: uid 1000
+        // cannot deliver a SIGKILL into a root process group.
+        await handle.signal('SIGKILL');
+        const { exitCode } = await handle.wait();
+        expect(exitCode).toBe(137);
+      },
+      timeoutMs,
+    );
+
+    it(
+      "a PTY with user:'root' is a root shell",
+      async () => {
+        const id = await ctx.fresh();
+        const seen: string[] = [];
+        const handle = await ctx.executor.execStream(id, {
+          timeoutSeconds: 60,
+          pty: { cols: 80, rows: 24 },
+          user: 'root',
+          env: { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' },
+          onStdout: (c) => {
+            seen.push(c.toString('utf8'));
+          },
+          onStderr: () => {},
+        });
+        // `id`, not `whoami`: a root prompt already contains "root", while
+        // "uid=0" can only come from the command actually running as root.
+        await handle.sendStdin(Buffer.from('id\r'));
+        await ctx.until(() => seen.join('').includes('uid=0'));
+        await handle.sendStdin(Buffer.from('exit\r'));
+        await handle.wait();
+      },
+      timeoutMs,
+    );
+
     it(
       'resizePty changes what stty size reports',
       async () => {
diff --git a/packages/server/src/executor/contract/exec.ts b/packages/server/src/executor/contract/exec.ts
index 75d2d07..3e8db42 100644
--- a/packages/server/src/executor/contract/exec.ts
+++ b/packages/server/src/executor/contract/exec.ts
@@ -150,5 +150,43 @@ export function execTests(ctx: ContractContext) {
       },
       timeoutMs,
     );
+
+    it(
+      'exec runs as user (uid 1000) unless told otherwise',
+      async () => {
+        const id = await ctx.fresh();
+        const who = await ctx.executor.exec(id, {
+          command: 'whoami',
+          timeoutSeconds: 30,
+        });
+        expect(who.stdout).toBe('user\n');
+        const uid = await ctx.executor.exec(id, {
+          command: 'id -u',
+          timeoutSeconds: 30,
+        });
+        expect(uid.stdout).toBe('1000\n');
+      },
+      timeoutMs,
+    );
+
+    it(
+      "exec with user:'root' runs as uid 0",
+      async () => {
+        const id = await ctx.fresh();
+        const who = await ctx.executor.exec(id, {
+          command: 'whoami',
+          timeoutSeconds: 30,
+          user: 'root',
+        });
+        expect(who.stdout).toBe('root\n');
+        const uid = await ctx.executor.exec(id, {
+          command: 'id -u',
+          timeoutSeconds: 30,
+          user: 'root',
+        });
+        expect(uid.stdout).toBe('0\n');
+      },
+      timeoutMs,
+    );
   });
 }
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 4ccdb38..178deea 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -375,6 +375,7 @@ export class DockerExecutor implements Executor {
       outputCap: EXEC_OUTPUT_LIMIT_BYTES,
       workingDir: opts.cwd,
       env: opts.env,
+      user: opts.user,
     });
     return {
       exitCode: run.exitCode,
@@ -423,6 +424,7 @@ export class DockerExecutor implements Executor {
       stdin: opts.stdin ? 'open' : undefined,
       workingDir: opts.cwd,
       env: opts.env,
+      user: opts.user,
     });
     let finished = false;
     const done = started.wait().then((exitCode) => {
@@ -461,7 +463,7 @@ export class DockerExecutor implements Executor {
         if (finished) {
           throw new Error('process already exited');
         }
-        await this.signalProcess(container, sandboxId, pidfile, sig);
+        await this.signalProcess(container, sandboxId, pidfile, sig, opts.user);
       },
       resizePty: async () => {
         throw new Error('process has no PTY');
@@ -469,16 +471,22 @@ export class DockerExecutor implements Executor {
     };
   }
 
-  /** Delivers a signal to an execStream'd process group via its pidfile. */
+  /**
+   * Delivers a signal to an execStream'd process group via its pidfile —
+   * as the same user the process runs as: uid 1000 cannot signal a root
+   * process group, and root needs no help signaling anyone.
+   */
   private async signalProcess(
     container: Docker.Container,
     sandboxId: string,
     pidfile: string,
     sig: 'SIGTERM' | 'SIGKILL',
+    user?: string,
   ): Promise<void> {
     const run = await this.runInContainer(container, sandboxId, {
       cmd: ['bash', '-c', SIGNAL_SCRIPT, 'bash', pidfile, sig],
       outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+      user,
     });
     if (run.exitCode !== 0) {
       throw new Error(
@@ -509,7 +517,8 @@ export class DockerExecutor implements Executor {
       Env: opts.env
         ? Object.entries(opts.env).map(([key, value]) => `${key}=${value}`)
         : undefined,
-      User: 'user',
+      // The PTY twin of startInContainer's identity point.
+      User: opts.user ?? 'user',
     });
     const stream = await exec.start({ hijack: true, stdin: true, Tty: true });
     stream.pipe(new CallbackSink(opts.onStdout));
@@ -547,7 +556,7 @@ export class DockerExecutor implements Executor {
         if (finishedFlag) {
           throw new Error('process already exited');
         }
-        await this.signalProcess(container, sandboxId, pidfile, sig);
+        await this.signalProcess(container, sandboxId, pidfile, sig, opts.user);
       },
       resizePty: async (next) => {
         await exec.resize({ h: next.rows, w: next.cols });
@@ -583,7 +592,11 @@ export class DockerExecutor implements Executor {
     return info.ExitCode;
   }
 
-  async writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void> {
+  async writeFiles(
+    sandboxId: string,
+    files: FileToWrite[],
+    user?: string,
+  ): Promise<void> {
     const containerId = await this.expectState(sandboxId, 'running');
     const container = this.docker.getContainer(containerId);
     // In array order, failing fast — the batch saves round-trips, it is not
@@ -603,6 +616,7 @@ export class DockerExecutor implements Executor {
         ],
         outputCap: EXEC_OUTPUT_LIMIT_BYTES,
         stdin: file.content,
+        user,
       });
       if (run.exitCode === NOT_A_FILE_EXIT) {
         throw new NotAFileError(`not a regular file: ${path}`);
@@ -615,7 +629,11 @@ export class DockerExecutor implements Executor {
     }
   }
 
-  async readFile(sandboxId: string, path: string): Promise<Buffer> {
+  async readFile(
+    sandboxId: string,
+    path: string,
+    user?: string,
+  ): Promise<Buffer> {
     const resolved = resolveSandboxPath(path);
     const containerId = await this.expectState(sandboxId, 'running');
     const container = this.docker.getContainer(containerId);
@@ -632,6 +650,7 @@ export class DockerExecutor implements Executor {
         String(FILE_SIZE_LIMIT_BYTES),
       ],
       outputCap: FILE_SIZE_LIMIT_BYTES,
+      user,
     });
     if (run.exitCode === NO_SUCH_FILE_EXIT) {
       throw new FileNotFoundError(`no such file: ${resolved}`);
@@ -664,6 +683,7 @@ export class DockerExecutor implements Executor {
     sandboxId: string,
     path: string,
     onChunk: (chunk: Buffer) => void | Promise<void>,
+    user?: string,
   ): Promise<void> {
     const resolved = resolveSandboxPath(path);
     const containerId = await this.expectState(sandboxId, 'running');
@@ -682,6 +702,7 @@ export class DockerExecutor implements Executor {
       ],
       stdout: new CallbackSink(onChunk),
       stderr,
+      user,
     });
     const exitCode = await started.wait();
     if (exitCode === NO_SUCH_FILE_EXIT) {
@@ -701,6 +722,7 @@ export class DockerExecutor implements Executor {
     sandboxId: string,
     path: string,
     content: NodeJS.ReadableStream,
+    user?: string,
   ): Promise<void> {
     const resolved = resolveSandboxPath(path);
     const containerId = await this.expectState(sandboxId, 'running');
@@ -718,6 +740,7 @@ export class DockerExecutor implements Executor {
       ],
       outputCap: EXEC_OUTPUT_LIMIT_BYTES,
       stdin: content,
+      user,
     });
     if (run.exitCode === NOT_A_FILE_EXIT) {
       throw new NotAFileError(`not a regular file: ${resolved}`);
@@ -737,6 +760,7 @@ export class DockerExecutor implements Executor {
     sandboxId: string,
     path: string,
     depth: number,
+    user?: string,
   ): Promise<SandboxEntry[]> {
     const resolved = resolveSandboxPath(path);
     const containerId = await this.expectState(sandboxId, 'running');
@@ -754,6 +778,7 @@ export class DockerExecutor implements Executor {
         String(depth),
       ],
       outputCap: LIST_OUTPUT_LIMIT_BYTES,
+      user,
     });
     if (run.exitCode === NO_SUCH_FILE_EXIT) {
       throw new FileNotFoundError(`no such file: ${resolved}`);
@@ -781,7 +806,11 @@ export class DockerExecutor implements Executor {
       .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
   }
 
-  async statEntry(sandboxId: string, path: string): Promise<SandboxEntry> {
+  async statEntry(
+    sandboxId: string,
+    path: string,
+    user?: string,
+  ): Promise<SandboxEntry> {
     const resolved = resolveSandboxPath(path);
     const containerId = await this.expectState(sandboxId, 'running');
     const container = this.docker.getContainer(containerId);
@@ -797,6 +826,7 @@ export class DockerExecutor implements Executor {
         resolved,
       ],
       outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+      user,
     });
     if (run.exitCode === NO_SUCH_FILE_EXIT) {
       throw new FileNotFoundError(`no such file: ${resolved}`);
@@ -809,7 +839,11 @@ export class DockerExecutor implements Executor {
     return entryFromStatLine(resolved, run.stdout.text());
   }
 
-  async makeDir(sandboxId: string, path: string): Promise<boolean> {
+  async makeDir(
+    sandboxId: string,
+    path: string,
+    user?: string,
+  ): Promise<boolean> {
     const resolved = resolveSandboxPath(path);
     const containerId = await this.expectState(sandboxId, 'running');
     const container = this.docker.getContainer(containerId);
@@ -825,6 +859,7 @@ export class DockerExecutor implements Executor {
         resolved,
       ],
       outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+      user,
     });
     if (run.exitCode === ALREADY_EXISTS_EXIT) {
       return false;
@@ -841,6 +876,7 @@ export class DockerExecutor implements Executor {
     sandboxId: string,
     from: string,
     to: string,
+    user?: string,
   ): Promise<SandboxEntry> {
     const source = resolveSandboxPath(from);
     const destination = resolveSandboxPath(to);
@@ -859,6 +895,7 @@ export class DockerExecutor implements Executor {
         destination,
       ],
       outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+      user,
     });
     if (run.exitCode === NO_SUCH_FILE_EXIT) {
       throw new FileNotFoundError(`no such file: ${source}`);
@@ -868,10 +905,10 @@ export class DockerExecutor implements Executor {
         `moving ${source} to ${destination} in ${sandboxId} failed (exit ${run.exitCode}): ${run.stderr.text().trim()}`,
       );
     }
-    return this.statEntry(sandboxId, destination);
+    return this.statEntry(sandboxId, destination, user);
   }
 
-  async remove(sandboxId: string, path: string): Promise<void> {
+  async remove(sandboxId: string, path: string, user?: string): Promise<void> {
     const resolved = resolveSandboxPath(path);
     const containerId = await this.expectState(sandboxId, 'running');
     const container = this.docker.getContainer(containerId);
@@ -887,6 +924,7 @@ export class DockerExecutor implements Executor {
         resolved,
       ],
       outputCap: EXEC_OUTPUT_LIMIT_BYTES,
+      user,
     });
     if (run.exitCode === NO_SUCH_FILE_EXIT) {
       throw new FileNotFoundError(`no such file: ${resolved}`);
@@ -1010,6 +1048,7 @@ export class DockerExecutor implements Executor {
       stdin?: Buffer | NodeJS.ReadableStream;
       workingDir?: string;
       env?: Record<string, string>;
+      user?: string;
     },
   ): Promise<{ exitCode: number; stdout: CappedBuffer; stderr: CappedBuffer }> {
     const stdout = new CappedBuffer(spec.outputCap);
@@ -1021,6 +1060,7 @@ export class DockerExecutor implements Executor {
       stdin: spec.stdin,
       workingDir: spec.workingDir,
       env: spec.env,
+      user: spec.user,
     });
     return { exitCode: await started.wait(), stdout, stderr };
   }
@@ -1051,6 +1091,7 @@ export class DockerExecutor implements Executor {
       stdin?: Buffer | NodeJS.ReadableStream | 'open';
       workingDir?: string;
       env?: Record<string, string>;
+      user?: string;
     },
   ): Promise<{ wait: () => Promise<number>; stdinStream?: Duplex }> {
     const exec = await container.exec({
@@ -1062,7 +1103,10 @@ export class DockerExecutor implements Executor {
       Env: spec.env
         ? Object.entries(spec.env).map(([key, value]) => `${key}=${value}`)
         : undefined,
-      User: 'user',
+      // One of the two physical points where identity is decided (the PTY
+      // exec is the other). Root here is root inside gVisor's guest kernel,
+      // nothing more.
+      User: spec.user ?? 'user',
     });
     const stream = await exec.start(
       spec.stdin !== undefined ? { hijack: true, stdin: true } : {},
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index a63dc73..da8e038 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -17,6 +17,13 @@ export interface ExecOptions {
   /** Working directory inside the sandbox; defaults to the image's /home/user. */
   cwd?: string;
   env?: Record<string, string>;
+  /**
+   * Unix user the command runs as; defaults to 'user' (uid 1000). The
+   * executor passes the name through to the runtime verbatim — which names
+   * are allowed is the wire layer's decision, not modeled here. In-sandbox
+   * root is contained by gVisor exactly like any other sandbox code.
+   */
+  user?: string;
 }
 
 export interface ExecResult {
@@ -69,6 +76,8 @@ export interface ExecStreamOptions {
    * sendStdin, the size through resizePty.
    */
   pty?: PtySize;
+  /** Same as ExecOptions.user; applies to PTY sessions too. */
+  user?: string;
   /**
    * Called with each output chunk as it arrives. No cap: nothing accumulates
    * server-side. A returned promise MAY be awaited before the next chunk
@@ -306,15 +315,23 @@ export interface Executor {
    * never the host's; this is why file I/O goes through the container and
    * not through the host-side mount. No size check here: the protocol
    * schema is the single write-cap adjudicator.
+   *
+   * Every file verb takes a trailing optional `user` — the identity the
+   * in-container operation runs as (ExecOptions.user's rules): ownership of
+   * written files and permission outcomes follow it. Absent means 'user'.
    */
-  writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void>;
+  writeFiles(
+    sandboxId: string,
+    files: FileToWrite[],
+    user?: string,
+  ): Promise<void>;
   /**
    * Returns one file's bytes. Requires state `running`. Throws the typed
    * file errors above; a file over FILE_SIZE_LIMIT_BYTES is refused, never
    * truncated — a truncated file is a corrupt file. The read cap lives here
    * and not in the schema because only the executor can observe the size.
    */
-  readFile(sandboxId: string, path: string): Promise<Buffer>;
+  readFile(sandboxId: string, path: string, user?: string): Promise<Buffer>;
   /**
    * Streams one file's bytes through the callback, uncapped — nothing
    * accumulates server-side, so the disk quota is the only ceiling (the E2B
@@ -327,6 +344,7 @@ export interface Executor {
     sandboxId: string,
     path: string,
     onChunk: (chunk: Buffer) => void | Promise<void>,
+    user?: string,
   ): Promise<void>;
   /**
    * Streams content into one file, uncapped, parents created, overwriting —
@@ -337,6 +355,7 @@ export interface Executor {
     sandboxId: string,
     path: string,
     content: NodeJS.ReadableStream,
+    user?: string,
   ): Promise<void>;
   /**
    * Entries under a directory, depth ≥ 1 levels down, sorted by path.
@@ -347,28 +366,38 @@ export interface Executor {
     sandboxId: string,
     path: string,
     depth: number,
+    user?: string,
   ): Promise<SandboxEntry[]>;
   /** One path's entry. FileNotFoundError when nothing is there. */
-  statEntry(sandboxId: string, path: string): Promise<SandboxEntry>;
+  statEntry(
+    sandboxId: string,
+    path: string,
+    user?: string,
+  ): Promise<SandboxEntry>;
   /**
    * mkdir -p. True when created; false when the path already exists —
    * whatever it is: claiming "created" over an existing file would be a lie,
    * and the caller's next stat tells the truth either way.
    */
-  makeDir(sandboxId: string, path: string): Promise<boolean>;
+  makeDir(sandboxId: string, path: string, user?: string): Promise<boolean>;
   /**
    * rename(2) semantics (`mv -T`): an existing destination file is
    * replaced, a destination directory is not merged into. The source must
    * exist (FileNotFoundError); parents of the destination are not created.
    * Returns the destination's entry.
    */
-  move(sandboxId: string, from: string, to: string): Promise<SandboxEntry>;
+  move(
+    sandboxId: string,
+    from: string,
+    to: string,
+    user?: string,
+  ): Promise<SandboxEntry>;
   /**
    * rm -rf: file or directory tree. FileNotFoundError when nothing is there
    * — removing nothing is a caller's confusion worth reporting, not a goal
    * state (unlike removeDisk, whose caller is reconciliation).
    */
-  remove(sandboxId: string, path: string): Promise<void>;
+  remove(sandboxId: string, path: string, user?: string): Promise<void>;
   /**
    * Starts watching a directory for filesystem events. The path must exist
    * (FileNotFoundError) and be a directory (NotADirectoryError) — checked
@@ -378,6 +407,8 @@ export interface Executor {
    * events cannot be missed while frozen — the disk only changes from
    * inside, and anything that reaches inside wakes the sandbox first.
    * Lifetime is bounded by the sandbox's own 24h exec backstop.
+   * Deliberately no user option (a v1 narrowing): the watcher runs as
+   * 'user', and watching a root-only subtree refuses honestly.
    */
   watchDir(sandboxId: string, opts: WatchDirOptions): Promise<WatchDirHandle>;
 }
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index 2d0157e..c697b63 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -390,6 +390,7 @@ export class FakeExecutor implements Executor {
       timeoutSeconds: opts.timeoutSeconds,
       cwd: opts.cwd,
       env: opts.env,
+      user: opts.user,
       onStdout: (chunk) => stdout.push(chunk),
       onStderr: (chunk) => stderr.push(chunk),
     });
@@ -450,7 +451,16 @@ export class FakeExecutor implements Executor {
       try {
         const run = opts.pty
           ? ptySession(opts, emit, io)
-          : interpret({ ...opts, command: command as string }, emit, io);
+          : interpret(
+              {
+                command: command as string,
+                cwd: opts.cwd,
+                env: opts.env,
+                user: opts.user,
+              },
+              emit,
+              io,
+            );
         return {
           exitCode: await Promise.race([run, deadline, killed]),
         };
@@ -571,6 +581,12 @@ export class FakeExecutor implements Executor {
     };
   }
 
+  // The file verbs deliberately omit the interface's trailing `user`
+  // parameter (fewer params is structurally sound TS): the fake models no
+  // permission system, so identity could change nothing here. It reaches
+  // the pocket interpreter's identity verbs only; real permission outcomes
+  // (root reading /root, ownership of written files) are the docker
+  // executor's physics, pinned by the docker-only e2e questions.
   async writeFiles(sandboxId: string, files: FileToWrite[]): Promise<void> {
     this.expect(sandboxId, 'running');
     const disk = this.disk(sandboxId);
@@ -842,7 +858,7 @@ interface Emit {
  * escape sequences, so the contract asserts with contains, never equals.
  */
 async function ptySession(
-  opts: { cwd?: string; env?: Record<string, string> },
+  opts: { cwd?: string; env?: Record<string, string>; user?: string },
   emit: Emit,
   io: FakeProcessIO,
 ): Promise<number> {
@@ -867,7 +883,7 @@ async function ptySession(
         continue;
       }
       await interpret(
-        { command: commandLine, cwd: opts.cwd, env: opts.env },
+        { command: commandLine, cwd: opts.cwd, env: opts.env, user: opts.user },
         merged,
         io,
       );
@@ -876,16 +892,22 @@ async function ptySession(
 }
 
 /**
- * A pocket bash: the seven verbs plus `;` sequencing — exactly what the
- * contract exam and the e2e suite need to exercise exec through the same
- * questions the real executor answers, nothing more. Each verb's output is
- * its own live chunk (the contract's streaming questions time the gaps).
- * Not a shell — an unknown verb gets bash's honest 127 and, like bash, the
- * sequence carries on; `exit` ends it. If the real bash's wording ever
- * proves different on the test machine, this string yields: reality wins.
+ * A pocket bash: the identity-aware verbs plus `;` sequencing — exactly
+ * what the contract exam and the e2e suite need to exercise exec through
+ * the same questions the real executor answers, nothing more. Each verb's
+ * output is its own live chunk (the contract's streaming questions time the
+ * gaps). Not a shell — an unknown verb gets bash's honest 127 and, like
+ * bash, the sequence carries on; `exit` ends it. If the real bash's wording
+ * ever proves different on the test machine, this string yields: reality
+ * wins.
  */
 async function interpret(
-  opts: { command: string; cwd?: string; env?: Record<string, string> },
+  opts: {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    user?: string;
+  },
   emit: Emit,
   io: FakeProcessIO,
 ): Promise<number> {
@@ -902,7 +924,7 @@ async function interpret(
 
 async function interpretVerb(
   command: string,
-  opts: { cwd?: string; env?: Record<string, string> },
+  opts: { cwd?: string; env?: Record<string, string>; user?: string },
   emit: Emit,
   io: FakeProcessIO,
 ): Promise<number> {
@@ -933,6 +955,25 @@ async function interpretVerb(
     emit.stdout(`${opts.cwd ?? '/home/user'}\n`);
     return 0;
   }
+  // The identity verbs answer from the exec's user option — the fake's
+  // window into who a command runs as (the real image has exactly these
+  // two users; permission outcomes are the real executor's business).
+  if (command === 'whoami') {
+    emit.stdout(`${opts.user ?? 'user'}\n`);
+    return 0;
+  }
+  if (command === 'id -u') {
+    emit.stdout(opts.user === 'root' ? '0\n' : '1000\n');
+    return 0;
+  }
+  if (command === 'id') {
+    emit.stdout(
+      opts.user === 'root'
+        ? 'uid=0(root) gid=0(root) groups=0(root)\n'
+        : 'uid=1000(user) gid=1000(user) groups=1000(user)\n',
+    );
+    return 0;
+  }
   const envKey = command.match(/^printenv (\w+)$/)?.[1];
   if (envKey !== undefined) {
     const value = opts.env?.[envKey];

From da6a76f21aabd537b3687bb6b6d80110bb921dd4 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 18:09:15 +0800
Subject: [PATCH 032/133] Publish plumbing for shared, sdk and cli: metadata,
 changesets, 0.1.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The three public packages move in one fixed version group; server joins
web and e2e as private — the daemon ships through install.sh, and npm
could not deliver its full shape (native better-sqlite3, the console
dist, migrations) anyway.

publishConfig.access=public lives in each package.json instead of a
publish-time flag; workspace:^ ranges are rewritten by pnpm at pack
time. Verified end to end: tarballs unpacked and inspected, then
installed into a clean directory — the SDK imports and dor runs.
---
 .changeset/README.md                          |   8 +
 .changeset/config.json                        |  12 +
 e2e/src/{ui.test.ts => console.test.ts}       |   0
 package.json                                  |   1 +
 packages/cli/CHANGELOG.md                     |  14 +
 packages/cli/LICENSE                          | 201 ++++++
 packages/cli/README.md                        |  41 ++
 packages/cli/package.json                     |  25 +-
 packages/{web => console}/components.json     |   0
 packages/{web => console}/index.html          |   0
 packages/{web => console}/package.json        |   0
 .../src/components/ui/accordion.tsx           |   0
 .../src/components/ui/alert-dialog.tsx        |   0
 .../src/components/ui/alert.tsx               |   0
 .../src/components/ui/aspect-ratio.tsx        |   0
 .../src/components/ui/attachment.tsx          |   0
 .../src/components/ui/avatar.tsx              |   0
 .../src/components/ui/badge.tsx               |   0
 .../src/components/ui/breadcrumb.tsx          |   0
 .../src/components/ui/bubble.tsx              |   0
 .../src/components/ui/button-group.tsx        |   0
 .../src/components/ui/button.tsx              |   0
 .../src/components/ui/calendar.tsx            |   0
 .../src/components/ui/card.tsx                |   0
 .../src/components/ui/carousel.tsx            |   0
 .../src/components/ui/chart.tsx               |   0
 .../src/components/ui/checkbox.tsx            |   0
 .../src/components/ui/collapsible.tsx         |   0
 .../src/components/ui/combobox.tsx            |   0
 .../src/components/ui/command.tsx             |   0
 .../src/components/ui/context-menu.tsx        |   0
 .../src/components/ui/dialog.tsx              |   0
 .../src/components/ui/direction.tsx           |   0
 .../src/components/ui/drawer.tsx              |   0
 .../src/components/ui/dropdown-menu.tsx       |   0
 .../src/components/ui/empty.tsx               |   0
 .../src/components/ui/field.tsx               |   0
 .../src/components/ui/hover-card.tsx          |   0
 .../src/components/ui/input-group.tsx         |   0
 .../src/components/ui/input-otp.tsx           |   0
 .../src/components/ui/input.tsx               |   0
 .../src/components/ui/item.tsx                |   0
 .../src/components/ui/kbd.tsx                 |   0
 .../src/components/ui/label.tsx               |   0
 .../src/components/ui/marker.tsx              |   0
 .../src/components/ui/menubar.tsx             |   0
 .../src/components/ui/message-scroller.tsx    |   0
 .../src/components/ui/message.tsx             |   0
 .../src/components/ui/native-select.tsx       |   0
 .../src/components/ui/navigation-menu.tsx     |   0
 .../src/components/ui/pagination.tsx          |   0
 .../src/components/ui/popover.tsx             |   0
 .../src/components/ui/progress.tsx            |   0
 .../src/components/ui/radio-group.tsx         |   0
 .../src/components/ui/resizable.tsx           |   0
 .../src/components/ui/scroll-area.tsx         |   0
 .../src/components/ui/select.tsx              |   0
 .../src/components/ui/separator.tsx           |   0
 .../src/components/ui/sheet.tsx               |   0
 .../src/components/ui/sidebar.tsx             |   0
 .../src/components/ui/skeleton.tsx            |   0
 .../src/components/ui/slider.tsx              |   0
 .../src/components/ui/sonner.tsx              |   0
 .../src/components/ui/spinner.tsx             |   0
 .../src/components/ui/switch.tsx              |   0
 .../src/components/ui/table.tsx               |   0
 .../src/components/ui/tabs.tsx                |   0
 .../src/components/ui/textarea.tsx            |   0
 .../src/components/ui/toggle-group.tsx        |   0
 .../src/components/ui/toggle.tsx              |   0
 .../src/components/ui/tooltip.tsx             |   0
 .../src/features/auth/pages/LoginPage.tsx     |   0
 .../features/connect/pages/ConnectPage.tsx    |   0
 .../components/CreateSandboxDialog.tsx        |   0
 .../components/RebuildSandboxButton.tsx       |   0
 .../components/ReleaseSandboxButton.tsx       |   0
 .../components/SandboxStateBadge.tsx          |   0
 .../sandboxes/components/SandboxTerminal.tsx  |   0
 .../src/features/sandboxes/envd-pty.ts        |   0
 .../src/features/sandboxes/format.ts          |   0
 .../features/sandboxes/hooks/useSandboxes.ts  |   0
 .../sandboxes/pages/SandboxDetailPage.tsx     |   0
 .../sandboxes/pages/SandboxesPage.tsx         |   0
 .../{web => console}/src/hooks/use-mobile.ts  |   0
 packages/{web => console}/src/index.css       |   0
 packages/{web => console}/src/lib/api.ts      |   0
 .../{web => console}/src/lib/queryClient.ts   |   0
 packages/{web => console}/src/lib/session.ts  |   0
 packages/{web => console}/src/lib/utils.ts    |   0
 packages/{web => console}/src/main.tsx        |   0
 .../{web => console}/src/routeTree.gen.ts     |   0
 .../{web => console}/src/routes/__root.tsx    |   0
 packages/{web => console}/src/routes/_app.tsx |   0
 .../src/routes/_app/connect.tsx               |   0
 .../src/routes/_app/index.tsx                 |   0
 .../src/routes/_app/sandboxes/$userKey.tsx    |   0
 .../{web => console}/src/routes/login.tsx     |   0
 packages/{web => console}/src/shadcn.css      |   0
 packages/{web => console}/tsconfig.json       |   0
 packages/{web => console}/vite.config.ts      |   0
 packages/sdk/CHANGELOG.md                     |  14 +
 packages/sdk/LICENSE                          | 201 ++++++
 packages/sdk/README.md                        |  68 ++
 packages/sdk/package.json                     |  27 +-
 packages/server/package.json                  |   1 +
 .../routes/{ui.test.ts => console.test.ts}    |   0
 .../server/src/routes/{ui.ts => console.ts}   |   0
 packages/shared/CHANGELOG.md                  |   9 +
 packages/shared/LICENSE                       | 201 ++++++
 packages/shared/README.md                     |  15 +
 packages/shared/package.json                  |  23 +-
 pnpm-lock.yaml                                | 632 ++++++++++++++++--
 112 files changed, 1418 insertions(+), 75 deletions(-)
 create mode 100644 .changeset/README.md
 create mode 100644 .changeset/config.json
 rename e2e/src/{ui.test.ts => console.test.ts} (100%)
 create mode 100644 packages/cli/CHANGELOG.md
 create mode 100644 packages/cli/LICENSE
 create mode 100644 packages/cli/README.md
 rename packages/{web => console}/components.json (100%)
 rename packages/{web => console}/index.html (100%)
 rename packages/{web => console}/package.json (100%)
 rename packages/{web => console}/src/components/ui/accordion.tsx (100%)
 rename packages/{web => console}/src/components/ui/alert-dialog.tsx (100%)
 rename packages/{web => console}/src/components/ui/alert.tsx (100%)
 rename packages/{web => console}/src/components/ui/aspect-ratio.tsx (100%)
 rename packages/{web => console}/src/components/ui/attachment.tsx (100%)
 rename packages/{web => console}/src/components/ui/avatar.tsx (100%)
 rename packages/{web => console}/src/components/ui/badge.tsx (100%)
 rename packages/{web => console}/src/components/ui/breadcrumb.tsx (100%)
 rename packages/{web => console}/src/components/ui/bubble.tsx (100%)
 rename packages/{web => console}/src/components/ui/button-group.tsx (100%)
 rename packages/{web => console}/src/components/ui/button.tsx (100%)
 rename packages/{web => console}/src/components/ui/calendar.tsx (100%)
 rename packages/{web => console}/src/components/ui/card.tsx (100%)
 rename packages/{web => console}/src/components/ui/carousel.tsx (100%)
 rename packages/{web => console}/src/components/ui/chart.tsx (100%)
 rename packages/{web => console}/src/components/ui/checkbox.tsx (100%)
 rename packages/{web => console}/src/components/ui/collapsible.tsx (100%)
 rename packages/{web => console}/src/components/ui/combobox.tsx (100%)
 rename packages/{web => console}/src/components/ui/command.tsx (100%)
 rename packages/{web => console}/src/components/ui/context-menu.tsx (100%)
 rename packages/{web => console}/src/components/ui/dialog.tsx (100%)
 rename packages/{web => console}/src/components/ui/direction.tsx (100%)
 rename packages/{web => console}/src/components/ui/drawer.tsx (100%)
 rename packages/{web => console}/src/components/ui/dropdown-menu.tsx (100%)
 rename packages/{web => console}/src/components/ui/empty.tsx (100%)
 rename packages/{web => console}/src/components/ui/field.tsx (100%)
 rename packages/{web => console}/src/components/ui/hover-card.tsx (100%)
 rename packages/{web => console}/src/components/ui/input-group.tsx (100%)
 rename packages/{web => console}/src/components/ui/input-otp.tsx (100%)
 rename packages/{web => console}/src/components/ui/input.tsx (100%)
 rename packages/{web => console}/src/components/ui/item.tsx (100%)
 rename packages/{web => console}/src/components/ui/kbd.tsx (100%)
 rename packages/{web => console}/src/components/ui/label.tsx (100%)
 rename packages/{web => console}/src/components/ui/marker.tsx (100%)
 rename packages/{web => console}/src/components/ui/menubar.tsx (100%)
 rename packages/{web => console}/src/components/ui/message-scroller.tsx (100%)
 rename packages/{web => console}/src/components/ui/message.tsx (100%)
 rename packages/{web => console}/src/components/ui/native-select.tsx (100%)
 rename packages/{web => console}/src/components/ui/navigation-menu.tsx (100%)
 rename packages/{web => console}/src/components/ui/pagination.tsx (100%)
 rename packages/{web => console}/src/components/ui/popover.tsx (100%)
 rename packages/{web => console}/src/components/ui/progress.tsx (100%)
 rename packages/{web => console}/src/components/ui/radio-group.tsx (100%)
 rename packages/{web => console}/src/components/ui/resizable.tsx (100%)
 rename packages/{web => console}/src/components/ui/scroll-area.tsx (100%)
 rename packages/{web => console}/src/components/ui/select.tsx (100%)
 rename packages/{web => console}/src/components/ui/separator.tsx (100%)
 rename packages/{web => console}/src/components/ui/sheet.tsx (100%)
 rename packages/{web => console}/src/components/ui/sidebar.tsx (100%)
 rename packages/{web => console}/src/components/ui/skeleton.tsx (100%)
 rename packages/{web => console}/src/components/ui/slider.tsx (100%)
 rename packages/{web => console}/src/components/ui/sonner.tsx (100%)
 rename packages/{web => console}/src/components/ui/spinner.tsx (100%)
 rename packages/{web => console}/src/components/ui/switch.tsx (100%)
 rename packages/{web => console}/src/components/ui/table.tsx (100%)
 rename packages/{web => console}/src/components/ui/tabs.tsx (100%)
 rename packages/{web => console}/src/components/ui/textarea.tsx (100%)
 rename packages/{web => console}/src/components/ui/toggle-group.tsx (100%)
 rename packages/{web => console}/src/components/ui/toggle.tsx (100%)
 rename packages/{web => console}/src/components/ui/tooltip.tsx (100%)
 rename packages/{web => console}/src/features/auth/pages/LoginPage.tsx (100%)
 rename packages/{web => console}/src/features/connect/pages/ConnectPage.tsx (100%)
 rename packages/{web => console}/src/features/sandboxes/components/CreateSandboxDialog.tsx (100%)
 rename packages/{web => console}/src/features/sandboxes/components/RebuildSandboxButton.tsx (100%)
 rename packages/{web => console}/src/features/sandboxes/components/ReleaseSandboxButton.tsx (100%)
 rename packages/{web => console}/src/features/sandboxes/components/SandboxStateBadge.tsx (100%)
 rename packages/{web => console}/src/features/sandboxes/components/SandboxTerminal.tsx (100%)
 rename packages/{web => console}/src/features/sandboxes/envd-pty.ts (100%)
 rename packages/{web => console}/src/features/sandboxes/format.ts (100%)
 rename packages/{web => console}/src/features/sandboxes/hooks/useSandboxes.ts (100%)
 rename packages/{web => console}/src/features/sandboxes/pages/SandboxDetailPage.tsx (100%)
 rename packages/{web => console}/src/features/sandboxes/pages/SandboxesPage.tsx (100%)
 rename packages/{web => console}/src/hooks/use-mobile.ts (100%)
 rename packages/{web => console}/src/index.css (100%)
 rename packages/{web => console}/src/lib/api.ts (100%)
 rename packages/{web => console}/src/lib/queryClient.ts (100%)
 rename packages/{web => console}/src/lib/session.ts (100%)
 rename packages/{web => console}/src/lib/utils.ts (100%)
 rename packages/{web => console}/src/main.tsx (100%)
 rename packages/{web => console}/src/routeTree.gen.ts (100%)
 rename packages/{web => console}/src/routes/__root.tsx (100%)
 rename packages/{web => console}/src/routes/_app.tsx (100%)
 rename packages/{web => console}/src/routes/_app/connect.tsx (100%)
 rename packages/{web => console}/src/routes/_app/index.tsx (100%)
 rename packages/{web => console}/src/routes/_app/sandboxes/$userKey.tsx (100%)
 rename packages/{web => console}/src/routes/login.tsx (100%)
 rename packages/{web => console}/src/shadcn.css (100%)
 rename packages/{web => console}/tsconfig.json (100%)
 rename packages/{web => console}/vite.config.ts (100%)
 create mode 100644 packages/sdk/CHANGELOG.md
 create mode 100644 packages/sdk/LICENSE
 create mode 100644 packages/sdk/README.md
 rename packages/server/src/routes/{ui.test.ts => console.test.ts} (100%)
 rename packages/server/src/routes/{ui.ts => console.ts} (100%)
 create mode 100644 packages/shared/CHANGELOG.md
 create mode 100644 packages/shared/LICENSE
 create mode 100644 packages/shared/README.md

diff --git a/.changeset/README.md b/.changeset/README.md
new file mode 100644
index 0000000..654c6d4
--- /dev/null
+++ b/.changeset/README.md
@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).
diff --git a/.changeset/config.json b/.changeset/config.json
new file mode 100644
index 0000000..f10de02
--- /dev/null
+++ b/.changeset/config.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [["@dormice/shared", "@dormice/sdk", "@dormice/cli"]],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": [],
+  "privatePackages": { "version": false, "tag": false }
+}
diff --git a/e2e/src/ui.test.ts b/e2e/src/console.test.ts
similarity index 100%
rename from e2e/src/ui.test.ts
rename to e2e/src/console.test.ts
diff --git a/package.json b/package.json
index badf980..0ec2ef4 100644
--- a/package.json
+++ b/package.json
@@ -15,6 +15,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.2",
+    "@changesets/cli": "^2.31.0",
     "@types/node": "^26.1.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
new file mode 100644
index 0000000..9667f36
--- /dev/null
+++ b/packages/cli/CHANGELOG.md
@@ -0,0 +1,14 @@
+# @dormice/cli
+
+## 0.1.0
+
+### Minor Changes
+
+- First public release. The native TypeScript SDK (acquire/list/release/rebuild,
+  exec, file in/out), the `dormice`/`dor` CLI (host doctor plus the sandbox
+  verbs), and the shared protocol schemas they are built on.
+
+### Patch Changes
+
+- Updated dependencies
+  - @dormice/sdk@0.1.0
diff --git a/packages/cli/LICENSE b/packages/cli/LICENSE
new file mode 100644
index 0000000..261eeb9
--- /dev/null
+++ b/packages/cli/LICENSE
@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/cli/README.md b/packages/cli/README.md
new file mode 100644
index 0000000..39763d0
--- /dev/null
+++ b/packages/cli/README.md
@@ -0,0 +1,41 @@
+# @dormice/cli
+
+Command-line tool for [Dormice](https://github.com/BitMiracle-AI/Dormice)
+daemons. Installs two names for the same binary: `dormice`, and `dor` for
+people who type it all day.
+
+## Install
+
+```sh
+npm install -g @dormice/cli
+```
+
+## Connect
+
+Everything under `dor sandbox` talks to a daemon named by two environment
+variables (it complains by name if one is missing):
+
+```sh
+export DORMICE_ENDPOINT=http://127.0.0.1:3676
+export DORMICE_API_TOKEN=...
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `dor doctor [--quick]` | Read-only host check: can this machine run the daemon? (Linux, Docker, gVisor, swap, …) |
+| `dor sandbox ls` | List every sandbox and its lifecycle state |
+| `dor sandbox exec <key> <cmd> [-t seconds]` | Run a command inside a sandbox (wakes it first); its exit code passes through |
+| `dor sandbox push <key> <local> [remote]` | Copy a local file into the sandbox |
+| `dor sandbox pull <key> <remote> [local]` | Copy a file out; no local path = raw bytes to stdout |
+| `dor sandbox rebuild <key>` | Swap the container, keep `/home/user` — next use starts on the daemon's current base image |
+| `dor sandbox release <key>` | Destroy the sandbox (idempotent) |
+
+`doctor` inspects the local host, never writes, and prints the fix for
+anything it flags — the checks are the distilled lessons of running the
+daemon on real machines.
+
+## License
+
+Apache-2.0
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 336c231..b322b50 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,8 +1,29 @@
 {
   "name": "@dormice/cli",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Dormice command-line tool (dormice, or dor for short)",
+  "keywords": [
+    "dormice",
+    "sandbox",
+    "agent",
+    "cli",
+    "gvisor",
+    "docker"
+  ],
   "license": "Apache-2.0",
+  "homepage": "https://github.com/BitMiracle-AI/Dormice#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BitMiracle-AI/Dormice.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/BitMiracle-AI/Dormice/issues",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "bin": {
     "dormice": "./dist/main.js",
@@ -17,7 +38,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@dormice/sdk": "workspace:*",
+    "@dormice/sdk": "workspace:^",
     "commander": "^14.0.0"
   },
   "devDependencies": {
diff --git a/packages/web/components.json b/packages/console/components.json
similarity index 100%
rename from packages/web/components.json
rename to packages/console/components.json
diff --git a/packages/web/index.html b/packages/console/index.html
similarity index 100%
rename from packages/web/index.html
rename to packages/console/index.html
diff --git a/packages/web/package.json b/packages/console/package.json
similarity index 100%
rename from packages/web/package.json
rename to packages/console/package.json
diff --git a/packages/web/src/components/ui/accordion.tsx b/packages/console/src/components/ui/accordion.tsx
similarity index 100%
rename from packages/web/src/components/ui/accordion.tsx
rename to packages/console/src/components/ui/accordion.tsx
diff --git a/packages/web/src/components/ui/alert-dialog.tsx b/packages/console/src/components/ui/alert-dialog.tsx
similarity index 100%
rename from packages/web/src/components/ui/alert-dialog.tsx
rename to packages/console/src/components/ui/alert-dialog.tsx
diff --git a/packages/web/src/components/ui/alert.tsx b/packages/console/src/components/ui/alert.tsx
similarity index 100%
rename from packages/web/src/components/ui/alert.tsx
rename to packages/console/src/components/ui/alert.tsx
diff --git a/packages/web/src/components/ui/aspect-ratio.tsx b/packages/console/src/components/ui/aspect-ratio.tsx
similarity index 100%
rename from packages/web/src/components/ui/aspect-ratio.tsx
rename to packages/console/src/components/ui/aspect-ratio.tsx
diff --git a/packages/web/src/components/ui/attachment.tsx b/packages/console/src/components/ui/attachment.tsx
similarity index 100%
rename from packages/web/src/components/ui/attachment.tsx
rename to packages/console/src/components/ui/attachment.tsx
diff --git a/packages/web/src/components/ui/avatar.tsx b/packages/console/src/components/ui/avatar.tsx
similarity index 100%
rename from packages/web/src/components/ui/avatar.tsx
rename to packages/console/src/components/ui/avatar.tsx
diff --git a/packages/web/src/components/ui/badge.tsx b/packages/console/src/components/ui/badge.tsx
similarity index 100%
rename from packages/web/src/components/ui/badge.tsx
rename to packages/console/src/components/ui/badge.tsx
diff --git a/packages/web/src/components/ui/breadcrumb.tsx b/packages/console/src/components/ui/breadcrumb.tsx
similarity index 100%
rename from packages/web/src/components/ui/breadcrumb.tsx
rename to packages/console/src/components/ui/breadcrumb.tsx
diff --git a/packages/web/src/components/ui/bubble.tsx b/packages/console/src/components/ui/bubble.tsx
similarity index 100%
rename from packages/web/src/components/ui/bubble.tsx
rename to packages/console/src/components/ui/bubble.tsx
diff --git a/packages/web/src/components/ui/button-group.tsx b/packages/console/src/components/ui/button-group.tsx
similarity index 100%
rename from packages/web/src/components/ui/button-group.tsx
rename to packages/console/src/components/ui/button-group.tsx
diff --git a/packages/web/src/components/ui/button.tsx b/packages/console/src/components/ui/button.tsx
similarity index 100%
rename from packages/web/src/components/ui/button.tsx
rename to packages/console/src/components/ui/button.tsx
diff --git a/packages/web/src/components/ui/calendar.tsx b/packages/console/src/components/ui/calendar.tsx
similarity index 100%
rename from packages/web/src/components/ui/calendar.tsx
rename to packages/console/src/components/ui/calendar.tsx
diff --git a/packages/web/src/components/ui/card.tsx b/packages/console/src/components/ui/card.tsx
similarity index 100%
rename from packages/web/src/components/ui/card.tsx
rename to packages/console/src/components/ui/card.tsx
diff --git a/packages/web/src/components/ui/carousel.tsx b/packages/console/src/components/ui/carousel.tsx
similarity index 100%
rename from packages/web/src/components/ui/carousel.tsx
rename to packages/console/src/components/ui/carousel.tsx
diff --git a/packages/web/src/components/ui/chart.tsx b/packages/console/src/components/ui/chart.tsx
similarity index 100%
rename from packages/web/src/components/ui/chart.tsx
rename to packages/console/src/components/ui/chart.tsx
diff --git a/packages/web/src/components/ui/checkbox.tsx b/packages/console/src/components/ui/checkbox.tsx
similarity index 100%
rename from packages/web/src/components/ui/checkbox.tsx
rename to packages/console/src/components/ui/checkbox.tsx
diff --git a/packages/web/src/components/ui/collapsible.tsx b/packages/console/src/components/ui/collapsible.tsx
similarity index 100%
rename from packages/web/src/components/ui/collapsible.tsx
rename to packages/console/src/components/ui/collapsible.tsx
diff --git a/packages/web/src/components/ui/combobox.tsx b/packages/console/src/components/ui/combobox.tsx
similarity index 100%
rename from packages/web/src/components/ui/combobox.tsx
rename to packages/console/src/components/ui/combobox.tsx
diff --git a/packages/web/src/components/ui/command.tsx b/packages/console/src/components/ui/command.tsx
similarity index 100%
rename from packages/web/src/components/ui/command.tsx
rename to packages/console/src/components/ui/command.tsx
diff --git a/packages/web/src/components/ui/context-menu.tsx b/packages/console/src/components/ui/context-menu.tsx
similarity index 100%
rename from packages/web/src/components/ui/context-menu.tsx
rename to packages/console/src/components/ui/context-menu.tsx
diff --git a/packages/web/src/components/ui/dialog.tsx b/packages/console/src/components/ui/dialog.tsx
similarity index 100%
rename from packages/web/src/components/ui/dialog.tsx
rename to packages/console/src/components/ui/dialog.tsx
diff --git a/packages/web/src/components/ui/direction.tsx b/packages/console/src/components/ui/direction.tsx
similarity index 100%
rename from packages/web/src/components/ui/direction.tsx
rename to packages/console/src/components/ui/direction.tsx
diff --git a/packages/web/src/components/ui/drawer.tsx b/packages/console/src/components/ui/drawer.tsx
similarity index 100%
rename from packages/web/src/components/ui/drawer.tsx
rename to packages/console/src/components/ui/drawer.tsx
diff --git a/packages/web/src/components/ui/dropdown-menu.tsx b/packages/console/src/components/ui/dropdown-menu.tsx
similarity index 100%
rename from packages/web/src/components/ui/dropdown-menu.tsx
rename to packages/console/src/components/ui/dropdown-menu.tsx
diff --git a/packages/web/src/components/ui/empty.tsx b/packages/console/src/components/ui/empty.tsx
similarity index 100%
rename from packages/web/src/components/ui/empty.tsx
rename to packages/console/src/components/ui/empty.tsx
diff --git a/packages/web/src/components/ui/field.tsx b/packages/console/src/components/ui/field.tsx
similarity index 100%
rename from packages/web/src/components/ui/field.tsx
rename to packages/console/src/components/ui/field.tsx
diff --git a/packages/web/src/components/ui/hover-card.tsx b/packages/console/src/components/ui/hover-card.tsx
similarity index 100%
rename from packages/web/src/components/ui/hover-card.tsx
rename to packages/console/src/components/ui/hover-card.tsx
diff --git a/packages/web/src/components/ui/input-group.tsx b/packages/console/src/components/ui/input-group.tsx
similarity index 100%
rename from packages/web/src/components/ui/input-group.tsx
rename to packages/console/src/components/ui/input-group.tsx
diff --git a/packages/web/src/components/ui/input-otp.tsx b/packages/console/src/components/ui/input-otp.tsx
similarity index 100%
rename from packages/web/src/components/ui/input-otp.tsx
rename to packages/console/src/components/ui/input-otp.tsx
diff --git a/packages/web/src/components/ui/input.tsx b/packages/console/src/components/ui/input.tsx
similarity index 100%
rename from packages/web/src/components/ui/input.tsx
rename to packages/console/src/components/ui/input.tsx
diff --git a/packages/web/src/components/ui/item.tsx b/packages/console/src/components/ui/item.tsx
similarity index 100%
rename from packages/web/src/components/ui/item.tsx
rename to packages/console/src/components/ui/item.tsx
diff --git a/packages/web/src/components/ui/kbd.tsx b/packages/console/src/components/ui/kbd.tsx
similarity index 100%
rename from packages/web/src/components/ui/kbd.tsx
rename to packages/console/src/components/ui/kbd.tsx
diff --git a/packages/web/src/components/ui/label.tsx b/packages/console/src/components/ui/label.tsx
similarity index 100%
rename from packages/web/src/components/ui/label.tsx
rename to packages/console/src/components/ui/label.tsx
diff --git a/packages/web/src/components/ui/marker.tsx b/packages/console/src/components/ui/marker.tsx
similarity index 100%
rename from packages/web/src/components/ui/marker.tsx
rename to packages/console/src/components/ui/marker.tsx
diff --git a/packages/web/src/components/ui/menubar.tsx b/packages/console/src/components/ui/menubar.tsx
similarity index 100%
rename from packages/web/src/components/ui/menubar.tsx
rename to packages/console/src/components/ui/menubar.tsx
diff --git a/packages/web/src/components/ui/message-scroller.tsx b/packages/console/src/components/ui/message-scroller.tsx
similarity index 100%
rename from packages/web/src/components/ui/message-scroller.tsx
rename to packages/console/src/components/ui/message-scroller.tsx
diff --git a/packages/web/src/components/ui/message.tsx b/packages/console/src/components/ui/message.tsx
similarity index 100%
rename from packages/web/src/components/ui/message.tsx
rename to packages/console/src/components/ui/message.tsx
diff --git a/packages/web/src/components/ui/native-select.tsx b/packages/console/src/components/ui/native-select.tsx
similarity index 100%
rename from packages/web/src/components/ui/native-select.tsx
rename to packages/console/src/components/ui/native-select.tsx
diff --git a/packages/web/src/components/ui/navigation-menu.tsx b/packages/console/src/components/ui/navigation-menu.tsx
similarity index 100%
rename from packages/web/src/components/ui/navigation-menu.tsx
rename to packages/console/src/components/ui/navigation-menu.tsx
diff --git a/packages/web/src/components/ui/pagination.tsx b/packages/console/src/components/ui/pagination.tsx
similarity index 100%
rename from packages/web/src/components/ui/pagination.tsx
rename to packages/console/src/components/ui/pagination.tsx
diff --git a/packages/web/src/components/ui/popover.tsx b/packages/console/src/components/ui/popover.tsx
similarity index 100%
rename from packages/web/src/components/ui/popover.tsx
rename to packages/console/src/components/ui/popover.tsx
diff --git a/packages/web/src/components/ui/progress.tsx b/packages/console/src/components/ui/progress.tsx
similarity index 100%
rename from packages/web/src/components/ui/progress.tsx
rename to packages/console/src/components/ui/progress.tsx
diff --git a/packages/web/src/components/ui/radio-group.tsx b/packages/console/src/components/ui/radio-group.tsx
similarity index 100%
rename from packages/web/src/components/ui/radio-group.tsx
rename to packages/console/src/components/ui/radio-group.tsx
diff --git a/packages/web/src/components/ui/resizable.tsx b/packages/console/src/components/ui/resizable.tsx
similarity index 100%
rename from packages/web/src/components/ui/resizable.tsx
rename to packages/console/src/components/ui/resizable.tsx
diff --git a/packages/web/src/components/ui/scroll-area.tsx b/packages/console/src/components/ui/scroll-area.tsx
similarity index 100%
rename from packages/web/src/components/ui/scroll-area.tsx
rename to packages/console/src/components/ui/scroll-area.tsx
diff --git a/packages/web/src/components/ui/select.tsx b/packages/console/src/components/ui/select.tsx
similarity index 100%
rename from packages/web/src/components/ui/select.tsx
rename to packages/console/src/components/ui/select.tsx
diff --git a/packages/web/src/components/ui/separator.tsx b/packages/console/src/components/ui/separator.tsx
similarity index 100%
rename from packages/web/src/components/ui/separator.tsx
rename to packages/console/src/components/ui/separator.tsx
diff --git a/packages/web/src/components/ui/sheet.tsx b/packages/console/src/components/ui/sheet.tsx
similarity index 100%
rename from packages/web/src/components/ui/sheet.tsx
rename to packages/console/src/components/ui/sheet.tsx
diff --git a/packages/web/src/components/ui/sidebar.tsx b/packages/console/src/components/ui/sidebar.tsx
similarity index 100%
rename from packages/web/src/components/ui/sidebar.tsx
rename to packages/console/src/components/ui/sidebar.tsx
diff --git a/packages/web/src/components/ui/skeleton.tsx b/packages/console/src/components/ui/skeleton.tsx
similarity index 100%
rename from packages/web/src/components/ui/skeleton.tsx
rename to packages/console/src/components/ui/skeleton.tsx
diff --git a/packages/web/src/components/ui/slider.tsx b/packages/console/src/components/ui/slider.tsx
similarity index 100%
rename from packages/web/src/components/ui/slider.tsx
rename to packages/console/src/components/ui/slider.tsx
diff --git a/packages/web/src/components/ui/sonner.tsx b/packages/console/src/components/ui/sonner.tsx
similarity index 100%
rename from packages/web/src/components/ui/sonner.tsx
rename to packages/console/src/components/ui/sonner.tsx
diff --git a/packages/web/src/components/ui/spinner.tsx b/packages/console/src/components/ui/spinner.tsx
similarity index 100%
rename from packages/web/src/components/ui/spinner.tsx
rename to packages/console/src/components/ui/spinner.tsx
diff --git a/packages/web/src/components/ui/switch.tsx b/packages/console/src/components/ui/switch.tsx
similarity index 100%
rename from packages/web/src/components/ui/switch.tsx
rename to packages/console/src/components/ui/switch.tsx
diff --git a/packages/web/src/components/ui/table.tsx b/packages/console/src/components/ui/table.tsx
similarity index 100%
rename from packages/web/src/components/ui/table.tsx
rename to packages/console/src/components/ui/table.tsx
diff --git a/packages/web/src/components/ui/tabs.tsx b/packages/console/src/components/ui/tabs.tsx
similarity index 100%
rename from packages/web/src/components/ui/tabs.tsx
rename to packages/console/src/components/ui/tabs.tsx
diff --git a/packages/web/src/components/ui/textarea.tsx b/packages/console/src/components/ui/textarea.tsx
similarity index 100%
rename from packages/web/src/components/ui/textarea.tsx
rename to packages/console/src/components/ui/textarea.tsx
diff --git a/packages/web/src/components/ui/toggle-group.tsx b/packages/console/src/components/ui/toggle-group.tsx
similarity index 100%
rename from packages/web/src/components/ui/toggle-group.tsx
rename to packages/console/src/components/ui/toggle-group.tsx
diff --git a/packages/web/src/components/ui/toggle.tsx b/packages/console/src/components/ui/toggle.tsx
similarity index 100%
rename from packages/web/src/components/ui/toggle.tsx
rename to packages/console/src/components/ui/toggle.tsx
diff --git a/packages/web/src/components/ui/tooltip.tsx b/packages/console/src/components/ui/tooltip.tsx
similarity index 100%
rename from packages/web/src/components/ui/tooltip.tsx
rename to packages/console/src/components/ui/tooltip.tsx
diff --git a/packages/web/src/features/auth/pages/LoginPage.tsx b/packages/console/src/features/auth/pages/LoginPage.tsx
similarity index 100%
rename from packages/web/src/features/auth/pages/LoginPage.tsx
rename to packages/console/src/features/auth/pages/LoginPage.tsx
diff --git a/packages/web/src/features/connect/pages/ConnectPage.tsx b/packages/console/src/features/connect/pages/ConnectPage.tsx
similarity index 100%
rename from packages/web/src/features/connect/pages/ConnectPage.tsx
rename to packages/console/src/features/connect/pages/ConnectPage.tsx
diff --git a/packages/web/src/features/sandboxes/components/CreateSandboxDialog.tsx b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
similarity index 100%
rename from packages/web/src/features/sandboxes/components/CreateSandboxDialog.tsx
rename to packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
diff --git a/packages/web/src/features/sandboxes/components/RebuildSandboxButton.tsx b/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx
similarity index 100%
rename from packages/web/src/features/sandboxes/components/RebuildSandboxButton.tsx
rename to packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx
diff --git a/packages/web/src/features/sandboxes/components/ReleaseSandboxButton.tsx b/packages/console/src/features/sandboxes/components/ReleaseSandboxButton.tsx
similarity index 100%
rename from packages/web/src/features/sandboxes/components/ReleaseSandboxButton.tsx
rename to packages/console/src/features/sandboxes/components/ReleaseSandboxButton.tsx
diff --git a/packages/web/src/features/sandboxes/components/SandboxStateBadge.tsx b/packages/console/src/features/sandboxes/components/SandboxStateBadge.tsx
similarity index 100%
rename from packages/web/src/features/sandboxes/components/SandboxStateBadge.tsx
rename to packages/console/src/features/sandboxes/components/SandboxStateBadge.tsx
diff --git a/packages/web/src/features/sandboxes/components/SandboxTerminal.tsx b/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
similarity index 100%
rename from packages/web/src/features/sandboxes/components/SandboxTerminal.tsx
rename to packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
diff --git a/packages/web/src/features/sandboxes/envd-pty.ts b/packages/console/src/features/sandboxes/envd-pty.ts
similarity index 100%
rename from packages/web/src/features/sandboxes/envd-pty.ts
rename to packages/console/src/features/sandboxes/envd-pty.ts
diff --git a/packages/web/src/features/sandboxes/format.ts b/packages/console/src/features/sandboxes/format.ts
similarity index 100%
rename from packages/web/src/features/sandboxes/format.ts
rename to packages/console/src/features/sandboxes/format.ts
diff --git a/packages/web/src/features/sandboxes/hooks/useSandboxes.ts b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
similarity index 100%
rename from packages/web/src/features/sandboxes/hooks/useSandboxes.ts
rename to packages/console/src/features/sandboxes/hooks/useSandboxes.ts
diff --git a/packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
similarity index 100%
rename from packages/web/src/features/sandboxes/pages/SandboxDetailPage.tsx
rename to packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
diff --git a/packages/web/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
similarity index 100%
rename from packages/web/src/features/sandboxes/pages/SandboxesPage.tsx
rename to packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
diff --git a/packages/web/src/hooks/use-mobile.ts b/packages/console/src/hooks/use-mobile.ts
similarity index 100%
rename from packages/web/src/hooks/use-mobile.ts
rename to packages/console/src/hooks/use-mobile.ts
diff --git a/packages/web/src/index.css b/packages/console/src/index.css
similarity index 100%
rename from packages/web/src/index.css
rename to packages/console/src/index.css
diff --git a/packages/web/src/lib/api.ts b/packages/console/src/lib/api.ts
similarity index 100%
rename from packages/web/src/lib/api.ts
rename to packages/console/src/lib/api.ts
diff --git a/packages/web/src/lib/queryClient.ts b/packages/console/src/lib/queryClient.ts
similarity index 100%
rename from packages/web/src/lib/queryClient.ts
rename to packages/console/src/lib/queryClient.ts
diff --git a/packages/web/src/lib/session.ts b/packages/console/src/lib/session.ts
similarity index 100%
rename from packages/web/src/lib/session.ts
rename to packages/console/src/lib/session.ts
diff --git a/packages/web/src/lib/utils.ts b/packages/console/src/lib/utils.ts
similarity index 100%
rename from packages/web/src/lib/utils.ts
rename to packages/console/src/lib/utils.ts
diff --git a/packages/web/src/main.tsx b/packages/console/src/main.tsx
similarity index 100%
rename from packages/web/src/main.tsx
rename to packages/console/src/main.tsx
diff --git a/packages/web/src/routeTree.gen.ts b/packages/console/src/routeTree.gen.ts
similarity index 100%
rename from packages/web/src/routeTree.gen.ts
rename to packages/console/src/routeTree.gen.ts
diff --git a/packages/web/src/routes/__root.tsx b/packages/console/src/routes/__root.tsx
similarity index 100%
rename from packages/web/src/routes/__root.tsx
rename to packages/console/src/routes/__root.tsx
diff --git a/packages/web/src/routes/_app.tsx b/packages/console/src/routes/_app.tsx
similarity index 100%
rename from packages/web/src/routes/_app.tsx
rename to packages/console/src/routes/_app.tsx
diff --git a/packages/web/src/routes/_app/connect.tsx b/packages/console/src/routes/_app/connect.tsx
similarity index 100%
rename from packages/web/src/routes/_app/connect.tsx
rename to packages/console/src/routes/_app/connect.tsx
diff --git a/packages/web/src/routes/_app/index.tsx b/packages/console/src/routes/_app/index.tsx
similarity index 100%
rename from packages/web/src/routes/_app/index.tsx
rename to packages/console/src/routes/_app/index.tsx
diff --git a/packages/web/src/routes/_app/sandboxes/$userKey.tsx b/packages/console/src/routes/_app/sandboxes/$userKey.tsx
similarity index 100%
rename from packages/web/src/routes/_app/sandboxes/$userKey.tsx
rename to packages/console/src/routes/_app/sandboxes/$userKey.tsx
diff --git a/packages/web/src/routes/login.tsx b/packages/console/src/routes/login.tsx
similarity index 100%
rename from packages/web/src/routes/login.tsx
rename to packages/console/src/routes/login.tsx
diff --git a/packages/web/src/shadcn.css b/packages/console/src/shadcn.css
similarity index 100%
rename from packages/web/src/shadcn.css
rename to packages/console/src/shadcn.css
diff --git a/packages/web/tsconfig.json b/packages/console/tsconfig.json
similarity index 100%
rename from packages/web/tsconfig.json
rename to packages/console/tsconfig.json
diff --git a/packages/web/vite.config.ts b/packages/console/vite.config.ts
similarity index 100%
rename from packages/web/vite.config.ts
rename to packages/console/vite.config.ts
diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.md
new file mode 100644
index 0000000..39ed441
--- /dev/null
+++ b/packages/sdk/CHANGELOG.md
@@ -0,0 +1,14 @@
+# @dormice/sdk
+
+## 0.1.0
+
+### Minor Changes
+
+- First public release. The native TypeScript SDK (acquire/list/release/rebuild,
+  exec, file in/out), the `dormice`/`dor` CLI (host doctor plus the sandbox
+  verbs), and the shared protocol schemas they are built on.
+
+### Patch Changes
+
+- Updated dependencies
+  - @dormice/shared@0.1.0
diff --git a/packages/sdk/LICENSE b/packages/sdk/LICENSE
new file mode 100644
index 0000000..261eeb9
--- /dev/null
+++ b/packages/sdk/LICENSE
@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
new file mode 100644
index 0000000..94fe0e0
--- /dev/null
+++ b/packages/sdk/README.md
@@ -0,0 +1,68 @@
+# @dormice/sdk
+
+TypeScript client for [Dormice](https://github.com/BitMiracle-AI/Dormice) — a self-hosted agent sandbox platform: one machine, sandboxes that live forever, idle costs nothing.
+
+This is the native SDK. It talks to your own Dormice daemon over its RPC API; nothing here calls a hosted service.
+
+## Install
+
+```sh
+npm install @dormice/sdk
+```
+
+## Quick start
+
+```ts
+import { Dormice } from '@dormice/sdk';
+
+const client = new Dormice({
+  endpoint: 'http://127.0.0.1:3676', // your daemon
+  token: process.env.DORMICE_API_TOKEN!,
+});
+
+// acquire is idempotent: one key, one sandbox — created, woken or
+// restored as needed. Call it as often as you like.
+await client.acquireSandbox('my-agent');
+
+const result = await client.execCommand('my-agent', 'echo hello');
+console.log(result.stdout); // "hello\n"
+
+await client.writeFiles('my-agent', [
+  { path: 'notes.txt', content: 'kept on the sandbox disk' },
+]);
+const file = await client.readFile('my-agent', 'notes.txt');
+console.log(new TextDecoder().decode(file.content));
+
+await client.releaseSandbox('my-agent'); // destroy, idempotent
+```
+
+Idle sandboxes freeze (RAM squeezed out, ~50 ms wake), then stop (disk only);
+`acquireSandbox` — or any command or file call — brings them back. The
+lifecycle policy is set at creation: `freezeAfterSeconds`, `stopAfterSeconds`
+(pass `null` for a resident agent that never cold-starts), `archiveAfterSeconds`.
+
+## Methods
+
+| Method | What it does |
+| --- | --- |
+| `acquireSandbox(userKey, policy?)` | Create or wake the sandbox behind a key (idempotent) |
+| `listSandboxes()` | Every sandbox with its current lifecycle state |
+| `execCommand(userKey, command, opts?)` | Run a shell command; buffered stdout/stderr and the real exit code |
+| `writeFiles(userKey, files)` | Write files onto the sandbox disk (relative paths land under `/home/user`) |
+| `readFile(userKey, path)` | Read a file back as bytes |
+| `rebuildSandbox(userKey)` | Swap the container, keep `/home/user` — next use starts on the daemon's current base image |
+| `releaseSandbox(userKey)` | Destroy the sandbox (idempotent) |
+
+A non-zero exit code is a result, not an error. API failures throw
+`DormiceApiError` carrying the HTTP status and the daemon's message.
+
+## E2B compatibility
+
+The daemon also speaks the E2B protocol: the official `e2b` package works
+against it by changing two URLs. See the
+[repository](https://github.com/BitMiracle-AI/Dormice) for details — this SDK
+is the smaller, native alternative.
+
+## License
+
+Apache-2.0
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 43da360..fc4261d 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -1,8 +1,31 @@
 {
   "name": "@dormice/sdk",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "TypeScript SDK for Dormice sandboxes",
+  "keywords": [
+    "dormice",
+    "sandbox",
+    "agent",
+    "ai",
+    "e2b",
+    "gvisor",
+    "docker"
+  ],
   "license": "Apache-2.0",
+  "homepage": "https://github.com/BitMiracle-AI/Dormice#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BitMiracle-AI/Dormice.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": "https://github.com/BitMiracle-AI/Dormice/issues",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -19,7 +42,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@dormice/shared": "workspace:*",
+    "@dormice/shared": "workspace:^",
     "undici": "^8.7.0"
   },
   "devDependencies": {
diff --git a/packages/server/package.json b/packages/server/package.json
index c3b9594..db08d0e 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -1,6 +1,7 @@
 {
   "name": "@dormice/server",
   "version": "0.0.0",
+  "private": true,
   "description": "Dormice daemon: sandbox lifecycle over Docker + gVisor, SQLite ledger",
   "license": "Apache-2.0",
   "type": "module",
diff --git a/packages/server/src/routes/ui.test.ts b/packages/server/src/routes/console.test.ts
similarity index 100%
rename from packages/server/src/routes/ui.test.ts
rename to packages/server/src/routes/console.test.ts
diff --git a/packages/server/src/routes/ui.ts b/packages/server/src/routes/console.ts
similarity index 100%
rename from packages/server/src/routes/ui.ts
rename to packages/server/src/routes/console.ts
diff --git a/packages/shared/CHANGELOG.md b/packages/shared/CHANGELOG.md
new file mode 100644
index 0000000..574d7b0
--- /dev/null
+++ b/packages/shared/CHANGELOG.md
@@ -0,0 +1,9 @@
+# @dormice/shared
+
+## 0.1.0
+
+### Minor Changes
+
+- First public release. The native TypeScript SDK (acquire/list/release/rebuild,
+  exec, file in/out), the `dormice`/`dor` CLI (host doctor plus the sandbox
+  verbs), and the shared protocol schemas they are built on.
diff --git a/packages/shared/LICENSE b/packages/shared/LICENSE
new file mode 100644
index 0000000..261eeb9
--- /dev/null
+++ b/packages/shared/LICENSE
@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/shared/README.md b/packages/shared/README.md
new file mode 100644
index 0000000..d6a1277
--- /dev/null
+++ b/packages/shared/README.md
@@ -0,0 +1,15 @@
+# @dormice/shared
+
+Protocol schemas ([zod](https://zod.dev)) and types shared by the
+[Dormice](https://github.com/BitMiracle-AI/Dormice) daemon, SDK and web
+console: sandbox lifecycle states, the three-knob lifecycle policy,
+request/response shapes, and the sandbox path resolver.
+
+You probably want [`@dormice/sdk`](https://www.npmjs.com/package/@dormice/sdk)
+instead — it depends on this package and re-exports what applications need.
+This one exists so the server, the SDK and the browser console all validate
+against a single source of truth.
+
+## License
+
+Apache-2.0
diff --git a/packages/shared/package.json b/packages/shared/package.json
index a61aa49..0a5c745 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -1,8 +1,29 @@
 {
   "name": "@dormice/shared",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Protocol types and schemas shared by the Dormice server, SDK, and WebUI",
+  "keywords": [
+    "dormice",
+    "sandbox",
+    "protocol",
+    "schemas",
+    "zod"
+  ],
   "license": "Apache-2.0",
+  "homepage": "https://github.com/BitMiracle-AI/Dormice#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BitMiracle-AI/Dormice.git",
+    "directory": "packages/shared"
+  },
+  "bugs": "https://github.com/BitMiracle-AI/Dormice/issues",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e0d87ec..bb1a584 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -11,6 +11,9 @@ importers:
       '@biomejs/biome':
         specifier: ^2.5.2
         version: 2.5.2
+      '@changesets/cli':
+        specifier: ^2.31.0
+        version: 2.31.0(@types/node@26.1.0)
       '@types/node':
         specifier: ^26.1.0
         version: 26.1.0
@@ -36,7 +39,7 @@ importers:
   packages/cli:
     dependencies:
       '@dormice/sdk':
-        specifier: workspace:*
+        specifier: workspace:^
         version: link:../sdk
       commander:
         specifier: ^14.0.0
@@ -46,75 +49,7 @@ importers:
         specifier: workspace:*
         version: link:../server
 
-  packages/sdk:
-    dependencies:
-      '@dormice/shared':
-        specifier: workspace:*
-        version: link:../shared
-      undici:
-        specifier: ^8.7.0
-        version: 8.7.0
-    devDependencies:
-      '@dormice/server':
-        specifier: workspace:*
-        version: link:../server
-
-  packages/server:
-    dependencies:
-      '@dormice/shared':
-        specifier: workspace:*
-        version: link:../shared
-      '@fastify/cookie':
-        specifier: ^11.0.2
-        version: 11.0.2
-      '@fastify/multipart':
-        specifier: ^10.0.0
-        version: 10.0.0
-      '@fastify/static':
-        specifier: ^9.1.3
-        version: 9.1.3
-      better-sqlite3:
-        specifier: ^12.11.1
-        version: 12.11.1
-      dockerode:
-        specifier: ^5.0.1
-        version: 5.0.1
-      drizzle-orm:
-        specifier: ^0.45.2
-        version: 0.45.2(@types/better-sqlite3@7.6.13)(better-sqlite3@12.11.1)
-      execa:
-        specifier: ^9.6.1
-        version: 9.6.1
-      fastify:
-        specifier: ^5.10.0
-        version: 5.10.0
-      fastify-type-provider-zod:
-        specifier: ^7.0.0
-        version: 7.0.0(@fastify/swagger@9.7.0)(fastify@5.10.0)(openapi-types@12.1.3)(zod@4.4.3)
-      pino:
-        specifier: ^10.3.1
-        version: 10.3.1
-      zod:
-        specifier: ^4.4.3
-        version: 4.4.3
-    devDependencies:
-      '@types/better-sqlite3':
-        specifier: ^7.6.13
-        version: 7.6.13
-      '@types/dockerode':
-        specifier: ^4.0.1
-        version: 4.0.1
-      drizzle-kit:
-        specifier: ^0.31.10
-        version: 0.31.10
-
-  packages/shared:
-    dependencies:
-      zod:
-        specifier: ^4.4.3
-        version: 4.4.3
-
-  packages/web:
+  packages/console:
     dependencies:
       '@base-ui/react':
         specifier: ^1.6.0
@@ -217,6 +152,74 @@ importers:
         specifier: ^8.1.3
         version: 8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)
 
+  packages/sdk:
+    dependencies:
+      '@dormice/shared':
+        specifier: workspace:^
+        version: link:../shared
+      undici:
+        specifier: ^8.7.0
+        version: 8.7.0
+    devDependencies:
+      '@dormice/server':
+        specifier: workspace:*
+        version: link:../server
+
+  packages/server:
+    dependencies:
+      '@dormice/shared':
+        specifier: workspace:*
+        version: link:../shared
+      '@fastify/cookie':
+        specifier: ^11.0.2
+        version: 11.0.2
+      '@fastify/multipart':
+        specifier: ^10.0.0
+        version: 10.0.0
+      '@fastify/static':
+        specifier: ^9.1.3
+        version: 9.1.3
+      better-sqlite3:
+        specifier: ^12.11.1
+        version: 12.11.1
+      dockerode:
+        specifier: ^5.0.1
+        version: 5.0.1
+      drizzle-orm:
+        specifier: ^0.45.2
+        version: 0.45.2(@types/better-sqlite3@7.6.13)(better-sqlite3@12.11.1)
+      execa:
+        specifier: ^9.6.1
+        version: 9.6.1
+      fastify:
+        specifier: ^5.10.0
+        version: 5.10.0
+      fastify-type-provider-zod:
+        specifier: ^7.0.0
+        version: 7.0.0(@fastify/swagger@9.7.0)(fastify@5.10.0)(openapi-types@12.1.3)(zod@4.4.3)
+      pino:
+        specifier: ^10.3.1
+        version: 10.3.1
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+    devDependencies:
+      '@types/better-sqlite3':
+        specifier: ^7.6.13
+        version: 7.6.13
+      '@types/dockerode':
+        specifier: ^4.0.1
+        version: 4.0.1
+      drizzle-kit:
+        specifier: ^0.31.10
+        version: 0.31.10
+
+  packages/shared:
+    dependencies:
+      zod:
+        specifier: ^4.4.3
+        version: 4.4.3
+
 packages:
 
   '@babel/code-frame@7.29.7':
@@ -442,6 +445,61 @@ packages:
   '@bufbuild/protobuf@2.12.1':
     resolution: {integrity: sha512-BvAMfS6LrgZiryOAZ4pBYucu4wG/Ei/9o9DZ9akbREnMLbPJiom2i8b9C8IsKErQoiKqVhrerzt3kOT/RrzLHg==}
 
+  '@changesets/apply-release-plan@7.1.1':
+    resolution: {integrity: sha512-9qPCm/rLx/xoOFXIHGB229+4GOL76S4MC+7tyOuTsR6+1jYlfFDQORdvwR5hDA6y4FL2BPt3qpbcQIS+dW85LA==}
+
+  '@changesets/assemble-release-plan@6.0.10':
+    resolution: {integrity: sha512-rSDcqdJ9KbVyjpBIuCidhvZNIiVt1XaIYp73ycVQRIA5n/j6wQaEk0ChRLMUQ1vkxZe51PTQ9OIhbg6HQMW45A==}
+
+  '@changesets/changelog-git@0.2.1':
+    resolution: {integrity: sha512-x/xEleCFLH28c3bQeQIyeZf8lFXyDFVn1SgcBiR2Tw/r4IAWlk1fzxCEZ6NxQAjF2Nwtczoen3OA2qR+UawQ8Q==}
+
+  '@changesets/cli@2.31.0':
+    resolution: {integrity: sha512-AhI4enNTgHu2IZr6K4WZyf0EPch4XVMn1yOMFmCD9gsfBGqMYaHXls5HyDv6/CL5axVQABz68eG30eCtbr2wFg==}
+    hasBin: true
+
+  '@changesets/config@3.1.4':
+    resolution: {integrity: sha512-pf0bvD/v6WI2cRlZ6hzpjtZdSlXDXMAJ+Iz7xfFzV4ZxJ8OGGAON+1qYc99ZPrijnt4xp3VGG7eNvAOGS24V1Q==}
+
+  '@changesets/errors@0.2.0':
+    resolution: {integrity: sha512-6BLOQUscTpZeGljvyQXlWOItQyU71kCdGz7Pi8H8zdw6BI0g3m43iL4xKUVPWtG+qrrL9DTjpdn8eYuCQSRpow==}
+
+  '@changesets/get-dependents-graph@2.1.4':
+    resolution: {integrity: sha512-ZsS00x6WvmHq3sQv8oCMwL0f/z3wbXCVuSVTJwCnnmbC/iBdNJGFx1EcbMG4PC6sXRyH69liM4A2WKXzn/kRPg==}
+
+  '@changesets/get-release-plan@4.0.16':
+    resolution: {integrity: sha512-2K5Om6CrMPm45rtvckfzWo7e9jOVCKLCnXia5eUPaURH7/LWzri7pK1TycdzAuAtehLkW7VPbWLCSExTHmiI6g==}
+
+  '@changesets/get-version-range-type@0.4.0':
+    resolution: {integrity: sha512-hwawtob9DryoGTpixy1D3ZXbGgJu1Rhr+ySH2PvTLHvkZuQ7sRT4oQwMh0hbqZH1weAooedEjRsbrWcGLCeyVQ==}
+
+  '@changesets/git@3.0.4':
+    resolution: {integrity: sha512-BXANzRFkX+XcC1q/d27NKvlJ1yf7PSAgi8JG6dt8EfbHFHi4neau7mufcSca5zRhwOL8j9s6EqsxmT+s+/E6Sw==}
+
+  '@changesets/logger@0.1.1':
+    resolution: {integrity: sha512-OQtR36ZlnuTxKqoW4Sv6x5YIhOmClRd5pWsjZsddYxpWs517R0HkyiefQPIytCVh4ZcC5x9XaG8KTdd5iRQUfg==}
+
+  '@changesets/parse@0.4.3':
+    resolution: {integrity: sha512-ZDmNc53+dXdWEv7fqIUSgRQOLYoUom5Z40gmLgmATmYR9NbL6FJJHwakcCpzaeCy+1D0m0n7mT4jj2B/MQPl7A==}
+
+  '@changesets/pre@2.0.2':
+    resolution: {integrity: sha512-HaL/gEyFVvkf9KFg6484wR9s0qjAXlZ8qWPDkTyKF6+zqjBe/I2mygg3MbpZ++hdi0ToqNUF8cjj7fBy0dg8Ug==}
+
+  '@changesets/read@0.6.7':
+    resolution: {integrity: sha512-D1G4AUYGrBEk8vj8MGwf75k9GpN6XL3wg8i42P2jZZwFLXnlr2Pn7r9yuQNbaMCarP7ZQWNJbV6XLeysAIMhTA==}
+
+  '@changesets/should-skip-package@0.1.2':
+    resolution: {integrity: sha512-qAK/WrqWLNCP22UDdBTMPH5f41elVDlsNyat180A33dWxuUDyNpg6fPi/FyTZwRriVjg0L8gnjJn2F9XAoF0qw==}
+
+  '@changesets/types@4.1.0':
+    resolution: {integrity: sha512-LDQvVDv5Kb50ny2s25Fhm3d9QSZimsoUGBsUioj6MC3qbMUCuC8GPIvk/M6IvXx3lYhAs0lwWUQLb+VIEUCECw==}
+
+  '@changesets/types@6.1.0':
+    resolution: {integrity: sha512-rKQcJ+o1nKNgeoYRHKOS07tAMNd3YSN0uHaJOZYjBAgxfV7TUE7JE+z4BzZdQwb5hKaYbayKN5KrYV7ODb2rAA==}
+
+  '@changesets/write@0.4.0':
+    resolution: {integrity: sha512-CdTLvIOPiCNuH71pyDu3rA+Q0n65cmAbXnwWH84rKGiFumFzkmHNT8KHTMEchcxN+Kl8I54xGUhJ7l3E7X396Q==}
+
   '@connectrpc/connect-web@2.0.0-rc.3':
     resolution: {integrity: sha512-w88P8Lsn5CCsA7MFRl2e6oLY4J/5toiNtJns/YJrlyQaWOy3RO8pDgkz+iIkG98RPMhj2thuBvsd3Cn4DKKCkw==}
     peerDependencies:
@@ -1171,6 +1229,15 @@ packages:
     peerDependencies:
       react: '>=16.0.0'
 
+  '@inquirer/external-editor@1.0.3':
+    resolution: {integrity: sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
   '@isaacs/cliui@9.0.0':
     resolution: {integrity: sha512-AokJm4tuBHillT+FpMtxQ60n8ObyXBatq7jD2/JA9dxbDDokKQm8KMht5ibGzLVU9IJDIKK4TPKgMHEYMn3lMg==}
     engines: {node: '>=18'}
@@ -1202,6 +1269,12 @@ packages:
     resolution: {integrity: sha512-9I2Zn6+NJLfaGoz9jN3lpwDgAYvfGeNYdbAIjJOqzs4Tpc+VU3Jqq4IofSUBKajiDS8k9fZIg18/z13mpk1bsA==}
     engines: {node: '>=8'}
 
+  '@manypkg/find-root@1.1.0':
+    resolution: {integrity: sha512-mki5uBvhHzO8kYYix/WRy2WX8S3B5wdVSc9D6KcU5lQNglP2yt58/VfLuAK49glRXChosY8ap2oJ1qgma3GUVA==}
+
+  '@manypkg/get-packages@1.1.3':
+    resolution: {integrity: sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==}
+
   '@modelcontextprotocol/sdk@1.29.0':
     resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==}
     engines: {node: '>=18'}
@@ -1906,6 +1979,9 @@ packages:
   '@types/estree@1.0.9':
     resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
 
+  '@types/node@12.20.55':
+    resolution: {integrity: sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==}
+
   '@types/node@18.19.130':
     resolution: {integrity: sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==}
 
@@ -2031,6 +2107,9 @@ packages:
   any-promise@1.3.0:
     resolution: {integrity: sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==}
 
+  argparse@1.0.10:
+    resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==}
+
   argparse@2.0.1:
     resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
 
@@ -2038,6 +2117,10 @@ packages:
     resolution: {integrity: sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==}
     engines: {node: '>=10'}
 
+  array-union@2.1.0:
+    resolution: {integrity: sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==}
+    engines: {node: '>=8'}
+
   asn1@0.2.6:
     resolution: {integrity: sha512-ix/FxPn0MDjeyJ7i/yoHGFt/EX6LyNbxSEhPPXODPL+KB0VPk86UYfL0lMdy+KCnv+fmvIzySwaK5COwqVbWTQ==}
 
@@ -2078,6 +2161,10 @@ packages:
   bcrypt-pbkdf@1.0.2:
     resolution: {integrity: sha512-qeFIXtP4MSoi6NLqO12WfqARWWuCKi2Rn/9hJLEmtB5yTNr9DqFWkJRCf2qShWzPeAMRnOgCrq0sg/KLv5ES9w==}
 
+  better-path-resolve@1.0.0:
+    resolution: {integrity: sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g==}
+    engines: {node: '>=4'}
+
   better-sqlite3@12.11.1:
     resolution: {integrity: sha512-dq9AtApgg5PGFtBzPFSBl3HZQjHok5gaQCM6zh2Yk0aSmDCs1CbnVI8/HgASQkNKsWFpseIO9beg5xxpYhbIfA==}
     engines: {node: 20.x || 22.x || 23.x || 24.x || 25.x || 26.x}
@@ -2156,6 +2243,9 @@ packages:
     resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
     engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
 
+  chardet@2.2.0:
+    resolution: {integrity: sha512-rddelWYNPRrXq6PtNEN2S3f6t9ILzvqaN5pVgi4kqt9jHQaXIial9PznB5iSPVlQSLNaaH22ItWz3EJtQ10+OA==}
+
   chokidar@4.0.3:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
@@ -2398,6 +2488,10 @@ packages:
     resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
     engines: {node: '>=6'}
 
+  detect-indent@6.1.0:
+    resolution: {integrity: sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA==}
+    engines: {node: '>=8'}
+
   detect-libc@2.1.2:
     resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
     engines: {node: '>=8'}
@@ -2409,6 +2503,10 @@ packages:
     resolution: {integrity: sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==}
     engines: {node: '>=0.3.1'}
 
+  dir-glob@3.0.1:
+    resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==}
+    engines: {node: '>=8'}
+
   docker-modem@5.0.7:
     resolution: {integrity: sha512-XJgGhoR/CLpqshm4d3L7rzH6t8NgDFUIIpztYlLHIApeJjMZKYJMz2zxPsYxnejq5h3ELYSw/RBsi3t5h7gNTA==}
     engines: {node: '>= 8.0'}
@@ -2673,6 +2771,9 @@ packages:
     resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
     engines: {node: '>= 18'}
 
+  extendable-error@0.1.7:
+    resolution: {integrity: sha512-UOiS2in6/Q0FK0R0q6UY9vYpQ21mr/Qn1KOnte7vsACuNJf514WvCCUHSRCPcgjPT2bAhNIJdlE6bVap1GKmeg==}
+
   fast-decode-uri-component@1.0.1:
     resolution: {integrity: sha512-WKgKWg5eUxvRZGwW8FvfbaH7AXSh2cL+3j5fMGzUMCxWBJ3dV3a7Wz8y2f/uQ0e3B6WmodD3oS54jTQ9HVTIIg==}
 
@@ -2741,6 +2842,10 @@ packages:
     resolution: {integrity: sha512-1yD6RmLI1XBfxugvORwlck6f75tYL+iR0jqwsOrOxMZyGYqUuDhJ0l4AXdO1iX/FTs9cBAMEk1gWSEx1kSbylg==}
     engines: {node: '>=6'}
 
+  find-up@4.1.0:
+    resolution: {integrity: sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==}
+    engines: {node: '>=8'}
+
   fix-dts-default-cjs-exports@1.0.1:
     resolution: {integrity: sha512-pVIECanWFC61Hzl2+oOCtoJ3F17kglZC/6N94eRWycFgBH35hHx0Li604ZIzhseh97mf2p0cv7vVrOZGoqhlEg==}
 
@@ -2763,6 +2868,14 @@ packages:
     resolution: {integrity: sha512-w8ZNZr2mKIc7qeNaQ9AVPT1+iFaI+Avd4xudVOvdDJ8VytREi1Ft5Ih7hd9jjehod8vAM5GMsfQ/TpPf4EyoEA==}
     engines: {node: '>=14.14'}
 
+  fs-extra@7.0.1:
+    resolution: {integrity: sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==}
+    engines: {node: '>=6 <7 || >=8'}
+
+  fs-extra@8.1.0:
+    resolution: {integrity: sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==}
+    engines: {node: '>=6 <7 || >=8'}
+
   fsevents@2.3.3:
     resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
     engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
@@ -2829,6 +2942,10 @@ packages:
     resolution: {integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==}
     engines: {node: 18 || 20 || >=22}
 
+  globby@11.1.0:
+    resolution: {integrity: sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==}
+    engines: {node: '>=10'}
+
   gopd@1.2.0:
     resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==}
     engines: {node: '>= 0.4'}
@@ -2852,6 +2969,10 @@ packages:
     resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
     engines: {node: '>= 0.8'}
 
+  human-id@4.2.0:
+    resolution: {integrity: sha512-K3GbkIWqyvvlpfhBPlbEvD97TtqBpAYA4kt+cn2lD2x2HuohzZCibcA2nOlnJT6exqvJLggoB5nv2dNf192nEA==}
+    hasBin: true
+
   human-signals@2.1.0:
     resolution: {integrity: sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw==}
     engines: {node: '>=10.17.0'}
@@ -2978,6 +3099,10 @@ packages:
     resolution: {integrity: sha512-Dnz92NInDqYckGEUJv689RbRiTSEHCQ7wOVeALbkOz999YpqT46yMRIGtSNl2iCL1waAZSx40+h59NV/EwzV/A==}
     engines: {node: '>=18'}
 
+  is-subdir@1.2.0:
+    resolution: {integrity: sha512-2AT6j+gXe/1ueqbW6fLZJiIw3F8iXGJtt0yDrZaBhAZEG1raiTxKWU+IPqMCzQAXOUCKdA4UDMgacKH25XG2Cw==}
+    engines: {node: '>=4'}
+
   is-unicode-supported@1.3.0:
     resolution: {integrity: sha512-43r2mRvz+8JRIKnWJ+3j8JtjRKZ6GmjzfaE/qiBJnikNnYv/6bagRJ1kUhNk8R5EX/GkobD+r+sfxCPJsiKBLQ==}
     engines: {node: '>=12'}
@@ -2986,6 +3111,10 @@ packages:
     resolution: {integrity: sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ==}
     engines: {node: '>=18'}
 
+  is-windows@1.0.2:
+    resolution: {integrity: sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA==}
+    engines: {node: '>=0.10.0'}
+
   is-wsl@2.2.0:
     resolution: {integrity: sha512-fKzAra0rGJUUBwGBgNkHZuToZcn+TtXHpeCgmkMJMMYx1sQDYaCSyjJBSCa2nH1DGm7s3n1oBnohoVTBaN7Lww==}
     engines: {node: '>=8'}
@@ -3023,6 +3152,10 @@ packages:
   js-tokens@4.0.0:
     resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
 
+  js-yaml@3.15.0:
+    resolution: {integrity: sha512-ttBQIIQPDeLjpPOohtUdXuXUVoA2uIB6fEH9HyJ7234s5mBJ5wTx20njxplLZQgLaOfpmPQA7X2t5AX6tIPbog==}
+    hasBin: true
+
   js-yaml@4.3.0:
     resolution: {integrity: sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==}
     hasBin: true
@@ -3056,6 +3189,9 @@ packages:
     engines: {node: '>=6'}
     hasBin: true
 
+  jsonfile@4.0.0:
+    resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==}
+
   jsonfile@6.2.1:
     resolution: {integrity: sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==}
 
@@ -3159,9 +3295,16 @@ packages:
     resolution: {integrity: sha512-7AO748wWnIhNqAuaty2ZWHkQHRSNfPVIsPIfwEOWO22AmaoVrWavlOcMR5nzTLNYvp36X220/maaRsrec1G65A==}
     engines: {node: '>=6'}
 
+  locate-path@5.0.0:
+    resolution: {integrity: sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==}
+    engines: {node: '>=8'}
+
   lodash.camelcase@4.3.0:
     resolution: {integrity: sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==}
 
+  lodash.startcase@4.4.0:
+    resolution: {integrity: sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg==}
+
   log-symbols@6.0.0:
     resolution: {integrity: sha512-i24m8rpwhmPIS4zscNzK6MSEhk0DUWa/8iYQWxhffV8jkI4Phvs3F+quL5xvS0gdQR0FyTCMMH33Y78dDTzzIw==}
     engines: {node: '>=18'}
@@ -3252,6 +3395,10 @@ packages:
   mlly@1.8.2:
     resolution: {integrity: sha512-d+ObxMQFmbt10sretNDytwt85VrbkhhUA/JBGm1MPaWJ65Cl4wOgLaB1NYvJSZ0Ef03MMEU/0xpPMXUIQ29UfA==}
 
+  mri@1.2.0:
+    resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==}
+    engines: {node: '>=4'}
+
   ms@2.1.3:
     resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
 
@@ -3351,6 +3498,13 @@ packages:
     resolution: {integrity: sha512-weP+BZ8MVNnlCm8c0Qdc1WSWq4Qn7I+9CJGm7Qali6g44e/PUzbjNqJX5NJ9ljlNMosfJvg1fKEGILklK9cwnw==}
     engines: {node: '>=18'}
 
+  outdent@0.5.0:
+    resolution: {integrity: sha512-/jHxFIzoMXdqPzTaCpFzAAWhpkSjZPF4Vsn6jAfNpmbH/ymsmd7Qc6VE9BGn0L6YMj6uwpQLxCECpus4ukKS9Q==}
+
+  p-filter@2.1.0:
+    resolution: {integrity: sha512-ZBxxZ5sL2HghephhpGAQdoskxplTwr7ICaehZwLIlfL6acuVgZPm8yBNuRAFBGEqtD/hmUeq9eqLg2ys9Xr/yw==}
+    engines: {node: '>=8'}
+
   p-limit@2.3.0:
     resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==}
     engines: {node: '>=6'}
@@ -3359,6 +3513,14 @@ packages:
     resolution: {integrity: sha512-x+12w/To+4GFfgJhBEpiDcLozRJGegY+Ei7/z0tSLkMmxGZNybVMSfWj9aJn8Z5Fc7dBUNJOOVgPv2H7IwulSQ==}
     engines: {node: '>=6'}
 
+  p-locate@4.1.0:
+    resolution: {integrity: sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==}
+    engines: {node: '>=8'}
+
+  p-map@2.1.0:
+    resolution: {integrity: sha512-y3b8Kpd8OAN444hxfBbFfj1FY/RjtTd8tzYwhUqNYXx0fXx2iX4maP4Qr6qhIKbQXI02wTLAda4fYUbDagTUFw==}
+    engines: {node: '>=6'}
+
   p-try@2.2.0:
     resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==}
     engines: {node: '>=6'}
@@ -3366,6 +3528,9 @@ packages:
   package-json-from-dist@1.0.1:
     resolution: {integrity: sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==}
 
+  package-manager-detector@0.2.11:
+    resolution: {integrity: sha512-BEnLolu+yuz22S56CU1SUKq3XC3PkwD5wv4ikR4MfGvnRVcmzXR9DwSlW2fEamyTPyXHomBJRzgapeuBvRNzJQ==}
+
   parent-module@1.0.1:
     resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
     engines: {node: '>=6'}
@@ -3389,6 +3554,10 @@ packages:
     resolution: {integrity: sha512-bpC7GYwiDYQ4wYLe+FA8lhRjhQCMcQGuSgGGqDkg/QerRWw9CmGRT0iSOVRSZJ29NMLZgIzqaljJ63oaL4NIJQ==}
     engines: {node: '>=4'}
 
+  path-exists@4.0.0:
+    resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
+    engines: {node: '>=8'}
+
   path-key@3.1.1:
     resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==}
     engines: {node: '>=8'}
@@ -3404,6 +3573,10 @@ packages:
   path-to-regexp@8.4.2:
     resolution: {integrity: sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==}
 
+  path-type@4.0.0:
+    resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==}
+    engines: {node: '>=8'}
+
   pathe@2.0.3:
     resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
 
@@ -3418,6 +3591,10 @@ packages:
     resolution: {integrity: sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==}
     engines: {node: '>=12'}
 
+  pify@4.0.1:
+    resolution: {integrity: sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==}
+    engines: {node: '>=6'}
+
   pino-abstract-transport@3.0.0:
     resolution: {integrity: sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg==}
 
@@ -3482,6 +3659,11 @@ packages:
     deprecated: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
     hasBin: true
 
+  prettier@2.8.8:
+    resolution: {integrity: sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==}
+    engines: {node: '>=10.13.0'}
+    hasBin: true
+
   prettier@3.9.4:
     resolution: {integrity: sha512-yWG/o/4oJfo036EKAfK6ACAoDOfHeRHx4tuxkfBZiauURiaSmYwlpOr5LQqKtIkRD2z1PLteme2WoxEnj4tHTg==}
     engines: {node: '>=14'}
@@ -3516,6 +3698,9 @@ packages:
     resolution: {integrity: sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==}
     engines: {node: '>=0.6'}
 
+  quansync@0.2.11:
+    resolution: {integrity: sha512-AifT7QEbW9Nri4tAwR5M/uzpBuqfZf+zwaEM/QkzEjj7NBuFD2rBuy0K3dE+8wltbezDV7JMA0WfnCPYRSYbXA==}
+
   queue-microtask@1.2.3:
     resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
 
@@ -3604,6 +3789,10 @@ packages:
     resolution: {integrity: sha512-HNe9WslTbXmFK8o8cmwgAeJFSBvt1bPdHCVKtaaV+WlAN36mpT4hcRpwbf3fY56ar2oIXzsBpOAiIRHAdY0OlQ==}
     engines: {node: '>=0.10.0'}
 
+  read-yaml-file@1.1.0:
+    resolution: {integrity: sha512-VIMnQi/Z4HT2Fxuwg5KrY174U1VdUIASQVWXXyqtNRtxSr9IYkn1rsI6Tb6HsrHCmB7gVpNwX6JxPTHcH6IoTA==}
+    engines: {node: '>=6'}
+
   readable-stream@3.6.2:
     resolution: {integrity: sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==}
     engines: {node: '>= 6'}
@@ -3805,6 +3994,10 @@ packages:
   sisteransi@1.0.5:
     resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
 
+  slash@3.0.0:
+    resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==}
+    engines: {node: '>=8'}
+
   sonic-boom@4.2.1:
     resolution: {integrity: sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q==}
 
@@ -3829,6 +4022,9 @@ packages:
     resolution: {integrity: sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==}
     engines: {node: '>= 12'}
 
+  spawndamnit@3.0.1:
+    resolution: {integrity: sha512-MmnduQUuHCoFckZoWnXsTg7JaiLBJrKFj9UI2MbRPGaJeVpsLcVBu6P/IGZovziM/YBsellCmsprgNA+w0CzVg==}
+
   split-ca@1.0.1:
     resolution: {integrity: sha512-Q5thBSxp5t8WPTTJQS59LrGqOZqOsrhDGDVm8azCqIBjSBd7nd9o2PM+mDulQQkh8h//4U6hFZnc/mul8t5pWQ==}
 
@@ -3836,6 +4032,9 @@ packages:
     resolution: {integrity: sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==}
     engines: {node: '>= 10.x'}
 
+  sprintf-js@1.0.3:
+    resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==}
+
   ssh2@1.17.0:
     resolution: {integrity: sha512-wPldCk3asibAjQ/kziWQQt1Wh3PgDFpC0XpwclzKcdT1vql6KeYxf5LIt4nlFkUeR8WuphYMKqUA56X4rjbfgQ==}
     engines: {node: '>=10.16.0'}
@@ -3925,6 +4124,10 @@ packages:
     resolution: {integrity: sha512-4LeEWl96twnS2Q7Bz4MGqgazLqO+hJN63GZxXoIqh1T3VweYD997gbU1ItNsQafqqXTXd5WFyFdReLtwvRBNiw==}
     engines: {node: '>=18'}
 
+  term-size@2.2.1:
+    resolution: {integrity: sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg==}
+    engines: {node: '>=8'}
+
   thenify-all@1.6.0:
     resolution: {integrity: sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==}
     engines: {node: '>=0.8'}
@@ -4049,6 +4252,10 @@ packages:
     resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
     engines: {node: '>=18'}
 
+  universalify@0.1.2:
+    resolution: {integrity: sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==}
+    engines: {node: '>= 4.0.0'}
+
   universalify@2.0.1:
     resolution: {integrity: sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==}
     engines: {node: '>= 10.0.0'}
@@ -4551,6 +4758,149 @@ snapshots:
 
   '@bufbuild/protobuf@2.12.1': {}
 
+  '@changesets/apply-release-plan@7.1.1':
+    dependencies:
+      '@changesets/config': 3.1.4
+      '@changesets/get-version-range-type': 0.4.0
+      '@changesets/git': 3.0.4
+      '@changesets/should-skip-package': 0.1.2
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+      detect-indent: 6.1.0
+      fs-extra: 7.0.1
+      lodash.startcase: 4.4.0
+      outdent: 0.5.0
+      prettier: 2.8.8
+      resolve-from: 5.0.0
+      semver: 7.8.5
+
+  '@changesets/assemble-release-plan@6.0.10':
+    dependencies:
+      '@changesets/errors': 0.2.0
+      '@changesets/get-dependents-graph': 2.1.4
+      '@changesets/should-skip-package': 0.1.2
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+      semver: 7.8.5
+
+  '@changesets/changelog-git@0.2.1':
+    dependencies:
+      '@changesets/types': 6.1.0
+
+  '@changesets/cli@2.31.0(@types/node@26.1.0)':
+    dependencies:
+      '@changesets/apply-release-plan': 7.1.1
+      '@changesets/assemble-release-plan': 6.0.10
+      '@changesets/changelog-git': 0.2.1
+      '@changesets/config': 3.1.4
+      '@changesets/errors': 0.2.0
+      '@changesets/get-dependents-graph': 2.1.4
+      '@changesets/get-release-plan': 4.0.16
+      '@changesets/git': 3.0.4
+      '@changesets/logger': 0.1.1
+      '@changesets/pre': 2.0.2
+      '@changesets/read': 0.6.7
+      '@changesets/should-skip-package': 0.1.2
+      '@changesets/types': 6.1.0
+      '@changesets/write': 0.4.0
+      '@inquirer/external-editor': 1.0.3(@types/node@26.1.0)
+      '@manypkg/get-packages': 1.1.3
+      ansi-colors: 4.1.3
+      enquirer: 2.4.1
+      fs-extra: 7.0.1
+      mri: 1.2.0
+      package-manager-detector: 0.2.11
+      picocolors: 1.1.1
+      resolve-from: 5.0.0
+      semver: 7.8.5
+      spawndamnit: 3.0.1
+      term-size: 2.2.1
+    transitivePeerDependencies:
+      - '@types/node'
+
+  '@changesets/config@3.1.4':
+    dependencies:
+      '@changesets/errors': 0.2.0
+      '@changesets/get-dependents-graph': 2.1.4
+      '@changesets/logger': 0.1.1
+      '@changesets/should-skip-package': 0.1.2
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+      fs-extra: 7.0.1
+      micromatch: 4.0.8
+
+  '@changesets/errors@0.2.0':
+    dependencies:
+      extendable-error: 0.1.7
+
+  '@changesets/get-dependents-graph@2.1.4':
+    dependencies:
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+      picocolors: 1.1.1
+      semver: 7.8.5
+
+  '@changesets/get-release-plan@4.0.16':
+    dependencies:
+      '@changesets/assemble-release-plan': 6.0.10
+      '@changesets/config': 3.1.4
+      '@changesets/pre': 2.0.2
+      '@changesets/read': 0.6.7
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+
+  '@changesets/get-version-range-type@0.4.0': {}
+
+  '@changesets/git@3.0.4':
+    dependencies:
+      '@changesets/errors': 0.2.0
+      '@manypkg/get-packages': 1.1.3
+      is-subdir: 1.2.0
+      micromatch: 4.0.8
+      spawndamnit: 3.0.1
+
+  '@changesets/logger@0.1.1':
+    dependencies:
+      picocolors: 1.1.1
+
+  '@changesets/parse@0.4.3':
+    dependencies:
+      '@changesets/types': 6.1.0
+      js-yaml: 4.3.0
+
+  '@changesets/pre@2.0.2':
+    dependencies:
+      '@changesets/errors': 0.2.0
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+      fs-extra: 7.0.1
+
+  '@changesets/read@0.6.7':
+    dependencies:
+      '@changesets/git': 3.0.4
+      '@changesets/logger': 0.1.1
+      '@changesets/parse': 0.4.3
+      '@changesets/types': 6.1.0
+      fs-extra: 7.0.1
+      p-filter: 2.1.0
+      picocolors: 1.1.1
+
+  '@changesets/should-skip-package@0.1.2':
+    dependencies:
+      '@changesets/types': 6.1.0
+      '@manypkg/get-packages': 1.1.3
+
+  '@changesets/types@4.1.0': {}
+
+  '@changesets/types@6.1.0': {}
+
+  '@changesets/write@0.4.0':
+    dependencies:
+      '@changesets/types': 6.1.0
+      fs-extra: 7.0.1
+      human-id: 4.2.0
+      prettier: 2.8.8
+
   '@connectrpc/connect-web@2.0.0-rc.3(@bufbuild/protobuf@2.12.1)(@connectrpc/connect@2.0.0-rc.3(@bufbuild/protobuf@2.12.1))':
     dependencies:
       '@bufbuild/protobuf': 2.12.1
@@ -5028,6 +5378,13 @@ snapshots:
     dependencies:
       react: 19.2.7
 
+  '@inquirer/external-editor@1.0.3(@types/node@26.1.0)':
+    dependencies:
+      chardet: 2.2.0
+      iconv-lite: 0.7.3
+    optionalDependencies:
+      '@types/node': 26.1.0
+
   '@isaacs/cliui@9.0.0': {}
 
   '@isaacs/fs-minipass@4.0.1':
@@ -5057,6 +5414,22 @@ snapshots:
 
   '@lukeed/ms@2.0.2': {}
 
+  '@manypkg/find-root@1.1.0':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@types/node': 12.20.55
+      find-up: 4.1.0
+      fs-extra: 8.1.0
+
+  '@manypkg/get-packages@1.1.3':
+    dependencies:
+      '@babel/runtime': 7.29.7
+      '@changesets/types': 4.1.0
+      '@manypkg/find-root': 1.1.0
+      fs-extra: 8.1.0
+      globby: 11.1.0
+      read-yaml-file: 1.1.0
+
   '@modelcontextprotocol/sdk@1.29.0(zod@3.25.76)':
     dependencies:
       '@hono/node-server': 1.19.14(hono@4.12.28)
@@ -5621,6 +5994,8 @@ snapshots:
 
   '@types/estree@1.0.9': {}
 
+  '@types/node@12.20.55': {}
+
   '@types/node@18.19.130':
     dependencies:
       undici-types: 5.26.5
@@ -5733,12 +6108,18 @@ snapshots:
 
   any-promise@1.3.0: {}
 
+  argparse@1.0.10:
+    dependencies:
+      sprintf-js: 1.0.3
+
   argparse@2.0.1: {}
 
   aria-hidden@1.2.6:
     dependencies:
       tslib: 2.8.1
 
+  array-union@2.1.0: {}
+
   asn1@0.2.6:
     dependencies:
       safer-buffer: 2.1.2
@@ -5777,6 +6158,10 @@ snapshots:
     dependencies:
       tweetnacl: 0.14.5
 
+  better-path-resolve@1.0.0:
+    dependencies:
+      is-windows: 1.0.2
+
   better-sqlite3@12.11.1:
     dependencies:
       bindings: 1.5.0
@@ -5863,6 +6248,8 @@ snapshots:
 
   chalk@5.6.2: {}
 
+  chardet@2.2.0: {}
+
   chokidar@4.0.3:
     dependencies:
       readdirp: 4.1.2
@@ -6059,12 +6446,18 @@ snapshots:
 
   dequal@2.0.3: {}
 
+  detect-indent@6.1.0: {}
+
   detect-libc@2.1.2: {}
 
   detect-node-es@1.1.0: {}
 
   diff@8.0.4: {}
 
+  dir-glob@3.0.1:
+    dependencies:
+      path-type: 4.0.0
+
   docker-modem@5.0.7:
     dependencies:
       debug: 4.4.3
@@ -6383,6 +6776,8 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  extendable-error@0.1.7: {}
+
   fast-decode-uri-component@1.0.1: {}
 
   fast-deep-equal@3.1.3: {}
@@ -6477,6 +6872,11 @@ snapshots:
     dependencies:
       locate-path: 3.0.0
 
+  find-up@4.1.0:
+    dependencies:
+      locate-path: 5.0.0
+      path-exists: 4.0.0
+
   fix-dts-default-cjs-exports@1.0.1:
     dependencies:
       magic-string: 0.30.21
@@ -6500,6 +6900,18 @@ snapshots:
       jsonfile: 6.2.1
       universalify: 2.0.1
 
+  fs-extra@7.0.1:
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 4.0.0
+      universalify: 0.1.2
+
+  fs-extra@8.1.0:
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 4.0.0
+      universalify: 0.1.2
+
   fsevents@2.3.3:
     optional: true
 
@@ -6567,6 +6979,15 @@ snapshots:
       minipass: 7.1.3
       path-scurry: 2.0.2
 
+  globby@11.1.0:
+    dependencies:
+      array-union: 2.1.0
+      dir-glob: 3.0.1
+      fast-glob: 3.3.3
+      ignore: 5.3.2
+      merge2: 1.4.1
+      slash: 3.0.0
+
   gopd@1.2.0: {}
 
   graceful-fs@4.2.11: {}
@@ -6587,6 +7008,8 @@ snapshots:
       statuses: 2.0.2
       toidentifier: 1.0.1
 
+  human-id@4.2.0: {}
+
   human-signals@2.1.0: {}
 
   human-signals@8.0.1: {}
@@ -6663,10 +7086,16 @@ snapshots:
 
   is-stream@4.0.1: {}
 
+  is-subdir@1.2.0:
+    dependencies:
+      better-path-resolve: 1.0.0
+
   is-unicode-supported@1.3.0: {}
 
   is-unicode-supported@2.1.0: {}
 
+  is-windows@1.0.2: {}
+
   is-wsl@2.2.0:
     dependencies:
       is-docker: 2.2.1
@@ -6693,6 +7122,11 @@ snapshots:
 
   js-tokens@4.0.0: {}
 
+  js-yaml@3.15.0:
+    dependencies:
+      argparse: 1.0.10
+      esprima: 4.0.1
+
   js-yaml@4.3.0:
     dependencies:
       argparse: 2.0.1
@@ -6721,6 +7155,10 @@ snapshots:
 
   json5@2.2.3: {}
 
+  jsonfile@4.0.0:
+    optionalDependencies:
+      graceful-fs: 4.2.11
+
   jsonfile@6.2.1:
     dependencies:
       universalify: 2.0.1
@@ -6797,8 +7235,14 @@ snapshots:
       p-locate: 3.0.0
       path-exists: 3.0.0
 
+  locate-path@5.0.0:
+    dependencies:
+      p-locate: 4.1.0
+
   lodash.camelcase@4.3.0: {}
 
+  lodash.startcase@4.4.0: {}
+
   log-symbols@6.0.0:
     dependencies:
       chalk: 5.6.2
@@ -6868,6 +7312,8 @@ snapshots:
       pkg-types: 1.3.1
       ufo: 1.6.4
 
+  mri@1.2.0: {}
+
   ms@2.1.3: {}
 
   mz@2.7.0:
@@ -6966,6 +7412,12 @@ snapshots:
       string-width: 7.2.0
       strip-ansi: 7.2.0
 
+  outdent@0.5.0: {}
+
+  p-filter@2.1.0:
+    dependencies:
+      p-map: 2.1.0
+
   p-limit@2.3.0:
     dependencies:
       p-try: 2.2.0
@@ -6974,10 +7426,20 @@ snapshots:
     dependencies:
       p-limit: 2.3.0
 
+  p-locate@4.1.0:
+    dependencies:
+      p-limit: 2.3.0
+
+  p-map@2.1.0: {}
+
   p-try@2.2.0: {}
 
   package-json-from-dist@1.0.1: {}
 
+  package-manager-detector@0.2.11:
+    dependencies:
+      quansync: 0.2.11
+
   parent-module@1.0.1:
     dependencies:
       callsites: 3.1.0
@@ -6997,6 +7459,8 @@ snapshots:
 
   path-exists@3.0.0: {}
 
+  path-exists@4.0.0: {}
+
   path-key@3.1.1: {}
 
   path-key@4.0.0: {}
@@ -7008,6 +7472,8 @@ snapshots:
 
   path-to-regexp@8.4.2: {}
 
+  path-type@4.0.0: {}
+
   pathe@2.0.3: {}
 
   picocolors@1.1.1: {}
@@ -7016,6 +7482,8 @@ snapshots:
 
   picomatch@4.0.5: {}
 
+  pify@4.0.1: {}
+
   pino-abstract-transport@3.0.0:
     dependencies:
       split2: 4.2.0
@@ -7089,6 +7557,8 @@ snapshots:
       tar-fs: 2.1.5
       tunnel-agent: 0.6.0
 
+  prettier@2.8.8: {}
+
   prettier@3.9.4: {}
 
   pretty-ms@9.3.0:
@@ -7133,6 +7603,8 @@ snapshots:
       es-define-property: 1.0.1
       side-channel: 1.1.1
 
+  quansync@0.2.11: {}
+
   queue-microtask@1.2.3: {}
 
   quick-format-unescaped@4.0.4: {}
@@ -7211,6 +7683,13 @@ snapshots:
 
   react@19.2.7: {}
 
+  read-yaml-file@1.1.0:
+    dependencies:
+      graceful-fs: 4.2.11
+      js-yaml: 3.15.0
+      pify: 4.0.1
+      strip-bom: 3.0.0
+
   readable-stream@3.6.2:
     dependencies:
       inherits: 2.0.4
@@ -7495,6 +7974,8 @@ snapshots:
 
   sisteransi@1.0.5: {}
 
+  slash@3.0.0: {}
+
   sonic-boom@4.2.1:
     dependencies:
       atomic-sleep: 1.0.0
@@ -7515,10 +7996,17 @@ snapshots:
 
   source-map@0.7.6: {}
 
+  spawndamnit@3.0.1:
+    dependencies:
+      cross-spawn: 7.0.6
+      signal-exit: 4.1.0
+
   split-ca@1.0.1: {}
 
   split2@4.2.0: {}
 
+  sprintf-js@1.0.3: {}
+
   ssh2@1.17.0:
     dependencies:
       asn1: 0.2.6
@@ -7614,6 +8102,8 @@ snapshots:
       minizlib: 3.1.0
       yallist: 5.0.0
 
+  term-size@2.2.1: {}
+
   thenify-all@1.6.0:
     dependencies:
       thenify: 3.3.1
@@ -7728,6 +8218,8 @@ snapshots:
 
   unicorn-magic@0.3.0: {}
 
+  universalify@0.1.2: {}
+
   universalify@2.0.1: {}
 
   unpipe@1.0.0: {}

From 735a78e19200edb6593ed440bc7260a92c02aa3a Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 18:15:33 +0800
Subject: [PATCH 033/133] The web console settles on one name: @dormice/console
 at /console
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

website/ (docs + landing) is on the roadmap and "web" was one letter
away from it; console is what the thing actually is. The directory
rename itself rode along with the publish commit's staging; this
completes the content side: routes (/console/auth/*, /console/envdToken),
the SPA base and router basepath, the session HMAC domain string
(console-session:), the monorepo dist hop in main.ts
(AppDeps.consoleDistDir), and biome's vendored-file exclusion paths.
No redirect from /ui — zero users is the one moment a wire name moves
for free.
---
 README.md                                     |  6 +--
 biome.json                                    | 10 ++---
 e2e/src/console.test.ts                       | 16 ++++----
 packages/console/package.json                 |  4 +-
 .../src/features/auth/pages/LoginPage.tsx     |  2 +-
 .../sandboxes/pages/SandboxesPage.tsx         |  2 +-
 packages/console/src/lib/api.ts               | 12 ++++--
 packages/console/src/main.tsx                 |  6 +--
 packages/console/vite.config.ts               | 14 ++++---
 packages/server/src/app.ts                    | 15 +++----
 packages/server/src/auth.ts                   |  2 +-
 packages/server/src/main.ts                   | 12 +++---
 packages/server/src/routes/console.test.ts    | 31 +++++++-------
 packages/server/src/routes/console.ts         | 41 +++++++++----------
 14 files changed, 92 insertions(+), 81 deletions(-)

diff --git a/README.md b/README.md
index 984d1ab..fe2a117 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,7 @@ re-run on its own at any time.
 
 ## Web console
 
-The daemon serves a small web console at `http://127.0.0.1:3676/ui` —
+The daemon serves a small web console at `http://127.0.0.1:3676/console` —
 sign in with the API token once and it becomes an httpOnly session cookie;
 the token itself is never stored anywhere the page can read. The console
 shows every sandbox with its live lifecycle state (the same
@@ -44,7 +44,7 @@ is a choice you make explicitly, one of two ways:
 
 - **SSH tunnel** (private, zero setup):
   `ssh -L 3676:127.0.0.1:3676 root@host`, then open
-  `http://127.0.0.1:3676/ui`.
+  `http://127.0.0.1:3676/console`.
 - **Reverse proxy** for the console, the API, and the E2B surface at once —
   e.g. Caddy, which also handles TLS certificates automatically once you
   give it a domain:
@@ -97,7 +97,7 @@ pnpm monorepo:
 | `packages/server` | The daemon: Fastify + SQLite ledger + lifecycle engine |
 | `packages/sdk` | `@dormice/sdk` — TypeScript client for the native API |
 | `packages/cli` | `dormice` command-line tool (`dor` for short) |
-| `packages/web` | Web console: React SPA, served by the daemon at `/ui` |
+| `packages/console` | Web console: React SPA, served by the daemon at `/console` |
 | `e2e` | Black-box suite: boots the built daemon, drives it over the wire |
 
 ## Development
diff --git a/biome.json b/biome.json
index 21514d9..43b7ae9 100644
--- a/biome.json
+++ b/biome.json
@@ -4,11 +4,11 @@
     "includes": [
       "**",
       "!packages/*/drizzle",
-      "!packages/web/src/components/ui",
-      "!packages/web/src/hooks/use-mobile.ts",
-      "!packages/web/src/lib/utils.ts",
-      "!packages/web/src/shadcn.css",
-      "!packages/web/src/routeTree.gen.ts"
+      "!packages/console/src/components/ui",
+      "!packages/console/src/hooks/use-mobile.ts",
+      "!packages/console/src/lib/utils.ts",
+      "!packages/console/src/shadcn.css",
+      "!packages/console/src/routeTree.gen.ts"
     ]
   },
   "vcs": {
diff --git a/e2e/src/console.test.ts b/e2e/src/console.test.ts
index f28a3ec..3ddbf3d 100644
--- a/e2e/src/console.test.ts
+++ b/e2e/src/console.test.ts
@@ -1,14 +1,14 @@
 import { describe, expect, inject, it } from 'vitest';
 
 // The web console, black-box: plain fetch against the built daemon, the
-// same requests a browser would make. The daemon serves packages/web/dist
+// same requests a browser would make. The daemon serves packages/console/dist
 // (pnpm build ran before this suite), so this also proves the monorepo
 // path hop in main.ts survives the dist layout.
 
 const endpoint = () => inject('dormiceEndpoint');
 
 async function loginCookie(token: string): Promise<string> {
-  const res = await fetch(`${endpoint()}/ui/auth/login`, {
+  const res = await fetch(`${endpoint()}/console/auth/login`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({ token }),
@@ -23,25 +23,25 @@ async function loginCookie(token: string): Promise<string> {
 }
 
 describe('web console over a real daemon', () => {
-  it('serves the built SPA at /ui/, with assets under /ui/', async () => {
-    const res = await fetch(`${endpoint()}/ui/`);
+  it('serves the built SPA at /console/, with assets under /console/', async () => {
+    const res = await fetch(`${endpoint()}/console/`);
     expect(res.status).toBe(200);
     expect(res.headers.get('content-type')).toContain('text/html');
     const html = await res.text();
     expect(html).toContain('<title>Dormice</title>');
     // The base path is baked in at build time — a bare /assets reference
-    // would 404 behind the daemon's /ui prefix.
-    expect(html).toContain('/ui/assets/');
+    // would 404 behind the daemon's /console prefix.
+    expect(html).toContain('/console/assets/');
   });
 
   it('falls back to the SPA for client-side routes', async () => {
-    const res = await fetch(`${endpoint()}/ui/login`);
+    const res = await fetch(`${endpoint()}/console/login`);
     expect(res.status).toBe(200);
     expect(await res.text()).toContain('<title>Dormice</title>');
   });
 
   it('rejects a login with the wrong token', async () => {
-    const res = await fetch(`${endpoint()}/ui/auth/login`, {
+    const res = await fetch(`${endpoint()}/console/auth/login`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({ token: 'w'.repeat(64) }),
diff --git a/packages/console/package.json b/packages/console/package.json
index 26320fa..3da3b17 100644
--- a/packages/console/package.json
+++ b/packages/console/package.json
@@ -1,7 +1,7 @@
 {
-  "name": "@dormice/web",
+  "name": "@dormice/console",
   "version": "0.0.0",
-  "description": "Dormice web console: static SPA served by the daemon at /ui",
+  "description": "Dormice web console: static SPA served by the daemon at /console",
   "license": "Apache-2.0",
   "private": true,
   "type": "module",
diff --git a/packages/console/src/features/auth/pages/LoginPage.tsx b/packages/console/src/features/auth/pages/LoginPage.tsx
index 6a509e2..0ff9200 100644
--- a/packages/console/src/features/auth/pages/LoginPage.tsx
+++ b/packages/console/src/features/auth/pages/LoginPage.tsx
@@ -28,7 +28,7 @@ export function LoginPage() {
     mutationFn: login,
     onSuccess: () => {
       setSessionMarker();
-      window.location.href = redirect ?? '/ui/';
+      window.location.href = redirect ?? '/console/';
     },
   });
 
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index 791862e..a77e7ca 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -31,7 +31,7 @@ async function signOut() {
   // matters is clearing the marker and starting over from the login page.
   await logout().catch(() => undefined);
   clearSessionMarker();
-  window.location.href = '/ui/login';
+  window.location.href = '/console/login';
 }
 
 export function SandboxesPage() {
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index e279efd..c45117b 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -29,7 +29,7 @@ function interceptUnauthorized(): void {
   if (!hasSessionMarker()) return;
   clearSessionMarker();
   const here = window.location.pathname + window.location.search;
-  window.location.href = `/ui/login?redirect=${encodeURIComponent(here)}`;
+  window.location.href = `/console/login?redirect=${encodeURIComponent(here)}`;
 }
 
 async function rpc<T>(
@@ -64,10 +64,14 @@ async function rpc<T>(
 // Login's own 401 means "wrong token", a form error to show in place — the
 // interceptor is for sessions dying mid-flight, not for failed sign-ins.
 export const login = (token: string) =>
-  rpc<{ loggedIn: true }>('/ui/auth/login', { token }, { intercept401: false });
+  rpc<{ loggedIn: true }>(
+    '/console/auth/login',
+    { token },
+    { intercept401: false },
+  );
 
 export const logout = () =>
-  rpc<{ loggedIn: false }>('/ui/auth/logout', {}, { intercept401: false });
+  rpc<{ loggedIn: false }>('/console/auth/logout', {}, { intercept401: false });
 
 export const listSandboxes = () =>
   rpc<{ sandboxes: Sandbox[] }>('/listSandboxes');
@@ -86,4 +90,4 @@ export const rebuildSandbox = (userKey: string) =>
 // The terminal's key: trades the session cookie for one sandbox's envd
 // access token, so the browser can speak to the envd surface directly.
 export const mintEnvdToken = (sandboxId: string) =>
-  rpc<{ envdAccessToken: string }>('/ui/envdToken', { sandboxId });
+  rpc<{ envdAccessToken: string }>('/console/envdToken', { sandboxId });
diff --git a/packages/console/src/main.tsx b/packages/console/src/main.tsx
index 3b612b7..e90dde0 100644
--- a/packages/console/src/main.tsx
+++ b/packages/console/src/main.tsx
@@ -7,9 +7,9 @@ import { queryClient } from '@/lib/queryClient';
 import { routeTree } from './routeTree.gen';
 import './index.css';
 
-// The daemon serves the console under /ui; the router lives there too so
-// server paths and client paths are the same strings everywhere.
-const router = createRouter({ routeTree, basepath: '/ui' });
+// The daemon serves the console under /console; the router lives there too
+// so server paths and client paths are the same strings everywhere.
+const router = createRouter({ routeTree, basepath: '/console' });
 
 declare module '@tanstack/react-router' {
   interface Register {
diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index 7b5fa05..3fbb09a 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -5,8 +5,9 @@ import react from '@vitejs/plugin-react';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
-  // The daemon serves the built console under /ui — assets must resolve there.
-  base: '/ui/',
+  // The daemon serves the built console under /console — assets must
+  // resolve there.
+  base: '/console/',
   plugins: [
     // Must come before react(): it generates routeTree.gen.ts from routes/.
     tanstackRouter({ target: 'react', autoCodeSplitting: true }),
@@ -17,11 +18,12 @@ export default defineConfig({
     alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
   },
   server: {
-    // Dev mode: Vite owns /ui, the daemon (fake executor is fine) owns the
-    // API — same paths the browser uses in production, so no API base knob.
+    // Dev mode: Vite owns /console, the daemon (fake executor is fine) owns
+    // the API — same paths the browser uses in production, so no API base
+    // knob.
     proxy: {
-      '/ui/auth': 'http://127.0.0.1:3676',
-      '/ui/envdToken': 'http://127.0.0.1:3676',
+      '/console/auth': 'http://127.0.0.1:3676',
+      '/console/envdToken': 'http://127.0.0.1:3676',
       '/listSandboxes': 'http://127.0.0.1:3676',
       '/releaseSandbox': 'http://127.0.0.1:3676',
       '/acquireSandbox': 'http://127.0.0.1:3676',
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index c6cac60..00a74eb 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -16,8 +16,8 @@ import { ProcessTable } from './e2b/process-table';
 import { WatcherTable } from './e2b/watcher-table';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
+import { consoleRoutes } from './routes/console';
 import { sandboxRoutes } from './routes/sandboxes';
-import { uiRoutes } from './routes/ui';
 import { createSandboxProxy } from './sandbox-proxy';
 
 export interface AppDeps {
@@ -38,9 +38,10 @@ export interface AppDeps {
   logger?: boolean | Logger;
   /**
    * Where the built web console lives; main.ts resolves the monorepo
-   * layout, tests inject a fixture. Absent means /ui answers an honest 404.
+   * layout, tests inject a fixture. Absent means /console answers an
+   * honest 404.
    */
-  webDistDir?: string;
+  consoleDistDir?: string;
 }
 
 /**
@@ -58,7 +59,7 @@ export function buildApp({
   executor,
   locks,
   logger = true,
-  webDistDir,
+  consoleDistDir,
 }: AppDeps) {
   // Always a pino instance (booleans are normalized into one): two fastify()
   // call shapes would give the instance two different types.
@@ -126,7 +127,7 @@ export function buildApp({
   );
 
   // Cookie parsing app-wide: the auth arbiter reads the console's session
-  // cookie on the native routes, the /ui surface mints and clears it.
+  // cookie on the native routes, the /console surface mints and clears it.
   app.register(fastifyCookie);
 
   app.register(async (api) => {
@@ -136,8 +137,8 @@ export function buildApp({
 
   // The web console: session endpoints (open — login carries the token
   // itself) and the static SPA. Its API calls go through the routes above.
-  app.register(async (ui) => {
-    await ui.register(uiRoutes, { config, webDistDir });
+  app.register(async (scope) => {
+    await scope.register(consoleRoutes, { config, consoleDistDir });
   });
 
   // The E2B compatibility surface lives beside the native API with its own
diff --git a/packages/server/src/auth.ts b/packages/server/src/auth.ts
index 8f5579d..dd47190 100644
--- a/packages/server/src/auth.ts
+++ b/packages/server/src/auth.ts
@@ -28,7 +28,7 @@ export const CONSOLE_HEADER = 'x-dormice-console';
 
 function sessionHmac(apiToken: string, expiresAtSeconds: number): string {
   return createHmac('sha256', apiToken)
-    .update(`ui-session:${expiresAtSeconds}`)
+    .update(`console-session:${expiresAtSeconds}`)
     .digest('hex');
 }
 
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 08c9bca..4cdcc3b 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -69,11 +69,13 @@ const locks = new KeyedQueue();
 
 // The web console ships beside the server in the monorepo; this file sits
 // one level under packages/server both as src/main.ts and as dist/main.js,
-// so the relative hop to packages/web/dist is the same either way. A
+// so the relative hop to packages/console/dist is the same either way. A
 // missing dist is loud but not fatal: the API works without the console.
-const webDistDir = fileURLToPath(new URL('../../web/dist', import.meta.url));
-if (!existsSync(webDistDir)) {
-  log.warn(`web console not found at ${webDistDir} — /ui disabled`);
+const consoleDistDir = fileURLToPath(
+  new URL('../../console/dist', import.meta.url),
+);
+if (!existsSync(consoleDistDir)) {
+  log.warn(`web console not found at ${consoleDistDir} — /console disabled`);
 }
 
 const app = buildApp({
@@ -82,7 +84,7 @@ const app = buildApp({
   executor,
   locks,
   logger: log,
-  webDistDir: existsSync(webDistDir) ? webDistDir : undefined,
+  consoleDistDir: existsSync(consoleDistDir) ? consoleDistDir : undefined,
 });
 
 // Before trusting the pairing of this ledger and this reality, check it:
diff --git a/packages/server/src/routes/console.test.ts b/packages/server/src/routes/console.test.ts
index b150c28..4fbe8a1 100644
--- a/packages/server/src/routes/console.test.ts
+++ b/packages/server/src/routes/console.test.ts
@@ -20,7 +20,7 @@ import { KeyedQueue } from '../keyed-queue';
 const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
 const TOKEN = 'test-token-test-token-test-token';
 
-function testApp(webDistDir?: string) {
+function testApp(consoleDistDir?: string) {
   const db = openDb(':memory:');
   migrateDb(db, MIGRATIONS);
   const config = loadConfig({
@@ -33,13 +33,13 @@ function testApp(webDistDir?: string) {
     executor: new FakeExecutor(),
     locks: new KeyedQueue(),
     logger: false,
-    webDistDir,
+    consoleDistDir,
   });
 }
 
 /** A minimal built console: an index.html and one hashed asset. */
 function fixtureDist(): string {
-  const dir = mkdtempSync(join(tmpdir(), 'dormice-webdist-'));
+  const dir = mkdtempSync(join(tmpdir(), 'dormice-consoledist-'));
   writeFileSync(join(dir, 'index.html'), '<html>dormice console</html>');
   mkdirSync(join(dir, 'assets'));
   writeFileSync(join(dir, 'assets', 'app-abc123.js'), 'console.log("ui")');
@@ -49,7 +49,7 @@ function fixtureDist(): string {
 async function login(app: ReturnType<typeof testApp>, token = TOKEN) {
   return app.inject({
     method: 'POST',
-    url: '/ui/auth/login',
+    url: '/console/auth/login',
     payload: { token },
   });
 }
@@ -87,7 +87,7 @@ describe('session mint/verify', () => {
   });
 });
 
-describe('POST /ui/auth/login', () => {
+describe('POST /console/auth/login', () => {
   it('rejects a wrong token without setting a cookie', async () => {
     const res = await login(testApp(), 'wrong-token-wrong-token-wrong-tk');
     expect(res.statusCode).toBe(401);
@@ -160,7 +160,7 @@ describe('cookie-authenticated API access', () => {
   });
 });
 
-describe('POST /ui/envdToken', () => {
+describe('POST /console/envdToken', () => {
   async function mint(
     app: ReturnType<typeof testApp>,
     cookieValue: string,
@@ -168,7 +168,7 @@ describe('POST /ui/envdToken', () => {
   ) {
     return app.inject({
       method: 'POST',
-      url: '/ui/envdToken',
+      url: '/console/envdToken',
       cookies: { [SESSION_COOKIE]: cookieValue },
       headers,
       payload: { sandboxId: 'sb-terminal' },
@@ -199,11 +199,11 @@ describe('POST /ui/envdToken', () => {
   });
 });
 
-describe('POST /ui/auth/logout', () => {
+describe('POST /console/auth/logout', () => {
   it('clears the session cookie', async () => {
     const res = await testApp().inject({
       method: 'POST',
-      url: '/ui/auth/logout',
+      url: '/console/auth/logout',
     });
     expect(res.statusCode).toBe(200);
     const cookie = sessionCookie(res);
@@ -211,28 +211,31 @@ describe('POST /ui/auth/logout', () => {
   });
 });
 
-describe('static console at /ui', () => {
+describe('static console at /console', () => {
   it('serves index.html and assets from the injected dist', async () => {
     const app = testApp(fixtureDist());
-    const index = await app.inject({ method: 'GET', url: '/ui/' });
+    const index = await app.inject({ method: 'GET', url: '/console/' });
     expect(index.statusCode).toBe(200);
     expect(index.body).toContain('dormice console');
     const asset = await app.inject({
       method: 'GET',
-      url: '/ui/assets/app-abc123.js',
+      url: '/console/assets/app-abc123.js',
     });
     expect(asset.statusCode).toBe(200);
   });
 
   it('falls back to index.html for client-side routes (SPA)', async () => {
     const app = testApp(fixtureDist());
-    const res = await app.inject({ method: 'GET', url: '/ui/sandboxes/deep' });
+    const res = await app.inject({
+      method: 'GET',
+      url: '/console/sandboxes/deep',
+    });
     expect(res.statusCode).toBe(200);
     expect(res.body).toContain('dormice console');
   });
 
   it('answers an honest 404 when the console is not built', async () => {
-    const res = await testApp().inject({ method: 'GET', url: '/ui' });
+    const res = await testApp().inject({ method: 'GET', url: '/console' });
     expect(res.statusCode).toBe(404);
     expect(res.json().message).toContain('pnpm build');
   });
diff --git a/packages/server/src/routes/console.ts b/packages/server/src/routes/console.ts
index de0c9f0..0fa0c86 100644
--- a/packages/server/src/routes/console.ts
+++ b/packages/server/src/routes/console.ts
@@ -11,14 +11,14 @@ import {
 import type { Config } from '../config';
 import { mintEnvdToken } from '../e2b/protocol';
 
-export interface UiRoutesOptions {
+export interface ConsoleRoutesOptions {
   config: Config;
   /**
-   * Where the built web console lives (packages/web/dist). Injected so
+   * Where the built web console lives (packages/console/dist). Injected so
    * tests point it at a fixture and embedders can omit it; absent means
-   * /ui answers an honest 404 instead of guessing at paths.
+   * /console answers an honest 404 instead of guessing at paths.
    */
-  webDistDir?: string;
+  consoleDistDir?: string;
 }
 
 // No Secure flag: the daemon speaks plain http on 127.0.0.1 by design, and
@@ -34,12 +34,11 @@ const COOKIE_OPTIONS = {
  * Everything else the console does goes through the native RPC routes with
  * the session cookie — same routes, same truth as the SDK and CLI.
  */
-export const uiRoutes: FastifyPluginAsyncZod<UiRoutesOptions> = async (
-  app,
-  { config, webDistDir },
-) => {
+export const consoleRoutes: FastifyPluginAsyncZod<
+  ConsoleRoutesOptions
+> = async (app, { config, consoleDistDir }) => {
   app.post(
-    '/ui/auth/login',
+    '/console/auth/login',
     {
       schema: {
         body: z.object({ token: z.string() }),
@@ -63,7 +62,7 @@ export const uiRoutes: FastifyPluginAsyncZod<UiRoutesOptions> = async (
   );
 
   app.post(
-    '/ui/auth/logout',
+    '/console/auth/logout',
     {
       schema: {
         response: { 200: z.object({ loggedIn: z.literal(false) }) },
@@ -83,7 +82,7 @@ export const uiRoutes: FastifyPluginAsyncZod<UiRoutesOptions> = async (
   // header. Minting is stateless on purpose (like the token itself): a
   // made-up sandboxId yields a token that opens nothing.
   app.post(
-    '/ui/envdToken',
+    '/console/envdToken',
     {
       onRequest: requireApiAuth(config.DORMICE_API_TOKEN),
       schema: {
@@ -101,14 +100,14 @@ export const uiRoutes: FastifyPluginAsyncZod<UiRoutesOptions> = async (
     }),
   );
 
-  if (webDistDir) {
+  if (consoleDistDir) {
     await app.register(
-      async (ui) => {
-        await ui.register(fastifyStatic, { root: webDistDir });
-        // SPA fallback: the router owns paths under /ui, so any GET that
-        // matches no file is a client-side route — serve the app and let
-        // it resolve. Everything else keeps the honest 404.
-        ui.setNotFoundHandler((request, reply) => {
+      async (scope) => {
+        await scope.register(fastifyStatic, { root: consoleDistDir });
+        // SPA fallback: the router owns paths under /console, so any GET
+        // that matches no file is a client-side route — serve the app and
+        // let it resolve. Everything else keeps the honest 404.
+        scope.setNotFoundHandler((request, reply) => {
           if (request.method === 'GET') {
             return reply.sendFile('index.html');
           }
@@ -117,13 +116,13 @@ export const uiRoutes: FastifyPluginAsyncZod<UiRoutesOptions> = async (
           });
         });
       },
-      { prefix: '/ui' },
+      { prefix: '/console' },
     );
   } else {
-    app.get('/ui', async (_request, reply) =>
+    app.get('/console', async (_request, reply) =>
       reply.code(404).send({
         message:
-          'web console not available: packages/web/dist was not found at startup — run `pnpm build` first',
+          'web console not available: packages/console/dist was not found at startup — run `pnpm build` first',
       }),
     );
   }

From b5d847829df12f0087664fe628e43a3ddd676984 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 18:52:11 +0800
Subject: [PATCH 034/133] README: quick start, the E2B matrix as actually
 tested, and when not to use it

---
 README.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 109 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index fe2a117..18303c1 100644
--- a/README.md
+++ b/README.md
@@ -9,9 +9,9 @@
 Cloud sandbox platforms charge for every second a sandbox exists, so their sandboxes are disposable. Dormice inverts that: you run it on a machine you already pay for, and sandboxes are **permanent** — they just get cheaper to keep the longer they sit idle.
 
 - **`acquireSandbox(userKey)` is the entire mental model.** Idempotent: the same key always comes back to the same sandbox, whatever state it was in. No sandbox → create; frozen → wake; stopped → start; archived → restore.
-- **Idle is free.** Sandboxes cool down on their own — `active → frozen → stopped → archived` — one rung at a time, and any acquire brings them back.
+- **Idle is free.** Sandboxes cool down on their own — `active → frozen → stopped → archived` — one rung at a time, and any acquire brings them back. Measured on real hardware: freezing takes an idle sandbox holding 1 GiB down to ~5 MiB of resident memory, and waking it takes ~50 ms.
 - **Deploys like a single binary.** One daemon, one SQLite ledger, one port. No Kubernetes, no external database.
-- **E2B compatible**: the official `e2b` SDK works against Dormice by changing two URLs (`apiUrl`, `sandboxUrl`).
+- **[E2B compatible](#e2b-compatibility)**: the official `e2b` SDK works against Dormice by changing two URLs.
 
 ## Install
 
@@ -24,9 +24,94 @@ curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/i
 Behind a slow connection to the usual sources, add `-s -- --mirror cn`.
 The installer is idempotent — re-running it upgrades the code and repairs
 drift, and never rotates your API token. It ends by running `dor doctor`,
-19 read-only checks (including three that boot a real gVisor container)
-that decide whether the install actually succeeded; `dor doctor` can be
-re-run on its own at any time.
+a battery of read-only checks — three of them boot a real gVisor
+container — that decides whether the install actually succeeded;
+`dor doctor` can be re-run on its own at any time.
+
+## Quick start
+
+`@dormice/sdk` is the native TypeScript client. (Not on npm yet — the
+first release is queued; inside this repo, `pnpm build` produces it.)
+
+```ts
+import { Dormice } from '@dormice/sdk';
+
+const client = new Dormice({
+  endpoint: 'http://127.0.0.1:3676',
+  token: process.env.DORMICE_API_TOKEN!,
+});
+
+// One key, one sandbox — created, woken or restarted as needed.
+// stopAfterSeconds: null makes it a resident agent: it may freeze when
+// idle (~50 ms to wake) but never cold-starts.
+await client.acquireSandbox('my-agent', { stopAfterSeconds: null });
+
+const result = await client.execCommand('my-agent', 'python3 -c "print(6 * 7)"');
+console.log(result.exitCode, result.stdout); // 0 42
+
+await client.writeFiles('my-agent', [
+  { path: 'notes.txt', content: 'survives freeze and stop' },
+]);
+
+await client.releaseSandbox('my-agent'); // destroy — the only verb that loses data
+```
+
+The wire is plain HTTP RPC (`POST /acquireSandbox`, `POST /execCommand`, …),
+so `curl` works where the SDK doesn't reach, and the `dor` CLI covers the
+operator side: `dor sandbox ls / exec / push / pull / rebuild / release`,
+plus `dor doctor`. The full native surface is documented in
+[`packages/sdk`](packages/sdk/README.md).
+
+## E2B compatibility
+
+The daemon speaks the E2B protocol on two prefixes (`/e2b/api`,
+`/e2b/envd`). The **official `e2b` package** — unmodified, straight from
+npm — runs against Dormice with two URLs and an API-key prefix; migrating
+an application is configuration, not code:
+
+```ts
+import { Sandbox } from 'e2b';
+
+const sbx = await Sandbox.create({
+  apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`,
+  apiUrl: 'http://127.0.0.1:3676/e2b/api',
+  sandboxUrl: 'http://127.0.0.1:3676/e2b/envd',
+});
+```
+
+Everything below is exercised by the black-box e2e suite *through the
+official package*, and has passed against a real Docker + gVisor daemon:
+
+| Surface | Notes |
+| --- | --- |
+| `Sandbox.create` / `connect` / `kill` / `list` | `list` filters by state and metadata, and paginates |
+| Timeouts | `timeoutMs` and `setTimeout()` are real absolute deadlines; `lifecycle: { onTimeout: 'pause' }` parks the sandbox instead of killing it |
+| `pause()` / resume | explicit pause; `connect` revives it, files intact |
+| `commands.run` | live streaming (`onStdout` / `onStderr`), background + `connect` / `disconnect`, `sendStdin`, `kill`, `list`, per-command `envs`, `user: 'root'`; a non-zero exit raises the SDK's own `CommandExitError` |
+| `pty.*` | `create` / `sendInput` / `resize` / `kill` — a real interactive bash |
+| `files` read / write | text or bytes, streamed, no artificial size cap — the disk quota is the cap |
+| `uploadUrl()` / `downloadUrl()` | signed URLs: expiry enforced, a tampered signature is a 401 |
+| `files.list` / `exists` / `makeDir` / `rename` / `remove` | typed errors match the SDK's expectations |
+| `files.watchDir` | streamed events, and the polling watcher API the Python sync SDK uses |
+| `getHost(port)` | port proxy with wake-on-traffic (set `DORMICE_SANDBOX_DOMAIN`) |
+| `getMetrics()` | one live sample; observing never wakes a frozen sandbox |
+
+Deliberate deltas from the hosted product:
+
+- **No template builds.** Every sandbox runs the daemon's single base
+  image (`DORMICE_BASE_IMAGE`); the `template` argument is accepted and
+  ignored.
+- **Freezing keeps processes.** A frozen sandbox's processes suspend and
+  resume mid-flight — any touch wakes the sandbox in ~50 ms.
+- **Permanence stays the default.** Sandboxes created through the E2B
+  surface get real deadlines, as E2B semantics demand; deadlines are never
+  imposed on natively created sandboxes.
+- **`metadata.userKey`** turns `Sandbox.create` into Dormice's idempotent
+  acquire: the same key returns the same sandbox instead of a new one.
+- **Not implemented**, answered with an honest `unimplemented` on the
+  wire: `Process/StreamInput` (the JS SDK never calls it) and xattr-based
+  file metadata. The daemon reports envd `0.6.1`, so the SDK itself gates
+  those features client-side.
 
 ## Web console
 
@@ -87,6 +172,25 @@ verifies it, but these are the facts underneath:
   its ledger and refuses to start when its ledger and the machine's reality
   cannot belong together.
 
+## When Dormice is the wrong tool
+
+Pick something else if:
+
+- **You need a fleet.** One machine, one daemon, by design — that is where
+  the simplicity comes from. Multi-machine sharding is a future direction
+  (the schema already carries the fields), not a current feature.
+- **You want a managed service.** No hosted anything, no SLA. That is
+  E2B's product, and it is good at it.
+- **Your threat model demands hardware virtualization.** Sandboxes are
+  Docker + gVisor — a userspace kernel, chosen deliberately: freezing
+  requires sandboxes to be processes, and "installs anywhere" rules out
+  requiring KVM. If only Firecracker-class VM isolation will do, this
+  trade is not for you.
+- **You need cold archive today.** The `archived` state exists in the
+  protocol, but the S3 archiver is not built yet; the knob defaults to off
+  and nothing pretends otherwise.
+- **Your workloads aren't Linux.** Sandboxes are Linux containers.
+
 ## Repository layout
 
 pnpm monorepo:

From 63c29125441181e191f708976869da64a320a195 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 19:16:25 +0800
Subject: [PATCH 035/133] The website skeleton: Next.js static export with
 Fumadocs, seeded from the README

---
 .gitignore                                 |   13 +-
 biome.json                                 |    5 +
 pnpm-lock.yaml                             | 2782 +++++++++++++++++++-
 pnpm-workspace.yaml                        |    4 +-
 website/app/(home)/layout.tsx              |    7 +
 website/app/(home)/page.tsx                |   93 +
 website/app/api/search/route.ts            |    8 +
 website/app/docs/[[...slug]]/page.tsx      |   44 +
 website/app/docs/layout.tsx                |   12 +
 website/app/global.css                     |    7 +
 website/app/layout.tsx                     |   23 +
 website/app/provider.tsx                   |   11 +
 website/components/search.tsx              |   44 +
 website/content/docs/e2b-compatibility.mdx |   53 +
 website/content/docs/index.mdx             |   44 +
 website/content/docs/installation.mdx      |   68 +
 website/content/docs/meta.json             |    3 +
 website/content/docs/quickstart.mdx        |   59 +
 website/lib/layout.shared.tsx              |   10 +
 website/lib/source.ts                      |    8 +
 website/mdx-components.tsx                 |    6 +
 website/next.config.mjs                    |   15 +
 website/package.json                       |   32 +
 website/postcss.config.mjs                 |    5 +
 website/source.config.ts                   |    7 +
 website/tsconfig.json                      |   20 +
 26 files changed, 3335 insertions(+), 48 deletions(-)
 create mode 100644 website/app/(home)/layout.tsx
 create mode 100644 website/app/(home)/page.tsx
 create mode 100644 website/app/api/search/route.ts
 create mode 100644 website/app/docs/[[...slug]]/page.tsx
 create mode 100644 website/app/docs/layout.tsx
 create mode 100644 website/app/global.css
 create mode 100644 website/app/layout.tsx
 create mode 100644 website/app/provider.tsx
 create mode 100644 website/components/search.tsx
 create mode 100644 website/content/docs/e2b-compatibility.mdx
 create mode 100644 website/content/docs/index.mdx
 create mode 100644 website/content/docs/installation.mdx
 create mode 100644 website/content/docs/meta.json
 create mode 100644 website/content/docs/quickstart.mdx
 create mode 100644 website/lib/layout.shared.tsx
 create mode 100644 website/lib/source.ts
 create mode 100644 website/mdx-components.tsx
 create mode 100644 website/next.config.mjs
 create mode 100644 website/package.json
 create mode 100644 website/postcss.config.mjs
 create mode 100644 website/source.config.ts
 create mode 100644 website/tsconfig.json

diff --git a/.gitignore b/.gitignore
index 4401d9f..bd4a77e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,10 +1,11 @@
 # ── Internal development files, never committed ──
 # CLAUDE.md carries private cross-references; RULES/ and docs/ are internal
 # conventions and decision records. Public-facing docs (README, SECURITY.md, …)
-# are separate deliverables written on their own.
+# are separate deliverables written on their own. Anchored to the repo root:
+# an unanchored docs/ would swallow website/content/docs/ too.
 CLAUDE.md
-RULES/
-docs/
+/RULES/
+/docs/
 
 # Scratch code for verification and research (see RULES/临时代码.md):
 # deleted when done, and a public repo's history is append-only — one
@@ -23,6 +24,12 @@ node_modules/
 dist/
 *.tsbuildinfo
 
+# website (Next.js) build artifacts and generated files
+website/.next/
+website/out/
+website/.source/
+website/next-env.d.ts
+
 # Runtime data (SQLite ledger, sandbox volumes)
 data/
 
diff --git a/biome.json b/biome.json
index 43b7ae9..f37c027 100644
--- a/biome.json
+++ b/biome.json
@@ -30,5 +30,10 @@
     "formatter": {
       "quoteStyle": "single"
     }
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
   }
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bb1a584..274da15 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -220,8 +220,58 @@ importers:
         specifier: ^4.4.3
         version: 4.4.3
 
+  website:
+    dependencies:
+      fumadocs-core:
+        specifier: ^16.11.1
+        version: 16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3)
+      fumadocs-mdx:
+        specifier: ^15.1.0
+        version: 15.1.0(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.2.17)(fumadocs-core@16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)(rolldown@1.1.4)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
+      fumadocs-ui:
+        specifier: ^16.11.1
+        version: 16.11.1(@types/mdx@2.0.14)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(fumadocs-core@16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(tailwindcss@4.3.2)
+      next:
+        specifier: ^16.2.10
+        version: 16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      react:
+        specifier: ^19.2.7
+        version: 19.2.7
+      react-dom:
+        specifier: ^19.2.7
+        version: 19.2.7(react@19.2.7)
+    devDependencies:
+      '@tailwindcss/postcss':
+        specifier: ^4.3.2
+        version: 4.3.2
+      '@types/mdx':
+        specifier: ^2.0.14
+        version: 2.0.14
+      '@types/node':
+        specifier: ^26.1.0
+        version: 26.1.0
+      '@types/react':
+        specifier: ^19.2.17
+        version: 19.2.17
+      '@types/react-dom':
+        specifier: ^19.2.3
+        version: 19.2.3(@types/react@19.2.17)
+      postcss:
+        specifier: ^8.5.16
+        version: 8.5.16
+      tailwindcss:
+        specifier: ^4.3.2
+        version: 4.3.2
+      typescript:
+        specifier: ^6.0.3
+        version: 6.0.3
+
 packages:
 
+  '@alloc/quick-lru@5.2.0':
+    resolution: {integrity: sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==}
+    engines: {node: '>=10'}
+
   '@babel/code-frame@7.29.7':
     resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
     engines: {node: '>=6.9.0'}
@@ -1201,6 +1251,24 @@ packages:
   '@fontsource-variable/inter@5.2.8':
     resolution: {integrity: sha512-kOfP2D+ykbcX/P3IFnokOhVRNoTozo5/JxhAIVYLpea/UBmCQ/YWPBfWIDuBImXX/15KH+eKh4xpEUyS2sQQGQ==}
 
+  '@fuma-translate/react@1.0.2':
+    resolution: {integrity: sha512-uOiOtBx3nRXR8Nu1GzBf1tApgF1FErDBTHxRIAQeyQdyOoZbrNRN6H4kDCWObY4qyGeGbHydG0DHzgeUgFDMIw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^19.2.0
+      react-dom: ^19.2.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@fumadocs/tailwind@0.1.0':
+    resolution: {integrity: sha512-nF/DCAwOR21HZ4AkjIOv3Iqwyqywzb6pdyeMcoa+aZzirXj5ntvNZbe3jJ0v3ehhtrRfYYeXBezvjn8ZmV+fuQ==}
+    peerDependencies:
+      tailwindcss: ^4.0.0
+    peerDependenciesMeta:
+      tailwindcss:
+        optional: true
+
   '@grpc/grpc-js@1.14.4':
     resolution: {integrity: sha512-k9Dj3DV/itK9D06Y8f190Qgop7/Ui+D0njFV3LHMPwPT75DpXLQohE9Wmz0QElrJnzsjB7KPWiKJbOl7IPDArQ==}
     engines: {node: '>=12.10.0'}
@@ -1229,6 +1297,159 @@ packages:
     peerDependencies:
       react: '>=16.0.0'
 
+  '@img/colour@1.1.0':
+    resolution: {integrity: sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==}
+    engines: {node: '>=18'}
+
+  '@img/sharp-darwin-arm64@0.34.5':
+    resolution: {integrity: sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@img/sharp-darwin-x64@0.34.5':
+    resolution: {integrity: sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
+    resolution: {integrity: sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@img/sharp-libvips-darwin-x64@1.2.4':
+    resolution: {integrity: sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@img/sharp-libvips-linux-arm64@1.2.4':
+    resolution: {integrity: sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    resolution: {integrity: sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    resolution: {integrity: sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
+    resolution: {integrity: sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-s390x@1.2.4':
+    resolution: {integrity: sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-x64@1.2.4':
+    resolution: {integrity: sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
+    resolution: {integrity: sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
+    resolution: {integrity: sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-linux-arm64@0.34.5':
+    resolution: {integrity: sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-arm@0.34.5':
+    resolution: {integrity: sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-ppc64@0.34.5':
+    resolution: {integrity: sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    resolution: {integrity: sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-s390x@0.34.5':
+    resolution: {integrity: sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-x64@0.34.5':
+    resolution: {integrity: sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linuxmusl-arm64@0.34.5':
+    resolution: {integrity: sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    resolution: {integrity: sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-wasm32@0.34.5':
+    resolution: {integrity: sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [wasm32]
+
+  '@img/sharp-win32-arm64@0.34.5':
+    resolution: {integrity: sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@img/sharp-win32-ia32@0.34.5':
+    resolution: {integrity: sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [ia32]
+    os: [win32]
+
+  '@img/sharp-win32-x64@0.34.5':
+    resolution: {integrity: sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [win32]
+
   '@inquirer/external-editor@1.0.3':
     resolution: {integrity: sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA==}
     engines: {node: '>=18'}
@@ -1275,6 +1496,9 @@ packages:
   '@manypkg/get-packages@1.1.3':
     resolution: {integrity: sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==}
 
+  '@mdx-js/mdx@3.1.1':
+    resolution: {integrity: sha512-f6ZO2ifpwAQIpzGWaBQT2TXxPv6z3RBzQKpVftEWN78Vl/YweF1uwussDx8ECAXVtr3Rs89fKyG9YlzUs9DyGQ==}
+
   '@modelcontextprotocol/sdk@1.29.0':
     resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==}
     engines: {node: '>=18'}
@@ -1291,6 +1515,61 @@ packages:
       '@emnapi/core': ^1.7.1
       '@emnapi/runtime': ^1.7.1
 
+  '@next/env@16.2.10':
+    resolution: {integrity: sha512-zLPxg9M0MEHmygpj5OuxjQ+vHMiy/K7cSp74G8ecYolmgUWw0RwN02tF56npup/+qaI8JB97hQgS/r2Hb6QwVA==}
+
+  '@next/swc-darwin-arm64@16.2.10':
+    resolution: {integrity: sha512-v9IdJCa0H0mbo+8z5zwUpOk1Vj7RjkcI5uNYf5Ws1y6szf/p3Mzl9hLaST8SCt6L9h8NGnruZcd2+o0NTNwDhA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@next/swc-darwin-x64@16.2.10':
+    resolution: {integrity: sha512-17IS0jJRViROGmA9uGdNR8VPJpfbnaVG7E9qhso5jDLkmyd0lSDORWxbcKINzcFqzZqGwGtMSnrFRxBpuUYjLQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@next/swc-linux-arm64-gnu@16.2.10':
+    resolution: {integrity: sha512-GRQRsRtuciNJvB54AvvuQTiq0oZtFwa1owQqtZD8wwnGpM2L39MV22kpI72YSXLKIyY40LC66EiLFv4PiicXxg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@next/swc-linux-arm64-musl@16.2.10':
+    resolution: {integrity: sha512-zkN9MQYS7UQBro+FnISUq1itaQjXI9xqISzuQ+2bc921NcJ1x4yPCqrn77tVN6/dOOXaaWVX3k6/bR07pPwK+A==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@next/swc-linux-x64-gnu@16.2.10':
+    resolution: {integrity: sha512-iCVJnwvrPYECvA6WM/7+oo+OiTvedIKLxtCLAZP4xZR3nXa1zmzZyLPbYCmWvpd4CvMYF1EMTafd0ii3DygLvA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@next/swc-linux-x64-musl@16.2.10':
+    resolution: {integrity: sha512-ov2g4H0dHY9bPoOU83m91hWT7Iq5qy13bUnyyshLU3HGR1Ownn0X9QpmDPc5iIUaahTp7f7LeGAhV4DSFtackw==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@next/swc-win32-arm64-msvc@16.2.10':
+    resolution: {integrity: sha512-DwAnhLX76HQiFFQNgWlcK+JzlnD1rZ+UK/WY0ZMI/deXpvgnesjNYrqcfo1JzBuz4Kf7o3brIBL0glI1junatA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@next/swc-win32-x64-msvc@16.2.10':
+    resolution: {integrity: sha512-0JXq3b85Jk9Jg4ntLUbXSPvoDw3gpZou7twuKdoFG2jOw635v7+IiXfTaa0TxVMyx78pUjnrVYwLgjKfX4e6/A==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
   '@nodelib/fs.scandir@2.1.5':
     resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==}
     engines: {node: '>= 8'}
@@ -1303,6 +1582,10 @@ packages:
     resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
     engines: {node: '>= 8'}
 
+  '@orama/orama@3.1.18':
+    resolution: {integrity: sha512-a61ljmRVVyG5MC/698C8/FfFDw5a8LOIvyOLW5fztgUXqUpc1jOfQzOitSCbge657OgXXThmY3Tk8fpiDb4UcA==}
+    engines: {node: '>= 20.0.0'}
+
   '@oxc-project/types@0.138.0':
     resolution: {integrity: sha512-1a7ZKmrRTCoN1XMZ4L0PyyqrMnrNlLyPuOkdSX2MZg7IiIGRUyurNhAm73ptDOraoBcIordsIGKNPKUzy3ZmfA==}
 
@@ -1336,9 +1619,64 @@ packages:
   '@protobufjs/utf8@1.1.2':
     resolution: {integrity: sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==}
 
+  '@radix-ui/number@1.1.2':
+    resolution: {integrity: sha512-ceTwaxc4I5IOi97DgCotl3pqiyRGvffcc0oOsE2dQYaJOFIDsDt4VWG6xEbg1QePv9QWausCEIppud/tJ1wNig==}
+
   '@radix-ui/primitive@1.1.5':
     resolution: {integrity: sha512-d86WIWFYNtGA0H/d8exstrTRTp7eWJYlYJbtNofxr/3ljupZYn6EFDG/Qgu/0Kc8v7yMUxySagqJsL1+PdYjWg==}
 
+  '@radix-ui/react-accordion@1.2.16':
+    resolution: {integrity: sha512-BpZJNmetujnGgUI6OX0jEhEmlA46WPqgub8Rv09Kyquwd0cc1ndMKpiPYCjmBU6KSSRPAMtgLpEoZSG/tdNIWQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-arrow@1.1.11':
+    resolution: {integrity: sha512-Kdil9BB1rIFC/khmf4hC35bn8701AJcizTU7G7cUbEbk5XqqbjDuHW60uUfKqO5WojjZcbAW51Q7P0hRmMLw8A==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-collapsible@1.1.16':
+    resolution: {integrity: sha512-opfXRe6nnzyGmCDPx+l1Aqo/RbqWtQal2FnsBqF9hhePp6j0LsRoBaRxcMOlTv+uYTJVtWYZKg9t9wTe+BA/ZA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-collection@1.1.12':
+    resolution: {integrity: sha512-nb67INpE0IahJKN7EYPp9m9YGwYeKlnzxT3MwXVkgCskaSJia97kG4T0ywpjNUSSnoJk/uvk12V8vbrEHEj+/Q==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
   '@radix-ui/react-compose-refs@1.1.3':
     resolution: {integrity: sha512-rYOP8OMnuuPMQF1uhPVlGNcCDlkokKqGFE3JcxFViIkAXP7EvFWUliJAstrapypaBLJNHbZL6jGhbVDGTwmVhA==}
     peerDependencies:
@@ -1370,6 +1708,15 @@ packages:
       '@types/react-dom':
         optional: true
 
+  '@radix-ui/react-direction@1.1.2':
+    resolution: {integrity: sha512-C3vFhbyi4SW3PmbAi6Awpu4OzJtd0MxGurvSsYtr7p7nM8RNB3VAF3CUmnp2j50knpkrRcB7+ycVXzgLgF6yNA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
   '@radix-ui/react-dismissable-layer@1.1.15':
     resolution: {integrity: sha512-b0XaRlzn2QKuo10XyNgi2DAJDf5XC9d1nD3FJcuvCjbR7+4Ad28zmZsLsqx+hvDEzMnRuZaZxZm9gYObV6RmRA==}
     peerDependencies:
@@ -1414,6 +1761,45 @@ packages:
       '@types/react':
         optional: true
 
+  '@radix-ui/react-navigation-menu@1.2.18':
+    resolution: {integrity: sha512-K9HiuxZ6xCwSaHcIuUpxyhy4w5gpwzWjh9dHTSbMN3Ix4qAyVObS9RlU3zMycb0PO3v9Tpk0BXMwWvXOUbVXew==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-popover@1.1.19':
+    resolution: {integrity: sha512-jkrTdQVxnIB8fpn0NyyxW9CTB5aCXZZelVz5z+Xmii6g5WxMqS3fInNslZ63puP39+Puu4jYohUK31y3dT87gQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-popper@1.3.3':
+    resolution: {integrity: sha512-mS7dGpyjv6b+gsDjLF7e0ia1W4Im1B1hSCy2yuXlHuvnZxHKagfDaobt/KAKt27EpZMit2pss8eJBVyVjEWM+g==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
   '@radix-ui/react-portal@1.1.13':
     resolution: {integrity: sha512-z3oXfmaHLJTF1wktbjgD6cn9jiEbq3WSondB10LIuIt2m2Ym4iJlrW04/euMwENDdWDdE7z+OuY7Qyp1YpRSwA==}
     peerDependencies:
@@ -1437,24 +1823,108 @@ packages:
     peerDependenciesMeta:
       '@types/react':
         optional: true
-      '@types/react-dom':
-        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-primitive@2.1.7':
+    resolution: {integrity: sha512-bC3NiwsprbxKjuon9l7X6BUTw7FPVzEYaL92MPEY5SCd/9hUTPXVFtVwRix7778wtRsVao+zE062gL79FZleeQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-roving-focus@1.1.15':
+    resolution: {integrity: sha512-40svmmugfM3mUN7VUDGVE1tQGOhyi8enlGD0CNJEcMM36C1f71PKM21DFgNHUfem0XnA+d8H8oN3Z9ZpJjSslg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-scroll-area@1.2.14':
+    resolution: {integrity: sha512-bBODCWZK7JTbQLHs0uIP4f73wIWatakK4OS33UzkR1x897wu0PuO658a3f+6P2GEGyDzGYMuHRatMVoAk9WZTw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-slot@1.3.0':
+    resolution: {integrity: sha512-MojKku4U/miO8Av4Dkb+ctMAQx7JmY96LmtDQlAarCRtd7rN52QCSzBF+XAvr5S6coSVj9HEPBgHAHKEJVk/WA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-tabs@1.1.17':
+    resolution: {integrity: sha512-nRyXnrAVCwjeXcHbvEbLS6ndbTeKHG1RqCP4A8Gw5L4cemDzPXdD8rAmr6wet0v57R69wGvuIIsFjHSVkZiMzQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-use-callback-ref@1.1.2':
+    resolution: {integrity: sha512-xCso9j1/u8sEgP1RNHjFrXJLApL8LiqOkI1R4ywuN00rxWdYg4oQXuwKLS3i0j5NWLromUD27/4nlxj2UFVvIw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-controllable-state@1.2.3':
+    resolution: {integrity: sha512-PLzC90MS+ReootmjC597dvopoelpZ8Q61HJkDXZSExitIq7PL55vHNnesAHwguHK0aPfBnpdNzQtv1uliaqQrA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-effect-event@0.0.3':
+    resolution: {integrity: sha512-6c8ZqvPTWILEKnyVkP53EGRCcpnJiKTC21sS/6R1GF5xKyHJJWQEPfkqlcgUkdRQivd6tb23abUwe4ngWmY0JA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
 
-  '@radix-ui/react-primitive@2.1.7':
-    resolution: {integrity: sha512-bC3NiwsprbxKjuon9l7X6BUTw7FPVzEYaL92MPEY5SCd/9hUTPXVFtVwRix7778wtRsVao+zE062gL79FZleeQ==}
+  '@radix-ui/react-use-is-hydrated@0.1.1':
+    resolution: {integrity: sha512-qwOiz4Tjo8CNnrOLAYUMXeZwDzXgXpvK4TKQPmWLECM9XoWvA6+0Z2/7Ag3A4ivjS4ovbLJPbskkxioFyBhr8A==}
     peerDependencies:
       '@types/react': '*'
-      '@types/react-dom': '*'
       react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
-      '@types/react-dom':
-        optional: true
 
-  '@radix-ui/react-slot@1.3.0':
-    resolution: {integrity: sha512-MojKku4U/miO8Av4Dkb+ctMAQx7JmY96LmtDQlAarCRtd7rN52QCSzBF+XAvr5S6coSVj9HEPBgHAHKEJVk/WA==}
+  '@radix-ui/react-use-layout-effect@1.1.2':
+    resolution: {integrity: sha512-jrBWOxZITuGcnjRCM2t2U5ZPkCLxD+Ym6DjfssS5haTj2iiak/DOb64JeN6OdLfLgptb6/e2kKR+ZuTrGoZTPA==}
     peerDependencies:
       '@types/react': '*'
       react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
@@ -1462,8 +1932,8 @@ packages:
       '@types/react':
         optional: true
 
-  '@radix-ui/react-use-callback-ref@1.1.2':
-    resolution: {integrity: sha512-xCso9j1/u8sEgP1RNHjFrXJLApL8LiqOkI1R4ywuN00rxWdYg4oQXuwKLS3i0j5NWLromUD27/4nlxj2UFVvIw==}
+  '@radix-ui/react-use-previous@1.1.2':
+    resolution: {integrity: sha512-IGBQPtRFdhN6MQ8dbegVmBq1LVZluya3F1jWY+puIcQC3MHctRwTDSBWCkL/3ZcnMJLTMJ++Z+ktmvg0F89iCw==}
     peerDependencies:
       '@types/react': '*'
       react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
@@ -1471,8 +1941,8 @@ packages:
       '@types/react':
         optional: true
 
-  '@radix-ui/react-use-controllable-state@1.2.3':
-    resolution: {integrity: sha512-PLzC90MS+ReootmjC597dvopoelpZ8Q61HJkDXZSExitIq7PL55vHNnesAHwguHK0aPfBnpdNzQtv1uliaqQrA==}
+  '@radix-ui/react-use-rect@1.1.2':
+    resolution: {integrity: sha512-d8a+bBY/FxikNPlgJJoaBHZX+zKVbWHYJGTLnLvveQgFSTntkGdEKv3JDtHrMS0DNYpllz2nRsTLGLKYttbpmw==}
     peerDependencies:
       '@types/react': '*'
       react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
@@ -1480,8 +1950,8 @@ packages:
       '@types/react':
         optional: true
 
-  '@radix-ui/react-use-effect-event@0.0.3':
-    resolution: {integrity: sha512-6c8ZqvPTWILEKnyVkP53EGRCcpnJiKTC21sS/6R1GF5xKyHJJWQEPfkqlcgUkdRQivd6tb23abUwe4ngWmY0JA==}
+  '@radix-ui/react-use-size@1.1.2':
+    resolution: {integrity: sha512-giWQp+4mxjBPt4KZ0MmyuykFNWfbDxKt4x+fPkRYmgRFJSbCZFzUglvMb/Kjn38tm10YP4ufiQZDx3zna4LU6w==}
     peerDependencies:
       '@types/react': '*'
       react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
@@ -1489,14 +1959,21 @@ packages:
       '@types/react':
         optional: true
 
-  '@radix-ui/react-use-layout-effect@1.1.2':
-    resolution: {integrity: sha512-jrBWOxZITuGcnjRCM2t2U5ZPkCLxD+Ym6DjfssS5haTj2iiak/DOb64JeN6OdLfLgptb6/e2kKR+ZuTrGoZTPA==}
+  '@radix-ui/react-visually-hidden@1.2.7':
+    resolution: {integrity: sha512-1wNZBggTDK3GRuuQ6nP4k2yi7a6l7I5qbMPbZcRsrGsGVead/f/d5FhEzUvqFs0bcrDLx7n1zKQ3JvLR6whaaw==}
     peerDependencies:
       '@types/react': '*'
+      '@types/react-dom': '*'
       react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
     peerDependenciesMeta:
       '@types/react':
         optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/rect@1.1.2':
+    resolution: {integrity: sha512-xnXE7wG13PI+cxieVssYXlQJuYVRhH9NBoxt3KNwzghDIA69GMm7d4wXRouHIYjE+KvS6U/MsMO73NdS2MH9ZA==}
 
   '@reduxjs/toolkit@2.12.0':
     resolution: {integrity: sha512-KiT+RzZbp6mQET+Mg+h2c97+9j1sNflUxQkIHI7Yuzf6Peu+OYpmkn6nbHWmLLWj+1ZODUJFwGZ7gx3L9R9EOw==}
@@ -1759,6 +2236,37 @@ packages:
       react:
         optional: true
 
+  '@shikijs/core@4.3.1':
+    resolution: {integrity: sha512-ANMDxuaPsNMdDC1m4vfvhlDmJweMwkE5XitTwrq2rWHx5jM+dlm4MmHt2PP6t0uejfR77SuhrhJ0zEijIF/uhA==}
+    engines: {node: '>=20'}
+
+  '@shikijs/engine-javascript@4.3.1':
+    resolution: {integrity: sha512-JBItcnPuYq7jVJdZo/vMj94r+szT7XEjHFX+mvFDGSEIbVAXAGyHAHzhbWzpGOwYidCZrErJLLgn2PVeiokHnQ==}
+    engines: {node: '>=20'}
+
+  '@shikijs/engine-oniguruma@4.3.1':
+    resolution: {integrity: sha512-OXyNMzg0pews+msMj4cHeqT4xiYKKvbnn6VbdAXxfoFl3SSx4fJTc8FadECuc5/H9p3BzhNAoAUXKwAu9rWYhg==}
+    engines: {node: '>=20'}
+
+  '@shikijs/langs@4.3.1':
+    resolution: {integrity: sha512-m0l9nsDqgBHvbZbk7A0/kXz/impK3uB/c6rAn6Gpg/uPtdZRQ+alsN/17MU5thb68XTj/4DxkZAotrM0GGSpDQ==}
+    engines: {node: '>=20'}
+
+  '@shikijs/primitive@4.3.1':
+    resolution: {integrity: sha512-CXQRQOYy1leqQ8ceTeJdmXv/bsUY++6QyLpXJ94LZAAYj5X2SKRdc5ipguv4NPyGVKItB2PPwUpRNe0Sjh5S1A==}
+    engines: {node: '>=20'}
+
+  '@shikijs/themes@4.3.1':
+    resolution: {integrity: sha512-dgpoJ4WqNi2yTmizQHBJ5zcX6j2lE6icN/0yt4l1kkf16jrY/pwPLoTb1ETsWMz0OBLf9ZNvwmxft+cH+N9qSA==}
+    engines: {node: '>=20'}
+
+  '@shikijs/types@4.3.1':
+    resolution: {integrity: sha512-CHFxE0jztBIZRHH6gxXE7DXUCFXjReEGxZ/j0rfSLGKZuwp2xBYycEP14875DSa9KLL/6700oxIq6oO6ef9K2g==}
+    engines: {node: '>=20'}
+
+  '@shikijs/vscode-textmate@10.0.2':
+    resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
+
   '@sindresorhus/merge-streams@4.0.0':
     resolution: {integrity: sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==}
     engines: {node: '>=18'}
@@ -1769,6 +2277,9 @@ packages:
   '@standard-schema/utils@0.3.0':
     resolution: {integrity: sha512-e7Mew686owMaPJVNNLs55PUvgz371nKgwsc4vxE49zsODpJEnxgxRo2y/OKrqueavXgZNMDVj3DdHFlaSAeU8g==}
 
+  '@swc/helpers@0.5.15':
+    resolution: {integrity: sha512-JQ5TuMi45Owi4/BIMAJBoSQoOJu12oOk/gADqlcUL9JEdHB8vyjUSsxqeNXnmXHjYKMi2WcYtezGEEhqUI/E2g==}
+
   '@tailwindcss/node@4.3.2':
     resolution: {integrity: sha512-yWP/sqEcBLaD8JuA6zNwxoYKr75qxTioYwlRwekj5Jr/I5GXnoJfjetH/psLUIv74cYTH2lBUEzBkinthoYcBg==}
 
@@ -1858,6 +2369,9 @@ packages:
     resolution: {integrity: sha512-z8ZgnzX8gdNoWLBLqBPoh/sjnxkwvf9ZuWjnO0l0yIzbLa5/9S+eC5QxGZKRobVHIC3/1BoMWjHblqWjcgFgag==}
     engines: {node: '>= 20'}
 
+  '@tailwindcss/postcss@4.3.2':
+    resolution: {integrity: sha512-rjVWYCa7Ngbi5AarT6k8TkxUG3Wl1QKzHdIZVsjZSzf36Jmo2IKZt/NHRAwly8oDkbBOH0YTu+CHuf9jPxMc+g==}
+
   '@tailwindcss/vite@4.3.2':
     resolution: {integrity: sha512-eHpMeX4JXfVNJDEcsouTeCBubJBTcTLigeaw/NTUW6PB5ATKKXdyonnXgTBX2VuRbjz1hjfz6C5XAhr52ImQXA==}
     peerDependencies:
@@ -1967,6 +2481,9 @@ packages:
   '@types/d3-timer@3.0.2':
     resolution: {integrity: sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==}
 
+  '@types/debug@4.1.13':
+    resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
+
   '@types/deep-eql@4.0.2':
     resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
 
@@ -1976,9 +2493,24 @@ packages:
   '@types/dockerode@4.0.1':
     resolution: {integrity: sha512-cmUpB+dPN955PxBEuXE3f6lKO1hHiIGYJA46IVF3BJpNsZGvtBDcRnlrHYHtOH/B6vtDOyl2kZ2ShAu3mgc27Q==}
 
+  '@types/estree-jsx@1.0.5':
+    resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==}
+
   '@types/estree@1.0.9':
     resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
 
+  '@types/hast@3.0.5':
+    resolution: {integrity: sha512-rp/ezSWaD1m44dPKICGhiskI13nVr7qTloFwDa/IYkhhf5nzwP+zIQcIJh3WIFSBOy/H1PzB40jPjMDksN4F+g==}
+
+  '@types/mdast@4.0.4':
+    resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==}
+
+  '@types/mdx@2.0.14':
+    resolution: {integrity: sha512-T48PeuJtvLosNTPVhfnIp3i/n3a4g4Bad7YCq5k64D4u7NwDrAotikQ+5+sjtUvBmxCMlbo3dVL+C2dP0rWHzg==}
+
+  '@types/ms@2.1.0':
+    resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
+
   '@types/node@12.20.55':
     resolution: {integrity: sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==}
 
@@ -1999,12 +2531,21 @@ packages:
   '@types/ssh2@1.15.5':
     resolution: {integrity: sha512-N1ASjp/nXH3ovBHddRJpli4ozpk6UdDYIX4RJWFa9L1YKnzdhTlVmiGHm4DZnj/jLbqZpes4aeR30EFGQtvhQQ==}
 
+  '@types/unist@2.0.11':
+    resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==}
+
+  '@types/unist@3.0.3':
+    resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
+
   '@types/use-sync-external-store@0.0.6':
     resolution: {integrity: sha512-zFDAD+tlpf2r4asuHEj0XH6pY6i0g5NeAHPn+15wk3BV6JA69eERFXC1gyGThDkVa1zCyKr5jox1+2LbV/AMLg==}
 
   '@types/validate-npm-package-name@4.0.2':
     resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}
 
+  '@ungap/structured-clone@1.3.2':
+    resolution: {integrity: sha512-5jsZFwgR5rTdKwidH9Qmat75RKwqfpKlWWB1frDkljN127mwqBu8K0PYo7/hFpF03IEJpfVPpCQDY/eDx3iHvA==}
+
   '@vitejs/plugin-react@6.0.3':
     resolution: {integrity: sha512-vmFvco5/QuC2f9Oj+wTk0+9XeDFkHxSamwZKYc7MxYwKICfvUvlMhqKI0VuICPltGqh1neqBKDvO4kes1ya8vg==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -2060,6 +2601,11 @@ packages:
     resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
     engines: {node: '>= 0.6'}
 
+  acorn-jsx@5.3.2:
+    resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
+    peerDependencies:
+      acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
+
   acorn@8.17.0:
     resolution: {integrity: sha512-xRQbDb9BnwDafYNn6Vwl839DYVjqXYb1XVGtWAZ1kcDc6iwAL4hg3B1dZlRiuENFeO2H53gFG3in621AdERVAg==}
     engines: {node: '>=0.4.0'}
@@ -2132,6 +2678,10 @@ packages:
     resolution: {integrity: sha512-6t10qk83GOG8p0vKmaCr8eiilZwO171AvbROMtvvNiwrTly62t+7XkA8RdIIVbpMhCASAsxgAzdRSwh6nw/5Dg==}
     engines: {node: '>=4'}
 
+  astring@1.9.0:
+    resolution: {integrity: sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==}
+    hasBin: true
+
   atomic-sleep@1.0.0:
     resolution: {integrity: sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ==}
     engines: {node: '>=8.0.0'}
@@ -2146,6 +2696,9 @@ packages:
   babel-dead-code-elimination@1.0.12:
     resolution: {integrity: sha512-GERT7L2TiYcYDtYk1IpD+ASAYXjKbLTDPhBtYj7X1NuRMDTMtAx9kyBenub1Ev41lo91OHCKdmP+egTDmfQ7Ig==}
 
+  bail@2.0.2:
+    resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==}
+
   balanced-match@4.0.4:
     resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
     engines: {node: 18 || 20 || >=22}
@@ -2235,6 +2788,9 @@ packages:
   caniuse-lite@1.0.30001803:
     resolution: {integrity: sha512-g/uHREV2ZpK9qMalCsWaxmA6ol+DX8GYhuf3T40RKoP+oL7vhRJh8LNt73PCjpnR6l14FzfPrB5Yux4PKm2meg==}
 
+  ccount@2.0.1:
+    resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
+
   chai@6.2.2:
     resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
     engines: {node: '>=18'}
@@ -2243,6 +2799,18 @@ packages:
     resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
     engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
 
+  character-entities-html4@2.1.0:
+    resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
+
+  character-entities-legacy@3.0.0:
+    resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==}
+
+  character-entities@2.0.2:
+    resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
+
+  character-reference-invalid@2.0.1:
+    resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
+
   chardet@2.2.0:
     resolution: {integrity: sha512-rddelWYNPRrXq6PtNEN2S3f6t9ILzvqaN5pVgi4kqt9jHQaXIial9PznB5iSPVlQSLNaaH22ItWz3EJtQ10+OA==}
 
@@ -2272,6 +2840,9 @@ packages:
     resolution: {integrity: sha512-ywqV+5MmyL4E7ybXgKys4DugZbX0FC6LnwrhjuykIjnK9k8OQacQ7axGKnjDXWNhns0xot3bZI5h55H8yo9cJg==}
     engines: {node: '>=6'}
 
+  client-only@0.0.1:
+    resolution: {integrity: sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==}
+
   cliui@8.0.1:
     resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==}
     engines: {node: '>=12'}
@@ -2286,9 +2857,16 @@ packages:
       react: ^18 || ^19 || ^19.0.0-rc
       react-dom: ^18 || ^19 || ^19.0.0-rc
 
+  cnfast@0.0.8:
+    resolution: {integrity: sha512-EjXKMfGfdwtV4AcNSQ6AwQaVzpC1B7IxeiwA3FlhTXz+YFlMKVi4c1JX9tgD2QOlahQXjB8KUXrBaYG+3v871Q==}
+    hasBin: true
+
   code-block-writer@13.0.3:
     resolution: {integrity: sha512-Oofo0pq3IKnsFtuHqSF7TqBfr71aeyZDVJ0HpmqB7FBM2qEigL0iPONSCZSO9pE9dZTAxANe5XHG9Uy0YMv8cg==}
 
+  collapse-white-space@2.1.0:
+    resolution: {integrity: sha512-loKTxY1zCOuG4j9f6EPnuyyYkf58RnhhWTvRoZEokgB+WbdXehfjFviyOVYkqzEWz1Q5kRiZdBYS5SwxbQYwzw==}
+
   color-convert@2.0.1:
     resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
     engines: {node: '>=7.0.0'}
@@ -2296,6 +2874,9 @@ packages:
   color-name@1.1.4:
     resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
 
+  comma-separated-tokens@2.0.3:
+    resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==}
+
   commander@11.1.0:
     resolution: {integrity: sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==}
     engines: {node: '>=16'}
@@ -2311,6 +2892,9 @@ packages:
   compare-versions@6.1.1:
     resolution: {integrity: sha512-4hm4VPpIecmlg59CHXnRDnqGplJFrbLG4aFEl5vl6cK1u76ws3LLvX7ikFnTDl5vo39sjWD6AaDPYodJp/NNHg==}
 
+  compute-scroll-into-view@3.1.1:
+    resolution: {integrity: sha512-VRhuHOLoKYOy4UbilLbUzbYg93XLjv2PncJC50EuTWPA3gaja1UjBsUP/D/9/juV3vQFr6XBEzn9KCAHdUvOHw==}
+
   conf@10.2.0:
     resolution: {integrity: sha512-8fLl9F04EJqjSqH+QjITQfJF8BrOVaYr1jewVgSRAEWePfxT0sku4w2hrGQ60BC/TNLGQ2pgxNlTbWQmMPFvXg==}
     engines: {node: '>=12'}
@@ -2444,6 +3028,9 @@ packages:
   decimal.js-light@2.5.1:
     resolution: {integrity: sha512-qIMFpTMZmny+MMIitAB6D7iVPEorVw6YQRWkvarTkT4tBeSLLiHzcwj6q0MmYSFCiVpiqPJTJEYIrpcPzVEIvg==}
 
+  decode-named-character-reference@1.3.0:
+    resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==}
+
   decompress-response@6.0.0:
     resolution: {integrity: sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==}
     engines: {node: '>=10'}
@@ -2499,6 +3086,9 @@ packages:
   detect-node-es@1.1.0:
     resolution: {integrity: sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==}
 
+  devlop@1.1.0:
+    resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
+
   diff@8.0.4:
     resolution: {integrity: sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==}
     engines: {node: '>=0.3.1'}
@@ -2670,6 +3260,10 @@ packages:
     resolution: {integrity: sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==}
     engines: {node: '>=8.6'}
 
+  entities@6.0.1:
+    resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
+    engines: {node: '>=0.12'}
+
   env-paths@2.2.1:
     resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==}
     engines: {node: '>=6'}
@@ -2695,6 +3289,12 @@ packages:
   es-toolkit@1.49.0:
     resolution: {integrity: sha512-G5iZ6Pc/FNRY/soKZHC+TxGDD83rHUDXxzaWhGCX44vAv/tMs56WMusnm/KMNK+luUPsgA9U28cGr4RDlSzL2g==}
 
+  esast-util-from-estree@2.0.0:
+    resolution: {integrity: sha512-4CyanoAudUSBAn5K13H4JhsMH6L9ZP7XbLVe/dKybkxMO7eDyLsT8UHl9TRNrU2Gr9nz+FovfSIjuXWJ81uVwQ==}
+
+  esast-util-from-js@2.0.1:
+    resolution: {integrity: sha512-8Ja+rNJ0Lt56Pcf3TAmpBZjmx8ZcK5Ts4cAzIOjsjevg9oSXJnl6SUQ2EevU8tv3h6ZLWmoKL5H4fgWvdvfETw==}
+
   esbuild@0.18.20:
     resolution: {integrity: sha512-ceqxoedUrcayh7Y7ZX6NdbbDzGROiyVBgC4PriJThBKSVPWnnFHZAkfI1lJT8QFkOwH4qOS2SJkS4wvpGl8BpA==}
     engines: {node: '>=12'}
@@ -2722,11 +3322,36 @@ packages:
   escape-html@1.0.3:
     resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
 
+  escape-string-regexp@5.0.0:
+    resolution: {integrity: sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==}
+    engines: {node: '>=12'}
+
   esprima@4.0.1:
     resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==}
     engines: {node: '>=4'}
     hasBin: true
 
+  estree-util-attach-comments@3.0.0:
+    resolution: {integrity: sha512-cKUwm/HUcTDsYh/9FgnuFqpfquUbwIqwKM26BVCGDPVgvaCl/nDCCjUfiLlx6lsEZ3Z4RFxNbOQ60pkaEwFxGw==}
+
+  estree-util-build-jsx@3.0.1:
+    resolution: {integrity: sha512-8U5eiL6BTrPxp/CHbs2yMgP8ftMhR5ww1eIKoWRMlqvltHF8fZn5LRDvTKuxD3DUn+shRbLGqXemcP51oFCsGQ==}
+
+  estree-util-is-identifier-name@3.0.0:
+    resolution: {integrity: sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==}
+
+  estree-util-scope@1.0.0:
+    resolution: {integrity: sha512-2CAASclonf+JFWBNJPndcOpA8EMJwa0Q8LUFJEKqXLW6+qBvbFZuF5gItbQOs/umBUkjviCSDCbBwU2cXbmrhQ==}
+
+  estree-util-to-js@2.0.0:
+    resolution: {integrity: sha512-WDF+xj5rRWmD5tj6bIqRi6CkLIXbbNQUcxQHzGysQzvHmdYG2G7p/Tf0J0gpxGgkeMZNTIjT/AoSvC9Xehcgdg==}
+
+  estree-util-value-to-estree@3.5.0:
+    resolution: {integrity: sha512-aMV56R27Gv3QmfmF1MY12GWkGzzeAezAX+UplqHVASfjc9wNzI/X6hC0S9oxq61WT4aQesLGslWP9tKk6ghRZQ==}
+
+  estree-util-visit@2.0.0:
+    resolution: {integrity: sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==}
+
   estree-walker@3.0.3:
     resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
 
@@ -2771,6 +3396,9 @@ packages:
     resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
     engines: {node: '>= 18'}
 
+  extend@3.0.2:
+    resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==}
+
   extendable-error@0.1.7:
     resolution: {integrity: sha512-UOiS2in6/Q0FK0R0q6UY9vYpQ21mr/Qn1KOnte7vsACuNJf514WvCCUHSRCPcgjPT2bAhNIJdlE6bVap1GKmeg==}
 
@@ -2857,6 +3485,20 @@ packages:
     resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==}
     engines: {node: '>= 0.6'}
 
+  framer-motion@12.42.2:
+    resolution: {integrity: sha512-5XY9luDiu0oHfHBjpDthFMh0ES+122w6p/papSJBweMkO8Sn+PW2QaEgRblQBpWFnuvZS5qvarpt/hO2pjGmnw==}
+    peerDependencies:
+      '@emotion/is-prop-valid': '*'
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@emotion/is-prop-valid':
+        optional: true
+      react:
+        optional: true
+      react-dom:
+        optional: true
+
   fresh@2.0.0:
     resolution: {integrity: sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==}
     engines: {node: '>= 0.8'}
@@ -2881,6 +3523,122 @@ packages:
     engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
     os: [darwin]
 
+  fumadocs-core@16.11.1:
+    resolution: {integrity: sha512-tKuh1AKoVTb+f7IoAOM2cfz5djd3YhePeqA95q6mf422gEvDTeJms23OJ+icYRWZ6ryNQ5W/ZsgKEe87M5HVYg==}
+    peerDependencies:
+      '@mdx-js/mdx': '*'
+      '@mixedbread/sdk': 0.x.x
+      '@orama/core': 1.x.x
+      '@oramacloud/client': 2.x.x
+      '@tanstack/react-router': 1.x.x
+      '@types/estree-jsx': '*'
+      '@types/hast': '*'
+      '@types/mdast': '*'
+      '@types/react': '*'
+      algoliasearch: 5.x.x
+      flexsearch: '*'
+      lucide-react: '*'
+      next: 16.x.x
+      react: ^19.2.0
+      react-dom: ^19.2.0
+      react-router: 7.x.x || 8.x.x
+      waku: '*'
+      zod: 4.x.x
+    peerDependenciesMeta:
+      '@mdx-js/mdx':
+        optional: true
+      '@mixedbread/sdk':
+        optional: true
+      '@orama/core':
+        optional: true
+      '@oramacloud/client':
+        optional: true
+      '@tanstack/react-router':
+        optional: true
+      '@types/estree-jsx':
+        optional: true
+      '@types/hast':
+        optional: true
+      '@types/mdast':
+        optional: true
+      '@types/react':
+        optional: true
+      algoliasearch:
+        optional: true
+      flexsearch:
+        optional: true
+      lucide-react:
+        optional: true
+      next:
+        optional: true
+      react:
+        optional: true
+      react-dom:
+        optional: true
+      react-router:
+        optional: true
+      waku:
+        optional: true
+      zod:
+        optional: true
+
+  fumadocs-mdx@15.1.0:
+    resolution: {integrity: sha512-2nDusSlYFuNVcyB51jgY3tA3r01ALTwoURrMDNoc7cbJKZ2sac/PW+CDq6SHTArkgRMmFiKYQGfspJdjgTtPTg==}
+    hasBin: true
+    peerDependencies:
+      '@fumadocs/satteri': 0.x.x
+      '@types/mdast': '*'
+      '@types/mdx': '*'
+      '@types/react': '*'
+      fumadocs-core: ^16.7.0
+      mdast-util-directive: '*'
+      next: ^15.3.0 || ^16.0.0
+      react: ^19.2.0
+      rolldown: '*'
+      satteri: ^0.9.4
+      vite: 7.x.x || 8.x.x
+    peerDependenciesMeta:
+      '@fumadocs/satteri':
+        optional: true
+      '@types/mdast':
+        optional: true
+      '@types/mdx':
+        optional: true
+      '@types/react':
+        optional: true
+      mdast-util-directive:
+        optional: true
+      next:
+        optional: true
+      react:
+        optional: true
+      rolldown:
+        optional: true
+      satteri:
+        optional: true
+      vite:
+        optional: true
+
+  fumadocs-ui@16.11.1:
+    resolution: {integrity: sha512-Dq819PFV4RGhAI9Wd4erSCiRlEDLVOZae+kgE5LeOKFH8mbKX49U8N17ldFOhdkC9EZpxMZdEKul77RDgFHQww==}
+    peerDependencies:
+      '@takumi-rs/image-response': '*'
+      '@types/mdx': '*'
+      '@types/react': '*'
+      fumadocs-core: 16.11.1
+      next: 16.x.x
+      react: ^19.2.0
+      react-dom: ^19.2.0
+    peerDependenciesMeta:
+      '@takumi-rs/image-response':
+        optional: true
+      '@types/mdx':
+        optional: true
+      '@types/react':
+        optional: true
+      next:
+        optional: true
+
   function-bind@1.1.2:
     resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
 
@@ -2929,6 +3687,9 @@ packages:
   github-from-package@0.0.0:
     resolution: {integrity: sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==}
 
+  github-slugger@2.0.0:
+    resolution: {integrity: sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw==}
+
   glob-parent@5.1.2:
     resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
     engines: {node: '>= 6'}
@@ -2961,10 +3722,40 @@ packages:
     resolution: {integrity: sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==}
     engines: {node: '>= 0.4'}
 
+  hast-util-from-parse5@8.0.3:
+    resolution: {integrity: sha512-3kxEVkEKt0zvcZ3hCRYI8rqrgwtlIOFMWkbclACvjlDw8Li9S2hk/d51OI0nr/gIpdMHNepwgOKqZ/sy0Clpyg==}
+
+  hast-util-parse-selector@4.0.0:
+    resolution: {integrity: sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==}
+
+  hast-util-raw@9.1.0:
+    resolution: {integrity: sha512-Y8/SBAHkZGoNkpzqqfCldijcuUKh7/su31kEBp67cFY09Wy0mTRgtsLYsiIxMJxlu0f6AA5SUTbDR8K0rxnbUw==}
+
+  hast-util-to-estree@3.1.3:
+    resolution: {integrity: sha512-48+B/rJWAp0jamNbAAf9M7Uf//UVqAoMmgXhBdxTDJLGKY+LRnZ99qcG+Qjl5HfMpYNzS5v4EAwVEF34LeAj7w==}
+
+  hast-util-to-html@9.0.5:
+    resolution: {integrity: sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==}
+
+  hast-util-to-jsx-runtime@2.3.6:
+    resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==}
+
+  hast-util-to-parse5@8.0.1:
+    resolution: {integrity: sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA==}
+
+  hast-util-whitespace@3.0.0:
+    resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
+
+  hastscript@9.0.1:
+    resolution: {integrity: sha512-g7df9rMFX/SPi34tyGCyUBREQoKkapwdY/T04Qn9TDWfHhAYt4/I0gMVirzK5wEzeUqIjEB+LXC/ypb7Aqno5w==}
+
   hono@4.12.28:
     resolution: {integrity: sha512-YwUvVpSF7m1yOblFPrU3Hbo8XhPheBoiyfGuII6z19LnOr6JpDnyyp7LFNrfV56wS8tpvtBFGRISHN02pDdLOA==}
     engines: {node: '>=16.9.0'}
 
+  html-void-elements@3.0.0:
+    resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==}
+
   http-errors@2.0.1:
     resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
     engines: {node: '>= 0.8'}
@@ -3008,6 +3799,9 @@ packages:
   ini@1.3.8:
     resolution: {integrity: sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==}
 
+  inline-style-parser@0.2.7:
+    resolution: {integrity: sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==}
+
   input-otp@1.4.2:
     resolution: {integrity: sha512-l3jWwYNvrEa6NTCt7BECfCm48GvwuZzkoeG3gBL2w4CHeOXW3eKFmf9UNYkNfYc3mxMrthMnxjIE07MT0zLBQA==}
     peerDependencies:
@@ -3030,9 +3824,18 @@ packages:
     resolution: {integrity: sha512-9VGk3HGanVE6JoZXHiCpnGy5X0jYDnN4EA4lntFPj+1vIWlFhIylq2CrrCOJH9EAhc5CYhq18F2Av2tgoAPsYQ==}
     engines: {node: '>= 10'}
 
+  is-alphabetical@2.0.1:
+    resolution: {integrity: sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==}
+
+  is-alphanumerical@2.0.1:
+    resolution: {integrity: sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==}
+
   is-arrayish@0.2.1:
     resolution: {integrity: sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==}
 
+  is-decimal@2.0.1:
+    resolution: {integrity: sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==}
+
   is-docker@2.2.1:
     resolution: {integrity: sha512-F+i2BKsFrH66iaUFc0woD8sLy8getkwTwtOBjvs56Cx4CgJDeKQeqfz8wAYiSb8JOprWhHH5p77PbmYCvvUuXQ==}
     engines: {node: '>=8'}
@@ -3055,6 +3858,9 @@ packages:
     resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
     engines: {node: '>=0.10.0'}
 
+  is-hexadecimal@2.0.1:
+    resolution: {integrity: sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==}
+
   is-in-ssh@1.0.0:
     resolution: {integrity: sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw==}
     engines: {node: '>=20'}
@@ -3160,6 +3966,10 @@ packages:
     resolution: {integrity: sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==}
     hasBin: true
 
+  js-yaml@5.2.1:
+    resolution: {integrity: sha512-zfLtNfQqxVqq3uaTqSkh4x4hZw3KHobGUA0fJUj4wawW8bsQLTVqpHdXSIzidh7o+4lEW36tANuAGdaFx6Zgnw==}
+    hasBin: true
+
   jsesc@3.1.0:
     resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==}
     engines: {node: '>=6'}
@@ -3312,6 +4122,9 @@ packages:
   long@5.3.2:
     resolution: {integrity: sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==}
 
+  longest-streak@3.1.0:
+    resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==}
+
   lru-cache@11.5.2:
     resolution: {integrity: sha512-4pfM1Ff0x50o0tQwb5ucw/RzNyD0/YJME6IVcStalZuMWxdt3sR3huStTtxz4PUmvZfRguvDejasvQ2kifR11g==}
     engines: {node: 20 || >=22}
@@ -3319,13 +4132,73 @@ packages:
   lru-cache@5.1.1:
     resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
 
+  lucide-react@1.23.0:
+    resolution: {integrity: sha512-38BpJcD0JhFosxHApP/BYsBetLpQFRoTRzEzstM/XCc3jsAG7wqaY1lgVwxiUe3xqYE+lNxo2PkCmYwXWrwwIw==}
+    peerDependencies:
+      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
+  markdown-extensions@2.0.0:
+    resolution: {integrity: sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q==}
+    engines: {node: '>=16'}
+
+  markdown-table@3.0.4:
+    resolution: {integrity: sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==}
+
   math-intrinsics@1.1.0:
     resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
     engines: {node: '>= 0.4'}
 
+  mdast-util-find-and-replace@3.0.2:
+    resolution: {integrity: sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==}
+
+  mdast-util-from-markdown@2.0.3:
+    resolution: {integrity: sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==}
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    resolution: {integrity: sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==}
+
+  mdast-util-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==}
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    resolution: {integrity: sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==}
+
+  mdast-util-gfm-table@2.0.0:
+    resolution: {integrity: sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==}
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    resolution: {integrity: sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==}
+
+  mdast-util-gfm@3.1.0:
+    resolution: {integrity: sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==}
+
+  mdast-util-mdx-expression@2.0.1:
+    resolution: {integrity: sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==}
+
+  mdast-util-mdx-jsx@3.2.0:
+    resolution: {integrity: sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==}
+
+  mdast-util-mdx@3.0.0:
+    resolution: {integrity: sha512-JfbYLAW7XnYTTbUsmpu0kdBUVe+yKVJZBItEjwyYJiDJuZ9w4eeaqks4HQO+R7objWgS2ymV60GYpI14Ug554w==}
+
+  mdast-util-mdxjs-esm@2.0.1:
+    resolution: {integrity: sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==}
+
+  mdast-util-phrasing@4.1.0:
+    resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==}
+
+  mdast-util-to-hast@13.2.1:
+    resolution: {integrity: sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==}
+
+  mdast-util-to-markdown@2.1.2:
+    resolution: {integrity: sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==}
+
+  mdast-util-to-string@4.0.0:
+    resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==}
+
   media-typer@1.1.0:
     resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==}
     engines: {node: '>= 0.8'}
@@ -3341,6 +4214,111 @@ packages:
     resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
     engines: {node: '>= 8'}
 
+  micromark-core-commonmark@2.0.3:
+    resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==}
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    resolution: {integrity: sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==}
+
+  micromark-extension-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==}
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    resolution: {integrity: sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==}
+
+  micromark-extension-gfm-table@2.1.1:
+    resolution: {integrity: sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==}
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    resolution: {integrity: sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==}
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    resolution: {integrity: sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==}
+
+  micromark-extension-gfm@3.0.0:
+    resolution: {integrity: sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==}
+
+  micromark-extension-mdx-expression@3.0.1:
+    resolution: {integrity: sha512-dD/ADLJ1AeMvSAKBwO22zG22N4ybhe7kFIZ3LsDI0GlsNr2A3KYxb0LdC1u5rj4Nw+CHKY0RVdnHX8vj8ejm4Q==}
+
+  micromark-extension-mdx-jsx@3.0.2:
+    resolution: {integrity: sha512-e5+q1DjMh62LZAJOnDraSSbDMvGJ8x3cbjygy2qFEi7HCeUT4BDKCvMozPozcD6WmOt6sVvYDNBKhFSz3kjOVQ==}
+
+  micromark-extension-mdx-md@2.0.0:
+    resolution: {integrity: sha512-EpAiszsB3blw4Rpba7xTOUptcFeBFi+6PY8VnJ2hhimH+vCQDirWgsMpz7w1XcZE7LVrSAUGb9VJpG9ghlYvYQ==}
+
+  micromark-extension-mdxjs-esm@3.0.0:
+    resolution: {integrity: sha512-DJFl4ZqkErRpq/dAPyeWp15tGrcrrJho1hKK5uBS70BCtfrIFg81sqcTVu3Ta+KD1Tk5vAtBNElWxtAa+m8K9A==}
+
+  micromark-extension-mdxjs@3.0.0:
+    resolution: {integrity: sha512-A873fJfhnJ2siZyUrJ31l34Uqwy4xIFmvPY1oj+Ean5PHcPBYzEsvqvWGaWcfEIr11O5Dlw3p2y0tZWpKHDejQ==}
+
+  micromark-factory-destination@2.0.1:
+    resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==}
+
+  micromark-factory-label@2.0.1:
+    resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==}
+
+  micromark-factory-mdx-expression@2.0.3:
+    resolution: {integrity: sha512-kQnEtA3vzucU2BkrIa8/VaSAsP+EJ3CKOvhMuJgOEGg9KDC6OAY6nSnNDVRiVNRqj7Y4SlSzcStaH/5jge8JdQ==}
+
+  micromark-factory-space@2.0.1:
+    resolution: {integrity: sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==}
+
+  micromark-factory-title@2.0.1:
+    resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==}
+
+  micromark-factory-whitespace@2.0.1:
+    resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==}
+
+  micromark-util-character@2.1.1:
+    resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==}
+
+  micromark-util-chunked@2.0.1:
+    resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==}
+
+  micromark-util-classify-character@2.0.1:
+    resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==}
+
+  micromark-util-combine-extensions@2.0.1:
+    resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==}
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==}
+
+  micromark-util-decode-string@2.0.1:
+    resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==}
+
+  micromark-util-encode@2.0.1:
+    resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==}
+
+  micromark-util-events-to-acorn@2.0.3:
+    resolution: {integrity: sha512-jmsiEIiZ1n7X1Rr5k8wVExBQCg5jy4UXVADItHmNk1zkwEVhBuIUKRu3fqv+hs4nxLISi2DQGlqIOGiFxgbfHg==}
+
+  micromark-util-html-tag-name@2.0.1:
+    resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==}
+
+  micromark-util-normalize-identifier@2.0.1:
+    resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==}
+
+  micromark-util-resolve-all@2.0.1:
+    resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==}
+
+  micromark-util-sanitize-uri@2.0.1:
+    resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==}
+
+  micromark-util-subtokenize@2.1.0:
+    resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==}
+
+  micromark-util-symbol@2.0.1:
+    resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==}
+
+  micromark-util-types@2.0.2:
+    resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==}
+
+  micromark@4.0.2:
+    resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==}
+
   micromatch@4.0.8:
     resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
     engines: {node: '>=8.6'}
@@ -3395,6 +4373,26 @@ packages:
   mlly@1.8.2:
     resolution: {integrity: sha512-d+ObxMQFmbt10sretNDytwt85VrbkhhUA/JBGm1MPaWJ65Cl4wOgLaB1NYvJSZ0Ef03MMEU/0xpPMXUIQ29UfA==}
 
+  motion-dom@12.42.2:
+    resolution: {integrity: sha512-5gIMWLp/PycBtJRJWRgjxke5n8dlvkSn2DrYW+tr3XcqAZY1xZh6BJyooJXCM8wdfM7wfMjkBJNLge1CKPUIRA==}
+
+  motion-utils@12.39.0:
+    resolution: {integrity: sha512-8nadJAJjTtqRkmRF36FoJTrywK9nnFmnPwnSMyxaOCU7GDjN9RTMJIxx9De8ErM+vpPhMccr/6fo5WciyQLnMQ==}
+
+  motion@12.42.2:
+    resolution: {integrity: sha512-Atvv11yUKIid41cVrRBDVX5m8tF8kNpExRSlbpt6APClhDjtwQssgFHhQzejxw7/7YYbjHSPKBVbHo05BuJT5Q==}
+    peerDependencies:
+      '@emotion/is-prop-valid': '*'
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@emotion/is-prop-valid':
+        optional: true
+      react:
+        optional: true
+      react-dom:
+        optional: true
+
   mri@1.2.0:
     resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==}
     engines: {node: '>=4'}
@@ -3426,6 +4424,27 @@ packages:
       react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
       react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
 
+  next@16.2.10:
+    resolution: {integrity: sha512-2som5AVXb3kE6Yjine3/mNbBayYF58eguBWIVVUdr1y/L426xyVEgYxgBG+1QC34P2x5E+tcDup6XkuOAX3dCA==}
+    engines: {node: '>=20.9.0'}
+    hasBin: true
+    peerDependencies:
+      '@opentelemetry/api': ^1.1.0
+      '@playwright/test': ^1.51.1
+      babel-plugin-react-compiler: '*'
+      react: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      react-dom: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      sass: ^1.3.0
+    peerDependenciesMeta:
+      '@opentelemetry/api':
+        optional: true
+      '@playwright/test':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+      sass:
+        optional: true
+
   node-abi@3.94.0:
     resolution: {integrity: sha512-W5ZNO5KRPB5TkYmGVD9F6YqhsglXJzE6etpbmT+f6EQElhiX/UTG551cnsRGvLG3fyZEg9HwaDmNmj5nwJ4z9g==}
     engines: {node: '>=10'}
@@ -3477,6 +4496,12 @@ packages:
     resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==}
     engines: {node: '>=18'}
 
+  oniguruma-parser@0.12.2:
+    resolution: {integrity: sha512-6HVa5oIrgMC6aA6WF6XyyqbhRPJrKR02L20+2+zpDtO5QAzGHAUGw5TKQvwi5vctNnRHkJYmjAhRVQF2EKdTQw==}
+
+  oniguruma-to-es@4.3.6:
+    resolution: {integrity: sha512-csuQ9x3Yr0cEIs/Zgx/OEt9iBw9vqIunAPQkx19R/fiMq2oGVTgcMqO/V3Ybqefr1TBvosI6jU539ksaBULJyA==}
+
   open@11.0.0:
     resolution: {integrity: sha512-smsWv2LzFjP03xmvFoJ331ss6h+jixfA4UUV/Bsiyuu4YJPfN+FIQGOIiv4w9/+MoHkfkJ22UIaQWRVFRfH6Vw==}
     engines: {node: '>=20'}
@@ -3535,6 +4560,9 @@ packages:
     resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
     engines: {node: '>=6'}
 
+  parse-entities@4.0.2:
+    resolution: {integrity: sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==}
+
   parse-json@5.2.0:
     resolution: {integrity: sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==}
     engines: {node: '>=8'}
@@ -3543,6 +4571,9 @@ packages:
     resolution: {integrity: sha512-TXfryirbmq34y8QBwgqCVLi+8oA3oWx2eAnSn62ITyEhEYaWRlVZ2DvMM9eZbMs/RfxPu/PK/aBLyGj4IrqMHw==}
     engines: {node: '>=18'}
 
+  parse5@7.3.0:
+    resolution: {integrity: sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==}
+
   parseurl@1.3.3:
     resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==}
     engines: {node: '>= 0.8'}
@@ -3645,6 +4676,10 @@ packages:
     resolution: {integrity: sha512-HeP7D2wyhkR+XaK6v4W8oRF62Dsz4flyuczALJp61GckGm42u1saSSJ/0auvcBqxs3jMRFEcPK34At/0JBKdOg==}
     engines: {node: '>=4'}
 
+  postcss@8.4.31:
+    resolution: {integrity: sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==}
+    engines: {node: ^10 || ^12 || >=14}
+
   postcss@8.5.16:
     resolution: {integrity: sha512-vuwillviilfKZsg0VGj5R/YwwcHx4SLsIOI/7K6mQkWx+l5cUHTjj5g0AasTBcyXsbfTgrwsUNmVUb5xVwyPwg==}
     engines: {node: ^10 || ^12 || >=14}
@@ -3683,6 +4718,9 @@ packages:
     resolution: {integrity: sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==}
     engines: {node: '>= 6'}
 
+  property-information@7.2.0:
+    resolution: {integrity: sha512-IAtzIB6sUiWaJYrX9smp3V46pBGbBeLFRGdh25kg1334VcBlD8HzhPeNIWQH9zhGmo2itIe25EHt9dQP7G5hmg==}
+
   protobufjs@7.6.5:
     resolution: {integrity: sha512-/FPD0nUc9jH6rfFjji9IBqOz4pcSE3CsT1m7Ep6Mdb0LxSUMj8hgl6GomOvZzpNpAqqGaXA0P3VSrZLFzIhQrw==}
     engines: {node: '>=12.0.0'}
@@ -3824,6 +4862,20 @@ packages:
       react-dom: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
       react-is: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
+  recma-build-jsx@1.0.0:
+    resolution: {integrity: sha512-8GtdyqaBcDfva+GUKDr3nev3VpKAhup1+RvkMvUxURHpW7QyIvk9F5wz7Vzo06CEMSilw6uArgRqhpiUcWp8ew==}
+
+  recma-jsx@1.0.1:
+    resolution: {integrity: sha512-huSIy7VU2Z5OLv6oFLosQGGDqPqdO1iq6bWNAdhzMxSJP7RAso4fCZ1cKu8j9YHCZf3TPrq4dw3okhrylgcd7w==}
+    peerDependencies:
+      acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
+
+  recma-parse@1.0.0:
+    resolution: {integrity: sha512-OYLsIGBB5Y5wjnSnQW6t3Xg7q3fQ7FWbw/vcXtORTnyaSFscOtABg+7Pnz6YZ6c27fG1/aN8CjfwoUEUIdwqWQ==}
+
+  recma-stringify@1.0.0:
+    resolution: {integrity: sha512-cjwII1MdIIVloKvC9ErQ+OgAtwHBmcZ0Bg4ciz78FtbT8In39aAYbaA7zvxQ61xVMSPE8WxhLwLbhif4Js2C+g==}
+
   redux-thunk@3.1.0:
     resolution: {integrity: sha512-NW2r5T6ksUKXCabzhL9z+h206HQw/NJkcLm1GPImRQ8IzfXwRGqjVhKJGauHirT0DAuyy6hjdnMZaRoAcy0Klw==}
     peerDependencies:
@@ -3832,6 +4884,39 @@ packages:
   redux@5.0.1:
     resolution: {integrity: sha512-M9/ELqF6fy8FwmkpnF0S3YKOqMyoWJ4+CS5Efg2ct3oY9daQvd/Pc71FpGZsVsbl3Cpb+IIcjBDUnnyBdQbq4w==}
 
+  regex-recursion@6.0.2:
+    resolution: {integrity: sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==}
+
+  regex-utilities@2.3.0:
+    resolution: {integrity: sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==}
+
+  regex@6.1.0:
+    resolution: {integrity: sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==}
+
+  rehype-raw@7.0.0:
+    resolution: {integrity: sha512-/aE8hCfKlQeA8LmyeyQvQF3eBiLRGNlfBJEvWH7ivp9sBqs7TNqBL5X3v157rM4IFETqDnIOO+z5M/biZbo9Ww==}
+
+  rehype-recma@1.0.0:
+    resolution: {integrity: sha512-lqA4rGUf1JmacCNWWZx0Wv1dHqMwxzsDWYMTowuplHF3xH0N/MmrZ/G3BDZnzAkRmxDadujCjaKM2hqYdCBOGw==}
+
+  remark-gfm@4.0.1:
+    resolution: {integrity: sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==}
+
+  remark-mdx@3.1.1:
+    resolution: {integrity: sha512-Pjj2IYlUY3+D8x00UJsIOg5BEvfMyeI+2uLPn9VO9Wg4MEtN/VTIq2NEJQfde9PnX15KgtHyl9S0BcTnWrIuWg==}
+
+  remark-parse@11.0.0:
+    resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==}
+
+  remark-rehype@11.1.2:
+    resolution: {integrity: sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==}
+
+  remark-stringify@11.0.0:
+    resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==}
+
+  remark@15.0.1:
+    resolution: {integrity: sha512-Eht5w30ruCXgFmxVUSlNWQ9iiimq07URKeFS3hNc8cUWy1llX4KDWfyEDZRycMc+znsN9Ux5/tJ/BFdgdOwA3A==}
+
   require-directory@2.1.1:
     resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
     engines: {node: '>=0.10.0'}
@@ -3910,6 +4995,9 @@ packages:
   scheduler@0.27.0:
     resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
 
+  scroll-into-view-if-needed@3.1.0:
+    resolution: {integrity: sha512-49oNpRjWRvnU8NyGVmUaYG4jtTkNonFZI86MmGRDqBphEK2EXT9gdEUoQPZhuBM8yWHxCWbobltqYO5M4XrUvQ==}
+
   secure-json-parse@4.1.0:
     resolution: {integrity: sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA==}
 
@@ -3951,6 +5039,10 @@ packages:
     engines: {node: '>=20.18.1'}
     hasBin: true
 
+  sharp@0.34.5:
+    resolution: {integrity: sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+
   shebang-command@2.0.0:
     resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
     engines: {node: '>=8'}
@@ -3959,6 +5051,10 @@ packages:
     resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
     engines: {node: '>=8'}
 
+  shiki@4.3.1:
+    resolution: {integrity: sha512-oR+qDVi2OjX1tmDpyv+3KviX01KzO6Af+0NNnKnsp9491UEGz2YpxTuJboS/6VhYpTdqzmuJBuiTlrAWWJAssw==}
+    engines: {node: '>=20'}
+
   side-channel-list@1.0.1:
     resolution: {integrity: sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==}
     engines: {node: '>= 0.4'}
@@ -4022,6 +5118,9 @@ packages:
     resolution: {integrity: sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==}
     engines: {node: '>= 12'}
 
+  space-separated-tokens@2.0.2:
+    resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==}
+
   spawndamnit@3.0.1:
     resolution: {integrity: sha512-MmnduQUuHCoFckZoWnXsTg7JaiLBJrKFj9UI2MbRPGaJeVpsLcVBu6P/IGZovziM/YBsellCmsprgNA+w0CzVg==}
 
@@ -4064,6 +5163,9 @@ packages:
   string_decoder@1.3.0:
     resolution: {integrity: sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==}
 
+  stringify-entities@4.0.4:
+    resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==}
+
   stringify-object@5.0.0:
     resolution: {integrity: sha512-zaJYxz2FtcMb4f+g60KsRNFOpVMUyuJgA51Zi5Z1DOTC3S59+OQiVOzE9GZt0x72uBGWKsQIuBKeF9iusmKFsg==}
     engines: {node: '>=14.16'}
@@ -4092,6 +5194,25 @@ packages:
     resolution: {integrity: sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==}
     engines: {node: '>=0.10.0'}
 
+  style-to-js@1.1.21:
+    resolution: {integrity: sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==}
+
+  style-to-object@1.0.14:
+    resolution: {integrity: sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==}
+
+  styled-jsx@5.1.6:
+    resolution: {integrity: sha512-qSVyDTeMotdvQYoHWLNGwRFJHC+i+ZvdBRYosOFgC+Wg1vx4frN2/RG/NA7SYqqvKNLf39P2LSRA2pu6n0XYZA==}
+    engines: {node: '>= 12.0.0'}
+    peerDependencies:
+      '@babel/core': '*'
+      babel-plugin-macros: '*'
+      react: '>= 16.8.0 || 17.x.x || ^18.0.0-0 || ^19.0.0-0'
+    peerDependenciesMeta:
+      '@babel/core':
+        optional: true
+      babel-plugin-macros:
+        optional: true
+
   sucrase@3.35.1:
     resolution: {integrity: sha512-DhuTmvZWux4H1UOnWMB3sk0sbaCVOoQZjv8u1rDoTV0HTdGem9hkAZtl4JZy8P2z4Bg0nT+YMeOFyVr4zcG5Tw==}
     engines: {node: '>=16 || 14 >=14.17'}
@@ -4176,6 +5297,12 @@ packages:
     resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==}
     hasBin: true
 
+  trim-lines@3.0.1:
+    resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==}
+
+  trough@2.2.0:
+    resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==}
+
   ts-interface-checker@0.1.13:
     resolution: {integrity: sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==}
 
@@ -4252,6 +5379,30 @@ packages:
     resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
     engines: {node: '>=18'}
 
+  unified@11.0.5:
+    resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
+
+  unist-util-is@6.0.1:
+    resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==}
+
+  unist-util-position-from-estree@2.0.0:
+    resolution: {integrity: sha512-KaFVRjoqLyF6YXCbVLNad/eS4+OfPQQn2yOd7zF/h5T/CSL2v8NpN6a5TPvtbXthAGw5nG+PuTtq+DdIZr+cRQ==}
+
+  unist-util-position@5.0.0:
+    resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==}
+
+  unist-util-remove-position@5.0.0:
+    resolution: {integrity: sha512-Hp5Kh3wLxv0PHj9m2yZhhLt58KzPtEYKQQ4yxfYFEO7EvHwzyDYnduhHnY1mDxoqr7VUwVuHXk9RXKIiYS1N8Q==}
+
+  unist-util-stringify-position@4.0.0:
+    resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==}
+
+  unist-util-visit-parents@6.0.2:
+    resolution: {integrity: sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==}
+
+  unist-util-visit@5.1.0:
+    resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
+
   universalify@0.1.2:
     resolution: {integrity: sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==}
     engines: {node: '>= 4.0.0'}
@@ -4339,6 +5490,15 @@ packages:
     resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
     engines: {node: '>= 0.8'}
 
+  vfile-location@5.0.3:
+    resolution: {integrity: sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==}
+
+  vfile-message@4.0.3:
+    resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
+
+  vfile@6.0.3:
+    resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
+
   victory-vendor@37.3.6:
     resolution: {integrity: sha512-SbPDPdDBYp+5MJHhBCAyI7wKM3d5ivekigc2Dk2s7pgbZ9wIgIBYGVw4zGHBml/qTFbexrofXW6Gu4noGxrOwQ==}
 
@@ -4432,6 +5592,9 @@ packages:
   vscode-languageserver-types@3.18.0:
     resolution: {integrity: sha512-8TsGPNMIMiiBdkORgRSvLjuiEIiAFtO+KssmYWxQ+uSVvlf7RjK8YKCOjPzZ+YA04jXEV7+7LvkSmHkhpNS99g==}
 
+  web-namespaces@2.0.1:
+    resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==}
+
   webpack-virtual-modules@0.6.2:
     resolution: {integrity: sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ==}
 
@@ -4504,8 +5667,13 @@ packages:
   zod@4.4.3:
     resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}
 
+  zwitch@2.0.4:
+    resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
+
 snapshots:
 
+  '@alloc/quick-lru@5.2.0': {}
+
   '@babel/code-frame@7.29.7':
     dependencies:
       '@babel/helper-validator-identifier': 7.29.7
@@ -5349,6 +6517,17 @@ snapshots:
 
   '@fontsource-variable/inter@5.2.8': {}
 
+  '@fuma-translate/react@1.0.2(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@fumadocs/tailwind@0.1.0(tailwindcss@4.3.2)':
+    optionalDependencies:
+      tailwindcss: 4.3.2
+
   '@grpc/grpc-js@1.14.4':
     dependencies:
       '@grpc/proto-loader': 0.8.1
@@ -5378,6 +6557,103 @@ snapshots:
     dependencies:
       react: 19.2.7
 
+  '@img/colour@1.1.0':
+    optional: true
+
+  '@img/sharp-darwin-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-darwin-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-darwin-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-darwin-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-s390x@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-linux-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-arm@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-ppc64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-s390x@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-s390x': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-linuxmusl-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-wasm32@0.34.5':
+    dependencies:
+      '@emnapi/runtime': 1.11.1
+    optional: true
+
+  '@img/sharp-win32-arm64@0.34.5':
+    optional: true
+
+  '@img/sharp-win32-ia32@0.34.5':
+    optional: true
+
+  '@img/sharp-win32-x64@0.34.5':
+    optional: true
+
   '@inquirer/external-editor@1.0.3(@types/node@26.1.0)':
     dependencies:
       chardet: 2.2.0
@@ -5430,6 +6706,36 @@ snapshots:
       globby: 11.1.0
       read-yaml-file: 1.1.0
 
+  '@mdx-js/mdx@3.1.1':
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.5
+      '@types/mdx': 2.0.14
+      acorn: 8.17.0
+      collapse-white-space: 2.1.0
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      estree-util-scope: 1.0.0
+      estree-walker: 3.0.3
+      hast-util-to-jsx-runtime: 2.3.6
+      markdown-extensions: 2.0.0
+      recma-build-jsx: 1.0.0
+      recma-jsx: 1.0.1(acorn@8.17.0)
+      recma-stringify: 1.0.0
+      rehype-recma: 1.0.0
+      remark-mdx: 3.1.1
+      remark-parse: 11.0.0
+      remark-rehype: 11.1.2
+      source-map: 0.7.6
+      unified: 11.0.5
+      unist-util-position-from-estree: 2.0.0
+      unist-util-stringify-position: 4.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
   '@modelcontextprotocol/sdk@1.29.0(zod@3.25.76)':
     dependencies:
       '@hono/node-server': 1.19.14(hono@4.12.28)
@@ -5459,6 +6765,32 @@ snapshots:
       '@tybys/wasm-util': 0.10.3
     optional: true
 
+  '@next/env@16.2.10': {}
+
+  '@next/swc-darwin-arm64@16.2.10':
+    optional: true
+
+  '@next/swc-darwin-x64@16.2.10':
+    optional: true
+
+  '@next/swc-linux-arm64-gnu@16.2.10':
+    optional: true
+
+  '@next/swc-linux-arm64-musl@16.2.10':
+    optional: true
+
+  '@next/swc-linux-x64-gnu@16.2.10':
+    optional: true
+
+  '@next/swc-linux-x64-musl@16.2.10':
+    optional: true
+
+  '@next/swc-win32-arm64-msvc@16.2.10':
+    optional: true
+
+  '@next/swc-win32-x64-msvc@16.2.10':
+    optional: true
+
   '@nodelib/fs.scandir@2.1.5':
     dependencies:
       '@nodelib/fs.stat': 2.0.5
@@ -5471,6 +6803,8 @@ snapshots:
       '@nodelib/fs.scandir': 2.1.5
       fastq: 1.20.1
 
+  '@orama/orama@3.1.18': {}
+
   '@oxc-project/types@0.138.0': {}
 
   '@pinojs/redact@0.4.0': {}
@@ -5495,21 +6829,164 @@ snapshots:
 
   '@protobufjs/utf8@1.1.2': {}
 
+  '@radix-ui/number@1.1.2': {}
+
   '@radix-ui/primitive@1.1.5': {}
 
-  '@radix-ui/react-compose-refs@1.1.3(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-accordion@1.2.16(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.5
+      '@radix-ui/react-collapsible': 1.1.16(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-collection': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-arrow@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-collapsible@1.1.16(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.5
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-collection@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-compose-refs@1.1.3(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-context@1.2.0(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-dialog@1.1.19(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.5
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-dismissable-layer': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-focus-guards': 1.1.4(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-focus-scope': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-portal': 1.1.13(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
+      aria-hidden: 1.2.6
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      react-remove-scroll: 2.7.2(@types/react@19.2.17)(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-direction@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-dismissable-layer@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.5
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-focus-guards@1.1.4(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-focus-scope@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/react-id@1.1.2(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
     optionalDependencies:
       '@types/react': 19.2.17
 
-  '@radix-ui/react-context@1.2.0(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-navigation-menu@1.2.18(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
+      '@radix-ui/primitive': 1.1.5
+      '@radix-ui/react-collection': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-dismissable-layer': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-previous': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-visually-hidden': 1.2.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-dialog@1.1.19(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+  '@radix-ui/react-popover@1.1.19(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
       '@radix-ui/primitive': 1.1.5
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
@@ -5518,6 +6995,7 @@ snapshots:
       '@radix-ui/react-focus-guards': 1.1.4(@types/react@19.2.17)(react@19.2.7)
       '@radix-ui/react-focus-scope': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-popper': 1.3.3(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-portal': 1.1.13(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
@@ -5531,46 +7009,64 @@ snapshots:
       '@types/react': 19.2.17
       '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-dismissable-layer@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+  '@radix-ui/react-popper@1.3.3(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
-      '@radix-ui/primitive': 1.1.5
+      '@floating-ui/react-dom': 2.1.8(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-arrow': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
       '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-rect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-size': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/rect': 1.1.2
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
       '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-focus-guards@1.1.4(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-portal@1.1.13(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-focus-scope@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+  '@radix-ui/react-presence@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
       '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-id@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-primitive@2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-portal@1.1.13(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+  '@radix-ui/react-roving-focus@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
+      '@radix-ui/primitive': 1.1.5
+      '@radix-ui/react-collection': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@19.2.17)(react@19.2.7)
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
@@ -5578,8 +7074,16 @@ snapshots:
       '@types/react': 19.2.17
       '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-presence@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+  '@radix-ui/react-scroll-area@1.2.14(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
+      '@radix-ui/number': 1.1.2
+      '@radix-ui/primitive': 1.1.5
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
@@ -5587,21 +7091,28 @@ snapshots:
       '@types/react': 19.2.17
       '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-primitive@2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+  '@radix-ui/react-slot@1.3.0(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
-      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-slot@1.3.0(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-tabs@1.1.17(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/primitive': 1.1.5
+      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-roving-focus': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
   '@radix-ui/react-use-callback-ref@1.1.2(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
@@ -5624,12 +7135,49 @@ snapshots:
     optionalDependencies:
       '@types/react': 19.2.17
 
+  '@radix-ui/react-use-is-hydrated@0.1.1(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
   '@radix-ui/react-use-layout-effect@1.1.2(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
       react: 19.2.7
     optionalDependencies:
       '@types/react': 19.2.17
 
+  '@radix-ui/react-use-previous@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-use-rect@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      '@radix-ui/rect': 1.1.2
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-use-size@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      react: 19.2.7
+    optionalDependencies:
+      '@types/react': 19.2.17
+
+  '@radix-ui/react-visually-hidden@1.2.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+    optionalDependencies:
+      '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
+
+  '@radix-ui/rect@1.1.2': {}
+
   '@reduxjs/toolkit@2.12.0(react-redux@9.3.0(@types/react@19.2.17)(react@19.2.7)(redux@5.0.1))(react@19.2.7)':
     dependencies:
       '@standard-schema/spec': 1.1.0
@@ -5775,12 +7323,56 @@ snapshots:
       '@types/react': 19.2.17
       react: 19.2.7
 
+  '@shikijs/core@4.3.1':
+    dependencies:
+      '@shikijs/primitive': 4.3.1
+      '@shikijs/types': 4.3.1
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.5
+      hast-util-to-html: 9.0.5
+
+  '@shikijs/engine-javascript@4.3.1':
+    dependencies:
+      '@shikijs/types': 4.3.1
+      '@shikijs/vscode-textmate': 10.0.2
+      oniguruma-to-es: 4.3.6
+
+  '@shikijs/engine-oniguruma@4.3.1':
+    dependencies:
+      '@shikijs/types': 4.3.1
+      '@shikijs/vscode-textmate': 10.0.2
+
+  '@shikijs/langs@4.3.1':
+    dependencies:
+      '@shikijs/types': 4.3.1
+
+  '@shikijs/primitive@4.3.1':
+    dependencies:
+      '@shikijs/types': 4.3.1
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.5
+
+  '@shikijs/themes@4.3.1':
+    dependencies:
+      '@shikijs/types': 4.3.1
+
+  '@shikijs/types@4.3.1':
+    dependencies:
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.5
+
+  '@shikijs/vscode-textmate@10.0.2': {}
+
   '@sindresorhus/merge-streams@4.0.0': {}
 
   '@standard-schema/spec@1.1.0': {}
 
   '@standard-schema/utils@0.3.0': {}
 
+  '@swc/helpers@0.5.15':
+    dependencies:
+      tslib: 2.8.1
+
   '@tailwindcss/node@4.3.2':
     dependencies:
       '@jridgewell/remapping': 2.3.5
@@ -5842,6 +7434,14 @@ snapshots:
       '@tailwindcss/oxide-win32-arm64-msvc': 4.3.2
       '@tailwindcss/oxide-win32-x64-msvc': 4.3.2
 
+  '@tailwindcss/postcss@4.3.2':
+    dependencies:
+      '@alloc/quick-lru': 5.2.0
+      '@tailwindcss/node': 4.3.2
+      '@tailwindcss/oxide': 4.3.2
+      postcss: 8.5.16
+      tailwindcss: 4.3.2
+
   '@tailwindcss/vite@4.3.2(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))':
     dependencies:
       '@tailwindcss/node': 4.3.2
@@ -5979,6 +7579,10 @@ snapshots:
 
   '@types/d3-timer@3.0.2': {}
 
+  '@types/debug@4.1.13':
+    dependencies:
+      '@types/ms': 2.1.0
+
   '@types/deep-eql@4.0.2': {}
 
   '@types/docker-modem@3.0.6':
@@ -5992,8 +7596,24 @@ snapshots:
       '@types/node': 26.1.0
       '@types/ssh2': 1.15.5
 
+  '@types/estree-jsx@1.0.5':
+    dependencies:
+      '@types/estree': 1.0.9
+
   '@types/estree@1.0.9': {}
 
+  '@types/hast@3.0.5':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/mdast@4.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/mdx@2.0.14': {}
+
+  '@types/ms@2.1.0': {}
+
   '@types/node@12.20.55': {}
 
   '@types/node@18.19.130':
@@ -6016,10 +7636,16 @@ snapshots:
     dependencies:
       '@types/node': 18.19.130
 
+  '@types/unist@2.0.11': {}
+
+  '@types/unist@3.0.3': {}
+
   '@types/use-sync-external-store@0.0.6': {}
 
   '@types/validate-npm-package-name@4.0.2': {}
 
+  '@ungap/structured-clone@1.3.2': {}
+
   '@vitejs/plugin-react@6.0.3(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))':
     dependencies:
       '@rolldown/pluginutils': 1.0.1
@@ -6077,6 +7703,10 @@ snapshots:
       mime-types: 3.0.2
       negotiator: 1.0.0
 
+  acorn-jsx@5.3.2(acorn@8.17.0):
+    dependencies:
+      acorn: 8.17.0
+
   acorn@8.17.0: {}
 
   ajv-formats@2.1.1(ajv@8.20.0):
@@ -6130,6 +7760,8 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
+  astring@1.9.0: {}
+
   atomic-sleep@1.0.0: {}
 
   atomically@1.7.0: {}
@@ -6148,6 +7780,8 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  bail@2.0.2: {}
+
   balanced-match@4.0.4: {}
 
   base64-js@1.5.1: {}
@@ -6244,10 +7878,20 @@ snapshots:
 
   caniuse-lite@1.0.30001803: {}
 
+  ccount@2.0.1: {}
+
   chai@6.2.2: {}
 
   chalk@5.6.2: {}
 
+  character-entities-html4@2.1.0: {}
+
+  character-entities-legacy@3.0.0: {}
+
+  character-entities@2.0.2: {}
+
+  character-reference-invalid@2.0.1: {}
+
   chardet@2.2.0: {}
 
   chokidar@4.0.3:
@@ -6272,6 +7916,8 @@ snapshots:
 
   cli-spinners@2.9.2: {}
 
+  client-only@0.0.1: {}
+
   cliui@8.0.1:
     dependencies:
       string-width: 4.2.3
@@ -6292,14 +7938,20 @@ snapshots:
       - '@types/react'
       - '@types/react-dom'
 
+  cnfast@0.0.8: {}
+
   code-block-writer@13.0.3: {}
 
+  collapse-white-space@2.1.0: {}
+
   color-convert@2.0.1:
     dependencies:
       color-name: 1.1.4
 
   color-name@1.1.4: {}
 
+  comma-separated-tokens@2.0.3: {}
+
   commander@11.1.0: {}
 
   commander@14.0.3: {}
@@ -6308,6 +7960,8 @@ snapshots:
 
   compare-versions@6.1.1: {}
 
+  compute-scroll-into-view@3.1.1: {}
+
   conf@10.2.0:
     dependencies:
       ajv: 8.20.0
@@ -6421,6 +8075,10 @@ snapshots:
 
   decimal.js-light@2.5.1: {}
 
+  decode-named-character-reference@1.3.0:
+    dependencies:
+      character-entities: 2.0.2
+
   decompress-response@6.0.0:
     dependencies:
       mimic-response: 3.1.0
@@ -6452,6 +8110,10 @@ snapshots:
 
   detect-node-es@1.1.0: {}
 
+  devlop@1.1.0:
+    dependencies:
+      dequal: 2.0.3
+
   diff@8.0.4: {}
 
   dir-glob@3.0.1:
@@ -6557,6 +8219,8 @@ snapshots:
       ansi-colors: 4.1.3
       strip-ansi: 6.0.1
 
+  entities@6.0.1: {}
+
   env-paths@2.2.1: {}
 
   error-ex@1.3.4:
@@ -6575,6 +8239,20 @@ snapshots:
 
   es-toolkit@1.49.0: {}
 
+  esast-util-from-estree@2.0.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      devlop: 1.1.0
+      estree-util-visit: 2.0.0
+      unist-util-position-from-estree: 2.0.0
+
+  esast-util-from-js@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      acorn: 8.17.0
+      esast-util-from-estree: 2.0.0
+      vfile-message: 4.0.3
+
   esbuild@0.18.20:
     optionalDependencies:
       '@esbuild/android-arm': 0.18.20
@@ -6691,8 +8369,43 @@ snapshots:
 
   escape-html@1.0.3: {}
 
+  escape-string-regexp@5.0.0: {}
+
   esprima@4.0.1: {}
 
+  estree-util-attach-comments@3.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+
+  estree-util-build-jsx@3.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      estree-walker: 3.0.3
+
+  estree-util-is-identifier-name@3.0.0: {}
+
+  estree-util-scope@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      devlop: 1.1.0
+
+  estree-util-to-js@2.0.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      astring: 1.9.0
+      source-map: 0.7.6
+
+  estree-util-value-to-estree@3.5.0:
+    dependencies:
+      '@types/estree': 1.0.9
+
+  estree-util-visit@2.0.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/unist': 3.0.3
+
   estree-walker@3.0.3:
     dependencies:
       '@types/estree': 1.0.9
@@ -6776,6 +8489,8 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  extend@3.0.2: {}
+
   extendable-error@0.1.7: {}
 
   fast-decode-uri-component@1.0.1: {}
@@ -6890,6 +8605,15 @@ snapshots:
 
   forwarded@0.2.0: {}
 
+  framer-motion@12.42.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
+    dependencies:
+      motion-dom: 12.42.2
+      motion-utils: 12.39.0
+      tslib: 2.8.1
+    optionalDependencies:
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
   fresh@2.0.0: {}
 
   fs-constants@1.0.0: {}
@@ -6915,6 +8639,107 @@ snapshots:
   fsevents@2.3.3:
     optional: true
 
+  fumadocs-core@16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3):
+    dependencies:
+      '@orama/orama': 3.1.18
+      estree-util-value-to-estree: 3.5.0
+      github-slugger: 2.0.0
+      hast-util-to-estree: 3.1.3
+      hast-util-to-jsx-runtime: 2.3.6
+      js-yaml: 5.2.1
+      mdast-util-mdx: 3.0.0
+      mdast-util-to-markdown: 2.1.2
+      remark: 15.0.1
+      remark-gfm: 4.0.1
+      remark-rehype: 11.1.2
+      scroll-into-view-if-needed: 3.1.0
+      shiki: 4.3.1
+      tinyglobby: 0.2.17
+      unified: 11.0.5
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+    optionalDependencies:
+      '@mdx-js/mdx': 3.1.1
+      '@tanstack/react-router': 1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      '@types/react': 19.2.17
+      lucide-react: 1.23.0(react@19.2.7)
+      next: 16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      zod: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  fumadocs-mdx@15.1.0(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.2.17)(fumadocs-core@16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)(rolldown@1.1.4)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)):
+    dependencies:
+      '@mdx-js/mdx': 3.1.1
+      '@standard-schema/spec': 1.1.0
+      chokidar: 5.0.0
+      esbuild: 0.28.1
+      estree-util-value-to-estree: 3.5.0
+      fumadocs-core: 16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3)
+      github-slugger: 2.0.0
+      js-yaml: 5.2.1
+      mdast-util-mdx: 3.0.0
+      picocolors: 1.1.1
+      picomatch: 4.0.5
+      tinyexec: 1.2.4
+      tinyglobby: 0.2.17
+      unified: 11.0.5
+      unist-util-remove-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+      zod: 4.4.3
+    optionalDependencies:
+      '@types/mdast': 4.0.4
+      '@types/mdx': 2.0.14
+      '@types/react': 19.2.17
+      next: 16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      react: 19.2.7
+      rolldown: 1.1.4
+      vite: 8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  fumadocs-ui@16.11.1(@types/mdx@2.0.14)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(fumadocs-core@16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(tailwindcss@4.3.2):
+    dependencies:
+      '@fuma-translate/react': 1.0.2(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@fumadocs/tailwind': 0.1.0(tailwindcss@4.3.2)
+      '@radix-ui/react-accordion': 1.2.16(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-collapsible': 1.1.16(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-dialog': 1.1.19(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-navigation-menu': 1.2.18(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-popover': 1.1.19(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-scroll-area': 1.2.14(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-tabs': 1.1.17(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      class-variance-authority: 0.7.1
+      cnfast: 0.0.8
+      fumadocs-core: 16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3)
+      lucide-react: 1.23.0(react@19.2.7)
+      motion: 12.42.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      next-themes: 0.4.6(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      react-remove-scroll: 2.7.2(@types/react@19.2.17)(react@19.2.7)
+      rehype-raw: 7.0.0
+      scroll-into-view-if-needed: 3.1.0
+      shiki: 4.3.1
+      unist-util-visit: 5.1.0
+    optionalDependencies:
+      '@types/mdx': 2.0.14
+      '@types/react': 19.2.17
+      next: 16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+    transitivePeerDependencies:
+      - '@emotion/is-prop-valid'
+      - '@types/react-dom'
+      - tailwindcss
+
   function-bind@1.1.2: {}
 
   fuzzysort@3.1.0: {}
@@ -6960,6 +8785,8 @@ snapshots:
 
   github-from-package@0.0.0: {}
 
+  github-slugger@2.0.0: {}
+
   glob-parent@5.1.2:
     dependencies:
       is-glob: 4.0.3
@@ -6988,18 +8815,128 @@ snapshots:
       merge2: 1.4.1
       slash: 3.0.0
 
-  gopd@1.2.0: {}
+  gopd@1.2.0: {}
+
+  graceful-fs@4.2.11: {}
+
+  has-symbols@1.1.0: {}
+
+  hasown@2.0.4:
+    dependencies:
+      function-bind: 1.1.2
+
+  hast-util-from-parse5@8.0.3:
+    dependencies:
+      '@types/hast': 3.0.5
+      '@types/unist': 3.0.3
+      devlop: 1.1.0
+      hastscript: 9.0.1
+      property-information: 7.2.0
+      vfile: 6.0.3
+      vfile-location: 5.0.3
+      web-namespaces: 2.0.1
+
+  hast-util-parse-selector@4.0.0:
+    dependencies:
+      '@types/hast': 3.0.5
+
+  hast-util-raw@9.1.0:
+    dependencies:
+      '@types/hast': 3.0.5
+      '@types/unist': 3.0.3
+      '@ungap/structured-clone': 1.3.2
+      hast-util-from-parse5: 8.0.3
+      hast-util-to-parse5: 8.0.1
+      html-void-elements: 3.0.0
+      mdast-util-to-hast: 13.2.1
+      parse5: 7.3.0
+      unist-util-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+      web-namespaces: 2.0.1
+      zwitch: 2.0.4
+
+  hast-util-to-estree@3.1.3:
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.5
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      estree-util-attach-comments: 3.0.0
+      estree-util-is-identifier-name: 3.0.0
+      hast-util-whitespace: 3.0.0
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      property-information: 7.2.0
+      space-separated-tokens: 2.0.2
+      style-to-js: 1.1.21
+      unist-util-position: 5.0.0
+      zwitch: 2.0.4
+    transitivePeerDependencies:
+      - supports-color
+
+  hast-util-to-html@9.0.5:
+    dependencies:
+      '@types/hast': 3.0.5
+      '@types/unist': 3.0.3
+      ccount: 2.0.1
+      comma-separated-tokens: 2.0.3
+      hast-util-whitespace: 3.0.0
+      html-void-elements: 3.0.0
+      mdast-util-to-hast: 13.2.1
+      property-information: 7.2.0
+      space-separated-tokens: 2.0.2
+      stringify-entities: 4.0.4
+      zwitch: 2.0.4
+
+  hast-util-to-jsx-runtime@2.3.6:
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/hast': 3.0.5
+      '@types/unist': 3.0.3
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      hast-util-whitespace: 3.0.0
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      property-information: 7.2.0
+      space-separated-tokens: 2.0.2
+      style-to-js: 1.1.21
+      unist-util-position: 5.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
 
-  graceful-fs@4.2.11: {}
+  hast-util-to-parse5@8.0.1:
+    dependencies:
+      '@types/hast': 3.0.5
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      property-information: 7.2.0
+      space-separated-tokens: 2.0.2
+      web-namespaces: 2.0.1
+      zwitch: 2.0.4
 
-  has-symbols@1.1.0: {}
+  hast-util-whitespace@3.0.0:
+    dependencies:
+      '@types/hast': 3.0.5
 
-  hasown@2.0.4:
+  hastscript@9.0.1:
     dependencies:
-      function-bind: 1.1.2
+      '@types/hast': 3.0.5
+      comma-separated-tokens: 2.0.3
+      hast-util-parse-selector: 4.0.0
+      property-information: 7.2.0
+      space-separated-tokens: 2.0.2
 
   hono@4.12.28: {}
 
+  html-void-elements@3.0.0: {}
+
   http-errors@2.0.1:
     dependencies:
       depd: 2.0.0
@@ -7035,6 +8972,8 @@ snapshots:
 
   ini@1.3.8: {}
 
+  inline-style-parser@0.2.7: {}
+
   input-otp@1.4.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
     dependencies:
       react: 19.2.7
@@ -7048,8 +8987,17 @@ snapshots:
 
   ipaddr.js@2.4.0: {}
 
+  is-alphabetical@2.0.1: {}
+
+  is-alphanumerical@2.0.1:
+    dependencies:
+      is-alphabetical: 2.0.1
+      is-decimal: 2.0.1
+
   is-arrayish@0.2.1: {}
 
+  is-decimal@2.0.1: {}
+
   is-docker@2.2.1: {}
 
   is-docker@3.0.0: {}
@@ -7062,6 +9010,8 @@ snapshots:
     dependencies:
       is-extglob: 2.1.1
 
+  is-hexadecimal@2.0.1: {}
+
   is-in-ssh@1.0.0: {}
 
   is-inside-container@1.0.0:
@@ -7131,6 +9081,10 @@ snapshots:
     dependencies:
       argparse: 2.0.1
 
+  js-yaml@5.2.1:
+    dependencies:
+      argparse: 2.0.1
+
   jsesc@3.1.0: {}
 
   json-parse-even-better-errors@2.3.1: {}
@@ -7250,18 +9204,191 @@ snapshots:
 
   long@5.3.2: {}
 
+  longest-streak@3.1.0: {}
+
   lru-cache@11.5.2: {}
 
   lru-cache@5.1.1:
     dependencies:
       yallist: 3.1.1
 
+  lucide-react@1.23.0(react@19.2.7):
+    dependencies:
+      react: 19.2.7
+
   magic-string@0.30.21:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  markdown-extensions@2.0.0: {}
+
+  markdown-table@3.0.4: {}
+
   math-intrinsics@1.1.0: {}
 
+  mdast-util-find-and-replace@3.0.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      escape-string-regexp: 5.0.0
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  mdast-util-from-markdown@2.0.3:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      mdast-util-to-string: 4.0.0
+      micromark: 4.0.2
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-decode-string: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-stringify-position: 4.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-find-and-replace: 3.0.2
+      micromark-util-character: 2.1.1
+
+  mdast-util-gfm-footnote@2.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      micromark-util-normalize-identifier: 2.0.1
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-table@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      markdown-table: 3.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm@3.1.0:
+    dependencies:
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-gfm-autolink-literal: 2.0.1
+      mdast-util-gfm-footnote: 2.1.0
+      mdast-util-gfm-strikethrough: 2.0.0
+      mdast-util-gfm-table: 2.0.0
+      mdast-util-gfm-task-list-item: 2.0.0
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-expression@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-jsx@3.2.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      parse-entities: 4.0.2
+      stringify-entities: 4.0.4
+      unist-util-stringify-position: 4.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx@3.0.0:
+    dependencies:
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdxjs-esm@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-phrasing@4.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      unist-util-is: 6.0.1
+
+  mdast-util-to-hast@13.2.1:
+    dependencies:
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      '@ungap/structured-clone': 1.3.2
+      devlop: 1.1.0
+      micromark-util-sanitize-uri: 2.0.1
+      trim-lines: 3.0.1
+      unist-util-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+
+  mdast-util-to-markdown@2.1.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      longest-streak: 3.1.0
+      mdast-util-phrasing: 4.1.0
+      mdast-util-to-string: 4.0.0
+      micromark-util-classify-character: 2.0.1
+      micromark-util-decode-string: 2.0.1
+      unist-util-visit: 5.1.0
+      zwitch: 2.0.4
+
+  mdast-util-to-string@4.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+
   media-typer@1.1.0: {}
 
   merge-descriptors@2.0.0: {}
@@ -7270,6 +9397,270 @@ snapshots:
 
   merge2@1.4.1: {}
 
+  micromark-core-commonmark@2.0.3:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-factory-destination: 2.0.1
+      micromark-factory-label: 2.0.1
+      micromark-factory-space: 2.0.1
+      micromark-factory-title: 2.0.1
+      micromark-factory-whitespace: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-html-tag-name: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-footnote@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-table@2.1.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm@3.0.0:
+    dependencies:
+      micromark-extension-gfm-autolink-literal: 2.1.0
+      micromark-extension-gfm-footnote: 2.1.0
+      micromark-extension-gfm-strikethrough: 2.1.0
+      micromark-extension-gfm-table: 2.1.1
+      micromark-extension-gfm-tagfilter: 2.0.0
+      micromark-extension-gfm-task-list-item: 2.1.0
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-mdx-expression@3.0.1:
+    dependencies:
+      '@types/estree': 1.0.9
+      devlop: 1.1.0
+      micromark-factory-mdx-expression: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-mdx-jsx@3.0.2:
+    dependencies:
+      '@types/estree': 1.0.9
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      micromark-factory-mdx-expression: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      vfile-message: 4.0.3
+
+  micromark-extension-mdx-md@2.0.0:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-extension-mdxjs-esm@3.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-position-from-estree: 2.0.0
+      vfile-message: 4.0.3
+
+  micromark-extension-mdxjs@3.0.0:
+    dependencies:
+      acorn: 8.17.0
+      acorn-jsx: 5.3.2(acorn@8.17.0)
+      micromark-extension-mdx-expression: 3.0.1
+      micromark-extension-mdx-jsx: 3.0.2
+      micromark-extension-mdx-md: 2.0.0
+      micromark-extension-mdxjs-esm: 3.0.0
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-destination@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-label@2.0.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-mdx-expression@2.0.3:
+    dependencies:
+      '@types/estree': 1.0.9
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-position-from-estree: 2.0.0
+      vfile-message: 4.0.3
+
+  micromark-factory-space@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-title@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-whitespace@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-character@2.1.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-chunked@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-classify-character@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-combine-extensions@2.0.1:
+    dependencies:
+      micromark-util-chunked: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-decode-string@2.0.1:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      micromark-util-character: 2.1.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-encode@2.0.1: {}
+
+  micromark-util-events-to-acorn@2.0.3:
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/unist': 3.0.3
+      devlop: 1.1.0
+      estree-util-visit: 2.0.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      vfile-message: 4.0.3
+
+  micromark-util-html-tag-name@2.0.1: {}
+
+  micromark-util-normalize-identifier@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-resolve-all@2.0.1:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-util-sanitize-uri@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-encode: 2.0.1
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-subtokenize@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-symbol@2.0.1: {}
+
+  micromark-util-types@2.0.2: {}
+
+  micromark@4.0.2:
+    dependencies:
+      '@types/debug': 4.1.13
+      debug: 4.4.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-encode: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
   micromatch@4.0.8:
     dependencies:
       braces: 3.0.3
@@ -7312,6 +9703,20 @@ snapshots:
       pkg-types: 1.3.1
       ufo: 1.6.4
 
+  motion-dom@12.42.2:
+    dependencies:
+      motion-utils: 12.39.0
+
+  motion-utils@12.39.0: {}
+
+  motion@12.42.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
+    dependencies:
+      framer-motion: 12.42.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      tslib: 2.8.1
+    optionalDependencies:
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+
   mri@1.2.0: {}
 
   ms@2.1.3: {}
@@ -7336,6 +9741,30 @@ snapshots:
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
 
+  next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
+    dependencies:
+      '@next/env': 16.2.10
+      '@swc/helpers': 0.5.15
+      baseline-browser-mapping: 2.10.42
+      caniuse-lite: 1.0.30001803
+      postcss: 8.4.31
+      react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
+      styled-jsx: 5.1.6(react@19.2.7)
+    optionalDependencies:
+      '@next/swc-darwin-arm64': 16.2.10
+      '@next/swc-darwin-x64': 16.2.10
+      '@next/swc-linux-arm64-gnu': 16.2.10
+      '@next/swc-linux-arm64-musl': 16.2.10
+      '@next/swc-linux-x64-gnu': 16.2.10
+      '@next/swc-linux-x64-musl': 16.2.10
+      '@next/swc-win32-arm64-msvc': 16.2.10
+      '@next/swc-win32-x64-msvc': 16.2.10
+      sharp: 0.34.5
+    transitivePeerDependencies:
+      - '@babel/core'
+      - babel-plugin-macros
+
   node-abi@3.94.0:
     dependencies:
       semver: 7.8.5
@@ -7377,6 +9806,14 @@ snapshots:
     dependencies:
       mimic-function: 5.0.1
 
+  oniguruma-parser@0.12.2: {}
+
+  oniguruma-to-es@4.3.6:
+    dependencies:
+      oniguruma-parser: 0.12.2
+      regex: 6.1.0
+      regex-recursion: 6.0.2
+
   open@11.0.0:
     dependencies:
       default-browser: 5.5.0
@@ -7444,6 +9881,16 @@ snapshots:
     dependencies:
       callsites: 3.1.0
 
+  parse-entities@4.0.2:
+    dependencies:
+      '@types/unist': 2.0.11
+      character-entities-legacy: 3.0.0
+      character-reference-invalid: 2.0.1
+      decode-named-character-reference: 1.3.0
+      is-alphanumerical: 2.0.1
+      is-decimal: 2.0.1
+      is-hexadecimal: 2.0.1
+
   parse-json@5.2.0:
     dependencies:
       '@babel/code-frame': 7.29.7
@@ -7453,6 +9900,10 @@ snapshots:
 
   parse-ms@4.0.0: {}
 
+  parse5@7.3.0:
+    dependencies:
+      entities: 6.0.1
+
   parseurl@1.3.3: {}
 
   path-browserify@1.0.1: {}
@@ -7534,6 +9985,12 @@ snapshots:
       cssesc: 3.0.0
       util-deprecate: 1.0.2
 
+  postcss@8.4.31:
+    dependencies:
+      nanoid: 3.3.15
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
   postcss@8.5.16:
     dependencies:
       nanoid: 3.3.15
@@ -7574,6 +10031,8 @@ snapshots:
       kleur: 3.0.3
       sisteransi: 1.0.5
 
+  property-information@7.2.0: {}
+
   protobufjs@7.6.5:
     dependencies:
       '@protobufjs/aspromise': 1.1.2
@@ -7732,12 +10191,115 @@ snapshots:
       - '@types/react'
       - redux
 
+  recma-build-jsx@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      estree-util-build-jsx: 3.0.1
+      vfile: 6.0.3
+
+  recma-jsx@1.0.1(acorn@8.17.0):
+    dependencies:
+      acorn: 8.17.0
+      acorn-jsx: 5.3.2(acorn@8.17.0)
+      estree-util-to-js: 2.0.0
+      recma-parse: 1.0.0
+      recma-stringify: 1.0.0
+      unified: 11.0.5
+
+  recma-parse@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      esast-util-from-js: 2.0.1
+      unified: 11.0.5
+      vfile: 6.0.3
+
+  recma-stringify@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      estree-util-to-js: 2.0.0
+      unified: 11.0.5
+      vfile: 6.0.3
+
   redux-thunk@3.1.0(redux@5.0.1):
     dependencies:
       redux: 5.0.1
 
   redux@5.0.1: {}
 
+  regex-recursion@6.0.2:
+    dependencies:
+      regex-utilities: 2.3.0
+
+  regex-utilities@2.3.0: {}
+
+  regex@6.1.0:
+    dependencies:
+      regex-utilities: 2.3.0
+
+  rehype-raw@7.0.0:
+    dependencies:
+      '@types/hast': 3.0.5
+      hast-util-raw: 9.1.0
+      vfile: 6.0.3
+
+  rehype-recma@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/hast': 3.0.5
+      hast-util-to-estree: 3.1.3
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-gfm@4.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-gfm: 3.1.0
+      micromark-extension-gfm: 3.0.0
+      remark-parse: 11.0.0
+      remark-stringify: 11.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-mdx@3.1.1:
+    dependencies:
+      mdast-util-mdx: 3.0.0
+      micromark-extension-mdxjs: 3.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-parse@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      micromark-util-types: 2.0.2
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-rehype@11.1.2:
+    dependencies:
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      mdast-util-to-hast: 13.2.1
+      unified: 11.0.5
+      vfile: 6.0.3
+
+  remark-stringify@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-to-markdown: 2.1.2
+      unified: 11.0.5
+
+  remark@15.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      remark-parse: 11.0.0
+      remark-stringify: 11.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
   require-directory@2.1.1: {}
 
   require-from-string@2.0.2: {}
@@ -7843,6 +10405,10 @@ snapshots:
 
   scheduler@0.27.0: {}
 
+  scroll-into-view-if-needed@3.1.0:
+    dependencies:
+      compute-scroll-into-view: 3.1.1
+
   secure-json-parse@4.1.0: {}
 
   semver@6.3.1: {}
@@ -7924,12 +10490,55 @@ snapshots:
       - supports-color
       - typescript
 
+  sharp@0.34.5:
+    dependencies:
+      '@img/colour': 1.1.0
+      detect-libc: 2.1.2
+      semver: 7.8.5
+    optionalDependencies:
+      '@img/sharp-darwin-arm64': 0.34.5
+      '@img/sharp-darwin-x64': 0.34.5
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
+      '@img/sharp-libvips-darwin-x64': 1.2.4
+      '@img/sharp-libvips-linux-arm': 1.2.4
+      '@img/sharp-libvips-linux-arm64': 1.2.4
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
+      '@img/sharp-libvips-linux-s390x': 1.2.4
+      '@img/sharp-libvips-linux-x64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
+      '@img/sharp-linux-arm': 0.34.5
+      '@img/sharp-linux-arm64': 0.34.5
+      '@img/sharp-linux-ppc64': 0.34.5
+      '@img/sharp-linux-riscv64': 0.34.5
+      '@img/sharp-linux-s390x': 0.34.5
+      '@img/sharp-linux-x64': 0.34.5
+      '@img/sharp-linuxmusl-arm64': 0.34.5
+      '@img/sharp-linuxmusl-x64': 0.34.5
+      '@img/sharp-wasm32': 0.34.5
+      '@img/sharp-win32-arm64': 0.34.5
+      '@img/sharp-win32-ia32': 0.34.5
+      '@img/sharp-win32-x64': 0.34.5
+    optional: true
+
   shebang-command@2.0.0:
     dependencies:
       shebang-regex: 3.0.0
 
   shebang-regex@3.0.0: {}
 
+  shiki@4.3.1:
+    dependencies:
+      '@shikijs/core': 4.3.1
+      '@shikijs/engine-javascript': 4.3.1
+      '@shikijs/engine-oniguruma': 4.3.1
+      '@shikijs/langs': 4.3.1
+      '@shikijs/themes': 4.3.1
+      '@shikijs/types': 4.3.1
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.5
+
   side-channel-list@1.0.1:
     dependencies:
       es-errors: 1.3.0
@@ -7996,6 +10605,8 @@ snapshots:
 
   source-map@0.7.6: {}
 
+  space-separated-tokens@2.0.2: {}
+
   spawndamnit@3.0.1:
     dependencies:
       cross-spawn: 7.0.6
@@ -8039,6 +10650,11 @@ snapshots:
     dependencies:
       safe-buffer: 5.2.1
 
+  stringify-entities@4.0.4:
+    dependencies:
+      character-entities-html4: 2.1.0
+      character-entities-legacy: 3.0.0
+
   stringify-object@5.0.0:
     dependencies:
       get-own-enumerable-keys: 1.0.0
@@ -8061,6 +10677,19 @@ snapshots:
 
   strip-json-comments@2.0.1: {}
 
+  style-to-js@1.1.21:
+    dependencies:
+      style-to-object: 1.0.14
+
+  style-to-object@1.0.14:
+    dependencies:
+      inline-style-parser: 0.2.7
+
+  styled-jsx@5.1.6(react@19.2.7):
+    dependencies:
+      client-only: 0.0.1
+      react: 19.2.7
+
   sucrase@3.35.1:
     dependencies:
       '@jridgewell/gen-mapping': 0.3.13
@@ -8141,6 +10770,10 @@ snapshots:
 
   tree-kill@1.2.2: {}
 
+  trim-lines@3.0.1: {}
+
+  trough@2.2.0: {}
+
   ts-interface-checker@0.1.13: {}
 
   ts-morph@26.0.0:
@@ -8218,6 +10851,48 @@ snapshots:
 
   unicorn-magic@0.3.0: {}
 
+  unified@11.0.5:
+    dependencies:
+      '@types/unist': 3.0.3
+      bail: 2.0.2
+      devlop: 1.1.0
+      extend: 3.0.2
+      is-plain-obj: 4.1.0
+      trough: 2.2.0
+      vfile: 6.0.3
+
+  unist-util-is@6.0.1:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-position-from-estree@2.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-position@5.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-remove-position@5.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-visit: 5.1.0
+
+  unist-util-stringify-position@4.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-visit-parents@6.0.2:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+
+  unist-util-visit@5.1.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
   universalify@0.1.2: {}
 
   universalify@2.0.1: {}
@@ -8266,6 +10941,21 @@ snapshots:
 
   vary@1.1.2: {}
 
+  vfile-location@5.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      vfile: 6.0.3
+
+  vfile-message@4.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-stringify-position: 4.0.0
+
+  vfile@6.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      vfile-message: 4.0.3
+
   victory-vendor@37.3.6:
     dependencies:
       '@types/d3-array': 3.2.2
@@ -8344,6 +11034,8 @@ snapshots:
 
   vscode-languageserver-types@3.18.0: {}
 
+  web-namespaces@2.0.1: {}
+
   webpack-virtual-modules@0.6.2: {}
 
   which@2.0.2:
@@ -8405,3 +11097,5 @@ snapshots:
   zod@3.25.76: {}
 
   zod@4.4.3: {}
+
+  zwitch@2.0.4: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 09d7476..557d18a 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,9 +1,11 @@
 # Workspace members: every directory under packages/ is a package; e2e is its
 # own package — the black-box suite that boots the built daemon and drives it
-# over the wire (the E2B compatibility suite will join it when that layer lands)
+# over the wire (the E2B compatibility suite will join it when that layer lands);
+# website is the public site (Next.js static export), never published to npm
 packages:
   - packages/*
   - e2e
+  - website
 
 # Supply-chain defense: a newly published npm version must be at least 24 hours
 # (1440 minutes) old before it can be installed — poisoned releases are usually
diff --git a/website/app/(home)/layout.tsx b/website/app/(home)/layout.tsx
new file mode 100644
index 0000000..89a06f2
--- /dev/null
+++ b/website/app/(home)/layout.tsx
@@ -0,0 +1,7 @@
+import { HomeLayout } from 'fumadocs-ui/layouts/home';
+import type { ReactNode } from 'react';
+import { baseOptions } from '@/lib/layout.shared';
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return <HomeLayout {...baseOptions()}>{children}</HomeLayout>;
+}
diff --git a/website/app/(home)/page.tsx b/website/app/(home)/page.tsx
new file mode 100644
index 0000000..317ddc4
--- /dev/null
+++ b/website/app/(home)/page.tsx
@@ -0,0 +1,93 @@
+import Link from 'next/link';
+
+const GITHUB_URL = 'https://github.com/BitMiracle-AI/Dormice';
+
+const features = [
+  {
+    title: 'Sandboxes are permanent',
+    body: (
+      <>
+        <code>acquireSandbox(userKey)</code> is the entire mental model — the
+        same key always comes back to the same sandbox: created, woken or
+        restarted as needed.
+      </>
+    ),
+  },
+  {
+    title: 'Idle is free',
+    body: (
+      <>
+        Sandboxes cool down on their own, one rung at a time. Measured on real
+        hardware: 1 GiB of sandbox memory freezes down to ~5 MiB, and waking
+        takes ~50 ms — with every process still running.
+      </>
+    ),
+  },
+  {
+    title: 'Deploys like a single binary',
+    body: (
+      <>
+        One daemon, one SQLite ledger, one port. No Kubernetes, no external
+        database — one install command on a bare Linux host.
+      </>
+    ),
+  },
+  {
+    title: 'E2B compatible',
+    body: (
+      <>
+        The official <code>e2b</code> SDK runs against Dormice by changing two
+        URLs — commands, files, PTY, signed URLs, watch, metrics.
+      </>
+    ),
+  },
+];
+
+export default function HomePage() {
+  return (
+    <main className="flex flex-1 flex-col items-center px-4 py-16 text-center sm:py-24">
+      <h1 className="max-w-3xl text-4xl font-semibold tracking-tight text-balance sm:text-5xl">
+        The SQLite of agent sandboxes
+      </h1>
+      <p className="mt-6 max-w-2xl text-lg text-fd-muted-foreground">
+        A self-hosted sandbox platform for AI agents. One machine, sandboxes
+        that live forever, idle costs nothing.
+      </p>
+      <div className="mt-8 flex items-center gap-3">
+        <Link
+          href="/docs"
+          className="rounded-full bg-fd-primary px-6 py-2.5 text-sm font-medium text-fd-primary-foreground transition-colors hover:bg-fd-primary/90"
+        >
+          Get started
+        </Link>
+        <a
+          href={GITHUB_URL}
+          className="rounded-full border px-6 py-2.5 text-sm font-medium transition-colors hover:bg-fd-accent"
+        >
+          GitHub
+        </a>
+      </div>
+      <p className="mt-4 text-xs text-fd-muted-foreground">
+        Early development: works end to end against real infrastructure, not
+        production-ready yet.
+      </p>
+      <pre className="mt-10 max-w-full overflow-x-auto rounded-lg border bg-fd-card px-5 py-4 text-left text-sm">
+        <code>
+          curl -fsSL
+          https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh
+          | bash
+        </code>
+      </pre>
+      <div className="mt-16 grid w-full max-w-4xl gap-4 text-left sm:grid-cols-2">
+        {features.map((feature) => (
+          <div key={feature.title} className="rounded-lg border bg-fd-card p-6">
+            <h2 className="font-medium">{feature.title}</h2>
+            <p className="mt-2 text-sm text-fd-muted-foreground">
+              {feature.body}
+            </p>
+          </div>
+        ))}
+      </div>
+    </main>
+  );
+}
diff --git a/website/app/api/search/route.ts b/website/app/api/search/route.ts
new file mode 100644
index 0000000..aeb1e44
--- /dev/null
+++ b/website/app/api/search/route.ts
@@ -0,0 +1,8 @@
+import { createFromSource } from 'fumadocs-core/search/server';
+import { source } from '@/lib/source';
+
+// With output: 'export' this route is evaluated once at build time and the
+// whole search index lands in out/ as a static file; the search dialog
+// downloads it and queries client-side (components/search.tsx).
+export const revalidate = false;
+export const { staticGET: GET } = createFromSource(source);
diff --git a/website/app/docs/[[...slug]]/page.tsx b/website/app/docs/[[...slug]]/page.tsx
new file mode 100644
index 0000000..25d1856
--- /dev/null
+++ b/website/app/docs/[[...slug]]/page.tsx
@@ -0,0 +1,44 @@
+import {
+  DocsBody,
+  DocsDescription,
+  DocsPage,
+  DocsTitle,
+} from 'fumadocs-ui/layouts/docs/page';
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { source } from '@/lib/source';
+import { getMDXComponents } from '@/mdx-components';
+
+interface PageProps {
+  params: Promise<{ slug?: string[] }>;
+}
+
+export default async function Page(props: PageProps) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  return (
+    <DocsPage toc={page.data.toc} full={page.data.full}>
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription>{page.data.description}</DocsDescription>
+      <DocsBody>
+        <MDX components={getMDXComponents()} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(props: PageProps): Promise<Metadata> {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  return { title: page.data.title, description: page.data.description };
+}
diff --git a/website/app/docs/layout.tsx b/website/app/docs/layout.tsx
new file mode 100644
index 0000000..d4ebfcd
--- /dev/null
+++ b/website/app/docs/layout.tsx
@@ -0,0 +1,12 @@
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import type { ReactNode } from 'react';
+import { baseOptions } from '@/lib/layout.shared';
+import { source } from '@/lib/source';
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <DocsLayout {...baseOptions()} tree={source.getPageTree()}>
+      {children}
+    </DocsLayout>
+  );
+}
diff --git a/website/app/global.css b/website/app/global.css
new file mode 100644
index 0000000..08ebee2
--- /dev/null
+++ b/website/app/global.css
@@ -0,0 +1,7 @@
+@import "tailwindcss";
+@import "fumadocs-ui/css/neutral.css";
+@import "fumadocs-ui/css/preset.css";
+
+/* Tell Tailwind where fumadocs-ui's class names live (path is relative to
+ * this file; the package is symlinked by pnpm, Tailwind follows it). */
+@source "../node_modules/fumadocs-ui/dist/**/*.js";
diff --git a/website/app/layout.tsx b/website/app/layout.tsx
new file mode 100644
index 0000000..6a98fd9
--- /dev/null
+++ b/website/app/layout.tsx
@@ -0,0 +1,23 @@
+import type { Metadata } from 'next';
+import type { ReactNode } from 'react';
+import { Provider } from './provider';
+import './global.css';
+
+export const metadata: Metadata = {
+  title: {
+    default: 'Dormice — the SQLite of agent sandboxes',
+    template: '%s | Dormice',
+  },
+  description:
+    'A self-hosted sandbox platform for AI agents. One machine, sandboxes that live forever, idle costs nothing.',
+};
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className="flex min-h-screen flex-col">
+        <Provider>{children}</Provider>
+      </body>
+    </html>
+  );
+}
diff --git a/website/app/provider.tsx b/website/app/provider.tsx
new file mode 100644
index 0000000..2c0ac7b
--- /dev/null
+++ b/website/app/provider.tsx
@@ -0,0 +1,11 @@
+'use client';
+
+import { RootProvider } from 'fumadocs-ui/provider/next';
+import type { ReactNode } from 'react';
+import SearchDialog from '@/components/search';
+
+// Client wrapper so the root layout (a server component) can hand
+// RootProvider a component — the static search dialog.
+export function Provider({ children }: { children: ReactNode }) {
+  return <RootProvider search={{ SearchDialog }}>{children}</RootProvider>;
+}
diff --git a/website/components/search.tsx b/website/components/search.tsx
new file mode 100644
index 0000000..1793953
--- /dev/null
+++ b/website/components/search.tsx
@@ -0,0 +1,44 @@
+'use client';
+
+import { useDocsSearch } from 'fumadocs-core/search/client';
+import { oramaStaticClient } from 'fumadocs-core/search/client/orama-static';
+import {
+  SearchDialog,
+  SearchDialogClose,
+  SearchDialogContent,
+  SearchDialogHeader,
+  SearchDialogIcon,
+  SearchDialogInput,
+  SearchDialogList,
+  SearchDialogOverlay,
+  type SharedProps,
+} from 'fumadocs-ui/components/dialog/search';
+
+// Static search: the whole index is exported at build time by
+// app/api/search/route.ts and queried in the browser — no server involved,
+// which is what output: 'export' demands. Module scope so the client (and
+// its downloaded index) survives re-renders.
+const client = oramaStaticClient();
+
+export default function StaticSearchDialog(props: SharedProps) {
+  const { search, setSearch, query } = useDocsSearch({ client });
+
+  return (
+    <SearchDialog
+      search={search}
+      onSearchChange={setSearch}
+      isLoading={query.isLoading}
+      {...props}
+    >
+      <SearchDialogOverlay />
+      <SearchDialogContent>
+        <SearchDialogHeader>
+          <SearchDialogIcon />
+          <SearchDialogInput />
+          <SearchDialogClose />
+        </SearchDialogHeader>
+        <SearchDialogList items={query.data !== 'empty' ? query.data : null} />
+      </SearchDialogContent>
+    </SearchDialog>
+  );
+}
diff --git a/website/content/docs/e2b-compatibility.mdx b/website/content/docs/e2b-compatibility.mdx
new file mode 100644
index 0000000..0995820
--- /dev/null
+++ b/website/content/docs/e2b-compatibility.mdx
@@ -0,0 +1,53 @@
+---
+title: E2B compatibility
+description: The official e2b SDK runs against Dormice by changing two URLs.
+---
+
+The daemon speaks the E2B protocol on two prefixes (`/e2b/api`,
+`/e2b/envd`). The **official `e2b` package** — unmodified, straight from
+npm — runs against Dormice with two URLs and an API-key prefix; migrating
+an application is configuration, not code:
+
+```ts
+import { Sandbox } from 'e2b';
+
+const sbx = await Sandbox.create({
+  apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`,
+  apiUrl: 'http://127.0.0.1:3676/e2b/api',
+  sandboxUrl: 'http://127.0.0.1:3676/e2b/envd',
+});
+```
+
+Everything below is exercised by the black-box e2e suite *through the
+official package*, and has passed against a real Docker + gVisor daemon:
+
+| Surface | Notes |
+| --- | --- |
+| `Sandbox.create` / `connect` / `kill` / `list` | `list` filters by state and metadata, and paginates |
+| Timeouts | `timeoutMs` and `setTimeout()` are real absolute deadlines; `lifecycle: { onTimeout: 'pause' }` parks the sandbox instead of killing it |
+| `pause()` / resume | explicit pause; `connect` revives it, files intact |
+| `commands.run` | live streaming (`onStdout` / `onStderr`), background + `connect` / `disconnect`, `sendStdin`, `kill`, `list`, per-command `envs`, `user: 'root'`; a non-zero exit raises the SDK's own `CommandExitError` |
+| `pty.*` | `create` / `sendInput` / `resize` / `kill` — a real interactive bash |
+| `files` read / write | text or bytes, streamed, no artificial size cap — the disk quota is the cap |
+| `uploadUrl()` / `downloadUrl()` | signed URLs: expiry enforced, a tampered signature is a 401 |
+| `files.list` / `exists` / `makeDir` / `rename` / `remove` | typed errors match the SDK's expectations |
+| `files.watchDir` | streamed events, and the polling watcher API the Python sync SDK uses |
+| `getHost(port)` | port proxy with wake-on-traffic (set `DORMICE_SANDBOX_DOMAIN`) |
+| `getMetrics()` | one live sample; observing never wakes a frozen sandbox |
+
+## Deliberate deltas from the hosted product
+
+- **No template builds.** Every sandbox runs the daemon's single base
+  image (`DORMICE_BASE_IMAGE`); the `template` argument is accepted and
+  ignored.
+- **Freezing keeps processes.** A frozen sandbox's processes suspend and
+  resume mid-flight — any touch wakes the sandbox in ~50 ms.
+- **Permanence stays the default.** Sandboxes created through the E2B
+  surface get real deadlines, as E2B semantics demand; deadlines are never
+  imposed on natively created sandboxes.
+- **`metadata.userKey`** turns `Sandbox.create` into Dormice's idempotent
+  acquire: the same key returns the same sandbox instead of a new one.
+- **Not implemented**, answered with an honest `unimplemented` on the
+  wire: `Process/StreamInput` (the JS SDK never calls it) and xattr-based
+  file metadata. The daemon reports envd `0.6.1`, so the SDK itself gates
+  those features client-side.
diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdx
new file mode 100644
index 0000000..c7c4906
--- /dev/null
+++ b/website/content/docs/index.mdx
@@ -0,0 +1,44 @@
+---
+title: What is Dormice?
+description: A self-hosted sandbox platform for AI agents — one machine, sandboxes that live forever, idle costs nothing.
+---
+
+Cloud sandbox platforms charge for every second a sandbox exists, so their
+sandboxes are disposable. Dormice inverts that: you run it on a machine you
+already pay for, and sandboxes are **permanent** — they just get cheaper to
+keep the longer they sit idle.
+
+- **`acquireSandbox(userKey)` is the entire mental model.** Idempotent: the
+  same key always comes back to the same sandbox, whatever state it was in.
+  No sandbox → create; frozen → wake; stopped → start; archived → restore.
+- **Idle is free.** Sandboxes cool down on their own —
+  `active → frozen → stopped → archived` — one rung at a time, and any
+  acquire brings them back. Measured on real hardware: freezing takes an
+  idle sandbox holding 1 GiB down to ~5 MiB of resident memory, and waking
+  it takes ~50 ms.
+- **Deploys like a single binary.** One daemon, one SQLite ledger, one
+  port. No Kubernetes, no external database.
+- **E2B compatible.** The official `e2b` SDK works against Dormice by
+  changing two URLs — see [E2B compatibility](/docs/e2b-compatibility).
+
+## How it works
+
+The daemon keeps a SQLite ledger of sandboxes and drives Docker + gVisor to
+match it. Each sandbox is a gVisor container with its own disk-quota volume;
+freezing suspends its processes and squeezes their memory out to swap, so an
+idle sandbox costs a few megabytes of RAM and wakes in about 50 ms with all
+its processes still running.
+
+Because the disk — not the container — is the sandbox's body, a sandbox
+survives anything short of an explicit release: the daemon restarts, the
+host reboots, even `docker container prune` eating the container object.
+
+## Status
+
+Early development. The daemon, its lifecycle engine, the SDK, the CLI, the
+web console, the real Docker + gVisor executor, and the E2B-compatible API
+work end to end and pass a black-box test suite against real
+infrastructure. Nothing here is ready for production yet.
+
+Next steps: [Installation](/docs/installation), then the
+[Quick start](/docs/quickstart).
diff --git a/website/content/docs/installation.mdx b/website/content/docs/installation.mdx
new file mode 100644
index 0000000..81a8ccb
--- /dev/null
+++ b/website/content/docs/installation.mdx
@@ -0,0 +1,68 @@
+---
+title: Installation
+description: One command on a bare Ubuntu/Debian x86_64 host.
+---
+
+Run as root on a bare Ubuntu/Debian x86_64 host:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash
+```
+
+Behind a slow connection to the usual sources, add `-s -- --mirror cn`.
+
+The installer is idempotent — re-running it upgrades the code and repairs
+drift, and never rotates your API token. It ends by running `dor doctor`, a
+battery of read-only checks — three of them boot a real gVisor container —
+that decides whether the install actually succeeded; `dor doctor` can be
+re-run on its own at any time.
+
+## What the host needs
+
+The daemon itself runs anywhere Node 22+ runs, with an in-memory fake
+executor for development. Running **real** sandboxes needs a Linux host —
+`install.sh` automates all of it and `dor doctor` verifies it, but these
+are the facts underneath:
+
+- **Docker + gVisor (`runsc`)**, and root (loop mounts, cgroup writes).
+- **Swap, and `vm.swappiness=100`.** Freezing squeezes an idle sandbox's
+  memory out to swap; gVisor holds sandbox memory as shared memory, which
+  the kernel refuses to swap at the default swappiness — measured on real
+  hardware: 0 bytes reclaimed at the default, 99.5% reclaimed at 100. Note
+  that some cloud images (Alibaba Cloud, for one) ship `vm.swappiness=0`;
+  check the *effective* value with `sysctl vm.swappiness`, not the config
+  files.
+- **Network hardening is not optional.** Sandboxes run untrusted code:
+  block the cloud metadata service from containers
+  (`iptables -I DOCKER-USER -d 169.254.0.0/16 -j DROP`, persisted) and
+  disable inter-container traffic (`"icc": false` in `daemon.json`). The
+  daemon binds to 127.0.0.1 only, by design without a knob; exposing it is
+  a reverse proxy's job.
+- **One machine, one daemon.** The daemon enforces this with a lock next
+  to its ledger and refuses to start when its ledger and the machine's
+  reality cannot belong together.
+
+## Reaching the daemon from outside
+
+The daemon listens on 127.0.0.1 only, so reaching it from another machine
+is a choice you make explicitly, one of two ways:
+
+- **SSH tunnel** (private, zero setup):
+  `ssh -L 3676:127.0.0.1:3676 root@host`, then use
+  `http://127.0.0.1:3676` as your endpoint.
+- **Reverse proxy** for the console, the API, and the E2B surface at once —
+  e.g. Caddy, which also handles TLS certificates automatically once you
+  give it a domain:
+
+  ```
+  your-domain.example {
+  	reverse_proxy 127.0.0.1:3676 {
+  		flush_interval -1
+  	}
+  }
+  ```
+
+  `flush_interval -1` matters: streamed command output is written frame by
+  frame, and a buffering proxy would turn it into one lump at the end.
+  Anything exposed beyond localhost should be HTTPS — the API token and
+  the session cookie travel in every request.
diff --git a/website/content/docs/meta.json b/website/content/docs/meta.json
new file mode 100644
index 0000000..6da52f8
--- /dev/null
+++ b/website/content/docs/meta.json
@@ -0,0 +1,3 @@
+{
+  "pages": ["index", "installation", "quickstart", "e2b-compatibility"]
+}
diff --git a/website/content/docs/quickstart.mdx b/website/content/docs/quickstart.mdx
new file mode 100644
index 0000000..439d68c
--- /dev/null
+++ b/website/content/docs/quickstart.mdx
@@ -0,0 +1,59 @@
+---
+title: Quick start
+description: Acquire a sandbox, run commands, move files — with the SDK, curl, or the CLI.
+---
+
+`@dormice/sdk` is the native TypeScript client. (Not on npm yet — the
+first release is queued; inside the repo, `pnpm build` produces it.)
+
+```ts
+import { Dormice } from '@dormice/sdk';
+
+const client = new Dormice({
+  endpoint: 'http://127.0.0.1:3676',
+  token: process.env.DORMICE_API_TOKEN!,
+});
+
+// One key, one sandbox — created, woken or restarted as needed.
+// stopAfterSeconds: null makes it a resident agent: it may freeze when
+// idle (~50 ms to wake) but never cold-starts.
+await client.acquireSandbox('my-agent', { stopAfterSeconds: null });
+
+const result = await client.execCommand('my-agent', 'python3 -c "print(6 * 7)"');
+console.log(result.exitCode, result.stdout); // 0 42
+
+await client.writeFiles('my-agent', [
+  { path: 'notes.txt', content: 'survives freeze and stop' },
+]);
+
+await client.releaseSandbox('my-agent'); // destroy — the only verb that loses data
+```
+
+## The wire is plain HTTP
+
+Every operation is an RPC route named after the SDK method
+(`POST /acquireSandbox`, `POST /execCommand`, …), authenticated with
+`Authorization: Bearer` and your API token, so `curl` works where the SDK
+doesn't reach:
+
+```sh
+curl -X POST http://127.0.0.1:3676/listSandboxes \
+  -H "Authorization: Bearer $DORMICE_API_TOKEN" \
+  -H "content-type: application/json" -d '{}'
+```
+
+## The CLI
+
+The `dor` command (long form: `dormice`) covers the operator side. It
+connects with the `DORMICE_ENDPOINT` and `DORMICE_API_TOKEN` environment
+variables:
+
+```sh
+dor sandbox ls                        # every sandbox, with lifecycle state
+dor sandbox exec my-agent 'uname -r'  # run a command, exit code passes through
+dor sandbox push my-agent ./data.csv  # copy a file in…
+dor sandbox pull my-agent notes.txt   # …and out
+dor sandbox rebuild my-agent          # fresh container, /home/user kept
+dor sandbox release my-agent          # destroy
+dor doctor                            # can this machine run sandboxes?
+```
diff --git a/website/lib/layout.shared.tsx b/website/lib/layout.shared.tsx
new file mode 100644
index 0000000..a7729ce
--- /dev/null
+++ b/website/lib/layout.shared.tsx
@@ -0,0 +1,10 @@
+import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+
+// Chrome shared by every layout (home and docs): title, links, GitHub.
+export function baseOptions(): BaseLayoutProps {
+  return {
+    nav: { title: 'Dormice' },
+    githubUrl: 'https://github.com/BitMiracle-AI/Dormice',
+    links: [{ text: 'Documentation', url: '/docs' }],
+  };
+}
diff --git a/website/lib/source.ts b/website/lib/source.ts
new file mode 100644
index 0000000..664dcd8
--- /dev/null
+++ b/website/lib/source.ts
@@ -0,0 +1,8 @@
+import { loader } from 'fumadocs-core/source';
+import { docs } from '@/.source/server';
+
+// The one content loader: page tree, slugs and page data all come from here.
+export const source = loader({
+  baseUrl: '/docs',
+  source: docs.toFumadocsSource(),
+});
diff --git a/website/mdx-components.tsx b/website/mdx-components.tsx
new file mode 100644
index 0000000..cf053e1
--- /dev/null
+++ b/website/mdx-components.tsx
@@ -0,0 +1,6 @@
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import type { MDXComponents } from 'mdx/types';
+
+export function getMDXComponents(components?: MDXComponents): MDXComponents {
+  return { ...defaultMdxComponents, ...components };
+}
diff --git a/website/next.config.mjs b/website/next.config.mjs
new file mode 100644
index 0000000..10f08b7
--- /dev/null
+++ b/website/next.config.mjs
@@ -0,0 +1,15 @@
+import { createMDX } from 'fumadocs-mdx/next';
+
+const withMDX = createMDX();
+
+/** @type {import('next').NextConfig} */
+const config = {
+  // Static export, pinned from day one: the site must stay deployable as
+  // plain files anywhere (GitHub Pages, an object store, any CDN) and never
+  // grow a dependency on a Node server or a specific host.
+  output: 'export',
+  // A static export has no image-optimization server.
+  images: { unoptimized: true },
+};
+
+export default withMDX(config);
diff --git a/website/package.json b/website/package.json
new file mode 100644
index 0000000..bfc73bf
--- /dev/null
+++ b/website/package.json
@@ -0,0 +1,32 @@
+{
+  "name": "@dormice/website",
+  "version": "0.0.0",
+  "description": "Dormice website and documentation: Next.js static export, deployable as plain files",
+  "license": "Apache-2.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "NEXT_TELEMETRY_DISABLED=1 next build",
+    "dev": "NEXT_TELEMETRY_DISABLED=1 next dev",
+    "postinstall": "fumadocs-mdx",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "fumadocs-core": "^16.11.1",
+    "fumadocs-mdx": "^15.1.0",
+    "fumadocs-ui": "^16.11.1",
+    "next": "^16.2.10",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.2",
+    "@types/mdx": "^2.0.14",
+    "@types/node": "^26.1.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "postcss": "^8.5.16",
+    "tailwindcss": "^4.3.2",
+    "typescript": "^6.0.3"
+  }
+}
diff --git a/website/postcss.config.mjs b/website/postcss.config.mjs
new file mode 100644
index 0000000..a34a3d5
--- /dev/null
+++ b/website/postcss.config.mjs
@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
diff --git a/website/source.config.ts b/website/source.config.ts
new file mode 100644
index 0000000..0564068
--- /dev/null
+++ b/website/source.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
+
+export const docs = defineDocs({
+  dir: 'content/docs',
+});
+
+export default defineConfig();
diff --git a/website/tsconfig.json b/website/tsconfig.json
new file mode 100644
index 0000000..fbe9cee
--- /dev/null
+++ b/website/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "jsx": "preserve",
+    "allowJs": true,
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "baseUrl": ".",
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".source/**/*.ts"
+  ],
+  "exclude": ["node_modules", "out"]
+}

From f9e4ec89f3926aa2a2d85d8cd4508a545baa91c8 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 19:36:58 +0800
Subject: [PATCH 036/133] Templates phase 1: named images in the ledger,
 resolved at shell birth

A template is a name for a Docker image that already lives on the host
- the host's Docker daemon is the image store, the templates table only
records which name points where. Native verbs registerTemplate (an
upsert: re-pointing a name is the upgrade), listTemplates and
removeTemplate (refused while referenced, naming the keys); acquire
gains a creation-time template field with policy-override semantics;
sandbox rows record the template name and every shell rebuild resolves
it to the template's current image, composing with rebuildSandbox as
the upgrade front door.

The E2B surface resolves templateID for real now: a registered name
wins, 'base' and the base image's own name stay on the base image (the
SDK's default is the literal string 'base'), anything else is an
honest 404 the official SDK surfaces verbatim. Views echo the template
as templateID plus alias only when one was used.

Executor create/start gain ShellOptions.image, applied only at shell
birth - starting an existing container never changes its image; the
contract's new image chapter pins that on both executors, with the
docker subject tagging its base image under an alias to tell names
apart. CLI grows dor template add/ls/rm; the console create dialog
offers registered templates and the detail page shows one.
---
 e2e/src/cli.test.ts                           |  14 ++
 e2e/src/e2b.test.ts                           |  50 ++++-
 e2e/src/native.test.ts                        |  61 ++++--
 packages/cli/src/commands.test.ts             |  21 +++
 packages/cli/src/commands.ts                  |  90 +++++++--
 packages/cli/src/main.ts                      |  37 +++-
 .../components/CreateSandboxDialog.tsx        |  31 ++++
 .../features/sandboxes/hooks/useTemplates.ts  |  16 ++
 .../sandboxes/pages/SandboxDetailPage.tsx     |   1 +
 packages/console/src/lib/api.ts               |  10 +-
 packages/sdk/src/client.test.ts               |  40 +++-
 packages/sdk/src/client.ts                    |  69 ++++++-
 packages/sdk/src/index.ts                     |   1 +
 packages/server/drizzle/0003_templates.sql    |   7 +
 .../server/drizzle/meta/0003_snapshot.json    | 173 ++++++++++++++++++
 packages/server/drizzle/meta/_journal.json    |   7 +
 packages/server/src/app.test.ts               | 133 ++++++++++++++
 packages/server/src/app.ts                    |   2 +
 packages/server/src/db/ledger.ts              |   3 +
 packages/server/src/db/schema.ts              |  21 +++
 packages/server/src/db/templates.ts           |  83 +++++++++
 packages/server/src/e2b/compat.test.ts        | 109 ++++++++++-
 packages/server/src/e2b/control.ts            |  40 +++-
 packages/server/src/e2b/view.test.ts          |   1 +
 .../server/src/executor/contract/image.ts     |  66 +++++++
 .../server/src/executor/contract/index.ts     |  28 ++-
 .../src/executor/docker.contract.test.ts      |  30 ++-
 packages/server/src/executor/docker.ts        |  19 +-
 packages/server/src/executor/executor.ts      |  29 ++-
 packages/server/src/executor/fake.test.ts     |  12 +-
 packages/server/src/executor/fake.ts          |  27 ++-
 packages/server/src/lifecycle.ts              |  16 +-
 packages/server/src/routes/sandboxes.ts       |  23 ++-
 packages/server/src/routes/templates.ts       |  81 ++++++++
 packages/shared/src/acquire.ts                |   8 +
 packages/shared/src/index.ts                  |   1 +
 packages/shared/src/sandbox.ts                |   7 +
 packages/shared/src/templates.ts              |  86 +++++++++
 38 files changed, 1367 insertions(+), 86 deletions(-)
 create mode 100644 packages/console/src/features/sandboxes/hooks/useTemplates.ts
 create mode 100644 packages/server/drizzle/0003_templates.sql
 create mode 100644 packages/server/drizzle/meta/0003_snapshot.json
 create mode 100644 packages/server/src/db/templates.ts
 create mode 100644 packages/server/src/executor/contract/image.ts
 create mode 100644 packages/server/src/routes/templates.ts
 create mode 100644 packages/shared/src/templates.ts

diff --git a/e2e/src/cli.test.ts b/e2e/src/cli.test.ts
index 3416576..711034a 100644
--- a/e2e/src/cli.test.ts
+++ b/e2e/src/cli.test.ts
@@ -95,6 +95,20 @@ describe('dor CLI against a real daemon', () => {
     expect(pulled.stdout).toBe('through the CLI\n');
   });
 
+  it('template add, ls and rm run the registration life through the real binary', async () => {
+    const added = await cli('template', 'add', 'cli-tpl', 'img:cli');
+    expect(added.stdout).toContain('Registered template "cli-tpl" -> img:cli.');
+
+    const listed = await cli('template', 'ls');
+    expect(listed.stdout).toMatch(/NAME\s{2,}IMAGE\s{2,}CREATED/);
+    expect(listed.stdout).toMatch(/cli-tpl\s{2,}img:cli/);
+
+    const removed = await cli('template', 'rm', 'cli-tpl');
+    expect(removed.stdout).toContain('Removed template "cli-tpl".');
+    const again = await cli('template', 'rm', 'cli-tpl');
+    expect(again.stdout).toContain('nothing to remove');
+  });
+
   it('fails honestly when the environment is missing', async () => {
     await expect(
       run('node', [CLI, 'sandbox', 'ls'], {
diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 42d8cb9..097ac01 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -534,8 +534,7 @@ describe('official e2b SDK against the daemon', () => {
     // Native acquire sets the second-scale policy; the e2b face then joins
     // the same sandbox through the userKey extension.
     await dormice.acquireSandbox(userKey, {
-      freezeAfterSeconds: 1,
-      stopAfterSeconds: null,
+      policy: { freezeAfterSeconds: 1, stopAfterSeconds: null },
     });
     const sbx = await Sandbox.create({
       ...connection(),
@@ -649,6 +648,31 @@ describe('official e2b SDK against the daemon', () => {
       await first.kill();
     }
   });
+
+  it('creates from a registered template name; info reports it as templateId and name', async () => {
+    // Registration is the operator's native verb; the official SDK then
+    // consumes the name as its templateID — aliases are the same wire.
+    const dormice = new Dormice({
+      endpoint: inject('dormiceEndpoint'),
+      token: inject('dormiceToken'),
+    });
+    await dormice.registerTemplate('e2e-tpl', 'img:e2e-tpl');
+    const sbx = await Sandbox.create('e2e-tpl', connection());
+    try {
+      const info = await sbx.getInfo();
+      expect(info.templateId).toBe('e2e-tpl');
+      expect(info.name).toBe('e2e-tpl');
+    } finally {
+      await sbx.kill();
+      await dormice.removeTemplate('e2e-tpl');
+    }
+  });
+
+  it('refuses an unregistered template name with the 404 the SDK can read', async () => {
+    await expect(
+      Sandbox.create('never-registered', connection()),
+    ).rejects.toThrow(/404: template 'never-registered' not found/);
+  });
 });
 
 // The proxy's end-to-end round trip against the fake executor's echo
@@ -822,5 +846,27 @@ describe.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
         await sbx.kill();
       }
     });
+
+    it('a registered template boots real containers through the table-hit path', async () => {
+      // The template points at the daemon's own base image under its
+      // registered name: resolution goes through the templates table (not
+      // the base-image sentinel), and the container must actually work.
+      const image = process.env.DORMICE_BASE_IMAGE;
+      if (!image) throw new Error('docker e2e requires DORMICE_BASE_IMAGE');
+      const dormice = new Dormice({
+        endpoint: inject('dormiceEndpoint'),
+        token: inject('dormiceToken'),
+      });
+      await dormice.registerTemplate('e2e-real-tpl', image);
+      const sbx = await Sandbox.create('e2e-real-tpl', connection());
+      try {
+        expect((await sbx.getInfo()).templateId).toBe('e2e-real-tpl');
+        const result = await sbx.commands.run('whoami');
+        expect(result.stdout).toBe('user\n');
+      } finally {
+        await sbx.kill();
+        await dormice.removeTemplate('e2e-real-tpl');
+      }
+    });
   },
 );
diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index f5c403a..86d1248 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -43,8 +43,7 @@ describe('native API over a real daemon', () => {
 
   it('stores a policy override, including null for never-archive', async () => {
     const res = await client().acquireSandbox('override-key', {
-      freezeAfterSeconds: 120,
-      archiveAfterSeconds: null,
+      policy: { freezeAfterSeconds: 120, archiveAfterSeconds: null },
     });
     expect(res.sandbox.policy).toEqual({
       ...DEFAULT_LIFECYCLE_POLICY,
@@ -55,7 +54,9 @@ describe('native API over a real daemon', () => {
 
   it('rejects a policy override that breaks the ordering rule', async () => {
     await expect(
-      client().acquireSandbox('bad-policy-key', { archiveAfterSeconds: 1 }),
+      client().acquireSandbox('bad-policy-key', {
+        policy: { archiveAfterSeconds: 1 },
+      }),
     ).rejects.toMatchObject({
       status: 400,
       message: expect.stringMatching(/stopAfterSeconds/),
@@ -174,9 +175,11 @@ describe('native API over a real daemon', () => {
     // dies against a paused container. Reverse-verified with the
     // heartbeat disabled.
     await client().acquireSandbox('exec-busy-key', {
-      freezeAfterSeconds: 1,
-      stopAfterSeconds: null,
-      archiveAfterSeconds: null,
+      policy: {
+        freezeAfterSeconds: 1,
+        stopAfterSeconds: null,
+        archiveAfterSeconds: null,
+      },
     });
     const result = await client().execCommand('exec-busy-key', 'sleep 3');
     expect(result.exitCode).toBe(0);
@@ -188,9 +191,11 @@ describe('native API over a real daemon', () => {
 
   it('exec wakes a frozen sandbox before running the command', async () => {
     await client().acquireSandbox('exec-wake-key', {
-      freezeAfterSeconds: 1,
-      stopAfterSeconds: null,
-      archiveAfterSeconds: null,
+      policy: {
+        freezeAfterSeconds: 1,
+        stopAfterSeconds: null,
+        archiveAfterSeconds: null,
+      },
     });
     // Watch it actually freeze from outside, on real wall-clock time.
     const deadline = Date.now() + 15_000;
@@ -220,9 +225,11 @@ describe('native API over a real daemon', () => {
 
   it('survives the cold cycle: idle -> frozen -> stopped -> re-acquire wakes it', async () => {
     const created = await client().acquireSandbox('sleeper-key', {
-      freezeAfterSeconds: 1,
-      stopAfterSeconds: 2,
-      archiveAfterSeconds: null,
+      policy: {
+        freezeAfterSeconds: 1,
+        stopAfterSeconds: 2,
+        archiveAfterSeconds: null,
+      },
     });
     expect(created.sandbox.state).toBe('active');
 
@@ -289,11 +296,35 @@ describe('native API over a real daemon', () => {
     });
   });
 
+  it('templates: register, create from, removal guarded while in use', async () => {
+    await client().registerTemplate('native-tpl', 'img:native');
+    const created = await client().acquireSandbox('tpl-key', {
+      template: 'native-tpl',
+    });
+    expect(created.sandbox.template).toBe('native-tpl');
+    const listed = (await client().listSandboxes()).find(
+      (s) => s.userKey === 'tpl-key',
+    );
+    expect(listed?.template).toBe('native-tpl');
+
+    await expect(client().removeTemplate('native-tpl')).rejects.toMatchObject({
+      name: 'DormiceApiError',
+      status: 409,
+      message: expect.stringMatching(/tpl-key/),
+    });
+    await client().releaseSandbox('tpl-key');
+    expect(await client().removeTemplate('native-tpl')).toEqual({
+      removed: true,
+    });
+  });
+
   it('reading a file wakes a frozen sandbox, and the file survived the cold', async () => {
     await client().acquireSandbox('files-wake-key', {
-      freezeAfterSeconds: 1,
-      stopAfterSeconds: null,
-      archiveAfterSeconds: null,
+      policy: {
+        freezeAfterSeconds: 1,
+        stopAfterSeconds: null,
+        archiveAfterSeconds: null,
+      },
     });
     await client().writeFiles('files-wake-key', [
       { path: 'keep.txt', content: 'still here' },
diff --git a/packages/cli/src/commands.test.ts b/packages/cli/src/commands.test.ts
index c129022..2b92160 100644
--- a/packages/cli/src/commands.test.ts
+++ b/packages/cli/src/commands.test.ts
@@ -18,6 +18,9 @@ import {
   sandboxPush,
   sandboxRebuild,
   sandboxRelease,
+  templateAdd,
+  templateLs,
+  templateRm,
 } from './commands';
 
 const TOKEN = 'test-token-test-token-test-token';
@@ -177,3 +180,21 @@ describe('sandbox commands over real HTTP', () => {
     );
   });
 });
+
+describe('template commands over real HTTP', () => {
+  it('add, ls and rm walk the registration life end to end', async () => {
+    expect(await templateLs(client)).toBe('No templates.');
+
+    expect(await templateAdd(client, 'py311', 'img:py311')).toBe(
+      'Registered template "py311" -> img:py311.',
+    );
+    const output = await templateLs(client);
+    expect(output.split('\n')[0]).toMatch(/^NAME\s{2,}IMAGE\s{2,}CREATED$/);
+    expect(output).toMatch(/py311\s{2,}img:py311/);
+
+    expect(await templateRm(client, 'py311')).toBe('Removed template "py311".');
+    expect(await templateRm(client, 'py311')).toBe(
+      'No template named "py311" — nothing to remove.',
+    );
+  });
+});
diff --git a/packages/cli/src/commands.ts b/packages/cli/src/commands.ts
index 6dad8f2..fe8e86f 100644
--- a/packages/cli/src/commands.ts
+++ b/packages/cli/src/commands.ts
@@ -1,4 +1,9 @@
-import { Dormice, type ReadFileResult, type Sandbox } from '@dormice/sdk';
+import {
+  Dormice,
+  type ReadFileResult,
+  type Sandbox,
+  type Template,
+} from '@dormice/sdk';
 
 /**
  * Builds the API client from the environment. The daemon's address and
@@ -43,29 +48,29 @@ function printable(value: string): string {
   return value.replace(/\p{Cc}/gu, '?');
 }
 
+/** Plain-column rendering shared by the ls verbs. Cells must be printable already. */
+function renderTable(headers: string[], rows: string[][]): string {
+  const widths = headers.map((header, i) =>
+    Math.max(header.length, ...rows.map((row) => (row[i] ?? '').length)),
+  );
+  const line = (cells: string[]) =>
+    cells
+      .map((cell, i) => cell.padEnd(widths[i] ?? 0))
+      .join('  ')
+      .trimEnd();
+  return [line(headers), ...rows.map(line)].join('\n');
+}
+
 /** `dor sandbox ls`: every sandbox with its lifecycle state, as plain columns. */
 export async function sandboxLs(client: Dormice): Promise<string> {
   const sandboxes = await client.listSandboxes();
   if (sandboxes.length === 0) {
     return 'No sandboxes.';
   }
-  const cell = (column: (typeof COLUMNS)[number], s: Sandbox) =>
-    printable(column.value(s));
-  const widths = COLUMNS.map((column) =>
-    Math.max(
-      column.header.length,
-      ...sandboxes.map((s) => cell(column, s).length),
-    ),
+  return renderTable(
+    COLUMNS.map((column) => column.header),
+    sandboxes.map((s) => COLUMNS.map((column) => printable(column.value(s)))),
   );
-  const line = (cells: string[]) =>
-    cells
-      .map((cell, i) => cell.padEnd(widths[i] ?? 0))
-      .join('  ')
-      .trimEnd();
-  return [
-    line(COLUMNS.map((column) => column.header)),
-    ...sandboxes.map((s) => line(COLUMNS.map((column) => cell(column, s)))),
-  ].join('\n');
 }
 
 export interface ExecOutput {
@@ -139,17 +144,20 @@ export function pullSavedMessage(
 
 /**
  * `dor sandbox rebuild <userKey>`: swap the sandbox's container, keep its
- * disk. /home/user survives; everything else resets onto the daemon's
- * current base image at the next use.
+ * disk. /home/user survives; everything else resets onto the current image
+ * of the sandbox's template (or the base image) at the next use.
  */
 export async function sandboxRebuild(
   client: Dormice,
   userKey: string,
 ): Promise<string> {
   const { sandbox } = await client.rebuildSandbox(userKey);
+  const target = sandbox.template
+    ? `template "${printable(sandbox.template)}"'s current image`
+    : 'the current base image';
   return (
     `Rebuilt the sandbox for key "${printable(userKey)}" — /home/user kept, ` +
-    `now ${sandbox.state}; its next use starts on the current base image.`
+    `now ${sandbox.state}; its next use starts on ${target}.`
   );
 }
 
@@ -163,3 +171,45 @@ export async function sandboxRelease(
     ? `Released the sandbox for key "${printable(userKey)}".`
     : `No sandbox for key "${printable(userKey)}" — nothing to release.`;
 }
+
+/**
+ * `dor template add <name> <image>`: name a Docker image on the daemon's
+ * host as a template. An upsert — re-adding a name re-points it, which is
+ * how a template is upgraded; existing sandboxes move on their next rebuild.
+ */
+export async function templateAdd(
+  client: Dormice,
+  name: string,
+  image: string,
+): Promise<string> {
+  const { template } = await client.registerTemplate(name, image);
+  return `Registered template "${printable(template.name)}" -> ${printable(template.image)}.`;
+}
+
+/** `dor template ls`: every registered template, as plain columns. */
+export async function templateLs(client: Dormice): Promise<string> {
+  const templates = await client.listTemplates();
+  if (templates.length === 0) {
+    return 'No templates.';
+  }
+  const columns: { header: string; value: (t: Template) => string }[] = [
+    { header: 'NAME', value: (t) => t.name },
+    { header: 'IMAGE', value: (t) => t.image },
+    { header: 'CREATED', value: (t) => t.createdAt },
+  ];
+  return renderTable(
+    columns.map((column) => column.header),
+    templates.map((t) => columns.map((column) => printable(column.value(t)))),
+  );
+}
+
+/** `dor template rm <name>`: drop a template's registration (never the image), idempotently. */
+export async function templateRm(
+  client: Dormice,
+  name: string,
+): Promise<string> {
+  const { removed } = await client.removeTemplate(name);
+  return removed
+    ? `Removed template "${printable(name)}".`
+    : `No template named "${printable(name)}" — nothing to remove.`;
+}
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index 261cf3f..ae07267 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -15,6 +15,9 @@ import {
   sandboxPush,
   sandboxRebuild,
   sandboxRelease,
+  templateAdd,
+  templateLs,
+  templateRm,
 } from './commands';
 import { realDoctorContext, runDoctor } from './doctor';
 
@@ -121,7 +124,7 @@ sandbox
 sandbox
   .command('rebuild')
   .description(
-    'Swap the container, keep /home/user — next use starts on the current base image',
+    "Swap the container, keep /home/user — next use starts on the template's current image (or the base image)",
   )
   .argument('<userKey>', 'the user key whose sandbox to rebuild')
   .action(async (userKey: string) => {
@@ -136,6 +139,38 @@ sandbox
     console.log(await sandboxRelease(clientFromEnv(process.env), userKey));
   });
 
+const template = program
+  .command('template')
+  .description('Name Docker images on the daemon host as sandbox templates');
+
+template
+  .command('add')
+  .description(
+    'Register (or re-point — that is the upgrade) a template name to an image on the daemon host',
+  )
+  .argument('<name>', 'template name; doubles as the E2B templateID')
+  .argument('<image>', 'Docker image reference, e.g. my-python:3.11')
+  .action(async (name: string, image: string) => {
+    console.log(await templateAdd(clientFromEnv(process.env), name, image));
+  });
+
+template
+  .command('ls')
+  .description('List every registered template')
+  .action(async () => {
+    console.log(await templateLs(clientFromEnv(process.env)));
+  });
+
+template
+  .command('rm')
+  .description(
+    'Remove a template registration (refused while sandboxes still use it; never removes the image)',
+  )
+  .argument('<name>', 'template name to remove')
+  .action(async (name: string) => {
+    console.log(await templateRm(clientFromEnv(process.env), name));
+  });
+
 try {
   await program.parseAsync();
 } catch (error) {
diff --git a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
index 817121c..cb4a641 100644
--- a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
+++ b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
@@ -21,9 +21,14 @@ import {
   FieldLabel,
 } from '@/components/ui/field';
 import { Input } from '@/components/ui/input';
+import {
+  NativeSelect,
+  NativeSelectOption,
+} from '@/components/ui/native-select';
 import { Spinner } from '@/components/ui/spinner';
 import { Switch } from '@/components/ui/switch';
 import { useAcquireSandbox } from '../hooks/useSandboxes';
+import { useTemplates } from '../hooks/useTemplates';
 
 /**
  * The console speaks the same verb as everyone else: acquire. Same key,
@@ -37,13 +42,16 @@ import { useAcquireSandbox } from '../hooks/useSandboxes';
 export function CreateSandboxDialog() {
   const [open, setOpen] = useState(false);
   const [userKey, setUserKey] = useState('');
+  const [template, setTemplate] = useState('');
   const [freezeAfter, setFreezeAfter] = useState('');
   const [neverStop, setNeverStop] = useState(false);
   const [stopAfter, setStopAfter] = useState('');
   const mutation = useAcquireSandbox();
+  const templates = useTemplates().data?.templates ?? [];
 
   const reset = () => {
     setUserKey('');
+    setTemplate('');
     setFreezeAfter('');
     setNeverStop(false);
     setStopAfter('');
@@ -59,6 +67,7 @@ export function CreateSandboxDialog() {
     mutation.mutate(
       {
         userKey,
+        ...(template !== '' ? { template } : {}),
         ...(Object.keys(policy).length > 0 ? { policy } : {}),
       },
       {
@@ -117,6 +126,28 @@ export function CreateSandboxDialog() {
                 key always comes back to the same sandbox.
               </FieldDescription>
             </Field>
+            {templates.length > 0 && (
+              <Field>
+                <FieldLabel htmlFor="create-template">Template</FieldLabel>
+                <NativeSelect
+                  id="create-template"
+                  className="w-full"
+                  value={template}
+                  onChange={(event) => setTemplate(event.target.value)}
+                >
+                  <NativeSelectOption value="">Base image</NativeSelectOption>
+                  {templates.map((t) => (
+                    <NativeSelectOption key={t.name} value={t.name}>
+                      {t.name} ({t.image})
+                    </NativeSelectOption>
+                  ))}
+                </NativeSelect>
+                <FieldDescription>
+                  Applied only when this key creates a new sandbox. Register
+                  templates with `dor template add`.
+                </FieldDescription>
+              </Field>
+            )}
             <Field>
               <FieldLabel htmlFor="create-freeze-after">
                 Freeze after idle (seconds)
diff --git a/packages/console/src/features/sandboxes/hooks/useTemplates.ts b/packages/console/src/features/sandboxes/hooks/useTemplates.ts
new file mode 100644
index 0000000..bdcf9ba
--- /dev/null
+++ b/packages/console/src/features/sandboxes/hooks/useTemplates.ts
@@ -0,0 +1,16 @@
+import { useQuery } from '@tanstack/react-query';
+import { listTemplates } from '@/lib/api';
+
+/**
+ * The console only consumes templates (the create form's dropdown, the
+ * detail row); registration lives in the CLI (`dor template add`). No
+ * polling: templates change at operator speed, a mount-time read is honest
+ * enough.
+ */
+export function useTemplates() {
+  return useQuery({
+    queryKey: ['templates'],
+    queryFn: listTemplates,
+    retry: false,
+  });
+}
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index 0dfbe26..8b38d2f 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -90,6 +90,7 @@ export function SandboxDetailPage() {
         <CardContent>
           <dl>
             <Row label="Sandbox ID">{sandbox.sandboxId}</Row>
+            <Row label="Template">{sandbox.template ?? 'base image'}</Row>
             <Row label="Node">{sandbox.nodeId}</Row>
             <Row label="Endpoint">{sandbox.endpoint}</Row>
             <Row label="Created">
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index c45117b..267f904 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -1,4 +1,9 @@
-import type { AcquireRequest, AcquireResponse, Sandbox } from '@dormice/shared';
+import type {
+  AcquireRequest,
+  AcquireResponse,
+  Sandbox,
+  Template,
+} from '@dormice/shared';
 import { clearSessionMarker, hasSessionMarker } from './session';
 
 /**
@@ -76,6 +81,9 @@ export const logout = () =>
 export const listSandboxes = () =>
   rpc<{ sandboxes: Sandbox[] }>('/listSandboxes');
 
+export const listTemplates = () =>
+  rpc<{ templates: Template[] }>('/listTemplates');
+
 export const acquireSandbox = (request: AcquireRequest) =>
   rpc<AcquireResponse>('/acquireSandbox', request);
 
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 68eedc8..3a683d0 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -78,8 +78,7 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
 
   it('passes a policy override through', async () => {
     const res = await client.acquireSandbox('bob', {
-      freezeAfterSeconds: 60,
-      archiveAfterSeconds: null,
+      policy: { freezeAfterSeconds: 60, archiveAfterSeconds: null },
     });
     expect(res.sandbox.policy).toEqual({
       ...DEFAULT_LIFECYCLE_POLICY,
@@ -98,7 +97,7 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
 
   it("surfaces the server's message for an invalid policy", async () => {
     await expect(
-      client.acquireSandbox('carol', { archiveAfterSeconds: 1 }),
+      client.acquireSandbox('carol', { policy: { archiveAfterSeconds: 1 } }),
     ).rejects.toMatchObject({
       status: 400,
       message: expect.stringMatching(/stopAfterSeconds/),
@@ -277,3 +276,38 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
     expect(again.sandbox.sandboxId).not.toBe(created.sandbox.sandboxId);
   });
 });
+
+describe('templates over real HTTP', () => {
+  it('registers, lists, applies at acquire, and removes through the full life', async () => {
+    await client.registerTemplate('tpl-sdk', 'img-sdk');
+    expect(await client.listTemplates()).toMatchObject([
+      { name: 'tpl-sdk', image: 'img-sdk' },
+    ]);
+
+    const res = await client.acquireSandbox('tpl-user', {
+      template: 'tpl-sdk',
+    });
+    expect(res.sandbox.template).toBe('tpl-sdk');
+    expect(executor.imageOf(res.sandbox.sandboxId)).toBe('img-sdk');
+
+    // In use: removal is refused, naming the key that holds it.
+    await expect(client.removeTemplate('tpl-sdk')).rejects.toMatchObject({
+      name: 'DormiceApiError',
+      status: 409,
+      message: expect.stringMatching(/tpl-user/),
+    });
+
+    await client.releaseSandbox('tpl-user');
+    expect(await client.removeTemplate('tpl-sdk')).toEqual({ removed: true });
+    expect(await client.removeTemplate('tpl-sdk')).toEqual({ removed: false });
+  });
+
+  it("surfaces the server's 400 for an unknown template", async () => {
+    await expect(
+      client.acquireSandbox('tpl-nobody', { template: 'ghost' }),
+    ).rejects.toMatchObject({
+      status: 400,
+      message: "unknown template 'ghost' — register it first",
+    });
+  });
+});
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index ec9f10b..204a753 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -6,12 +6,18 @@ import {
   execCommandResponseSchema,
   type LifecyclePolicyOverride,
   listSandboxesResponseSchema,
+  listTemplatesResponseSchema,
   type RebuildSandboxResponse,
+  type RegisterTemplateResponse,
   type ReleaseSandboxResponse,
+  type RemoveTemplateResponse,
   readFileResponseSchema,
   rebuildSandboxResponseSchema,
+  registerTemplateResponseSchema,
   releaseSandboxResponseSchema,
+  removeTemplateResponseSchema,
   type Sandbox,
+  type Template,
   type WriteFilesResponse,
   writeFilesResponseSchema,
 } from '@dormice/shared';
@@ -59,6 +65,21 @@ export interface ExecCommandOptions {
   env?: Record<string, string>;
 }
 
+export interface AcquireSandboxOptions {
+  /**
+   * Lifecycle override applied when this acquire creates the sandbox;
+   * an existing sandbox keeps its stored policy, but an invalid override
+   * is still a 400.
+   */
+  policy?: LifecyclePolicyOverride;
+  /**
+   * Registered template to create the sandbox from; omitted means the
+   * daemon's base image. Same rules as policy: creation-time only, and an
+   * unknown name is a 400.
+   */
+  template?: string;
+}
+
 /** A non-2xx answer from the daemon, carrying the HTTP status and the server's message. */
 export class DormiceApiError extends Error {
   readonly status: number;
@@ -89,9 +110,13 @@ export class Dormice {
    */
   async acquireSandbox(
     userKey: string,
-    policy?: LifecyclePolicyOverride,
+    options?: AcquireSandboxOptions,
   ): Promise<AcquireResponse> {
-    const data = await this.rpc('acquireSandbox', { userKey, policy });
+    const data = await this.rpc('acquireSandbox', {
+      userKey,
+      policy: options?.policy,
+      template: options?.template,
+    });
     // Never trust the wire blindly: parsing against the shared schema makes
     // a version-skewed or misbehaving server fail loudly right here.
     return acquireResponseSchema.parse(data);
@@ -105,11 +130,12 @@ export class Dormice {
 
   /**
    * Swaps the sandbox's container while keeping its disk: /home/user is
-   * untouched, and the next use builds a fresh container from the daemon's
-   * current base image — how an existing sandbox picks up new shared layers
-   * (anything outside /home/user is reset). The sandbox is left `stopped`;
-   * the next acquire or exec wakes it, paying one cold start. Unknown key:
-   * 404 — rebuild is not a creator.
+   * untouched, and the next use builds a fresh container from the current
+   * image of the sandbox's template (or the daemon's current base image) —
+   * how an existing sandbox picks up new shared layers (anything outside
+   * /home/user is reset). The sandbox is left `stopped`; the next acquire
+   * or exec wakes it, paying one cold start. Unknown key: 404 — rebuild is
+   * not a creator.
    */
   async rebuildSandbox(userKey: string): Promise<RebuildSandboxResponse> {
     const data = await this.rpc('rebuildSandbox', { userKey });
@@ -126,6 +152,35 @@ export class Dormice {
     return releaseSandboxResponseSchema.parse(data);
   }
 
+  /**
+   * Names a Docker image on the daemon's host as a template. An upsert:
+   * re-registering a name re-points it at the new image — how a template is
+   * upgraded (existing sandboxes move on their next rebuildSandbox). The
+   * image is not checked for existence; it may arrive after registration.
+   */
+  async registerTemplate(
+    name: string,
+    image: string,
+  ): Promise<RegisterTemplateResponse> {
+    const data = await this.rpc('registerTemplate', { name, image });
+    return registerTemplateResponseSchema.parse(data);
+  }
+
+  /** Every registered template. */
+  async listTemplates(): Promise<Template[]> {
+    const data = await this.rpc('listTemplates', {});
+    return listTemplatesResponseSchema.parse(data).templates;
+  }
+
+  /**
+   * Removes a template's registration (never the image). Refused with a 409
+   * while any sandbox still uses it; idempotent on an unknown name.
+   */
+  async removeTemplate(name: string): Promise<RemoveTemplateResponse> {
+    const data = await this.rpc('removeTemplate', { name });
+    return removeTemplateResponseSchema.parse(data);
+  }
+
   /**
    * Runs a shell command inside the sandbox behind a user key and returns
    * the buffered result: honest exit code (a nonzero exit is a result, not
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index 5f1cda1..34feb4b 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -3,6 +3,7 @@
 // without installing @dormice/shared themselves.
 export * from '@dormice/shared';
 export {
+  type AcquireSandboxOptions,
   Dormice,
   DormiceApiError,
   type DormiceOptions,
diff --git a/packages/server/drizzle/0003_templates.sql b/packages/server/drizzle/0003_templates.sql
new file mode 100644
index 0000000..8ad92f0
--- /dev/null
+++ b/packages/server/drizzle/0003_templates.sql
@@ -0,0 +1,7 @@
+CREATE TABLE `templates` (
+	`name` text PRIMARY KEY NOT NULL,
+	`image` text NOT NULL,
+	`created_at` text NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE `sandboxes` ADD `template` text;
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/0003_snapshot.json b/packages/server/drizzle/meta/0003_snapshot.json
new file mode 100644
index 0000000..89c5063
--- /dev/null
+++ b/packages/server/drizzle/meta/0003_snapshot.json
@@ -0,0 +1,173 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "1f1a3eaf-d3bf-47d5-b6e4-364b73fd1b3a",
+  "prevId": "f741bfad-03cf-4605-a353-c4b409ddc2a0",
+  "tables": {
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "user_key": {
+          "name": "user_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_user_key_unique": {
+          "name": "sandboxes_user_key_unique",
+          "columns": [
+            "user_key"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index 624a755..aab5880 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -22,6 +22,13 @@
       "when": 1783592514453,
       "tag": "0002_e2b-columns",
       "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1783681552934,
+      "tag": "0003_templates",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index 4826518..358f6b9 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -859,3 +859,136 @@ describe('POST /releaseSandbox', () => {
     expect(res.json()).toEqual({ released: false });
   });
 });
+
+describe('templates', () => {
+  it('registers, lists and requires auth like every native verb', async () => {
+    const { app } = testApp();
+    const anon = await app.inject({
+      method: 'POST',
+      url: '/registerTemplate',
+      payload: { name: 'py', image: 'img-a' },
+    });
+    expect(anon.statusCode).toBe(401);
+
+    const res = await rpc(app, '/registerTemplate', {
+      name: 'py',
+      image: 'img-a',
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().template).toMatchObject({ name: 'py', image: 'img-a' });
+
+    const listed = await rpc(app, '/listTemplates');
+    expect(listed.json().templates).toMatchObject([
+      { name: 'py', image: 'img-a' },
+    ]);
+  });
+
+  it('re-registering re-points the name and keeps its birth date — the upgrade verb', async () => {
+    const { app } = testApp();
+    const first = (
+      await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' })
+    ).json().template;
+    const second = (
+      await rpc(app, '/registerTemplate', { name: 'py', image: 'img-b' })
+    ).json().template;
+    expect(second.image).toBe('img-b');
+    expect(second.createdAt).toBe(first.createdAt);
+    expect((await rpc(app, '/listTemplates')).json().templates).toHaveLength(1);
+  });
+
+  it("rejects a malformed name, and 'base' as reserved", async () => {
+    const { app } = testApp();
+    const bad = await rpc(app, '/registerTemplate', {
+      name: '-bad',
+      image: 'img',
+    });
+    expect(bad.statusCode).toBe(400);
+    const base = await rpc(app, '/registerTemplate', {
+      name: 'base',
+      image: 'img',
+    });
+    expect(base.statusCode).toBe(400);
+    expect(base.json().message).toMatch(/'base' is reserved/);
+  });
+
+  it('acquire with a template creates the sandbox from its image and records the name', async () => {
+    const { app, executor } = testApp();
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' });
+    const res = await acquire(app, { userKey: 'alice', template: 'py' });
+    expect(res.statusCode).toBe(200);
+    const sandbox = res.json().sandbox;
+    expect(sandbox.template).toBe('py');
+    // The physical half: the shell was actually born from the template's image.
+    expect(executor.imageOf(sandbox.sandboxId)).toBe('img-a');
+    // A template-less acquire stays on the base image, template null.
+    const plain = (await acquire(app, { userKey: 'bob' })).json().sandbox;
+    expect(plain.template).toBeNull();
+  });
+
+  it('rejects an unknown template with 400, on the wake path too', async () => {
+    const { app } = testApp();
+    const res = await acquire(app, { userKey: 'alice', template: 'ghost' });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().message).toBe(
+      "unknown template 'ghost' — register it first",
+    );
+    // Same answer when the key already has a sandbox: the caller's mistake
+    // deserves a 400 even when the value would not apply.
+    await acquire(app, { userKey: 'bob' });
+    const wake = await acquire(app, { userKey: 'bob', template: 'ghost' });
+    expect(wake.statusCode).toBe(400);
+  });
+
+  it('a valid template on an existing key is not applied — creation-time only', async () => {
+    const { app } = testApp();
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' });
+    const created = (await acquire(app, { userKey: 'alice' })).json().sandbox;
+    expect(created.template).toBeNull();
+    const again = (
+      await acquire(app, { userKey: 'alice', template: 'py' })
+    ).json().sandbox;
+    expect(again.sandboxId).toBe(created.sandboxId);
+    expect(again.template).toBeNull();
+  });
+
+  it('refuses to remove a template while sandboxes use it, naming the keys', async () => {
+    const { app } = testApp();
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' });
+    await acquire(app, { userKey: 'alice', template: 'py' });
+
+    const refused = await rpc(app, '/removeTemplate', { name: 'py' });
+    expect(refused.statusCode).toBe(409);
+    expect(refused.json().message).toBe(
+      "template 'py' is used by 1 sandbox(es): alice — release them first",
+    );
+
+    await rpc(app, '/releaseSandbox', { userKey: 'alice' });
+    expect((await rpc(app, '/removeTemplate', { name: 'py' })).json()).toEqual({
+      removed: true,
+    });
+    // Idempotent on an unknown name, like releaseSandbox.
+    expect((await rpc(app, '/removeTemplate', { name: 'py' })).json()).toEqual({
+      removed: false,
+    });
+  });
+
+  it('re-point then rebuild moves the sandbox onto the new image — the upgrade front door', async () => {
+    const { app, executor } = testApp();
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
+    const created = (
+      await acquire(app, { userKey: 'alice', template: 'py' })
+    ).json().sandbox;
+    expect(executor.imageOf(created.sandboxId)).toBe('img-v1');
+
+    // Operator builds a new image and re-points the name; the stock moves
+    // per sandbox, on its own rebuild — never behind its back.
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });
+    expect(executor.imageOf(created.sandboxId)).toBe('img-v1');
+
+    await rpc(app, '/rebuildSandbox', { userKey: 'alice' });
+    const woken = (await acquire(app, { userKey: 'alice' })).json().sandbox;
+    expect(woken.sandboxId).toBe(created.sandboxId);
+    // The rebuilt shell was born from the template's *current* image.
+    expect(executor.imageOf(created.sandboxId)).toBe('img-v2');
+  });
+});
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 00a74eb..bf1127c 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -18,6 +18,7 @@ import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
 import { consoleRoutes } from './routes/console';
 import { sandboxRoutes } from './routes/sandboxes';
+import { templateRoutes } from './routes/templates';
 import { createSandboxProxy } from './sandbox-proxy';
 
 export interface AppDeps {
@@ -133,6 +134,7 @@ export function buildApp({
   app.register(async (api) => {
     api.addHook('onRequest', requireApiAuth(config.DORMICE_API_TOKEN));
     await api.register(sandboxRoutes, { config, db, executor, locks });
+    await api.register(templateRoutes, { db });
   });
 
   // The web console: session endpoints (open — login carries the token
diff --git a/packages/server/src/db/ledger.ts b/packages/server/src/db/ledger.ts
index a92fb24..1cb95bf 100644
--- a/packages/server/src/db/ledger.ts
+++ b/packages/server/src/db/ledger.ts
@@ -31,6 +31,8 @@ export interface CreateSandboxInput {
   userKey: string;
   nodeId: string;
   policy: LifecyclePolicy;
+  /** Template the sandbox is created from; absent/null means the base image. */
+  template?: string | null;
   /** E2B-surface extras; native acquire never sets them. */
   e2b?: {
     /** JSON-serialized objects, stored verbatim. */
@@ -52,6 +54,7 @@ export function createSandbox(db: Db, input: CreateSandboxInput): SandboxRow {
     freezeAfterSeconds: input.policy.freezeAfterSeconds,
     stopAfterSeconds: input.policy.stopAfterSeconds,
     archiveAfterSeconds: input.policy.archiveAfterSeconds,
+    template: input.template ?? null,
     createdAt: now,
     lastActiveAt: now,
     metadata: input.e2b?.metadata ?? null,
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index f61a6cc..5fc70b1 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -21,6 +21,13 @@ export const sandboxes = sqliteTable('sandboxes', {
   stopAfterSeconds: integer('stop_after_seconds'),
   /** NULL means never archive. */
   archiveAfterSeconds: integer('archive_after_seconds'),
+  /**
+   * Template the sandbox was created from; NULL means the base image. The
+   * name is recorded, not the image it pointed at when the sandbox was born:
+   * shells are rebuilt from the template's *current* image — the same rule
+   * that already governs the base image.
+   */
+  template: text('template'),
   createdAt: text('created_at').notNull(),
   lastActiveAt: text('last_active_at').notNull(),
   /**
@@ -45,3 +52,17 @@ export const sandboxes = sqliteTable('sandboxes', {
 });
 
 export type SandboxRow = typeof sandboxes.$inferSelect;
+
+/**
+ * Registered templates: a name for a Docker image that lives on this host.
+ * The host's Docker daemon is the image store; this table only records which
+ * name points where. Sandboxes reference templates by name (column above),
+ * so re-pointing a name upgrades every future shell built for it.
+ */
+export const templates = sqliteTable('templates', {
+  name: text('name').primaryKey(),
+  image: text('image').notNull(),
+  createdAt: text('created_at').notNull(),
+});
+
+export type TemplateRow = typeof templates.$inferSelect;
diff --git a/packages/server/src/db/templates.ts b/packages/server/src/db/templates.ts
new file mode 100644
index 0000000..7193314
--- /dev/null
+++ b/packages/server/src/db/templates.ts
@@ -0,0 +1,83 @@
+import { eq } from 'drizzle-orm';
+import type { Db } from './db';
+import { sandboxes, type TemplateRow, templates } from './schema';
+
+/**
+ * Upsert: registering an existing name re-points it at the new image. That
+ * is the template upgrade front door — build a new image, re-register the
+ * name, then rebuildSandbox the stock that should move onto it.
+ */
+export function registerTemplate(
+  db: Db,
+  input: { name: string; image: string },
+): TemplateRow {
+  const row: TemplateRow = {
+    name: input.name,
+    image: input.image,
+    createdAt: new Date().toISOString(),
+  };
+  db.insert(templates)
+    .values(row)
+    .onConflictDoUpdate({
+      target: templates.name,
+      set: { image: input.image },
+    })
+    .run();
+  // Re-read instead of returning the literal: an upsert on an existing name
+  // keeps its original createdAt.
+  const stored = findTemplate(db, input.name);
+  if (!stored) {
+    throw new Error(`template ${input.name} vanished mid-register`);
+  }
+  return stored;
+}
+
+export function listTemplates(db: Db): TemplateRow[] {
+  return db.select().from(templates).all();
+}
+
+export function findTemplate(db: Db, name: string): TemplateRow | undefined {
+  return db.select().from(templates).where(eq(templates.name, name)).get();
+}
+
+/** Returns true when a row existed and was removed. */
+export function removeTemplate(db: Db, name: string): boolean {
+  const existed = findTemplate(db, name) !== undefined;
+  db.delete(templates).where(eq(templates.name, name)).run();
+  return existed;
+}
+
+/**
+ * User keys of sandboxes still created from this template — removal is
+ * refused while this is non-empty, so wakes never resolve a dangling name.
+ */
+export function sandboxKeysUsingTemplate(db: Db, name: string): string[] {
+  return db
+    .select({ userKey: sandboxes.userKey })
+    .from(sandboxes)
+    .where(eq(sandboxes.template, name))
+    .all()
+    .map((row) => row.userKey);
+}
+
+/**
+ * The single arbiter turning a sandbox row's template into the image its
+ * next shell boots. Null means the base image — expressed as undefined so
+ * the executor falls back to its own configured default. A registered name
+ * resolves to the template's *current* image; a missing row means the
+ * removal guard was bypassed (ledger drift), which is worth an honest crash,
+ * not a silent fallback to the wrong image.
+ */
+export function resolveImage(
+  db: Db,
+  template: string | null,
+): string | undefined {
+  if (template === null) {
+    return undefined;
+  }
+  const row = findTemplate(db, template);
+  if (!row) {
+    throw new Error(`template '${template}' is not registered`);
+  }
+  return row.image;
+}
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 02265c8..e13593b 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -5,7 +5,7 @@ import { buildApp } from '../app';
 import { loadConfig } from '../config';
 import { migrateDb, openDb } from '../db/db';
 import { findBySandboxId, setDeadline } from '../db/ledger';
-import { FakeExecutor } from '../executor/fake';
+import { FAKE_BASE_IMAGE, FakeExecutor } from '../executor/fake';
 import { KeyedQueue } from '../keyed-queue';
 import { scanOnce } from '../scanner';
 import { mintEnvdToken } from './protocol';
@@ -13,13 +13,17 @@ import { mintEnvdToken } from './protocol';
 const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
 const TOKEN = 'test-token-test-token-test-token';
 
-function testApp(executor: FakeExecutor = new FakeExecutor()) {
+function testApp(
+  executor: FakeExecutor = new FakeExecutor(),
+  env: Record<string, string> = {},
+) {
   const db = openDb(':memory:');
   migrateDb(db, MIGRATIONS);
   const config = loadConfig({
     DORMICE_DB_PATH: ':memory:',
     DORMICE_NODE_ID: 'node-test',
     DORMICE_API_TOKEN: TOKEN,
+    ...env,
   });
   const locks = new KeyedQueue();
   const app = buildApp({ config, db, executor, locks, logger: false });
@@ -1549,3 +1553,104 @@ describe('signed file URLs at the daemon root', () => {
     expect(asRoot.body).toBe('root readable\n');
   });
 });
+
+describe('E2B templates', () => {
+  // Registration is a native verb; the compat surface only consumes it.
+  async function registerTemplate(t: TestApp, name: string, image: string) {
+    const res = await t.app.inject({
+      method: 'POST',
+      url: '/registerTemplate',
+      headers: { authorization: `Bearer ${TOKEN}` },
+      payload: { name, image },
+    });
+    expect(res.statusCode).toBe(200);
+  }
+
+  it('creates from a registered templateID: its image boots, name echoes as templateID and alias', async () => {
+    const t = testApp();
+    await registerTemplate(t, 'py311', 'img-py');
+    const res = await control(t, 'POST', '/sandboxes', { templateID: 'py311' });
+    expect(res.statusCode).toBe(201);
+    const body = res.json();
+    expect(body.templateID).toBe('py311');
+    expect(body.alias).toBe('py311');
+    // The physical half: the shell was born from the template's image.
+    expect(t.executor.imageOf(body.sandboxID)).toBe('img-py');
+
+    const info = await control(t, 'GET', `/sandboxes/${body.sandboxID}`);
+    // The SDK maps wire templateID -> SandboxInfo.templateId and a truthy
+    // alias -> SandboxInfo.name.
+    expect(info.json()).toMatchObject({ templateID: 'py311', alias: 'py311' });
+  });
+
+  it('answers an unknown templateID with 404 in the control-plane dialect', async () => {
+    const res = await control(testApp(), 'POST', '/sandboxes', {
+      templateID: 'nope',
+    });
+    expect(res.statusCode).toBe(404);
+    // openapi-fetch parses this body; the SDK then throws
+    // SandboxError("404: template 'nope' not found").
+    expect(res.json()).toEqual({
+      code: 404,
+      message: "template 'nope' not found",
+    });
+  });
+
+  it("'base', the configured base image name, and absence all mean the base image", async () => {
+    const t = testApp(new FakeExecutor(), {
+      DORMICE_BASE_IMAGE: 'dormice-base:test',
+    });
+    for (const payload of [
+      {},
+      { templateID: 'base' },
+      { templateID: 'dormice-base:test' },
+    ]) {
+      const res = await control(t, 'POST', '/sandboxes', payload);
+      expect(res.statusCode).toBe(201);
+      const body = res.json();
+      // Echo keeps the pre-templates shape: the base image name, no alias.
+      expect(body.templateID).toBe('dormice-base:test');
+      expect(body.alias).toBeUndefined();
+      expect(t.executor.imageOf(body.sandboxID)).toBe(FAKE_BASE_IMAGE);
+    }
+  });
+
+  it('userKey reuse keeps the original template; an unknown one still 404s first', async () => {
+    const t = testApp();
+    await registerTemplate(t, 'tpl-a', 'img-a');
+    await registerTemplate(t, 'tpl-b', 'img-b');
+    const first = await createSandbox(t, {
+      templateID: 'tpl-a',
+      metadata: { userKey: 'alice' },
+    });
+
+    // Same key, different template: the stored one stays — same principle
+    // as metadata and envs on the reuse path.
+    const again = await control(t, 'POST', '/sandboxes', {
+      templateID: 'tpl-b',
+      metadata: { userKey: 'alice' },
+    });
+    expect(again.statusCode).toBe(201);
+    expect(again.json().sandboxID).toBe(first.sandboxID);
+    expect(again.json().templateID).toBe('tpl-a');
+
+    // Validation happens before the reuse shortcut: a typo is a typo.
+    const typo = await control(t, 'POST', '/sandboxes', {
+      templateID: 'ghost',
+      metadata: { userKey: 'alice' },
+    });
+    expect(typo.statusCode).toBe(404);
+  });
+
+  it('list items carry the template as templateID', async () => {
+    const t = testApp();
+    await registerTemplate(t, 'py311', 'img-py');
+    await createSandbox(t, {
+      templateID: 'py311',
+      metadata: { userKey: 'tpl-list' },
+    });
+    const res = await control(t, 'GET', '/v2/sandboxes');
+    const items = res.json() as Array<{ templateID: string; alias?: string }>;
+    expect(items).toMatchObject([{ templateID: 'py311', alias: 'py311' }]);
+  });
+});
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index c3bd47d..d3e7e56 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -13,6 +13,7 @@ import {
   touch,
 } from '../db/ledger';
 import type { SandboxRow } from '../db/schema';
+import { findTemplate, resolveImage } from '../db/templates';
 import {
   freezeSandbox,
   releaseSandbox,
@@ -125,12 +126,22 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     ? { domain: config.DORMICE_SANDBOX_DOMAIN }
     : {};
 
+  // What the views report as the sandbox's template. E2B's alias is the
+  // template's human name — present only when a registered template was
+  // used; a base sandbox echoes the base image name (or 'base') as its
+  // templateID, the honest pre-templates behavior kept for round-trips.
+  function templateFields(row: SandboxRow) {
+    return {
+      templateID: row.template ?? config.DORMICE_BASE_IMAGE ?? 'base',
+      ...(row.template ? { alias: row.template } : {}),
+    };
+  }
+
   /** What create and connect answer with. */
   function sessionView(row: SandboxRow) {
     return {
       sandboxID: row.sandboxId,
-      templateID: config.DORMICE_BASE_IMAGE ?? 'base',
-      alias: row.userKey,
+      ...templateFields(row),
       envdVersion: ENVD_VERSION,
       envdAccessToken: mintEnvdToken(config.DORMICE_API_TOKEN, row.sandboxId),
       ...domainField,
@@ -141,8 +152,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   function infoView(row: SandboxRow, state: 'running' | 'paused') {
     return {
       sandboxID: row.sandboxId,
-      templateID: config.DORMICE_BASE_IMAGE ?? 'base',
-      alias: row.userKey,
+      ...templateFields(row),
       metadata: row.metadata ? JSON.parse(row.metadata) : {},
       state,
       startedAt: row.createdAt,
@@ -208,6 +218,23 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       }
       const userKey = requestedKey ?? `e2b-${randomUUID()}`;
 
+      // templateID resolution: a registered name wins; 'base', the base
+      // image's own name (we have always echoed it as templateID, so it must
+      // round-trip) and absence mean the base image; anything else is 404 —
+      // the SDK default is the literal string 'base', so `Sandbox.create()`
+      // with no template lands on the base image by name, not by fallback.
+      let template: string | null = null;
+      if (body.templateID !== undefined) {
+        if (findTemplate(db, body.templateID)) {
+          template = body.templateID;
+        } else if (
+          body.templateID !== 'base' &&
+          body.templateID !== config.DORMICE_BASE_IMAGE
+        ) {
+          throw apiError(404, `template '${body.templateID}' not found`);
+        }
+      }
+
       const row = await locks.run(userKey, async () => {
         const existing = findByUserKey(db, userKey);
         if (existing && e2bView(existing, new Date()) !== 'dead') {
@@ -232,12 +259,15 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
           );
         }
         const sandboxId = randomUUID();
-        await executor.create(sandboxId);
+        await executor.create(sandboxId, {
+          image: resolveImage(db, template),
+        });
         return createSandbox(db, {
           sandboxId,
           userKey,
           nodeId: config.DORMICE_NODE_ID,
           policy: resolvePolicy(undefined),
+          template,
           e2b: {
             metadata: body.metadata ? JSON.stringify(body.metadata) : null,
             envs:
diff --git a/packages/server/src/e2b/view.test.ts b/packages/server/src/e2b/view.test.ts
index 22cf17b..91a98ae 100644
--- a/packages/server/src/e2b/view.test.ts
+++ b/packages/server/src/e2b/view.test.ts
@@ -11,6 +11,7 @@ function row(overrides: Partial<SandboxRow>): SandboxRow {
     freezeAfterSeconds: 60,
     stopAfterSeconds: null,
     archiveAfterSeconds: null,
+    template: null,
     createdAt: '2026-07-09T00:00:00.000Z',
     lastActiveAt: '2026-07-09T00:00:00.000Z',
     metadata: null,
diff --git a/packages/server/src/executor/contract/image.ts b/packages/server/src/executor/contract/image.ts
new file mode 100644
index 0000000..c85a457
--- /dev/null
+++ b/packages/server/src/executor/contract/image.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import type { ContractContext } from './index';
+
+/**
+ * Which image a shell boots from — the physical half of templates. The rule
+ * under exam: an image is a property of the shell, fixed at the shell's
+ * birth (create, or start's rebuild-from-surviving-disk), and never changed
+ * by merely starting an existing container.
+ */
+export function imageTests(ctx: ContractContext) {
+  const { timeoutMs } = ctx;
+
+  describe('image', () => {
+    it(
+      'create boots the requested image',
+      async () => {
+        const id = await ctx.fresh({ image: ctx.subject.altImage });
+        expect(await ctx.subject.imageOf(id)).toBe(ctx.subject.altImage);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'create without an image boots the base image',
+      async () => {
+        const id = await ctx.fresh();
+        expect(await ctx.subject.imageOf(id)).toBe(ctx.subject.baseImage);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a rebuilt shell boots the requested image over the same disk',
+      async () => {
+        // Born on the base image, with data on the disk.
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: 'kept.txt', content: Buffer.from('survives the swap') },
+        ]);
+        await ctx.executor.freeze(id);
+        await ctx.executor.stop(id);
+        await ctx.subject.vanishContainer(id);
+        // The rebuild is where a new image takes effect: new shell, old disk.
+        await ctx.executor.start(id, { image: ctx.subject.altImage });
+        expect(await ctx.subject.imageOf(id)).toBe(ctx.subject.altImage);
+        const kept = await ctx.executor.readFile(id, 'kept.txt');
+        expect(kept.toString()).toBe('survives the swap');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'starting an existing container never changes its image',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.freeze(id);
+        await ctx.executor.stop(id);
+        // The exited container object still exists — start only starts it;
+        // the image asked for here must be ignored, not applied.
+        await ctx.executor.start(id, { image: ctx.subject.altImage });
+        expect(await ctx.subject.imageOf(id)).toBe(ctx.subject.baseImage);
+      },
+      timeoutMs,
+    );
+  });
+}
diff --git a/packages/server/src/executor/contract/index.ts b/packages/server/src/executor/contract/index.ts
index 0bb48df..81a7a6b 100644
--- a/packages/server/src/executor/contract/index.ts
+++ b/packages/server/src/executor/contract/index.ts
@@ -1,17 +1,19 @@
 import { randomUUID } from 'node:crypto';
 import { afterEach, beforeEach, describe } from 'vitest';
-import type { ContainerState, Executor } from '../executor';
+import type { ContainerState, Executor, ShellOptions } from '../executor';
 import { entryTests } from './entries';
 import { execTests } from './exec';
 import { execStreamTests } from './exec-stream';
 import { fileTests } from './files';
+import { imageTests } from './image';
 import { lifecycleTests } from './lifecycle';
 import { metricsTests } from './metrics';
 import { watchTests } from './watch';
 
 /**
  * What a contract run needs beyond the executor itself: a way to stage the
- * one drift an executor cannot produce through its own verbs.
+ * one drift an executor cannot produce through its own verbs, and a window
+ * on which image a shell was born from.
  */
 export interface ContractSubject {
   executor: Executor;
@@ -23,6 +25,21 @@ export interface ContractSubject {
    * and "destroy takes the leftover disk" must hold on both implementations.
    */
   vanishContainer(sandboxId: string): Promise<void>;
+  /** The image shells boot from when create/start name none. */
+  baseImage: string;
+  /**
+   * A second image name that resolves on this subject — templates are named
+   * images, so the exam needs two names to tell apart. The docker subject
+   * tags its base image under an alias (physically identical, which is fine:
+   * the question is which name the shell records); the fake uses any string.
+   */
+  altImage: string;
+  /**
+   * The image the sandbox's current shell was born from. The fake reads its
+   * map; the docker subject inspects Config.Image. Throws when no shell
+   * exists — an image is a property of the shell.
+   */
+  imageOf(sandboxId: string): Promise<string>;
 }
 
 /**
@@ -35,7 +52,7 @@ export interface ContractContext {
   readonly subject: ContractSubject;
   timeoutMs: number;
   /** A fresh running sandbox, registered for after-test destruction. */
-  fresh(): Promise<string>;
+  fresh(opts?: ShellOptions): Promise<string>;
   /** Walks a fresh sandbox down to stopped: exited container plus disk. */
   freshStopped(): Promise<string>;
   stateOf(sandboxId: string): Promise<ContainerState | undefined>;
@@ -91,10 +108,10 @@ export function describeExecutorContract(
         return subject;
       },
       timeoutMs,
-      async fresh() {
+      async fresh(opts) {
         const sandboxId = randomUUID();
         created.push(sandboxId);
-        await executor.create(sandboxId);
+        await executor.create(sandboxId, opts);
         return sandboxId;
       },
       async freshStopped() {
@@ -118,6 +135,7 @@ export function describeExecutorContract(
     };
 
     lifecycleTests(ctx);
+    imageTests(ctx);
     execTests(ctx);
     execStreamTests(ctx);
     fileTests(ctx);
diff --git a/packages/server/src/executor/docker.contract.test.ts b/packages/server/src/executor/docker.contract.test.ts
index 2bc8e56..615fc68 100644
--- a/packages/server/src/executor/docker.contract.test.ts
+++ b/packages/server/src/executor/docker.contract.test.ts
@@ -2,10 +2,17 @@ import { mkdtemp } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import Docker from 'dockerode';
-import { describe } from 'vitest';
+import { afterAll, describe } from 'vitest';
 import { describeExecutorContract } from './contract';
 import { containerName, DockerExecutor } from './docker';
 
+/**
+ * The exam's second image name: the base image tagged under an alias.
+ * Physically identical to the base — the image chapter asks which *name*
+ * a shell records, not what is inside.
+ */
+const ALT_IMAGE = 'dormice-contract-alt:latest';
+
 /**
  * The real-machine half of the executor contract. Needs a Linux host with
  * Docker + gVisor, the base image built, and root (loop mounts, cgroups) —
@@ -34,6 +41,11 @@ if (process.env.DORMICE_DOCKER_CONTRACT === '1' && image) {
         pidsLimit: 256,
         reclaimTimeoutSeconds: 45,
       });
+      // Idempotent: re-tagging the same target is a no-op, and the tag is
+      // removed once after the whole file (afterAll below).
+      await new Docker()
+        .getImage(image)
+        .tag({ repo: 'dormice-contract-alt', tag: 'latest' });
       return {
         executor,
         // The prune analog: remove the container object straight through
@@ -43,11 +55,27 @@ if (process.env.DORMICE_DOCKER_CONTRACT === '1' && image) {
             .getContainer(containerName(sandboxId))
             .remove({ force: true });
         },
+        baseImage: image,
+        altImage: ALT_IMAGE,
+        imageOf: async (sandboxId: string) => {
+          const info = await new Docker()
+            .getContainer(containerName(sandboxId))
+            .inspect();
+          return info.Config.Image;
+        },
       };
     },
     // Real containers under gVisor take seconds per operation.
     { timeoutMs: 120_000 },
   );
+
+  afterAll(async () => {
+    try {
+      await new Docker().getImage(ALT_IMAGE).remove();
+    } catch {
+      // Never tagged (suite failed before makeSubject) — nothing to clean.
+    }
+  });
 } else {
   describe.skip('executor contract: DockerExecutor (set DORMICE_DOCKER_CONTRACT=1 and DORMICE_DOCKER_CONTRACT_IMAGE on a Linux docker host)', () => {});
 }
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 178deea..5b54a17 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -60,6 +60,7 @@ import {
   type PtySize,
   type SandboxEntry,
   type SandboxMetrics,
+  type ShellOptions,
   type WatchDirHandle,
   type WatchDirOptions,
 } from './executor';
@@ -142,12 +143,12 @@ export class DockerExecutor implements Executor {
     this.docker = docker ?? new Docker({ socketPath: '/var/run/docker.sock' });
   }
 
-  async create(sandboxId: string): Promise<void> {
+  async create(sandboxId: string, opts?: ShellOptions): Promise<void> {
     if ((await this.inspect(sandboxId)) !== null) {
       throw new Error(`container ${sandboxId} already exists`);
     }
     await this.provisionDisk(sandboxId);
-    await this.launchContainer(sandboxId);
+    await this.launchContainer(sandboxId, opts?.image);
   }
 
   async freeze(sandboxId: string): Promise<void> {
@@ -180,7 +181,7 @@ export class DockerExecutor implements Executor {
     await container.wait({ condition: 'not-running' });
   }
 
-  async start(sandboxId: string): Promise<void> {
+  async start(sandboxId: string, opts?: ShellOptions): Promise<void> {
     const found = await this.inspect(sandboxId);
     if (found === null) {
       // The container object is gone — a routine `docker container prune`
@@ -190,7 +191,7 @@ export class DockerExecutor implements Executor {
         throw new Error(`disk ${sandboxId} is absent, cannot start`);
       }
       await this.ensureMounted(sandboxId);
-      await this.launchContainer(sandboxId);
+      await this.launchContainer(sandboxId, opts?.image);
       return;
     }
     const actual = containerStateFromDocker(found.status);
@@ -1154,14 +1155,18 @@ export class DockerExecutor implements Executor {
   /**
    * Creates and starts the sandbox's container around its already-mounted
    * disk — the shell half of a sandbox, shared by create() (first birth)
-   * and start() (rebuild after the container object was lost).
+   * and start() (rebuild after the container object was lost). The single
+   * point where an image becomes a container.
    */
-  private async launchContainer(sandboxId: string): Promise<void> {
+  private async launchContainer(
+    sandboxId: string,
+    image?: string,
+  ): Promise<void> {
     let container: Docker.Container;
     try {
       container = await this.docker.createContainer({
         name: containerName(sandboxId),
-        Image: this.opts.baseImage,
+        Image: image ?? this.opts.baseImage,
         Cmd: ['sleep', 'infinity'],
         Labels: { [SANDBOX_LABEL]: sandboxId },
         HostConfig: {
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index da8e038..7d5c1e8 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -209,6 +209,16 @@ export class FileTooLargeError extends Error {}
  */
 export class DiskFullError extends Error {}
 
+/**
+ * What a sandbox's shell is built from. Consulted only at the shell's birth
+ * — create(), and start()'s rebuild-from-surviving-disk path; an existing
+ * container keeps the image it was born with.
+ */
+export interface ShellOptions {
+  /** Image reference on this host; absent means the executor's configured base image. */
+  image?: string;
+}
+
 /**
  * The executor is where lifecycle decisions become physical reality:
  * containers created, paused, stopped. The daemon's decision logic (the
@@ -218,8 +228,12 @@ export class DiskFullError extends Error {}
  * a container runtime.
  */
 export interface Executor {
-  /** Brings a brand-new sandbox up to running. */
-  create(sandboxId: string): Promise<void>;
+  /**
+   * Brings a brand-new sandbox up to running. `image` picks what the shell
+   * boots from (a template's current image); absent means the executor's
+   * configured base image.
+   */
+  create(sandboxId: string, opts?: ShellOptions): Promise<void>;
   /** Running -> paused: stops consuming CPU, memory becomes reclaimable. */
   freeze(sandboxId: string): Promise<void>;
   /** Paused -> running. */
@@ -230,9 +244,11 @@ export interface Executor {
    * Stopped -> running again, from the kept disk. The disk is required; the
    * container object is not — if it was removed behind the daemon's back
    * (a `docker container prune` eats exited containers), a fresh container
-   * is rebuilt around the surviving disk.
+   * is rebuilt around the surviving disk. `image` applies only to that
+   * rebuild: an image is a property of the shell, fixed at the shell's
+   * birth — starting a container that already exists never changes it.
    */
-  start(sandboxId: string): Promise<void>;
+  start(sandboxId: string, opts?: ShellOptions): Promise<void>;
   /**
    * Removes the container and its disk for good, whatever state — or
    * whichever half of the pair — still exists. Throws only when both are
@@ -242,8 +258,9 @@ export interface Executor {
   /**
    * Removes the container object, whatever state, and keeps the disk —
    * rebuild's physical half. The next start() builds a fresh container from
-   * the surviving disk (and thus from the daemon's *current* base image);
-   * this is how a sandbox upgrades its shared layers without losing data.
+   * the surviving disk (and thus from the *current* image of the sandbox's
+   * template, or the daemon's current base image); this is how a sandbox
+   * upgrades its shared layers without losing data.
    * A container already gone is the goal state as long as the disk remains;
    * both absent throws, like destroy — the ledger and reality disagree.
    */
diff --git a/packages/server/src/executor/fake.test.ts b/packages/server/src/executor/fake.test.ts
index a9af5ee..c2c00db 100644
--- a/packages/server/src/executor/fake.test.ts
+++ b/packages/server/src/executor/fake.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { describeExecutorContract } from './contract';
-import { FakeExecutor } from './fake';
+import { FAKE_BASE_IMAGE, FakeExecutor } from './fake';
 
 describeExecutorContract('FakeExecutor', () => {
   const executor = new FakeExecutor();
@@ -8,6 +8,16 @@ describeExecutorContract('FakeExecutor', () => {
     executor,
     vanishContainer: async (sandboxId: string) =>
       executor.vanishContainer(sandboxId),
+    baseImage: FAKE_BASE_IMAGE,
+    // Any string: the fake plays whatever image it is asked to.
+    altImage: 'fake-alt-image',
+    imageOf: async (sandboxId: string) => {
+      const image = executor.imageOf(sandboxId);
+      if (!image) {
+        throw new Error(`no shell for ${sandboxId}`);
+      }
+      return image;
+    },
   };
 });
 
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index c697b63..6d3bb42 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -20,11 +20,15 @@ import {
   type PtySize,
   type SandboxEntry,
   type SandboxMetrics,
+  type ShellOptions,
   type WatchDirHandle,
   type WatchDirOptions,
   type WatchEvent,
 } from './executor';
 
+/** The image the fake's shells boot from when no other image is asked for. */
+export const FAKE_BASE_IMAGE = 'fake-base';
+
 /**
  * Directories every real sandbox is born with, with the owner and mode
  * reality gives them: the image's skeleton plus lost+found — the mkfs.ext4
@@ -177,6 +181,13 @@ class FakeProcessIO {
 export class FakeExecutor implements Executor {
   private readonly containers = new Map<string, ContainerState>();
   private readonly disks = new Set<string>();
+  /**
+   * The image each shell was born from. Keyed like containers, not disks:
+   * an image is a property of the shell, set at its birth and gone with it
+   * — that is what lets a rebuilt shell boot a different image over the
+   * same disk.
+   */
+  private readonly images = new Map<string, string>();
   /**
    * Live processes per sandbox. stop/destroy/vanish kill them — on the real
    * executor the container's death takes every exec with it, and the fake
@@ -209,6 +220,11 @@ export class FakeExecutor implements Executor {
     return this.containers.get(sandboxId);
   }
 
+  /** Test hook: the image the sandbox's current shell was born from. */
+  imageOf(sandboxId: string): string | undefined {
+    return this.images.get(sandboxId);
+  }
+
   /**
    * Test hook: the container disappears, the disk stays — a removal behind
    * the daemon's back, or a crash in the middle of destroy. The one-sided
@@ -218,6 +234,7 @@ export class FakeExecutor implements Executor {
     if (!this.containers.delete(sandboxId)) {
       throw new Error(`container ${sandboxId} is absent, cannot vanish`);
     }
+    this.images.delete(sandboxId);
     this.killProcesses(sandboxId);
   }
 
@@ -229,13 +246,14 @@ export class FakeExecutor implements Executor {
     this.disks.add(sandboxId);
   }
 
-  async create(sandboxId: string): Promise<void> {
+  async create(sandboxId: string, opts?: ShellOptions): Promise<void> {
     if (this.containers.has(sandboxId)) {
       throw new Error(`container ${sandboxId} already exists`);
     }
     this.disks.add(sandboxId);
     this.fs.set(sandboxId, seededDisk());
     this.containers.set(sandboxId, 'running');
+    this.images.set(sandboxId, opts?.image ?? FAKE_BASE_IMAGE);
   }
 
   async freeze(sandboxId: string): Promise<void> {
@@ -254,7 +272,7 @@ export class FakeExecutor implements Executor {
     this.killProcesses(sandboxId);
   }
 
-  async start(sandboxId: string): Promise<void> {
+  async start(sandboxId: string, opts?: ShellOptions): Promise<void> {
     const actual = this.containers.get(sandboxId);
     if (actual === undefined) {
       // The container object is gone (pruned, removed behind the daemon's
@@ -264,9 +282,12 @@ export class FakeExecutor implements Executor {
         throw new Error(`disk ${sandboxId} is absent, cannot start`);
       }
       this.containers.set(sandboxId, 'running');
+      this.images.set(sandboxId, opts?.image ?? FAKE_BASE_IMAGE);
       return;
     }
     this.expect(sandboxId, 'stopped');
+    // The existing shell keeps the image it was born with — start only
+    // starts; opts.image applies to the rebuild path above.
     this.containers.set(sandboxId, 'running');
   }
 
@@ -278,6 +299,7 @@ export class FakeExecutor implements Executor {
     // hearing.
     const hadContainer = this.containers.delete(sandboxId);
     const hadDisk = this.disks.delete(sandboxId);
+    this.images.delete(sandboxId);
     this.fs.delete(sandboxId);
     this.killProcesses(sandboxId);
     this.closeUpstream(sandboxId);
@@ -295,6 +317,7 @@ export class FakeExecutor implements Executor {
     if (!hadContainer && !this.disks.has(sandboxId)) {
       throw new Error(`container ${sandboxId} is absent, cannot remove`);
     }
+    this.images.delete(sandboxId);
     // The container's death takes every process and watcher with it, same
     // physics as stop and vanish.
     this.killProcesses(sandboxId);
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index b25f805..41bfaf1 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -1,6 +1,7 @@
 import type { Db } from './db/db';
 import { deleteSandbox, setPausedByUser, transition } from './db/ledger';
 import type { SandboxRow } from './db/schema';
+import { resolveImage } from './db/templates';
 import type { Executor } from './executor/executor';
 
 /**
@@ -51,10 +52,11 @@ export async function releaseSandbox(
  * Swap the shell, keep the body: the container is removed (whatever state),
  * the disk stays, and the ledger records `stopped` — the state whose wake
  * path builds a fresh container from the surviving disk, and therefore from
- * the daemon's *current* base image. This is how an existing sandbox picks
- * up new shared layers without losing a byte of /home/user. Already-stopped
- * rows skip the ledger write: removing a pruned-away container is a no-op
- * and stopped -> stopped is not a transition.
+ * the *current* image of the sandbox's template (or the daemon's current
+ * base image). This is how an existing sandbox picks up new shared layers
+ * without losing a byte of /home/user. Already-stopped rows skip the ledger
+ * write: removing a pruned-away container is a no-op and stopped -> stopped
+ * is not a transition.
  */
 export async function rebuildSandbox(
   db: Db,
@@ -81,7 +83,11 @@ export async function wakeSandbox(
       await executor.unfreeze(row.sandboxId);
       return awaken(db, row);
     case 'stopped':
-      await executor.start(row.sandboxId);
+      // If the container object was pruned away, start rebuilds the shell —
+      // from the template's current image, resolved here at wake time.
+      await executor.start(row.sandboxId, {
+        image: resolveImage(db, row.template),
+      });
       return awaken(db, row);
     case 'archived':
     case 'restoring':
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index 99dd677..e39a8b8 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -30,6 +30,7 @@ import {
   touch,
 } from '../db/ledger';
 import type { SandboxRow } from '../db/schema';
+import { findTemplate, resolveImage } from '../db/templates';
 import { startExecHeartbeat } from '../exec-heartbeat';
 import {
   type Executor,
@@ -62,6 +63,7 @@ function toSandbox(row: SandboxRow, endpoint: string): Sandbox {
       stopAfterSeconds: row.stopAfterSeconds,
       archiveAfterSeconds: row.archiveAfterSeconds,
     },
+    template: row.template,
     createdAt: row.createdAt,
     lastActiveAt: row.lastActiveAt,
   };
@@ -84,11 +86,14 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
   async function findOrCreate(
     userKey: string,
     policy: LifecyclePolicy,
+    template: string | null,
   ): Promise<SandboxRow> {
     const existing = findByUserKey(db, userKey);
     if (existing) {
       // Wake whatever cold state it is in (a single jump back to active),
       // then refresh the idle clock — an acquire is what "activity" means.
+      // A requested template is not applied: like policy, it takes effect
+      // only when this acquire creates the sandbox.
       const awake = await wakeSandbox(db, executor, existing);
       return touch(db, awake.sandboxId);
     }
@@ -112,12 +117,13 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     // alphabet is safe everywhere an id will land — Docker names, file
     // names, DNS labels.
     const sandboxId = randomUUID();
-    await executor.create(sandboxId);
+    await executor.create(sandboxId, { image: resolveImage(db, template) });
     return createSandbox(db, {
       sandboxId,
       userKey,
       nodeId: config.DORMICE_NODE_ID,
       policy,
+      template,
     });
   }
 
@@ -154,7 +160,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request, reply) => {
-      const { userKey, policy: override } = request.body;
+      const { userKey, policy: override, template } = request.body;
 
       // Validate the policy before taking the key's slot, so a queued
       // rejection can only come from the work itself, never from another
@@ -177,7 +183,18 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         throw error;
       }
 
-      const row = await locks.run(userKey, () => findOrCreate(userKey, policy));
+      // Same placement as the policy check: an unknown template is the
+      // caller's mistake and answers 400 before the slot, on the wake path
+      // too — never silently ignored.
+      if (template !== undefined && !findTemplate(db, template)) {
+        return reply.code(400).send({
+          message: `unknown template '${template}' — register it first`,
+        });
+      }
+
+      const row = await locks.run(userKey, () =>
+        findOrCreate(userKey, policy, template ?? null),
+      );
       return { status: 'ready' as const, sandbox: toSandbox(row, endpoint) };
     },
   );
diff --git a/packages/server/src/routes/templates.ts b/packages/server/src/routes/templates.ts
new file mode 100644
index 0000000..92c556b
--- /dev/null
+++ b/packages/server/src/routes/templates.ts
@@ -0,0 +1,81 @@
+import {
+  listTemplatesResponseSchema,
+  registerTemplateRequestSchema,
+  registerTemplateResponseSchema,
+  removeTemplateRequestSchema,
+  removeTemplateResponseSchema,
+} from '@dormice/shared';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import type { Db } from '../db/db';
+import {
+  listTemplates,
+  registerTemplate,
+  removeTemplate,
+  sandboxKeysUsingTemplate,
+} from '../db/templates';
+import { httpError } from '../http-error';
+
+export interface TemplateRoutesOptions {
+  db: Db;
+}
+
+/**
+ * Template registration: a name for a Docker image that already lives on
+ * this host. Pure ledger config — no executor involved: the image is not
+ * checked for existence (it may legitimately arrive after registration; a
+ * missing one fails a later create with Docker's own honest error), and
+ * removal only guards the ledger's referential integrity.
+ */
+export const templateRoutes: FastifyPluginAsyncZod<
+  TemplateRoutesOptions
+> = async (app, { db }) => {
+  // Upsert: re-registering a name re-points it at the new image — the
+  // template upgrade front door. No lock: better-sqlite3 is synchronous,
+  // there is no await between check and write.
+  app.post(
+    '/registerTemplate',
+    {
+      schema: {
+        body: registerTemplateRequestSchema,
+        response: { 200: registerTemplateResponseSchema },
+      },
+    },
+    async (request) => ({
+      template: registerTemplate(db, request.body),
+    }),
+  );
+
+  app.post(
+    '/listTemplates',
+    {
+      schema: {
+        response: { 200: listTemplatesResponseSchema },
+      },
+    },
+    async () => ({ templates: listTemplates(db) }),
+  );
+
+  app.post(
+    '/removeTemplate',
+    {
+      schema: {
+        body: removeTemplateRequestSchema,
+        response: { 200: removeTemplateResponseSchema },
+      },
+    },
+    async (request) => {
+      const { name } = request.body;
+      // Refused while referenced: a sandbox row pointing at a removed
+      // template would wake onto a dangling name. Named keys, so the
+      // operator knows exactly what to release.
+      const users = sandboxKeysUsingTemplate(db, name);
+      if (users.length > 0) {
+        throw httpError(
+          409,
+          `template '${name}' is used by ${users.length} sandbox(es): ${users.join(', ')} — release them first`,
+        );
+      }
+      return { removed: removeTemplate(db, name) };
+    },
+  );
+};
diff --git a/packages/shared/src/acquire.ts b/packages/shared/src/acquire.ts
index 889079f..6ee5c94 100644
--- a/packages/shared/src/acquire.ts
+++ b/packages/shared/src/acquire.ts
@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { lifecyclePolicyOverrideSchema } from './policy';
 import { sandboxSchema, userKeySchema } from './sandbox';
+import { templateNameSchema } from './templates';
 
 /**
  * acquire(userKey) — the platform's single entry point. Idempotent:
@@ -16,6 +17,13 @@ export const acquireRequestSchema = z.object({
    * never silently ignored.
    */
   policy: lifecyclePolicyOverrideSchema.optional(),
+  /**
+   * Template to create the sandbox from; omitted means the daemon's base
+   * image. Same rules as policy: applied only when this acquire creates the
+   * sandbox — an existing sandbox keeps its template — but an unknown
+   * template name is still answered with a 400, never silently ignored.
+   */
+  template: templateNameSchema.optional(),
 });
 
 export type AcquireRequest = z.infer<typeof acquireRequestSchema>;
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index b0638d2..b322f12 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -7,3 +7,4 @@ export * from './rebuild';
 export * from './release';
 export * from './sandbox';
 export * from './states';
+export * from './templates';
diff --git a/packages/shared/src/sandbox.ts b/packages/shared/src/sandbox.ts
index 815bf83..d17858f 100644
--- a/packages/shared/src/sandbox.ts
+++ b/packages/shared/src/sandbox.ts
@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { lifecyclePolicySchema } from './policy';
 import { SANDBOX_STATES } from './states';
+import { templateNameSchema } from './templates';
 
 /**
  * Caller-chosen key that acquire() is idempotent on: same key, same sandbox,
@@ -29,6 +30,12 @@ export const sandboxSchema = z.object({
    */
   endpoint: z.string(),
   policy: lifecyclePolicySchema,
+  /**
+   * Template the sandbox was created from; null means the daemon's base
+   * image. The name is recorded, not the image it pointed at: a rebuilt
+   * shell always boots the template's *current* image.
+   */
+  template: templateNameSchema.nullable(),
   createdAt: z.iso.datetime(),
   lastActiveAt: z.iso.datetime(),
 });
diff --git a/packages/shared/src/templates.ts b/packages/shared/src/templates.ts
new file mode 100644
index 0000000..9715f99
--- /dev/null
+++ b/packages/shared/src/templates.ts
@@ -0,0 +1,86 @@
+import { z } from 'zod';
+
+/**
+ * A template is a name for a Docker image that already exists on the daemon's
+ * host — nothing more. The host's Docker daemon is the image store; the
+ * ledger only records which name points where. The name doubles as the E2B
+ * `templateID` (the official SDK sends whatever string the caller passes, so
+ * aliases and ids are the same thing on that wire).
+ *
+ * 'base' is reserved: it always means the daemon's configured base image and
+ * can never be registered.
+ */
+export const templateNameSchema = z
+  .string()
+  .regex(
+    /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/,
+    'template name must be 1-64 chars of letters, digits, dots, underscores or dashes, starting alphanumeric',
+  )
+  .refine((name) => name !== 'base', {
+    message: "'base' is reserved — it always means the daemon's base image",
+  });
+
+export const templateSchema = z.object({
+  name: templateNameSchema,
+  /** Docker image reference on the daemon's host, e.g. my-python:3.11. */
+  image: z.string().min(1),
+  createdAt: z.iso.datetime(),
+});
+
+export type Template = z.infer<typeof templateSchema>;
+
+/**
+ * registerTemplate(name, image) — an upsert: registering an existing name
+ * re-points it at the new image. That is the template upgrade front door
+ * (build a new image, re-register, then rebuildSandbox the stock that should
+ * move) — the same declare-desired-state philosophy as acquire.
+ *
+ * The image is deliberately NOT checked for existence: registration is
+ * config, and the image may legitimately arrive later. A sandbox created
+ * from a template whose image is missing fails with Docker's own honest
+ * "No such image" error.
+ */
+export const registerTemplateRequestSchema = z.object({
+  name: templateNameSchema,
+  image: z.string().min(1),
+});
+
+export type RegisterTemplateRequest = z.infer<
+  typeof registerTemplateRequestSchema
+>;
+
+export const registerTemplateResponseSchema = z.object({
+  template: templateSchema,
+});
+
+export type RegisterTemplateResponse = z.infer<
+  typeof registerTemplateResponseSchema
+>;
+
+/** listTemplates() — no input, every registered template. */
+export const listTemplatesResponseSchema = z.object({
+  templates: z.array(templateSchema),
+});
+
+export type ListTemplatesResponse = z.infer<typeof listTemplatesResponseSchema>;
+
+/**
+ * removeTemplate(name) — refused with a 409 while any sandbox still uses the
+ * template (the sandboxes would wake onto a dangling name); idempotent on an
+ * unknown name, like releaseSandbox: "no template under this name" is the
+ * desired end state.
+ */
+export const removeTemplateRequestSchema = z.object({
+  name: templateNameSchema,
+});
+
+export type RemoveTemplateRequest = z.infer<typeof removeTemplateRequestSchema>;
+
+export const removeTemplateResponseSchema = z.object({
+  /** True when a template existed and was removed; false when the name already had nothing. */
+  removed: z.boolean(),
+});
+
+export type RemoveTemplateResponse = z.infer<
+  typeof removeTemplateResponseSchema
+>;

From 73f7011c816a981964fa501e7638c447a03cd06b Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 19:49:16 +0800
Subject: [PATCH 037/133] A template's missing image fails create with a named
 error, not a leaked 404
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The two template e2e tests registered images that only the fake could
play; on the real engine Docker answered 'No such image' — by design,
since registration never checks existence — but dockerode's 404
statusCode leaked through the error handler as this API's own
'sandbox not found' status. launchContainer now names the situation
(image X is not on this host - docker pull or build it, then retry) as
a plain 500, a docker-only e2e question pins it, and the e2e template
tests register the daemon's real base image so they boot in both
executor modes.
---
 e2e/src/e2b.test.ts                    |  6 ++++-
 e2e/src/native.test.ts                 | 31 +++++++++++++++++++++++++-
 packages/server/src/executor/docker.ts |  9 ++++++++
 3 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 097ac01..026fa65 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -652,11 +652,15 @@ describe('official e2b SDK against the daemon', () => {
   it('creates from a registered template name; info reports it as templateId and name', async () => {
     // Registration is the operator's native verb; the official SDK then
     // consumes the name as its templateID — aliases are the same wire.
+    // The image must exist in docker mode; the base image serves both.
     const dormice = new Dormice({
       endpoint: inject('dormiceEndpoint'),
       token: inject('dormiceToken'),
     });
-    await dormice.registerTemplate('e2e-tpl', 'img:e2e-tpl');
+    await dormice.registerTemplate(
+      'e2e-tpl',
+      process.env.DORMICE_BASE_IMAGE ?? 'img:e2e-tpl',
+    );
     const sbx = await Sandbox.create('e2e-tpl', connection());
     try {
       const info = await sbx.getInfo();
diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index 86d1248..f2470d9 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -297,7 +297,11 @@ describe('native API over a real daemon', () => {
   });
 
   it('templates: register, create from, removal guarded while in use', async () => {
-    await client().registerTemplate('native-tpl', 'img:native');
+    // In docker mode the image must actually exist — registration is only
+    // config; the fake plays any name. The daemon's own base image serves
+    // both: a real boot there, an arbitrary string here.
+    const image = process.env.DORMICE_BASE_IMAGE ?? 'img:native';
+    await client().registerTemplate('native-tpl', image);
     const created = await client().acquireSandbox('tpl-key', {
       template: 'native-tpl',
     });
@@ -318,6 +322,31 @@ describe('native API over a real daemon', () => {
     });
   });
 
+  // Registration never checks the image; only a real engine can show what
+  // happens when the promise is broken at create time.
+  it.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
+    'a template whose image is missing fails create with a named, honest error',
+    async () => {
+      await client().registerTemplate('hollow-tpl', 'img:does-not-exist');
+      await expect(
+        client().acquireSandbox('hollow-key', { template: 'hollow-tpl' }),
+      ).rejects.toMatchObject({
+        name: 'DormiceApiError',
+        status: 500,
+        message: expect.stringMatching(
+          /image img:does-not-exist is not on this host/,
+        ),
+      });
+      // Nothing was created: the key is still free, the template removable.
+      expect(await client().releaseSandbox('hollow-key')).toEqual({
+        released: false,
+      });
+      expect(await client().removeTemplate('hollow-tpl')).toEqual({
+        removed: true,
+      });
+    },
+  );
+
   it('reading a file wakes a frozen sandbox, and the file survived the cold', async () => {
     await client().acquireSandbox('files-wake-key', {
       policy: {
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 5b54a17..faa1469 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -1191,6 +1191,15 @@ export class DockerExecutor implements Executor {
       if (isDockerApiError(err) && err.statusCode === 409) {
         throw new Error(`container ${sandboxId} already exists`);
       }
+      // Registration never checks image existence (the image may arrive
+      // later), so this is where a missing one honestly surfaces. Named
+      // here — dockerode's own 404 would otherwise leak out as this API's
+      // "sandbox not found" status.
+      if (isDockerApiError(err) && err.statusCode === 404) {
+        throw new Error(
+          `image ${image ?? this.opts.baseImage} is not on this host — docker pull or build it, then retry`,
+        );
+      }
       throw err;
     }
     await container.start();

From 1e6d98aba58e16d65603f8f50f070b8a25926f78 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 20:37:40 +0800
Subject: [PATCH 038/133] The docs shell is ours: fumadocs out, @next/mdx and
 the shadcn preset in

---
 .gitignore                             |    1 -
 biome.json                             |    5 +-
 pnpm-lock.yaml                         | 1197 ++++++------------------
 website/app/(home)/layout.tsx          |    7 -
 website/app/api/search/route.ts        |    8 -
 website/app/docs/[[...slug]]/page.tsx  |   77 +-
 website/app/docs/layout.tsx            |   22 +-
 website/app/global.css                 |   31 +-
 website/app/layout.tsx                 |   17 +-
 website/app/{(home) => }/page.tsx      |   30 +-
 website/app/provider.tsx               |   11 -
 website/app/shadcn.css                 |  130 +++
 website/components.json                |   25 +
 website/components/docs-mobile-nav.tsx |   32 +
 website/components/docs-search.tsx     |   84 ++
 website/components/docs-sidebar.tsx    |   39 +
 website/components/docs-toc.tsx        |   72 ++
 website/components/search.tsx          |   44 -
 website/components/site-header.tsx     |   35 +
 website/components/theme-provider.tsx  |   17 +
 website/components/theme-toggle.tsx    |   27 +
 website/components/ui/button.tsx       |   56 ++
 website/components/ui/command.tsx      |  197 ++++
 website/components/ui/dialog.tsx       |  160 ++++
 website/components/ui/input-group.tsx  |  157 ++++
 website/components/ui/input.tsx        |   20 +
 website/components/ui/sheet.tsx        |  138 +++
 website/components/ui/textarea.tsx     |   18 +
 website/lib/docs.ts                    |   80 ++
 website/lib/layout.shared.tsx          |   10 -
 website/lib/source.ts                  |    8 -
 website/lib/utils.ts                   |    6 +
 website/mdx-components.tsx             |    7 +-
 website/mdx.d.ts                       |   12 +
 website/next.config.mjs                |   28 +-
 website/package.json                   |   26 +-
 website/source.config.ts               |    7 -
 website/tsconfig.json                  |    9 +-
 38 files changed, 1760 insertions(+), 1090 deletions(-)
 delete mode 100644 website/app/(home)/layout.tsx
 delete mode 100644 website/app/api/search/route.ts
 rename website/app/{(home) => }/page.tsx (74%)
 delete mode 100644 website/app/provider.tsx
 create mode 100644 website/app/shadcn.css
 create mode 100644 website/components.json
 create mode 100644 website/components/docs-mobile-nav.tsx
 create mode 100644 website/components/docs-search.tsx
 create mode 100644 website/components/docs-sidebar.tsx
 create mode 100644 website/components/docs-toc.tsx
 delete mode 100644 website/components/search.tsx
 create mode 100644 website/components/site-header.tsx
 create mode 100644 website/components/theme-provider.tsx
 create mode 100644 website/components/theme-toggle.tsx
 create mode 100644 website/components/ui/button.tsx
 create mode 100644 website/components/ui/command.tsx
 create mode 100644 website/components/ui/dialog.tsx
 create mode 100644 website/components/ui/input-group.tsx
 create mode 100644 website/components/ui/input.tsx
 create mode 100644 website/components/ui/sheet.tsx
 create mode 100644 website/components/ui/textarea.tsx
 create mode 100644 website/lib/docs.ts
 delete mode 100644 website/lib/layout.shared.tsx
 delete mode 100644 website/lib/source.ts
 create mode 100644 website/lib/utils.ts
 create mode 100644 website/mdx.d.ts
 delete mode 100644 website/source.config.ts

diff --git a/.gitignore b/.gitignore
index bd4a77e..389e222 100644
--- a/.gitignore
+++ b/.gitignore
@@ -27,7 +27,6 @@ dist/
 # website (Next.js) build artifacts and generated files
 website/.next/
 website/out/
-website/.source/
 website/next-env.d.ts
 
 # Runtime data (SQLite ledger, sandbox volumes)
diff --git a/biome.json b/biome.json
index f37c027..7a2ff3f 100644
--- a/biome.json
+++ b/biome.json
@@ -8,7 +8,10 @@
       "!packages/console/src/hooks/use-mobile.ts",
       "!packages/console/src/lib/utils.ts",
       "!packages/console/src/shadcn.css",
-      "!packages/console/src/routeTree.gen.ts"
+      "!packages/console/src/routeTree.gen.ts",
+      "!website/components/ui",
+      "!website/lib/utils.ts",
+      "!website/app/shadcn.css"
     ]
   },
   "vcs": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 274da15..8b8f2ba 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -222,28 +222,64 @@ importers:
 
   website:
     dependencies:
-      fumadocs-core:
-        specifier: ^16.11.1
-        version: 16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3)
-      fumadocs-mdx:
-        specifier: ^15.1.0
-        version: 15.1.0(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.2.17)(fumadocs-core@16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)(rolldown@1.1.4)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))
-      fumadocs-ui:
-        specifier: ^16.11.1
-        version: 16.11.1(@types/mdx@2.0.14)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(fumadocs-core@16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(tailwindcss@4.3.2)
+      '@base-ui/react':
+        specifier: ^1.6.0
+        version: 1.6.0(@date-fns/tz@1.5.0)(@types/react@19.2.17)(date-fns@4.4.0)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@fontsource-variable/inter':
+        specifier: ^5.2.8
+        version: 5.2.8
+      '@hugeicons/core-free-icons':
+        specifier: ^4.2.2
+        version: 4.2.2
+      '@hugeicons/react':
+        specifier: ^1.1.9
+        version: 1.1.9(react@19.2.7)
+      class-variance-authority:
+        specifier: ^0.7.1
+        version: 0.7.1
+      clsx:
+        specifier: ^2.1.1
+        version: 2.1.1
+      cmdk:
+        specifier: ^1.1.1
+        version: 1.1.1(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       next:
         specifier: ^16.2.10
-        version: 16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+        version: 16.2.10(@babel/core@7.29.7)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      next-themes:
+        specifier: ^0.4.6
+        version: 0.4.6(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       react:
         specifier: ^19.2.7
         version: 19.2.7
       react-dom:
         specifier: ^19.2.7
         version: 19.2.7(react@19.2.7)
+      tailwind-merge:
+        specifier: ^3.6.0
+        version: 3.6.0
+      tw-animate-css:
+        specifier: ^1.4.0
+        version: 1.4.0
     devDependencies:
+      '@mdx-js/loader':
+        specifier: ^3.1.1
+        version: 3.1.1
+      '@mdx-js/react':
+        specifier: ^3.1.1
+        version: 3.1.1(@types/react@19.2.17)(react@19.2.7)
+      '@next/mdx':
+        specifier: ^16.2.10
+        version: 16.2.10(@mdx-js/loader@3.1.1)(@mdx-js/react@3.1.1(@types/react@19.2.17)(react@19.2.7))
+      '@shikijs/rehype':
+        specifier: ^4.3.1
+        version: 4.3.1
       '@tailwindcss/postcss':
         specifier: ^4.3.2
         version: 4.3.2
+      '@tailwindcss/typography':
+        specifier: ^0.5.20
+        version: 0.5.20(tailwindcss@4.3.2)
       '@types/mdx':
         specifier: ^2.0.14
         version: 2.0.14
@@ -259,6 +295,21 @@ importers:
       postcss:
         specifier: ^8.5.16
         version: 8.5.16
+      rehype-slug:
+        specifier: ^6.0.0
+        version: 6.0.0
+      remark-frontmatter:
+        specifier: ^5.0.0
+        version: 5.0.0
+      remark-gfm:
+        specifier: ^4.0.1
+        version: 4.0.1
+      remark-mdx-frontmatter:
+        specifier: ^5.2.0
+        version: 5.2.0
+      shadcn:
+        specifier: ^4.13.0
+        version: 4.13.0(typescript@6.0.3)
       tailwindcss:
         specifier: ^4.3.2
         version: 4.3.2
@@ -1251,24 +1302,6 @@ packages:
   '@fontsource-variable/inter@5.2.8':
     resolution: {integrity: sha512-kOfP2D+ykbcX/P3IFnokOhVRNoTozo5/JxhAIVYLpea/UBmCQ/YWPBfWIDuBImXX/15KH+eKh4xpEUyS2sQQGQ==}
 
-  '@fuma-translate/react@1.0.2':
-    resolution: {integrity: sha512-uOiOtBx3nRXR8Nu1GzBf1tApgF1FErDBTHxRIAQeyQdyOoZbrNRN6H4kDCWObY4qyGeGbHydG0DHzgeUgFDMIw==}
-    peerDependencies:
-      '@types/react': '*'
-      react: ^19.2.0
-      react-dom: ^19.2.0
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-
-  '@fumadocs/tailwind@0.1.0':
-    resolution: {integrity: sha512-nF/DCAwOR21HZ4AkjIOv3Iqwyqywzb6pdyeMcoa+aZzirXj5ntvNZbe3jJ0v3ehhtrRfYYeXBezvjn8ZmV+fuQ==}
-    peerDependencies:
-      tailwindcss: ^4.0.0
-    peerDependenciesMeta:
-      tailwindcss:
-        optional: true
-
   '@grpc/grpc-js@1.14.4':
     resolution: {integrity: sha512-k9Dj3DV/itK9D06Y8f190Qgop7/Ui+D0njFV3LHMPwPT75DpXLQohE9Wmz0QElrJnzsjB7KPWiKJbOl7IPDArQ==}
     engines: {node: '>=12.10.0'}
@@ -1496,9 +1529,23 @@ packages:
   '@manypkg/get-packages@1.1.3':
     resolution: {integrity: sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==}
 
+  '@mdx-js/loader@3.1.1':
+    resolution: {integrity: sha512-0TTacJyZ9mDmY+VefuthVshaNIyCGZHJG2fMnGaDttCt8HmjUF7SizlHJpaCDoGnN635nK1wpzfpx/Xx5S4WnQ==}
+    peerDependencies:
+      webpack: '>=5'
+    peerDependenciesMeta:
+      webpack:
+        optional: true
+
   '@mdx-js/mdx@3.1.1':
     resolution: {integrity: sha512-f6ZO2ifpwAQIpzGWaBQT2TXxPv6z3RBzQKpVftEWN78Vl/YweF1uwussDx8ECAXVtr3Rs89fKyG9YlzUs9DyGQ==}
 
+  '@mdx-js/react@3.1.1':
+    resolution: {integrity: sha512-f++rKLQgUVYDAtECQ6fn/is15GkEH9+nZPM3MS0RcxVqoTfawHvDlSCH7JbMhAM6uJ32v3eXLvLmLvjGu7PTQw==}
+    peerDependencies:
+      '@types/react': '>=16'
+      react: '>=16'
+
   '@modelcontextprotocol/sdk@1.29.0':
     resolution: {integrity: sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==}
     engines: {node: '>=18'}
@@ -1518,6 +1565,17 @@ packages:
   '@next/env@16.2.10':
     resolution: {integrity: sha512-zLPxg9M0MEHmygpj5OuxjQ+vHMiy/K7cSp74G8ecYolmgUWw0RwN02tF56npup/+qaI8JB97hQgS/r2Hb6QwVA==}
 
+  '@next/mdx@16.2.10':
+    resolution: {integrity: sha512-r6T32AyQ0xy6p0vKd1lNbz6RUXuVXdGYSAI0dRrpbnqGnTWQXefADZGui4PlwjqROj0XQBMqVwot9ntPWao9PA==}
+    peerDependencies:
+      '@mdx-js/loader': '>=0.15.0'
+      '@mdx-js/react': '>=0.15.0'
+    peerDependenciesMeta:
+      '@mdx-js/loader':
+        optional: true
+      '@mdx-js/react':
+        optional: true
+
   '@next/swc-darwin-arm64@16.2.10':
     resolution: {integrity: sha512-v9IdJCa0H0mbo+8z5zwUpOk1Vj7RjkcI5uNYf5Ws1y6szf/p3Mzl9hLaST8SCt6L9h8NGnruZcd2+o0NTNwDhA==}
     engines: {node: '>= 10'}
@@ -1582,10 +1640,6 @@ packages:
     resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
     engines: {node: '>= 8'}
 
-  '@orama/orama@3.1.18':
-    resolution: {integrity: sha512-a61ljmRVVyG5MC/698C8/FfFDw5a8LOIvyOLW5fztgUXqUpc1jOfQzOitSCbge657OgXXThmY3Tk8fpiDb4UcA==}
-    engines: {node: '>= 20.0.0'}
-
   '@oxc-project/types@0.138.0':
     resolution: {integrity: sha512-1a7ZKmrRTCoN1XMZ4L0PyyqrMnrNlLyPuOkdSX2MZg7IiIGRUyurNhAm73ptDOraoBcIordsIGKNPKUzy3ZmfA==}
 
@@ -1619,64 +1673,9 @@ packages:
   '@protobufjs/utf8@1.1.2':
     resolution: {integrity: sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==}
 
-  '@radix-ui/number@1.1.2':
-    resolution: {integrity: sha512-ceTwaxc4I5IOi97DgCotl3pqiyRGvffcc0oOsE2dQYaJOFIDsDt4VWG6xEbg1QePv9QWausCEIppud/tJ1wNig==}
-
   '@radix-ui/primitive@1.1.5':
     resolution: {integrity: sha512-d86WIWFYNtGA0H/d8exstrTRTp7eWJYlYJbtNofxr/3ljupZYn6EFDG/Qgu/0Kc8v7yMUxySagqJsL1+PdYjWg==}
 
-  '@radix-ui/react-accordion@1.2.16':
-    resolution: {integrity: sha512-BpZJNmetujnGgUI6OX0jEhEmlA46WPqgub8Rv09Kyquwd0cc1ndMKpiPYCjmBU6KSSRPAMtgLpEoZSG/tdNIWQ==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
-  '@radix-ui/react-arrow@1.1.11':
-    resolution: {integrity: sha512-Kdil9BB1rIFC/khmf4hC35bn8701AJcizTU7G7cUbEbk5XqqbjDuHW60uUfKqO5WojjZcbAW51Q7P0hRmMLw8A==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
-  '@radix-ui/react-collapsible@1.1.16':
-    resolution: {integrity: sha512-opfXRe6nnzyGmCDPx+l1Aqo/RbqWtQal2FnsBqF9hhePp6j0LsRoBaRxcMOlTv+uYTJVtWYZKg9t9wTe+BA/ZA==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
-  '@radix-ui/react-collection@1.1.12':
-    resolution: {integrity: sha512-nb67INpE0IahJKN7EYPp9m9YGwYeKlnzxT3MwXVkgCskaSJia97kG4T0ywpjNUSSnoJk/uvk12V8vbrEHEj+/Q==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
   '@radix-ui/react-compose-refs@1.1.3':
     resolution: {integrity: sha512-rYOP8OMnuuPMQF1uhPVlGNcCDlkokKqGFE3JcxFViIkAXP7EvFWUliJAstrapypaBLJNHbZL6jGhbVDGTwmVhA==}
     peerDependencies:
@@ -1708,15 +1707,6 @@ packages:
       '@types/react-dom':
         optional: true
 
-  '@radix-ui/react-direction@1.1.2':
-    resolution: {integrity: sha512-C3vFhbyi4SW3PmbAi6Awpu4OzJtd0MxGurvSsYtr7p7nM8RNB3VAF3CUmnp2j50knpkrRcB7+ycVXzgLgF6yNA==}
-    peerDependencies:
-      '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-
   '@radix-ui/react-dismissable-layer@1.1.15':
     resolution: {integrity: sha512-b0XaRlzn2QKuo10XyNgi2DAJDf5XC9d1nD3FJcuvCjbR7+4Ad28zmZsLsqx+hvDEzMnRuZaZxZm9gYObV6RmRA==}
     peerDependencies:
@@ -1761,45 +1751,6 @@ packages:
       '@types/react':
         optional: true
 
-  '@radix-ui/react-navigation-menu@1.2.18':
-    resolution: {integrity: sha512-K9HiuxZ6xCwSaHcIuUpxyhy4w5gpwzWjh9dHTSbMN3Ix4qAyVObS9RlU3zMycb0PO3v9Tpk0BXMwWvXOUbVXew==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
-  '@radix-ui/react-popover@1.1.19':
-    resolution: {integrity: sha512-jkrTdQVxnIB8fpn0NyyxW9CTB5aCXZZelVz5z+Xmii6g5WxMqS3fInNslZ63puP39+Puu4jYohUK31y3dT87gQ==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
-  '@radix-ui/react-popper@1.3.3':
-    resolution: {integrity: sha512-mS7dGpyjv6b+gsDjLF7e0ia1W4Im1B1hSCy2yuXlHuvnZxHKagfDaobt/KAKt27EpZMit2pss8eJBVyVjEWM+g==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
   '@radix-ui/react-portal@1.1.13':
     resolution: {integrity: sha512-z3oXfmaHLJTF1wktbjgD6cn9jiEbq3WSondB10LIuIt2m2Ym4iJlrW04/euMwENDdWDdE7z+OuY7Qyp1YpRSwA==}
     peerDependencies:
@@ -1839,32 +1790,6 @@ packages:
       '@types/react-dom':
         optional: true
 
-  '@radix-ui/react-roving-focus@1.1.15':
-    resolution: {integrity: sha512-40svmmugfM3mUN7VUDGVE1tQGOhyi8enlGD0CNJEcMM36C1f71PKM21DFgNHUfem0XnA+d8H8oN3Z9ZpJjSslg==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
-  '@radix-ui/react-scroll-area@1.2.14':
-    resolution: {integrity: sha512-bBODCWZK7JTbQLHs0uIP4f73wIWatakK4OS33UzkR1x897wu0PuO658a3f+6P2GEGyDzGYMuHRatMVoAk9WZTw==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
   '@radix-ui/react-slot@1.3.0':
     resolution: {integrity: sha512-MojKku4U/miO8Av4Dkb+ctMAQx7JmY96LmtDQlAarCRtd7rN52QCSzBF+XAvr5S6coSVj9HEPBgHAHKEJVk/WA==}
     peerDependencies:
@@ -1874,19 +1799,6 @@ packages:
       '@types/react':
         optional: true
 
-  '@radix-ui/react-tabs@1.1.17':
-    resolution: {integrity: sha512-nRyXnrAVCwjeXcHbvEbLS6ndbTeKHG1RqCP4A8Gw5L4cemDzPXdD8rAmr6wet0v57R69wGvuIIsFjHSVkZiMzQ==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
   '@radix-ui/react-use-callback-ref@1.1.2':
     resolution: {integrity: sha512-xCso9j1/u8sEgP1RNHjFrXJLApL8LiqOkI1R4ywuN00rxWdYg4oQXuwKLS3i0j5NWLromUD27/4nlxj2UFVvIw==}
     peerDependencies:
@@ -1914,15 +1826,6 @@ packages:
       '@types/react':
         optional: true
 
-  '@radix-ui/react-use-is-hydrated@0.1.1':
-    resolution: {integrity: sha512-qwOiz4Tjo8CNnrOLAYUMXeZwDzXgXpvK4TKQPmWLECM9XoWvA6+0Z2/7Ag3A4ivjS4ovbLJPbskkxioFyBhr8A==}
-    peerDependencies:
-      '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-
   '@radix-ui/react-use-layout-effect@1.1.2':
     resolution: {integrity: sha512-jrBWOxZITuGcnjRCM2t2U5ZPkCLxD+Ym6DjfssS5haTj2iiak/DOb64JeN6OdLfLgptb6/e2kKR+ZuTrGoZTPA==}
     peerDependencies:
@@ -1932,49 +1835,6 @@ packages:
       '@types/react':
         optional: true
 
-  '@radix-ui/react-use-previous@1.1.2':
-    resolution: {integrity: sha512-IGBQPtRFdhN6MQ8dbegVmBq1LVZluya3F1jWY+puIcQC3MHctRwTDSBWCkL/3ZcnMJLTMJ++Z+ktmvg0F89iCw==}
-    peerDependencies:
-      '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-
-  '@radix-ui/react-use-rect@1.1.2':
-    resolution: {integrity: sha512-d8a+bBY/FxikNPlgJJoaBHZX+zKVbWHYJGTLnLvveQgFSTntkGdEKv3JDtHrMS0DNYpllz2nRsTLGLKYttbpmw==}
-    peerDependencies:
-      '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-
-  '@radix-ui/react-use-size@1.1.2':
-    resolution: {integrity: sha512-giWQp+4mxjBPt4KZ0MmyuykFNWfbDxKt4x+fPkRYmgRFJSbCZFzUglvMb/Kjn38tm10YP4ufiQZDx3zna4LU6w==}
-    peerDependencies:
-      '@types/react': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-
-  '@radix-ui/react-visually-hidden@1.2.7':
-    resolution: {integrity: sha512-1wNZBggTDK3GRuuQ6nP4k2yi7a6l7I5qbMPbZcRsrGsGVead/f/d5FhEzUvqFs0bcrDLx7n1zKQ3JvLR6whaaw==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
-  '@radix-ui/rect@1.1.2':
-    resolution: {integrity: sha512-xnXE7wG13PI+cxieVssYXlQJuYVRhH9NBoxt3KNwzghDIA69GMm7d4wXRouHIYjE+KvS6U/MsMO73NdS2MH9ZA==}
-
   '@reduxjs/toolkit@2.12.0':
     resolution: {integrity: sha512-KiT+RzZbp6mQET+Mg+h2c97+9j1sNflUxQkIHI7Yuzf6Peu+OYpmkn6nbHWmLLWj+1ZODUJFwGZ7gx3L9R9EOw==}
     peerDependencies:
@@ -2256,6 +2116,10 @@ packages:
     resolution: {integrity: sha512-CXQRQOYy1leqQ8ceTeJdmXv/bsUY++6QyLpXJ94LZAAYj5X2SKRdc5ipguv4NPyGVKItB2PPwUpRNe0Sjh5S1A==}
     engines: {node: '>=20'}
 
+  '@shikijs/rehype@4.3.1':
+    resolution: {integrity: sha512-oshrlfUF3VPUJfnp5K1lLwsS/SRBKrIxONpdWebSKZXdBE3UsZnxgqpvRUA8UsofS7vmjFOCAHIT71ECbmOxTw==}
+    engines: {node: '>=20'}
+
   '@shikijs/themes@4.3.1':
     resolution: {integrity: sha512-dgpoJ4WqNi2yTmizQHBJ5zcX6j2lE6icN/0yt4l1kkf16jrY/pwPLoTb1ETsWMz0OBLf9ZNvwmxft+cH+N9qSA==}
     engines: {node: '>=20'}
@@ -2372,6 +2236,11 @@ packages:
   '@tailwindcss/postcss@4.3.2':
     resolution: {integrity: sha512-rjVWYCa7Ngbi5AarT6k8TkxUG3Wl1QKzHdIZVsjZSzf36Jmo2IKZt/NHRAwly8oDkbBOH0YTu+CHuf9jPxMc+g==}
 
+  '@tailwindcss/typography@0.5.20':
+    resolution: {integrity: sha512-hwbzQuNUfcPvbegQFatVPl/MY/tcM9KLl963hQ5laJKPh81TEZ1+dNG9PirGvcaDBkp+BCshExAyKVPW91dozw==}
+    peerDependencies:
+      tailwindcss: '>=3.0.0 || >=4.0.0 || insiders'
+
   '@tailwindcss/vite@4.3.2':
     resolution: {integrity: sha512-eHpMeX4JXfVNJDEcsouTeCBubJBTcTLigeaw/NTUW6PB5ATKKXdyonnXgTBX2VuRbjz1hjfz6C5XAhr52ImQXA==}
     peerDependencies:
@@ -2857,10 +2726,6 @@ packages:
       react: ^18 || ^19 || ^19.0.0-rc
       react-dom: ^18 || ^19 || ^19.0.0-rc
 
-  cnfast@0.0.8:
-    resolution: {integrity: sha512-EjXKMfGfdwtV4AcNSQ6AwQaVzpC1B7IxeiwA3FlhTXz+YFlMKVi4c1JX9tgD2QOlahQXjB8KUXrBaYG+3v871Q==}
-    hasBin: true
-
   code-block-writer@13.0.3:
     resolution: {integrity: sha512-Oofo0pq3IKnsFtuHqSF7TqBfr71aeyZDVJ0HpmqB7FBM2qEigL0iPONSCZSO9pE9dZTAxANe5XHG9Uy0YMv8cg==}
 
@@ -2892,9 +2757,6 @@ packages:
   compare-versions@6.1.1:
     resolution: {integrity: sha512-4hm4VPpIecmlg59CHXnRDnqGplJFrbLG4aFEl5vl6cK1u76ws3LLvX7ikFnTDl5vo39sjWD6AaDPYodJp/NNHg==}
 
-  compute-scroll-into-view@3.1.1:
-    resolution: {integrity: sha512-VRhuHOLoKYOy4UbilLbUzbYg93XLjv2PncJC50EuTWPA3gaja1UjBsUP/D/9/juV3vQFr6XBEzn9KCAHdUvOHw==}
-
   conf@10.2.0:
     resolution: {integrity: sha512-8fLl9F04EJqjSqH+QjITQfJF8BrOVaYr1jewVgSRAEWePfxT0sku4w2hrGQ60BC/TNLGQ2pgxNlTbWQmMPFvXg==}
     engines: {node: '>=12'}
@@ -3260,10 +3122,6 @@ packages:
     resolution: {integrity: sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==}
     engines: {node: '>=8.6'}
 
-  entities@6.0.1:
-    resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
-    engines: {node: '>=0.12'}
-
   env-paths@2.2.1:
     resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==}
     engines: {node: '>=6'}
@@ -3438,6 +3296,9 @@ packages:
   fastq@1.20.1:
     resolution: {integrity: sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==}
 
+  fault@2.0.1:
+    resolution: {integrity: sha512-WtySTkS4OKev5JtpHXnib4Gxiurzh5NCGvWrFaZ34m6JehfTUhKZvn9njTfw48t6JumVQOmrKqpmGcdwxnhqBQ==}
+
   fdir@6.5.0:
     resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
     engines: {node: '>=12.0.0'}
@@ -3481,24 +3342,14 @@ packages:
     resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==}
     engines: {node: '>=14'}
 
+  format@0.2.2:
+    resolution: {integrity: sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww==}
+    engines: {node: '>=0.4.x'}
+
   forwarded@0.2.0:
     resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==}
     engines: {node: '>= 0.6'}
 
-  framer-motion@12.42.2:
-    resolution: {integrity: sha512-5XY9luDiu0oHfHBjpDthFMh0ES+122w6p/papSJBweMkO8Sn+PW2QaEgRblQBpWFnuvZS5qvarpt/hO2pjGmnw==}
-    peerDependencies:
-      '@emotion/is-prop-valid': '*'
-      react: ^18.0.0 || ^19.0.0
-      react-dom: ^18.0.0 || ^19.0.0
-    peerDependenciesMeta:
-      '@emotion/is-prop-valid':
-        optional: true
-      react:
-        optional: true
-      react-dom:
-        optional: true
-
   fresh@2.0.0:
     resolution: {integrity: sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==}
     engines: {node: '>= 0.8'}
@@ -3511,133 +3362,17 @@ packages:
     engines: {node: '>=14.14'}
 
   fs-extra@7.0.1:
-    resolution: {integrity: sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==}
-    engines: {node: '>=6 <7 || >=8'}
-
-  fs-extra@8.1.0:
-    resolution: {integrity: sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==}
-    engines: {node: '>=6 <7 || >=8'}
-
-  fsevents@2.3.3:
-    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
-    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
-    os: [darwin]
-
-  fumadocs-core@16.11.1:
-    resolution: {integrity: sha512-tKuh1AKoVTb+f7IoAOM2cfz5djd3YhePeqA95q6mf422gEvDTeJms23OJ+icYRWZ6ryNQ5W/ZsgKEe87M5HVYg==}
-    peerDependencies:
-      '@mdx-js/mdx': '*'
-      '@mixedbread/sdk': 0.x.x
-      '@orama/core': 1.x.x
-      '@oramacloud/client': 2.x.x
-      '@tanstack/react-router': 1.x.x
-      '@types/estree-jsx': '*'
-      '@types/hast': '*'
-      '@types/mdast': '*'
-      '@types/react': '*'
-      algoliasearch: 5.x.x
-      flexsearch: '*'
-      lucide-react: '*'
-      next: 16.x.x
-      react: ^19.2.0
-      react-dom: ^19.2.0
-      react-router: 7.x.x || 8.x.x
-      waku: '*'
-      zod: 4.x.x
-    peerDependenciesMeta:
-      '@mdx-js/mdx':
-        optional: true
-      '@mixedbread/sdk':
-        optional: true
-      '@orama/core':
-        optional: true
-      '@oramacloud/client':
-        optional: true
-      '@tanstack/react-router':
-        optional: true
-      '@types/estree-jsx':
-        optional: true
-      '@types/hast':
-        optional: true
-      '@types/mdast':
-        optional: true
-      '@types/react':
-        optional: true
-      algoliasearch:
-        optional: true
-      flexsearch:
-        optional: true
-      lucide-react:
-        optional: true
-      next:
-        optional: true
-      react:
-        optional: true
-      react-dom:
-        optional: true
-      react-router:
-        optional: true
-      waku:
-        optional: true
-      zod:
-        optional: true
-
-  fumadocs-mdx@15.1.0:
-    resolution: {integrity: sha512-2nDusSlYFuNVcyB51jgY3tA3r01ALTwoURrMDNoc7cbJKZ2sac/PW+CDq6SHTArkgRMmFiKYQGfspJdjgTtPTg==}
-    hasBin: true
-    peerDependencies:
-      '@fumadocs/satteri': 0.x.x
-      '@types/mdast': '*'
-      '@types/mdx': '*'
-      '@types/react': '*'
-      fumadocs-core: ^16.7.0
-      mdast-util-directive: '*'
-      next: ^15.3.0 || ^16.0.0
-      react: ^19.2.0
-      rolldown: '*'
-      satteri: ^0.9.4
-      vite: 7.x.x || 8.x.x
-    peerDependenciesMeta:
-      '@fumadocs/satteri':
-        optional: true
-      '@types/mdast':
-        optional: true
-      '@types/mdx':
-        optional: true
-      '@types/react':
-        optional: true
-      mdast-util-directive:
-        optional: true
-      next:
-        optional: true
-      react:
-        optional: true
-      rolldown:
-        optional: true
-      satteri:
-        optional: true
-      vite:
-        optional: true
-
-  fumadocs-ui@16.11.1:
-    resolution: {integrity: sha512-Dq819PFV4RGhAI9Wd4erSCiRlEDLVOZae+kgE5LeOKFH8mbKX49U8N17ldFOhdkC9EZpxMZdEKul77RDgFHQww==}
-    peerDependencies:
-      '@takumi-rs/image-response': '*'
-      '@types/mdx': '*'
-      '@types/react': '*'
-      fumadocs-core: 16.11.1
-      next: 16.x.x
-      react: ^19.2.0
-      react-dom: ^19.2.0
-    peerDependenciesMeta:
-      '@takumi-rs/image-response':
-        optional: true
-      '@types/mdx':
-        optional: true
-      '@types/react':
-        optional: true
-      next:
-        optional: true
+    resolution: {integrity: sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==}
+    engines: {node: '>=6 <7 || >=8'}
+
+  fs-extra@8.1.0:
+    resolution: {integrity: sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==}
+    engines: {node: '>=6 <7 || >=8'}
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
 
   function-bind@1.1.2:
     resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
@@ -3722,14 +3457,8 @@ packages:
     resolution: {integrity: sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==}
     engines: {node: '>= 0.4'}
 
-  hast-util-from-parse5@8.0.3:
-    resolution: {integrity: sha512-3kxEVkEKt0zvcZ3hCRYI8rqrgwtlIOFMWkbclACvjlDw8Li9S2hk/d51OI0nr/gIpdMHNepwgOKqZ/sy0Clpyg==}
-
-  hast-util-parse-selector@4.0.0:
-    resolution: {integrity: sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==}
-
-  hast-util-raw@9.1.0:
-    resolution: {integrity: sha512-Y8/SBAHkZGoNkpzqqfCldijcuUKh7/su31kEBp67cFY09Wy0mTRgtsLYsiIxMJxlu0f6AA5SUTbDR8K0rxnbUw==}
+  hast-util-heading-rank@3.0.0:
+    resolution: {integrity: sha512-EJKb8oMUXVHcWZTDepnr+WNbfnXKFNf9duMesmr4S8SXTJBJ9M4Yok08pu9vxdJwdlGRhVumk9mEhkEvKGifwA==}
 
   hast-util-to-estree@3.1.3:
     resolution: {integrity: sha512-48+B/rJWAp0jamNbAAf9M7Uf//UVqAoMmgXhBdxTDJLGKY+LRnZ99qcG+Qjl5HfMpYNzS5v4EAwVEF34LeAj7w==}
@@ -3740,15 +3469,12 @@ packages:
   hast-util-to-jsx-runtime@2.3.6:
     resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==}
 
-  hast-util-to-parse5@8.0.1:
-    resolution: {integrity: sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA==}
+  hast-util-to-string@3.0.1:
+    resolution: {integrity: sha512-XelQVTDWvqcl3axRfI0xSeoVKzyIFPwsAGSLIsKdJKQMXDYJS4WYrBNF/8J7RdhIcFI2BOHgAifggsvsxp/3+A==}
 
   hast-util-whitespace@3.0.0:
     resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
 
-  hastscript@9.0.1:
-    resolution: {integrity: sha512-g7df9rMFX/SPi34tyGCyUBREQoKkapwdY/T04Qn9TDWfHhAYt4/I0gMVirzK5wEzeUqIjEB+LXC/ypb7Aqno5w==}
-
   hono@4.12.28:
     resolution: {integrity: sha512-YwUvVpSF7m1yOblFPrU3Hbo8XhPheBoiyfGuII6z19LnOr6JpDnyyp7LFNrfV56wS8tpvtBFGRISHN02pDdLOA==}
     engines: {node: '>=16.9.0'}
@@ -3966,10 +3692,6 @@ packages:
     resolution: {integrity: sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==}
     hasBin: true
 
-  js-yaml@5.2.1:
-    resolution: {integrity: sha512-zfLtNfQqxVqq3uaTqSkh4x4hZw3KHobGUA0fJUj4wawW8bsQLTVqpHdXSIzidh7o+4lEW36tANuAGdaFx6Zgnw==}
-    hasBin: true
-
   jsesc@3.1.0:
     resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==}
     engines: {node: '>=6'}
@@ -4132,11 +3854,6 @@ packages:
   lru-cache@5.1.1:
     resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
 
-  lucide-react@1.23.0:
-    resolution: {integrity: sha512-38BpJcD0JhFosxHApP/BYsBetLpQFRoTRzEzstM/XCc3jsAG7wqaY1lgVwxiUe3xqYE+lNxo2PkCmYwXWrwwIw==}
-    peerDependencies:
-      react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
-
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
@@ -4157,6 +3874,9 @@ packages:
   mdast-util-from-markdown@2.0.3:
     resolution: {integrity: sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==}
 
+  mdast-util-frontmatter@2.0.1:
+    resolution: {integrity: sha512-LRqI9+wdgC25P0URIJY9vwocIzCcksduHQ9OF2joxQoyTNVduwLAFUzjoopuRJbJAReaKrNQKAZKL3uCMugWJA==}
+
   mdast-util-gfm-autolink-literal@2.0.1:
     resolution: {integrity: sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==}
 
@@ -4217,6 +3937,9 @@ packages:
   micromark-core-commonmark@2.0.3:
     resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==}
 
+  micromark-extension-frontmatter@2.0.0:
+    resolution: {integrity: sha512-C4AkuM3dA58cgZha7zVnuVxBhDsbttIMiytjgsM2XbHAB2faRVaHRle40558FBN+DJcrLNCoqG5mlrpdU4cRtg==}
+
   micromark-extension-gfm-autolink-literal@2.1.0:
     resolution: {integrity: sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==}
 
@@ -4373,26 +4096,6 @@ packages:
   mlly@1.8.2:
     resolution: {integrity: sha512-d+ObxMQFmbt10sretNDytwt85VrbkhhUA/JBGm1MPaWJ65Cl4wOgLaB1NYvJSZ0Ef03MMEU/0xpPMXUIQ29UfA==}
 
-  motion-dom@12.42.2:
-    resolution: {integrity: sha512-5gIMWLp/PycBtJRJWRgjxke5n8dlvkSn2DrYW+tr3XcqAZY1xZh6BJyooJXCM8wdfM7wfMjkBJNLge1CKPUIRA==}
-
-  motion-utils@12.39.0:
-    resolution: {integrity: sha512-8nadJAJjTtqRkmRF36FoJTrywK9nnFmnPwnSMyxaOCU7GDjN9RTMJIxx9De8ErM+vpPhMccr/6fo5WciyQLnMQ==}
-
-  motion@12.42.2:
-    resolution: {integrity: sha512-Atvv11yUKIid41cVrRBDVX5m8tF8kNpExRSlbpt6APClhDjtwQssgFHhQzejxw7/7YYbjHSPKBVbHo05BuJT5Q==}
-    peerDependencies:
-      '@emotion/is-prop-valid': '*'
-      react: ^18.0.0 || ^19.0.0
-      react-dom: ^18.0.0 || ^19.0.0
-    peerDependenciesMeta:
-      '@emotion/is-prop-valid':
-        optional: true
-      react:
-        optional: true
-      react-dom:
-        optional: true
-
   mri@1.2.0:
     resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==}
     engines: {node: '>=4'}
@@ -4571,9 +4274,6 @@ packages:
     resolution: {integrity: sha512-TXfryirbmq34y8QBwgqCVLi+8oA3oWx2eAnSn62ITyEhEYaWRlVZ2DvMM9eZbMs/RfxPu/PK/aBLyGj4IrqMHw==}
     engines: {node: '>=18'}
 
-  parse5@7.3.0:
-    resolution: {integrity: sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==}
-
   parseurl@1.3.3:
     resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==}
     engines: {node: '>= 0.8'}
@@ -4672,6 +4372,10 @@ packages:
       yaml:
         optional: true
 
+  postcss-selector-parser@6.0.10:
+    resolution: {integrity: sha512-IQ7TZdoaqbT+LCpShg46jnZVlhWD2w6iQYAcYXfHARZ7X1t/UGhhceQDs5X0cGqKvYlHNOuv7Oa1xmb0oQuA3w==}
+    engines: {node: '>=4'}
+
   postcss-selector-parser@7.1.4:
     resolution: {integrity: sha512-HeP7D2wyhkR+XaK6v4W8oRF62Dsz4flyuczALJp61GckGm42u1saSSJ/0auvcBqxs3jMRFEcPK34At/0JBKdOg==}
     engines: {node: '>=4'}
@@ -4893,15 +4597,21 @@ packages:
   regex@6.1.0:
     resolution: {integrity: sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==}
 
-  rehype-raw@7.0.0:
-    resolution: {integrity: sha512-/aE8hCfKlQeA8LmyeyQvQF3eBiLRGNlfBJEvWH7ivp9sBqs7TNqBL5X3v157rM4IFETqDnIOO+z5M/biZbo9Ww==}
-
   rehype-recma@1.0.0:
     resolution: {integrity: sha512-lqA4rGUf1JmacCNWWZx0Wv1dHqMwxzsDWYMTowuplHF3xH0N/MmrZ/G3BDZnzAkRmxDadujCjaKM2hqYdCBOGw==}
 
+  rehype-slug@6.0.0:
+    resolution: {integrity: sha512-lWyvf/jwu+oS5+hL5eClVd3hNdmwM1kAC0BUvEGD19pajQMIzcNUd/k9GsfQ+FfECvX+JE+e9/btsKH0EjJT6A==}
+
+  remark-frontmatter@5.0.0:
+    resolution: {integrity: sha512-XTFYvNASMe5iPN0719nPrdItC9aU0ssC4v14mH1BCi1u0n1gAocqcujWUrByftZTbLhRtiKRyjYTSIOcr69UVQ==}
+
   remark-gfm@4.0.1:
     resolution: {integrity: sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==}
 
+  remark-mdx-frontmatter@5.2.0:
+    resolution: {integrity: sha512-U/hjUYTkQqNjjMRYyilJgLXSPF65qbLPdoESOkXyrwz2tVyhAnm4GUKhfXqOOS9W34M3545xEMq+aMpHgVjEeQ==}
+
   remark-mdx@3.1.1:
     resolution: {integrity: sha512-Pjj2IYlUY3+D8x00UJsIOg5BEvfMyeI+2uLPn9VO9Wg4MEtN/VTIq2NEJQfde9PnX15KgtHyl9S0BcTnWrIuWg==}
 
@@ -4914,9 +4624,6 @@ packages:
   remark-stringify@11.0.0:
     resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==}
 
-  remark@15.0.1:
-    resolution: {integrity: sha512-Eht5w30ruCXgFmxVUSlNWQ9iiimq07URKeFS3hNc8cUWy1llX4KDWfyEDZRycMc+znsN9Ux5/tJ/BFdgdOwA3A==}
-
   require-directory@2.1.1:
     resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
     engines: {node: '>=0.10.0'}
@@ -4995,9 +4702,6 @@ packages:
   scheduler@0.27.0:
     resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
 
-  scroll-into-view-if-needed@3.1.0:
-    resolution: {integrity: sha512-49oNpRjWRvnU8NyGVmUaYG4jtTkNonFZI86MmGRDqBphEK2EXT9gdEUoQPZhuBM8yWHxCWbobltqYO5M4XrUvQ==}
-
   secure-json-parse@4.1.0:
     resolution: {integrity: sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA==}
 
@@ -5293,6 +4997,9 @@ packages:
     resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==}
     engines: {node: '>=0.6'}
 
+  toml@3.0.0:
+    resolution: {integrity: sha512-y/mWCZinnvxjTKYhJ+pYxwD0mRLVvOtdS2Awbgxln6iEnt4rk0yBxeSBHkGJcPucRiG0e55mwWp+g/05rsrd6w==}
+
   tree-kill@1.2.2:
     resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==}
     hasBin: true
@@ -5385,15 +5092,15 @@ packages:
   unist-util-is@6.0.1:
     resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==}
 
+  unist-util-mdx-define@1.1.2:
+    resolution: {integrity: sha512-9ncH7i7TN5Xn7/tzX5bE3rXgz1X/u877gYVAUB3mLeTKYJmQHmqKTDBi6BTGXV7AeolBCI9ErcVsOt2qryoD0g==}
+
   unist-util-position-from-estree@2.0.0:
     resolution: {integrity: sha512-KaFVRjoqLyF6YXCbVLNad/eS4+OfPQQn2yOd7zF/h5T/CSL2v8NpN6a5TPvtbXthAGw5nG+PuTtq+DdIZr+cRQ==}
 
   unist-util-position@5.0.0:
     resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==}
 
-  unist-util-remove-position@5.0.0:
-    resolution: {integrity: sha512-Hp5Kh3wLxv0PHj9m2yZhhLt58KzPtEYKQQ4yxfYFEO7EvHwzyDYnduhHnY1mDxoqr7VUwVuHXk9RXKIiYS1N8Q==}
-
   unist-util-stringify-position@4.0.0:
     resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==}
 
@@ -5490,9 +5197,6 @@ packages:
     resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
     engines: {node: '>= 0.8'}
 
-  vfile-location@5.0.3:
-    resolution: {integrity: sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==}
-
   vfile-message@4.0.3:
     resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
 
@@ -5592,9 +5296,6 @@ packages:
   vscode-languageserver-types@3.18.0:
     resolution: {integrity: sha512-8TsGPNMIMiiBdkORgRSvLjuiEIiAFtO+KssmYWxQ+uSVvlf7RjK8YKCOjPzZ+YA04jXEV7+7LvkSmHkhpNS99g==}
 
-  web-namespaces@2.0.1:
-    resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==}
-
   webpack-virtual-modules@0.6.2:
     resolution: {integrity: sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ==}
 
@@ -6517,17 +6218,6 @@ snapshots:
 
   '@fontsource-variable/inter@5.2.8': {}
 
-  '@fuma-translate/react@1.0.2(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-
-  '@fumadocs/tailwind@0.1.0(tailwindcss@4.3.2)':
-    optionalDependencies:
-      tailwindcss: 4.3.2
-
   '@grpc/grpc-js@1.14.4':
     dependencies:
       '@grpc/proto-loader': 0.8.1
@@ -6706,6 +6396,13 @@ snapshots:
       globby: 11.1.0
       read-yaml-file: 1.1.0
 
+  '@mdx-js/loader@3.1.1':
+    dependencies:
+      '@mdx-js/mdx': 3.1.1
+      source-map: 0.7.6
+    transitivePeerDependencies:
+      - supports-color
+
   '@mdx-js/mdx@3.1.1':
     dependencies:
       '@types/estree': 1.0.9
@@ -6736,6 +6433,12 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  '@mdx-js/react@3.1.1(@types/react@19.2.17)(react@19.2.7)':
+    dependencies:
+      '@types/mdx': 2.0.14
+      '@types/react': 19.2.17
+      react: 19.2.7
+
   '@modelcontextprotocol/sdk@1.29.0(zod@3.25.76)':
     dependencies:
       '@hono/node-server': 1.19.14(hono@4.12.28)
@@ -6767,6 +6470,13 @@ snapshots:
 
   '@next/env@16.2.10': {}
 
+  '@next/mdx@16.2.10(@mdx-js/loader@3.1.1)(@mdx-js/react@3.1.1(@types/react@19.2.17)(react@19.2.7))':
+    dependencies:
+      source-map: 0.7.6
+    optionalDependencies:
+      '@mdx-js/loader': 3.1.1
+      '@mdx-js/react': 3.1.1(@types/react@19.2.17)(react@19.2.7)
+
   '@next/swc-darwin-arm64@16.2.10':
     optional: true
 
@@ -6803,8 +6513,6 @@ snapshots:
       '@nodelib/fs.scandir': 2.1.5
       fastq: 1.20.1
 
-  '@orama/orama@3.1.18': {}
-
   '@oxc-project/types@0.138.0': {}
 
   '@pinojs/redact@0.4.0': {}
@@ -6829,64 +6537,8 @@ snapshots:
 
   '@protobufjs/utf8@1.1.2': {}
 
-  '@radix-ui/number@1.1.2': {}
-
   '@radix-ui/primitive@1.1.5': {}
 
-  '@radix-ui/react-accordion@1.2.16(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.5
-      '@radix-ui/react-collapsible': 1.1.16(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-collection': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-arrow@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-collapsible@1.1.16(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.5
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-collection@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
   '@radix-ui/react-compose-refs@1.1.3(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
       react: 19.2.7
@@ -6911,272 +6563,114 @@ snapshots:
       '@radix-ui/react-portal': 1.1.13(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
-      aria-hidden: 1.2.6
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-      react-remove-scroll: 2.7.2(@types/react@19.2.17)(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-direction@1.1.2(@types/react@19.2.17)(react@19.2.7)':
-    dependencies:
-      react: 19.2.7
-    optionalDependencies:
-      '@types/react': 19.2.17
-
-  '@radix-ui/react-dismissable-layer@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.5
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@19.2.17)(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-focus-guards@1.1.4(@types/react@19.2.17)(react@19.2.7)':
-    dependencies:
-      react: 19.2.7
-    optionalDependencies:
-      '@types/react': 19.2.17
-
-  '@radix-ui/react-focus-scope@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-id@1.1.2(@types/react@19.2.17)(react@19.2.7)':
-    dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      react: 19.2.7
-    optionalDependencies:
-      '@types/react': 19.2.17
-
-  '@radix-ui/react-navigation-menu@1.2.18(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.5
-      '@radix-ui/react-collection': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-dismissable-layer': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-previous': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-visually-hidden': 1.2.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-popover@1.1.19(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.5
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-dismissable-layer': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-focus-guards': 1.1.4(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-focus-scope': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-popper': 1.3.3(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-portal': 1.1.13(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
-      aria-hidden: 1.2.6
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-      react-remove-scroll: 2.7.2(@types/react@19.2.17)(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-popper@1.3.3(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@floating-ui/react-dom': 2.1.8(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-arrow': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-rect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-size': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/rect': 1.1.2
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-portal@1.1.13(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-presence@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-primitive@2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/react-roving-focus@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.5
-      '@radix-ui/react-collection': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
       '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-is-hydrated': 0.1.1(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      aria-hidden: 1.2.6
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
+      react-remove-scroll: 2.7.2(@types/react@19.2.17)(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
       '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-scroll-area@1.2.14(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+  '@radix-ui/react-dismissable-layer@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
-      '@radix-ui/number': 1.1.2
       '@radix-ui/primitive': 1.1.5
       '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
       '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-slot@1.3.0(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-focus-guards@1.1.4(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
-      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
     optionalDependencies:
       '@types/react': 19.2.17
 
-  '@radix-ui/react-tabs@1.1.17(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+  '@radix-ui/react-focus-scope@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
-      '@radix-ui/primitive': 1.1.5
-      '@radix-ui/react-context': 1.2.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-id': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
       '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-roving-focus': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-use-controllable-state': 1.2.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-callback-ref': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
       '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-use-callback-ref@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-id@1.1.2(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
     optionalDependencies:
       '@types/react': 19.2.17
 
-  '@radix-ui/react-use-controllable-state@1.2.3(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-portal@1.1.13(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
-      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-use-effect-event@0.0.3(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-presence@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-use-is-hydrated@0.1.1(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-primitive@2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
     dependencies:
+      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
+      react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
+      '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-use-layout-effect@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-slot@1.3.0(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
+      '@radix-ui/react-compose-refs': 1.1.3(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
     optionalDependencies:
       '@types/react': 19.2.17
 
-  '@radix-ui/react-use-previous@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-use-callback-ref@1.1.2(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
       react: 19.2.7
     optionalDependencies:
       '@types/react': 19.2.17
 
-  '@radix-ui/react-use-rect@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-use-controllable-state@1.2.3(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
-      '@radix-ui/rect': 1.1.2
+      '@radix-ui/react-use-effect-event': 0.0.3(@types/react@19.2.17)(react@19.2.7)
+      '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
     optionalDependencies:
       '@types/react': 19.2.17
 
-  '@radix-ui/react-use-size@1.1.2(@types/react@19.2.17)(react@19.2.7)':
+  '@radix-ui/react-use-effect-event@0.0.3(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
       '@radix-ui/react-use-layout-effect': 1.1.2(@types/react@19.2.17)(react@19.2.7)
       react: 19.2.7
     optionalDependencies:
       '@types/react': 19.2.17
 
-  '@radix-ui/react-visually-hidden@1.2.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
+  '@radix-ui/react-use-layout-effect@1.1.2(@types/react@19.2.17)(react@19.2.7)':
     dependencies:
-      '@radix-ui/react-primitive': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
     optionalDependencies:
       '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
-  '@radix-ui/rect@1.1.2': {}
 
   '@reduxjs/toolkit@2.12.0(react-redux@9.3.0(@types/react@19.2.17)(react@19.2.7)(redux@5.0.1))(react@19.2.7)':
     dependencies:
@@ -7352,6 +6846,15 @@ snapshots:
       '@shikijs/vscode-textmate': 10.0.2
       '@types/hast': 3.0.5
 
+  '@shikijs/rehype@4.3.1':
+    dependencies:
+      '@shikijs/types': 4.3.1
+      '@types/hast': 3.0.5
+      hast-util-to-string: 3.0.1
+      shiki: 4.3.1
+      unified: 11.0.5
+      unist-util-visit: 5.1.0
+
   '@shikijs/themes@4.3.1':
     dependencies:
       '@shikijs/types': 4.3.1
@@ -7442,6 +6945,11 @@ snapshots:
       postcss: 8.5.16
       tailwindcss: 4.3.2
 
+  '@tailwindcss/typography@0.5.20(tailwindcss@4.3.2)':
+    dependencies:
+      postcss-selector-parser: 6.0.10
+      tailwindcss: 4.3.2
+
   '@tailwindcss/vite@4.3.2(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0))':
     dependencies:
       '@tailwindcss/node': 4.3.2
@@ -7938,8 +7446,6 @@ snapshots:
       - '@types/react'
       - '@types/react-dom'
 
-  cnfast@0.0.8: {}
-
   code-block-writer@13.0.3: {}
 
   collapse-white-space@2.1.0: {}
@@ -7960,8 +7466,6 @@ snapshots:
 
   compare-versions@6.1.1: {}
 
-  compute-scroll-into-view@3.1.1: {}
-
   conf@10.2.0:
     dependencies:
       ajv: 8.20.0
@@ -8219,8 +7723,6 @@ snapshots:
       ansi-colors: 4.1.3
       strip-ansi: 6.0.1
 
-  entities@6.0.1: {}
-
   env-paths@2.2.1: {}
 
   error-ex@1.3.4:
@@ -8552,6 +8054,10 @@ snapshots:
     dependencies:
       reusify: 1.1.0
 
+  fault@2.0.1:
+    dependencies:
+      format: 0.2.2
+
   fdir@6.5.0(picomatch@4.0.5):
     optionalDependencies:
       picomatch: 4.0.5
@@ -8603,16 +8109,9 @@ snapshots:
       cross-spawn: 7.0.6
       signal-exit: 4.1.0
 
-  forwarded@0.2.0: {}
+  format@0.2.2: {}
 
-  framer-motion@12.42.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
-    dependencies:
-      motion-dom: 12.42.2
-      motion-utils: 12.39.0
-      tslib: 2.8.1
-    optionalDependencies:
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
+  forwarded@0.2.0: {}
 
   fresh@2.0.0: {}
 
@@ -8639,107 +8138,6 @@ snapshots:
   fsevents@2.3.3:
     optional: true
 
-  fumadocs-core@16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3):
-    dependencies:
-      '@orama/orama': 3.1.18
-      estree-util-value-to-estree: 3.5.0
-      github-slugger: 2.0.0
-      hast-util-to-estree: 3.1.3
-      hast-util-to-jsx-runtime: 2.3.6
-      js-yaml: 5.2.1
-      mdast-util-mdx: 3.0.0
-      mdast-util-to-markdown: 2.1.2
-      remark: 15.0.1
-      remark-gfm: 4.0.1
-      remark-rehype: 11.1.2
-      scroll-into-view-if-needed: 3.1.0
-      shiki: 4.3.1
-      tinyglobby: 0.2.17
-      unified: 11.0.5
-      unist-util-visit: 5.1.0
-      vfile: 6.0.3
-    optionalDependencies:
-      '@mdx-js/mdx': 3.1.1
-      '@tanstack/react-router': 1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@types/estree-jsx': 1.0.5
-      '@types/hast': 3.0.5
-      '@types/mdast': 4.0.4
-      '@types/react': 19.2.17
-      lucide-react: 1.23.0(react@19.2.7)
-      next: 16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-      zod: 4.4.3
-    transitivePeerDependencies:
-      - supports-color
-
-  fumadocs-mdx@15.1.0(@types/mdast@4.0.4)(@types/mdx@2.0.14)(@types/react@19.2.17)(fumadocs-core@16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react@19.2.7)(rolldown@1.1.4)(vite@8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)):
-    dependencies:
-      '@mdx-js/mdx': 3.1.1
-      '@standard-schema/spec': 1.1.0
-      chokidar: 5.0.0
-      esbuild: 0.28.1
-      estree-util-value-to-estree: 3.5.0
-      fumadocs-core: 16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3)
-      github-slugger: 2.0.0
-      js-yaml: 5.2.1
-      mdast-util-mdx: 3.0.0
-      picocolors: 1.1.1
-      picomatch: 4.0.5
-      tinyexec: 1.2.4
-      tinyglobby: 0.2.17
-      unified: 11.0.5
-      unist-util-remove-position: 5.0.0
-      unist-util-visit: 5.1.0
-      vfile: 6.0.3
-      zod: 4.4.3
-    optionalDependencies:
-      '@types/mdast': 4.0.4
-      '@types/mdx': 2.0.14
-      '@types/react': 19.2.17
-      next: 16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      react: 19.2.7
-      rolldown: 1.1.4
-      vite: 8.1.3(@types/node@26.1.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.0)(yaml@2.9.0)
-    transitivePeerDependencies:
-      - supports-color
-
-  fumadocs-ui@16.11.1(@types/mdx@2.0.14)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(fumadocs-core@16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(tailwindcss@4.3.2):
-    dependencies:
-      '@fuma-translate/react': 1.0.2(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@fumadocs/tailwind': 0.1.0(tailwindcss@4.3.2)
-      '@radix-ui/react-accordion': 1.2.16(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-collapsible': 1.1.16(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-dialog': 1.1.19(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-direction': 1.1.2(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-navigation-menu': 1.2.18(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-popover': 1.1.19(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-presence': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-scroll-area': 1.2.14(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      '@radix-ui/react-slot': 1.3.0(@types/react@19.2.17)(react@19.2.7)
-      '@radix-ui/react-tabs': 1.1.17(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      class-variance-authority: 0.7.1
-      cnfast: 0.0.8
-      fumadocs-core: 16.11.1(@mdx-js/mdx@3.1.1)(@tanstack/react-router@1.170.17(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(@types/estree-jsx@1.0.5)(@types/hast@3.0.5)(@types/mdast@4.0.4)(@types/react@19.2.17)(lucide-react@1.23.0(react@19.2.7))(next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7))(react-dom@19.2.7(react@19.2.7))(react@19.2.7)(zod@4.4.3)
-      lucide-react: 1.23.0(react@19.2.7)
-      motion: 12.42.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      next-themes: 0.4.6(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-      react-remove-scroll: 2.7.2(@types/react@19.2.17)(react@19.2.7)
-      rehype-raw: 7.0.0
-      scroll-into-view-if-needed: 3.1.0
-      shiki: 4.3.1
-      unist-util-visit: 5.1.0
-    optionalDependencies:
-      '@types/mdx': 2.0.14
-      '@types/react': 19.2.17
-      next: 16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-    transitivePeerDependencies:
-      - '@emotion/is-prop-valid'
-      - '@types/react-dom'
-      - tailwindcss
-
   function-bind@1.1.2: {}
 
   fuzzysort@3.1.0: {}
@@ -8825,36 +8223,9 @@ snapshots:
     dependencies:
       function-bind: 1.1.2
 
-  hast-util-from-parse5@8.0.3:
-    dependencies:
-      '@types/hast': 3.0.5
-      '@types/unist': 3.0.3
-      devlop: 1.1.0
-      hastscript: 9.0.1
-      property-information: 7.2.0
-      vfile: 6.0.3
-      vfile-location: 5.0.3
-      web-namespaces: 2.0.1
-
-  hast-util-parse-selector@4.0.0:
-    dependencies:
-      '@types/hast': 3.0.5
-
-  hast-util-raw@9.1.0:
+  hast-util-heading-rank@3.0.0:
     dependencies:
       '@types/hast': 3.0.5
-      '@types/unist': 3.0.3
-      '@ungap/structured-clone': 1.3.2
-      hast-util-from-parse5: 8.0.3
-      hast-util-to-parse5: 8.0.1
-      html-void-elements: 3.0.0
-      mdast-util-to-hast: 13.2.1
-      parse5: 7.3.0
-      unist-util-position: 5.0.0
-      unist-util-visit: 5.1.0
-      vfile: 6.0.3
-      web-namespaces: 2.0.1
-      zwitch: 2.0.4
 
   hast-util-to-estree@3.1.3:
     dependencies:
@@ -8911,28 +8282,14 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  hast-util-to-parse5@8.0.1:
+  hast-util-to-string@3.0.1:
     dependencies:
       '@types/hast': 3.0.5
-      comma-separated-tokens: 2.0.3
-      devlop: 1.1.0
-      property-information: 7.2.0
-      space-separated-tokens: 2.0.2
-      web-namespaces: 2.0.1
-      zwitch: 2.0.4
 
   hast-util-whitespace@3.0.0:
     dependencies:
       '@types/hast': 3.0.5
 
-  hastscript@9.0.1:
-    dependencies:
-      '@types/hast': 3.0.5
-      comma-separated-tokens: 2.0.3
-      hast-util-parse-selector: 4.0.0
-      property-information: 7.2.0
-      space-separated-tokens: 2.0.2
-
   hono@4.12.28: {}
 
   html-void-elements@3.0.0: {}
@@ -9081,10 +8438,6 @@ snapshots:
     dependencies:
       argparse: 2.0.1
 
-  js-yaml@5.2.1:
-    dependencies:
-      argparse: 2.0.1
-
   jsesc@3.1.0: {}
 
   json-parse-even-better-errors@2.3.1: {}
@@ -9212,10 +8565,6 @@ snapshots:
     dependencies:
       yallist: 3.1.1
 
-  lucide-react@1.23.0(react@19.2.7):
-    dependencies:
-      react: 19.2.7
-
   magic-string@0.30.21:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
@@ -9250,6 +8599,17 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  mdast-util-frontmatter@2.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      escape-string-regexp: 5.0.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      micromark-extension-frontmatter: 2.0.0
+    transitivePeerDependencies:
+      - supports-color
+
   mdast-util-gfm-autolink-literal@2.0.1:
     dependencies:
       '@types/mdast': 4.0.4
@@ -9416,6 +8776,13 @@ snapshots:
       micromark-util-symbol: 2.0.1
       micromark-util-types: 2.0.2
 
+  micromark-extension-frontmatter@2.0.0:
+    dependencies:
+      fault: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
   micromark-extension-gfm-autolink-literal@2.1.0:
     dependencies:
       micromark-util-character: 2.1.1
@@ -9703,20 +9070,6 @@ snapshots:
       pkg-types: 1.3.1
       ufo: 1.6.4
 
-  motion-dom@12.42.2:
-    dependencies:
-      motion-utils: 12.39.0
-
-  motion-utils@12.39.0: {}
-
-  motion@12.42.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
-    dependencies:
-      framer-motion: 12.42.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
-      tslib: 2.8.1
-    optionalDependencies:
-      react: 19.2.7
-      react-dom: 19.2.7(react@19.2.7)
-
   mri@1.2.0: {}
 
   ms@2.1.3: {}
@@ -9741,7 +9094,7 @@ snapshots:
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
 
-  next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
+  next@16.2.10(@babel/core@7.29.7)(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
     dependencies:
       '@next/env': 16.2.10
       '@swc/helpers': 0.5.15
@@ -9750,7 +9103,7 @@ snapshots:
       postcss: 8.4.31
       react: 19.2.7
       react-dom: 19.2.7(react@19.2.7)
-      styled-jsx: 5.1.6(react@19.2.7)
+      styled-jsx: 5.1.6(@babel/core@7.29.7)(react@19.2.7)
     optionalDependencies:
       '@next/swc-darwin-arm64': 16.2.10
       '@next/swc-darwin-x64': 16.2.10
@@ -9900,10 +9253,6 @@ snapshots:
 
   parse-ms@4.0.0: {}
 
-  parse5@7.3.0:
-    dependencies:
-      entities: 6.0.1
-
   parseurl@1.3.3: {}
 
   path-browserify@1.0.1: {}
@@ -9980,6 +9329,11 @@ snapshots:
       tsx: 4.23.0
       yaml: 2.9.0
 
+  postcss-selector-parser@6.0.10:
+    dependencies:
+      cssesc: 3.0.0
+      util-deprecate: 1.0.2
+
   postcss-selector-parser@7.1.4:
     dependencies:
       cssesc: 3.0.0
@@ -10236,12 +9590,6 @@ snapshots:
     dependencies:
       regex-utilities: 2.3.0
 
-  rehype-raw@7.0.0:
-    dependencies:
-      '@types/hast': 3.0.5
-      hast-util-raw: 9.1.0
-      vfile: 6.0.3
-
   rehype-recma@1.0.0:
     dependencies:
       '@types/estree': 1.0.9
@@ -10250,6 +9598,23 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  rehype-slug@6.0.0:
+    dependencies:
+      '@types/hast': 3.0.5
+      github-slugger: 2.0.0
+      hast-util-heading-rank: 3.0.0
+      hast-util-to-string: 3.0.1
+      unist-util-visit: 5.1.0
+
+  remark-frontmatter@5.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-frontmatter: 2.0.1
+      micromark-extension-frontmatter: 2.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
   remark-gfm@4.0.1:
     dependencies:
       '@types/mdast': 4.0.4
@@ -10261,6 +9626,15 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  remark-mdx-frontmatter@5.2.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      estree-util-value-to-estree: 3.5.0
+      toml: 3.0.0
+      unified: 11.0.5
+      unist-util-mdx-define: 1.1.2
+      yaml: 2.9.0
+
   remark-mdx@3.1.1:
     dependencies:
       mdast-util-mdx: 3.0.0
@@ -10291,15 +9665,6 @@ snapshots:
       mdast-util-to-markdown: 2.1.2
       unified: 11.0.5
 
-  remark@15.0.1:
-    dependencies:
-      '@types/mdast': 4.0.4
-      remark-parse: 11.0.0
-      remark-stringify: 11.0.0
-      unified: 11.0.5
-    transitivePeerDependencies:
-      - supports-color
-
   require-directory@2.1.1: {}
 
   require-from-string@2.0.2: {}
@@ -10405,10 +9770,6 @@ snapshots:
 
   scheduler@0.27.0: {}
 
-  scroll-into-view-if-needed@3.1.0:
-    dependencies:
-      compute-scroll-into-view: 3.1.1
-
   secure-json-parse@4.1.0: {}
 
   semver@6.3.1: {}
@@ -10685,10 +10046,12 @@ snapshots:
     dependencies:
       inline-style-parser: 0.2.7
 
-  styled-jsx@5.1.6(react@19.2.7):
+  styled-jsx@5.1.6(@babel/core@7.29.7)(react@19.2.7):
     dependencies:
       client-only: 0.0.1
       react: 19.2.7
+    optionalDependencies:
+      '@babel/core': 7.29.7
 
   sucrase@3.35.1:
     dependencies:
@@ -10768,6 +10131,8 @@ snapshots:
 
   toidentifier@1.0.1: {}
 
+  toml@3.0.0: {}
+
   tree-kill@1.2.2: {}
 
   trim-lines@3.0.1: {}
@@ -10865,18 +10230,23 @@ snapshots:
     dependencies:
       '@types/unist': 3.0.3
 
-  unist-util-position-from-estree@2.0.0:
+  unist-util-mdx-define@1.1.2:
     dependencies:
-      '@types/unist': 3.0.3
+      '@types/estree': 1.0.9
+      '@types/hast': 3.0.5
+      '@types/mdast': 4.0.4
+      estree-util-is-identifier-name: 3.0.0
+      estree-util-scope: 1.0.0
+      estree-walker: 3.0.3
+      vfile: 6.0.3
 
-  unist-util-position@5.0.0:
+  unist-util-position-from-estree@2.0.0:
     dependencies:
       '@types/unist': 3.0.3
 
-  unist-util-remove-position@5.0.0:
+  unist-util-position@5.0.0:
     dependencies:
       '@types/unist': 3.0.3
-      unist-util-visit: 5.1.0
 
   unist-util-stringify-position@4.0.0:
     dependencies:
@@ -10941,11 +10311,6 @@ snapshots:
 
   vary@1.1.2: {}
 
-  vfile-location@5.0.3:
-    dependencies:
-      '@types/unist': 3.0.3
-      vfile: 6.0.3
-
   vfile-message@4.0.3:
     dependencies:
       '@types/unist': 3.0.3
@@ -11034,8 +10399,6 @@ snapshots:
 
   vscode-languageserver-types@3.18.0: {}
 
-  web-namespaces@2.0.1: {}
-
   webpack-virtual-modules@0.6.2: {}
 
   which@2.0.2:
diff --git a/website/app/(home)/layout.tsx b/website/app/(home)/layout.tsx
deleted file mode 100644
index 89a06f2..0000000
--- a/website/app/(home)/layout.tsx
+++ /dev/null
@@ -1,7 +0,0 @@
-import { HomeLayout } from 'fumadocs-ui/layouts/home';
-import type { ReactNode } from 'react';
-import { baseOptions } from '@/lib/layout.shared';
-
-export default function Layout({ children }: { children: ReactNode }) {
-  return <HomeLayout {...baseOptions()}>{children}</HomeLayout>;
-}
diff --git a/website/app/api/search/route.ts b/website/app/api/search/route.ts
deleted file mode 100644
index aeb1e44..0000000
--- a/website/app/api/search/route.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import { createFromSource } from 'fumadocs-core/search/server';
-import { source } from '@/lib/source';
-
-// With output: 'export' this route is evaluated once at build time and the
-// whole search index lands in out/ as a static file; the search dialog
-// downloads it and queries client-side (components/search.tsx).
-export const revalidate = false;
-export const { staticGET: GET } = createFromSource(source);
diff --git a/website/app/docs/[[...slug]]/page.tsx b/website/app/docs/[[...slug]]/page.tsx
index 25d1856..2604017 100644
--- a/website/app/docs/[[...slug]]/page.tsx
+++ b/website/app/docs/[[...slug]]/page.tsx
@@ -1,13 +1,12 @@
-import {
-  DocsBody,
-  DocsDescription,
-  DocsPage,
-  DocsTitle,
-} from 'fumadocs-ui/layouts/docs/page';
 import type { Metadata } from 'next';
+import Link from 'next/link';
 import { notFound } from 'next/navigation';
-import { source } from '@/lib/source';
-import { getMDXComponents } from '@/mdx-components';
+import { DocsToc } from '@/components/docs-toc';
+import { docs, getDoc } from '@/lib/docs';
+
+// Static export: every page below /docs is enumerated here, nothing is
+// rendered on demand.
+export const dynamicParams = false;
 
 interface PageProps {
   params: Promise<{ slug?: string[] }>;
@@ -15,30 +14,60 @@ interface PageProps {
 
 export default async function Page(props: PageProps) {
   const params = await props.params;
-  const page = source.getPage(params.slug);
-  if (!page) notFound();
-
-  const MDX = page.data.body;
+  const doc = getDoc(params.slug);
+  if (!doc) notFound();
+  const { entry, Content, prev, next } = doc;
 
   return (
-    <DocsPage toc={page.data.toc} full={page.data.full}>
-      <DocsTitle>{page.data.title}</DocsTitle>
-      <DocsDescription>{page.data.description}</DocsDescription>
-      <DocsBody>
-        <MDX components={getMDXComponents()} />
-      </DocsBody>
-    </DocsPage>
+    <div className="flex items-start gap-10 py-8 lg:py-10">
+      <div className="min-w-0 flex-1">
+        <article
+          data-docs-article
+          className="prose prose-neutral max-w-none dark:prose-invert"
+        >
+          <h1>{entry.title}</h1>
+          <p className="lead">{entry.description}</p>
+          <Content />
+        </article>
+        <nav className="mt-10 flex justify-between gap-4 border-t pt-6 text-sm">
+          {prev ? (
+            <Link
+              href={prev.href}
+              className="text-muted-foreground transition-colors hover:text-foreground"
+            >
+              ← {prev.title}
+            </Link>
+          ) : (
+            <span />
+          )}
+          {next ? (
+            <Link
+              href={next.href}
+              className="text-right text-muted-foreground transition-colors hover:text-foreground"
+            >
+              {next.title} →
+            </Link>
+          ) : (
+            <span />
+          )}
+        </nav>
+      </div>
+      <aside className="sticky top-20 hidden w-56 shrink-0 xl:block">
+        <DocsToc />
+      </aside>
+    </div>
   );
 }
 
 export function generateStaticParams() {
-  return source.generateParams();
+  return docs.map((entry) => ({
+    slug: entry.slug === '' ? [] : entry.slug.split('/'),
+  }));
 }
 
 export async function generateMetadata(props: PageProps): Promise<Metadata> {
   const params = await props.params;
-  const page = source.getPage(params.slug);
-  if (!page) notFound();
-
-  return { title: page.data.title, description: page.data.description };
+  const doc = getDoc(params.slug);
+  if (!doc) notFound();
+  return { title: doc.entry.title, description: doc.entry.description };
 }
diff --git a/website/app/docs/layout.tsx b/website/app/docs/layout.tsx
index d4ebfcd..475d9aa 100644
--- a/website/app/docs/layout.tsx
+++ b/website/app/docs/layout.tsx
@@ -1,12 +1,22 @@
-import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 import type { ReactNode } from 'react';
-import { baseOptions } from '@/lib/layout.shared';
-import { source } from '@/lib/source';
+import { DocsMobileNav } from '@/components/docs-mobile-nav';
+import { DocsSidebar } from '@/components/docs-sidebar';
+import { docs } from '@/lib/docs';
 
 export default function Layout({ children }: { children: ReactNode }) {
+  const items = docs.map(({ href, title }) => ({ href, title }));
+
   return (
-    <DocsLayout {...baseOptions()} tree={source.getPageTree()}>
-      {children}
-    </DocsLayout>
+    <div className="mx-auto flex w-full max-w-6xl flex-1 items-start px-4">
+      <aside className="sticky top-14 hidden max-h-[calc(100vh-3.5rem)] w-52 shrink-0 overflow-y-auto border-r py-8 pr-4 md:block">
+        <DocsSidebar items={items} />
+      </aside>
+      <div className="min-w-0 flex-1 md:pl-8">
+        <div className="border-b py-3 md:hidden">
+          <DocsMobileNav items={items} />
+        </div>
+        {children}
+      </div>
+    </div>
   );
 }
diff --git a/website/app/global.css b/website/app/global.css
index 08ebee2..e91ad91 100644
--- a/website/app/global.css
+++ b/website/app/global.css
@@ -1,7 +1,26 @@
-@import "tailwindcss";
-@import "fumadocs-ui/css/neutral.css";
-@import "fumadocs-ui/css/preset.css";
+/* Style entry: imports plus project-level styling. app/shadcn.css is owned
+   by the shadcn CLI (rewritten wholesale by `shadcn apply`) — custom styles
+   live here, never there. */
+@import "./shadcn.css";
+@plugin "@tailwindcss/typography";
 
-/* Tell Tailwind where fumadocs-ui's class names live (path is relative to
- * this file; the package is symlinked by pnpm, Tailwind follows it). */
-@source "../node_modules/fumadocs-ui/dist/**/*.js";
+/* Shiki emits both themes as CSS variables (defaultColor: false in
+   next.config.mjs) — these rules pick the palette per color scheme. */
+.shiki,
+.shiki span {
+  color: var(--shiki-light);
+  background-color: var(--shiki-light-bg);
+}
+
+.dark .shiki,
+.dark .shiki span {
+  color: var(--shiki-dark);
+  background-color: var(--shiki-dark-bg);
+}
+
+/* Code blocks: shiki owns the colors, typography owns the rest — keep the
+   prose theme from painting its own background over shiki's. */
+.prose pre {
+  @apply rounded-lg border p-4;
+  background-color: unset;
+}
diff --git a/website/app/layout.tsx b/website/app/layout.tsx
index 6a98fd9..faab78c 100644
--- a/website/app/layout.tsx
+++ b/website/app/layout.tsx
@@ -1,6 +1,8 @@
 import type { Metadata } from 'next';
 import type { ReactNode } from 'react';
-import { Provider } from './provider';
+import { SiteHeader } from '@/components/site-header';
+import { ThemeProvider } from '@/components/theme-provider';
+import { docs } from '@/lib/docs';
 import './global.css';
 
 export const metadata: Metadata = {
@@ -13,10 +15,19 @@ export const metadata: Metadata = {
 };
 
 export default function Layout({ children }: { children: ReactNode }) {
+  const searchItems = docs.map(({ href, title, description }) => ({
+    href,
+    title,
+    description,
+  }));
+
   return (
     <html lang="en" suppressHydrationWarning>
-      <body className="flex min-h-screen flex-col">
-        <Provider>{children}</Provider>
+      <body className="flex min-h-screen flex-col antialiased">
+        <ThemeProvider>
+          <SiteHeader searchItems={searchItems} />
+          {children}
+        </ThemeProvider>
       </body>
     </html>
   );
diff --git a/website/app/(home)/page.tsx b/website/app/page.tsx
similarity index 74%
rename from website/app/(home)/page.tsx
rename to website/app/page.tsx
index 317ddc4..fcdd04e 100644
--- a/website/app/(home)/page.tsx
+++ b/website/app/page.tsx
@@ -1,6 +1,6 @@
 import Link from 'next/link';
-
-const GITHUB_URL = 'https://github.com/BitMiracle-AI/Dormice';
+import { GITHUB_URL } from '@/components/site-header';
+import { Button } from '@/components/ui/button';
 
 const features = [
   {
@@ -49,29 +49,23 @@ export default function HomePage() {
       <h1 className="max-w-3xl text-4xl font-semibold tracking-tight text-balance sm:text-5xl">
         The SQLite of agent sandboxes
       </h1>
-      <p className="mt-6 max-w-2xl text-lg text-fd-muted-foreground">
+      <p className="mt-6 max-w-2xl text-lg text-muted-foreground">
         A self-hosted sandbox platform for AI agents. One machine, sandboxes
         that live forever, idle costs nothing.
       </p>
       <div className="mt-8 flex items-center gap-3">
-        <Link
-          href="/docs"
-          className="rounded-full bg-fd-primary px-6 py-2.5 text-sm font-medium text-fd-primary-foreground transition-colors hover:bg-fd-primary/90"
-        >
+        <Button size="lg" render={<Link href="/docs" />}>
           Get started
-        </Link>
-        <a
-          href={GITHUB_URL}
-          className="rounded-full border px-6 py-2.5 text-sm font-medium transition-colors hover:bg-fd-accent"
-        >
+        </Button>
+        <Button size="lg" variant="outline" render={<a href={GITHUB_URL} />}>
           GitHub
-        </a>
+        </Button>
       </div>
-      <p className="mt-4 text-xs text-fd-muted-foreground">
+      <p className="mt-4 text-xs text-muted-foreground">
         Early development: works end to end against real infrastructure, not
         production-ready yet.
       </p>
-      <pre className="mt-10 max-w-full overflow-x-auto rounded-lg border bg-fd-card px-5 py-4 text-left text-sm">
+      <pre className="mt-10 max-w-full overflow-x-auto rounded-lg border bg-card px-5 py-4 text-left text-sm">
         <code>
           curl -fsSL
           https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh
@@ -80,11 +74,9 @@ export default function HomePage() {
       </pre>
       <div className="mt-16 grid w-full max-w-4xl gap-4 text-left sm:grid-cols-2">
         {features.map((feature) => (
-          <div key={feature.title} className="rounded-lg border bg-fd-card p-6">
+          <div key={feature.title} className="rounded-lg border bg-card p-6">
             <h2 className="font-medium">{feature.title}</h2>
-            <p className="mt-2 text-sm text-fd-muted-foreground">
-              {feature.body}
-            </p>
+            <p className="mt-2 text-sm text-muted-foreground">{feature.body}</p>
           </div>
         ))}
       </div>
diff --git a/website/app/provider.tsx b/website/app/provider.tsx
deleted file mode 100644
index 2c0ac7b..0000000
--- a/website/app/provider.tsx
+++ /dev/null
@@ -1,11 +0,0 @@
-'use client';
-
-import { RootProvider } from 'fumadocs-ui/provider/next';
-import type { ReactNode } from 'react';
-import SearchDialog from '@/components/search';
-
-// Client wrapper so the root layout (a server component) can hand
-// RootProvider a component — the static search dialog.
-export function Provider({ children }: { children: ReactNode }) {
-  return <RootProvider search={{ SearchDialog }}>{children}</RootProvider>;
-}
diff --git a/website/app/shadcn.css b/website/app/shadcn.css
new file mode 100644
index 0000000..451386c
--- /dev/null
+++ b/website/app/shadcn.css
@@ -0,0 +1,130 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "@fontsource-variable/inter";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+    --font-heading: var(--font-sans);
+    --font-sans: 'Inter Variable', sans-serif;
+    --color-sidebar-ring: var(--sidebar-ring);
+    --color-sidebar-border: var(--sidebar-border);
+    --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+    --color-sidebar-accent: var(--sidebar-accent);
+    --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+    --color-sidebar-primary: var(--sidebar-primary);
+    --color-sidebar-foreground: var(--sidebar-foreground);
+    --color-sidebar: var(--sidebar);
+    --color-chart-5: var(--chart-5);
+    --color-chart-4: var(--chart-4);
+    --color-chart-3: var(--chart-3);
+    --color-chart-2: var(--chart-2);
+    --color-chart-1: var(--chart-1);
+    --color-ring: var(--ring);
+    --color-input: var(--input);
+    --color-border: var(--border);
+    --color-destructive: var(--destructive);
+    --color-accent-foreground: var(--accent-foreground);
+    --color-accent: var(--accent);
+    --color-muted-foreground: var(--muted-foreground);
+    --color-muted: var(--muted);
+    --color-secondary-foreground: var(--secondary-foreground);
+    --color-secondary: var(--secondary);
+    --color-primary-foreground: var(--primary-foreground);
+    --color-primary: var(--primary);
+    --color-popover-foreground: var(--popover-foreground);
+    --color-popover: var(--popover);
+    --color-card-foreground: var(--card-foreground);
+    --color-card: var(--card);
+    --color-foreground: var(--foreground);
+    --color-background: var(--background);
+    --radius-sm: calc(var(--radius) * 0.6);
+    --radius-md: calc(var(--radius) * 0.8);
+    --radius-lg: var(--radius);
+    --radius-xl: calc(var(--radius) * 1.4);
+    --radius-2xl: calc(var(--radius) * 1.8);
+    --radius-3xl: calc(var(--radius) * 2.2);
+    --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+:root {
+    --background: oklch(1 0 0);
+    --foreground: oklch(0.145 0 0);
+    --card: oklch(1 0 0);
+    --card-foreground: oklch(0.145 0 0);
+    --popover: oklch(1 0 0);
+    --popover-foreground: oklch(0.145 0 0);
+    --primary: oklch(0.488 0.243 264.376);
+    --primary-foreground: oklch(0.97 0.014 254.604);
+    --secondary: oklch(0.967 0.001 286.375);
+    --secondary-foreground: oklch(0.21 0.006 285.885);
+    --muted: oklch(0.97 0 0);
+    --muted-foreground: oklch(0.556 0 0);
+    --accent: oklch(0.97 0 0);
+    --accent-foreground: oklch(0.205 0 0);
+    --destructive: oklch(0.577 0.245 27.325);
+    --border: oklch(0.922 0 0);
+    --input: oklch(0.922 0 0);
+    --ring: oklch(0.708 0 0);
+    --chart-1: oklch(0.809 0.105 251.813);
+    --chart-2: oklch(0.623 0.214 259.815);
+    --chart-3: oklch(0.546 0.245 262.881);
+    --chart-4: oklch(0.488 0.243 264.376);
+    --chart-5: oklch(0.424 0.199 265.638);
+    --radius: 0.625rem;
+    --sidebar: oklch(0.985 0 0);
+    --sidebar-foreground: oklch(0.145 0 0);
+    --sidebar-primary: oklch(0.546 0.245 262.881);
+    --sidebar-primary-foreground: oklch(0.97 0.014 254.604);
+    --sidebar-accent: oklch(0.97 0 0);
+    --sidebar-accent-foreground: oklch(0.205 0 0);
+    --sidebar-border: oklch(0.922 0 0);
+    --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+    --background: oklch(0.145 0 0);
+    --foreground: oklch(0.985 0 0);
+    --card: oklch(0.205 0 0);
+    --card-foreground: oklch(0.985 0 0);
+    --popover: oklch(0.205 0 0);
+    --popover-foreground: oklch(0.985 0 0);
+    --primary: oklch(0.424 0.199 265.638);
+    --primary-foreground: oklch(0.97 0.014 254.604);
+    --secondary: oklch(0.274 0.006 286.033);
+    --secondary-foreground: oklch(0.985 0 0);
+    --muted: oklch(0.269 0 0);
+    --muted-foreground: oklch(0.708 0 0);
+    --accent: oklch(0.269 0 0);
+    --accent-foreground: oklch(0.985 0 0);
+    --destructive: oklch(0.704 0.191 22.216);
+    --border: oklch(1 0 0 / 10%);
+    --input: oklch(1 0 0 / 15%);
+    --ring: oklch(0.556 0 0);
+    --chart-1: oklch(0.809 0.105 251.813);
+    --chart-2: oklch(0.623 0.214 259.815);
+    --chart-3: oklch(0.546 0.245 262.881);
+    --chart-4: oklch(0.488 0.243 264.376);
+    --chart-5: oklch(0.424 0.199 265.638);
+    --sidebar: oklch(0.205 0 0);
+    --sidebar-foreground: oklch(0.985 0 0);
+    --sidebar-primary: oklch(0.623 0.214 259.815);
+    --sidebar-primary-foreground: oklch(0.97 0.014 254.604);
+    --sidebar-accent: oklch(0.269 0 0);
+    --sidebar-accent-foreground: oklch(0.985 0 0);
+    --sidebar-border: oklch(1 0 0 / 10%);
+    --sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+    }
+  body {
+    @apply bg-background text-foreground;
+    }
+  html {
+    @apply font-sans;
+    }
+}
diff --git a/website/components.json b/website/components.json
new file mode 100644
index 0000000..6f81a57
--- /dev/null
+++ b/website/components.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-rhea",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/shadcn.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "hugeicons",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default-translucent",
+  "menuAccent": "subtle",
+  "registries": {}
+}
diff --git a/website/components/docs-mobile-nav.tsx b/website/components/docs-mobile-nav.tsx
new file mode 100644
index 0000000..4d42c4f
--- /dev/null
+++ b/website/components/docs-mobile-nav.tsx
@@ -0,0 +1,32 @@
+'use client';
+
+import { useState } from 'react';
+import { type DocsNavItem, DocsSidebar } from '@/components/docs-sidebar';
+import { Button } from '@/components/ui/button';
+import {
+  Sheet,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetTrigger,
+} from '@/components/ui/sheet';
+
+export function DocsMobileNav({ items }: { items: DocsNavItem[] }) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Sheet open={open} onOpenChange={setOpen}>
+      <SheetTrigger render={<Button variant="outline" size="sm" />}>
+        Menu
+      </SheetTrigger>
+      <SheetContent side="left">
+        <SheetHeader>
+          <SheetTitle>Documentation</SheetTitle>
+        </SheetHeader>
+        <div className="px-4">
+          <DocsSidebar items={items} onNavigate={() => setOpen(false)} />
+        </div>
+      </SheetContent>
+    </Sheet>
+  );
+}
diff --git a/website/components/docs-search.tsx b/website/components/docs-search.tsx
new file mode 100644
index 0000000..eddff3a
--- /dev/null
+++ b/website/components/docs-search.tsx
@@ -0,0 +1,84 @@
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { useEffect, useState } from 'react';
+import { Button } from '@/components/ui/button';
+import {
+  CommandDialog,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@/components/ui/command';
+
+export interface SearchItem {
+  href: string;
+  title: string;
+  description: string;
+}
+
+// Search over doc titles and descriptions, fully client-side — the honest
+// size for a docs set this small. Grow it into a real text index when the
+// page count earns it.
+export function DocsSearch({ items }: { items: SearchItem[] }) {
+  const [open, setOpen] = useState(false);
+  const router = useRouter();
+
+  useEffect(() => {
+    const down = (event: KeyboardEvent) => {
+      if (event.key === 'k' && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault();
+        setOpen((value) => !value);
+      }
+    };
+    document.addEventListener('keydown', down);
+    return () => document.removeEventListener('keydown', down);
+  }, []);
+
+  return (
+    <>
+      <Button
+        variant="outline"
+        size="sm"
+        className="hidden gap-3 font-normal text-muted-foreground sm:inline-flex"
+        onClick={() => setOpen(true)}
+      >
+        Search docs…
+        <kbd className="rounded border bg-muted px-1 font-sans text-[0.7rem] text-muted-foreground">
+          ⌘K
+        </kbd>
+      </Button>
+      <CommandDialog
+        open={open}
+        onOpenChange={setOpen}
+        title="Search documentation"
+        description="Search the Dormice documentation"
+      >
+        <CommandInput placeholder="Search documentation…" />
+        <CommandList>
+          <CommandEmpty>No results found.</CommandEmpty>
+          <CommandGroup heading="Documentation">
+            {items.map((item) => (
+              <CommandItem
+                key={item.href}
+                value={`${item.title} ${item.description}`}
+                onSelect={() => {
+                  setOpen(false);
+                  router.push(item.href);
+                }}
+              >
+                <div className="flex flex-col gap-0.5">
+                  <span>{item.title}</span>
+                  <span className="text-xs text-muted-foreground">
+                    {item.description}
+                  </span>
+                </div>
+              </CommandItem>
+            ))}
+          </CommandGroup>
+        </CommandList>
+      </CommandDialog>
+    </>
+  );
+}
diff --git a/website/components/docs-sidebar.tsx b/website/components/docs-sidebar.tsx
new file mode 100644
index 0000000..3c967b4
--- /dev/null
+++ b/website/components/docs-sidebar.tsx
@@ -0,0 +1,39 @@
+'use client';
+
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+import { cn } from '@/lib/utils';
+
+export interface DocsNavItem {
+  href: string;
+  title: string;
+}
+
+export function DocsSidebar({
+  items,
+  onNavigate,
+}: {
+  items: DocsNavItem[];
+  onNavigate?: () => void;
+}) {
+  const pathname = usePathname();
+
+  return (
+    <nav className="flex flex-col gap-0.5">
+      {items.map((item) => (
+        <Link
+          key={item.href}
+          href={item.href}
+          onClick={onNavigate}
+          className={cn(
+            'rounded-md px-2.5 py-1.5 text-sm text-muted-foreground transition-colors hover:text-foreground',
+            pathname === item.href &&
+              'bg-accent font-medium text-accent-foreground',
+          )}
+        >
+          {item.title}
+        </Link>
+      ))}
+    </nav>
+  );
+}
diff --git a/website/components/docs-toc.tsx b/website/components/docs-toc.tsx
new file mode 100644
index 0000000..098e6d9
--- /dev/null
+++ b/website/components/docs-toc.tsx
@@ -0,0 +1,72 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { cn } from '@/lib/utils';
+
+interface TocItem {
+  id: string;
+  text: string;
+  depth: number;
+}
+
+// Reads headings from the rendered article (single source: the DOM the
+// reader sees) and highlights the one currently in view.
+export function DocsToc() {
+  const [items, setItems] = useState<TocItem[]>([]);
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  useEffect(() => {
+    const article = document.querySelector('[data-docs-article]');
+    if (!article) return;
+    const headings = Array.from(article.querySelectorAll('h2, h3')).filter(
+      (heading) => heading.id,
+    );
+    setItems(
+      headings.map((heading) => ({
+        id: heading.id,
+        text: heading.textContent ?? '',
+        depth: heading.tagName === 'H2' ? 2 : 3,
+      })),
+    );
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id);
+            break;
+          }
+        }
+      },
+      // A heading counts as "current" while it sits in the top fifth of
+      // the viewport.
+      { rootMargin: '0% 0% -80% 0%' },
+    );
+    for (const heading of headings) observer.observe(heading);
+    return () => observer.disconnect();
+  }, []);
+
+  if (items.length === 0) return null;
+
+  return (
+    <nav className="text-sm">
+      <p className="mb-2 font-medium">On this page</p>
+      <ul className="flex flex-col gap-1.5 border-l">
+        {items.map((item) => (
+          <li key={item.id}>
+            <a
+              href={`#${item.id}`}
+              className={cn(
+                '-ml-px block border-l border-transparent pl-3 text-muted-foreground transition-colors hover:text-foreground',
+                item.depth === 3 && 'pl-6',
+                activeId === item.id && 'border-primary text-foreground',
+              )}
+            >
+              {item.text}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}
diff --git a/website/components/search.tsx b/website/components/search.tsx
deleted file mode 100644
index 1793953..0000000
--- a/website/components/search.tsx
+++ /dev/null
@@ -1,44 +0,0 @@
-'use client';
-
-import { useDocsSearch } from 'fumadocs-core/search/client';
-import { oramaStaticClient } from 'fumadocs-core/search/client/orama-static';
-import {
-  SearchDialog,
-  SearchDialogClose,
-  SearchDialogContent,
-  SearchDialogHeader,
-  SearchDialogIcon,
-  SearchDialogInput,
-  SearchDialogList,
-  SearchDialogOverlay,
-  type SharedProps,
-} from 'fumadocs-ui/components/dialog/search';
-
-// Static search: the whole index is exported at build time by
-// app/api/search/route.ts and queried in the browser — no server involved,
-// which is what output: 'export' demands. Module scope so the client (and
-// its downloaded index) survives re-renders.
-const client = oramaStaticClient();
-
-export default function StaticSearchDialog(props: SharedProps) {
-  const { search, setSearch, query } = useDocsSearch({ client });
-
-  return (
-    <SearchDialog
-      search={search}
-      onSearchChange={setSearch}
-      isLoading={query.isLoading}
-      {...props}
-    >
-      <SearchDialogOverlay />
-      <SearchDialogContent>
-        <SearchDialogHeader>
-          <SearchDialogIcon />
-          <SearchDialogInput />
-          <SearchDialogClose />
-        </SearchDialogHeader>
-        <SearchDialogList items={query.data !== 'empty' ? query.data : null} />
-      </SearchDialogContent>
-    </SearchDialog>
-  );
-}
diff --git a/website/components/site-header.tsx b/website/components/site-header.tsx
new file mode 100644
index 0000000..4c83f08
--- /dev/null
+++ b/website/components/site-header.tsx
@@ -0,0 +1,35 @@
+import Link from 'next/link';
+import { DocsSearch, type SearchItem } from '@/components/docs-search';
+import { ThemeToggle } from '@/components/theme-toggle';
+
+export const GITHUB_URL = 'https://github.com/BitMiracle-AI/Dormice';
+
+export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
+  return (
+    <header className="sticky top-0 z-40 border-b bg-background/80 backdrop-blur">
+      <div className="mx-auto flex h-14 w-full max-w-6xl items-center gap-6 px-4">
+        <Link href="/" className="font-semibold">
+          Dormice
+        </Link>
+        <nav className="flex items-center gap-4 text-sm text-muted-foreground">
+          <Link
+            href="/docs"
+            className="transition-colors hover:text-foreground"
+          >
+            Docs
+          </Link>
+          <a
+            href={GITHUB_URL}
+            className="transition-colors hover:text-foreground"
+          >
+            GitHub
+          </a>
+        </nav>
+        <div className="ml-auto flex items-center gap-2">
+          <DocsSearch items={searchItems} />
+          <ThemeToggle />
+        </div>
+      </div>
+    </header>
+  );
+}
diff --git a/website/components/theme-provider.tsx b/website/components/theme-provider.tsx
new file mode 100644
index 0000000..7e8f399
--- /dev/null
+++ b/website/components/theme-provider.tsx
@@ -0,0 +1,17 @@
+'use client';
+
+import { ThemeProvider as NextThemesProvider } from 'next-themes';
+import type { ReactNode } from 'react';
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  return (
+    <NextThemesProvider
+      attribute="class"
+      defaultTheme="system"
+      enableSystem
+      disableTransitionOnChange
+    >
+      {children}
+    </NextThemesProvider>
+  );
+}
diff --git a/website/components/theme-toggle.tsx b/website/components/theme-toggle.tsx
new file mode 100644
index 0000000..678b43a
--- /dev/null
+++ b/website/components/theme-toggle.tsx
@@ -0,0 +1,27 @@
+'use client';
+
+import { Moon02Icon, Sun01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useTheme } from 'next-themes';
+import { useEffect, useState } from 'react';
+import { Button } from '@/components/ui/button';
+
+export function ThemeToggle() {
+  const { resolvedTheme, setTheme } = useTheme();
+  // The page is static: the server can't know the visitor's theme, so the
+  // icon only becomes theme-dependent after mount (avoids hydration drift).
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  const dark = mounted && resolvedTheme === 'dark';
+
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      aria-label="Toggle theme"
+      onClick={() => setTheme(dark ? 'light' : 'dark')}
+    >
+      <HugeiconsIcon icon={dark ? Sun01Icon : Moon02Icon} />
+    </Button>
+  );
+}
diff --git a/website/components/ui/button.tsx b/website/components/ui/button.tsx
new file mode 100644
index 0000000..e87e24d
--- /dev/null
+++ b/website/components/ui/button.tsx
@@ -0,0 +1,56 @@
+import { Button as ButtonPrimitive } from "@base-ui/react/button"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva(
+  "group/button inline-flex shrink-0 items-center justify-center rounded-2xl border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/80",
+        outline:
+          "border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:bg-transparent dark:hover:bg-input/30",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-[color-mix(in_oklch,var(--secondary),var(--foreground)_5%)] aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
+        ghost:
+          "hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
+        destructive:
+          "bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default:
+          "h-8 gap-1.5 px-3 has-data-[icon=inline-end]:pr-2.5 has-data-[icon=inline-start]:pl-2.5",
+        xs: "h-6 gap-1 px-2.5 text-xs has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2 [&_svg:not([class*='size-'])]:size-3",
+        sm: "h-7 gap-1 px-3 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        lg: "h-9 gap-1.5 px-4 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3",
+        icon: "size-8",
+        "icon-xs": "size-6 [&_svg:not([class*='size-'])]:size-3",
+        "icon-sm": "size-7",
+        "icon-lg": "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function Button({
+  className,
+  variant = "default",
+  size = "default",
+  ...props
+}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>) {
+  return (
+    <ButtonPrimitive
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+}
+
+export { Button, buttonVariants }
diff --git a/website/components/ui/command.tsx b/website/components/ui/command.tsx
new file mode 100644
index 0000000..a0d1cc4
--- /dev/null
+++ b/website/components/ui/command.tsx
@@ -0,0 +1,197 @@
+"use client"
+
+import * as React from "react"
+import { Command as CommandPrimitive } from "cmdk"
+
+import { cn } from "@/lib/utils"
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog"
+import {
+  InputGroup,
+  InputGroupAddon,
+} from "@/components/ui/input-group"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { SearchIcon, Tick02Icon } from "@hugeicons/core-free-icons"
+
+function Command({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive>) {
+  return (
+    <CommandPrimitive
+      data-slot="command"
+      className={cn(
+        "flex size-full flex-col overflow-hidden rounded-3xl bg-popover p-1 text-popover-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CommandDialog({
+  title = "Command Palette",
+  description = "Search for a command to run...",
+  children,
+  className,
+  showCloseButton = false,
+  ...props
+}: Omit<React.ComponentProps<typeof Dialog>, "children"> & {
+  title?: string
+  description?: string
+  className?: string
+  showCloseButton?: boolean
+  children: React.ReactNode
+}) {
+  return (
+    <Dialog {...props}>
+      <DialogHeader className="sr-only">
+        <DialogTitle>{title}</DialogTitle>
+        <DialogDescription>{description}</DialogDescription>
+      </DialogHeader>
+      <DialogContent
+        className={cn(
+          "top-1/3 translate-y-0 overflow-hidden rounded-3xl! p-0",
+          className
+        )}
+        showCloseButton={showCloseButton}
+      >
+        {children}
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+function CommandInput({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Input>) {
+  return (
+    <div data-slot="command-input-wrapper" className="p-1 pb-0">
+      <InputGroup className="h-8! bg-input/50">
+        <CommandPrimitive.Input
+          data-slot="command-input"
+          className={cn(
+            "w-full text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50",
+            className
+          )}
+          {...props}
+        />
+        <InputGroupAddon>
+          <HugeiconsIcon icon={SearchIcon} strokeWidth={2} className="size-4 shrink-0 opacity-50" />
+        </InputGroupAddon>
+      </InputGroup>
+    </div>
+  )
+}
+
+function CommandList({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.List>) {
+  return (
+    <CommandPrimitive.List
+      data-slot="command-list"
+      className={cn(
+        "no-scrollbar max-h-72 scroll-py-1 overflow-x-hidden overflow-y-auto outline-none",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CommandEmpty({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Empty>) {
+  return (
+    <CommandPrimitive.Empty
+      data-slot="command-empty"
+      className={cn("py-6 text-center text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function CommandGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Group>) {
+  return (
+    <CommandPrimitive.Group
+      data-slot="command-group"
+      className={cn(
+        "overflow-hidden p-1 text-foreground **:[[cmdk-group-heading]]:px-2 **:[[cmdk-group-heading]]:py-1.5 **:[[cmdk-group-heading]]:text-xs **:[[cmdk-group-heading]]:font-medium **:[[cmdk-group-heading]]:text-muted-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CommandSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Separator>) {
+  return (
+    <CommandPrimitive.Separator
+      data-slot="command-separator"
+      className={cn("my-1 h-px bg-border/50", className)}
+      {...props}
+    />
+  )
+}
+
+function CommandItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Item>) {
+  return (
+    <CommandPrimitive.Item
+      data-slot="command-item"
+      className={cn(
+        "group/command-item relative flex min-h-7 cursor-default items-center gap-2 rounded-xl px-2 py-1.5 text-sm outline-hidden select-none in-data-[slot=dialog-content]:rounded-2xl data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-selected:bg-muted data-selected:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-selected:*:[svg]:text-foreground",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <HugeiconsIcon icon={Tick02Icon} strokeWidth={2} className="ml-auto opacity-0 group-has-data-[slot=command-shortcut]/command-item:hidden group-data-[checked=true]/command-item:opacity-100" />
+    </CommandPrimitive.Item>
+  )
+}
+
+function CommandShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="command-shortcut"
+      className={cn(
+        "ml-auto text-xs tracking-widest text-muted-foreground group-data-selected/command-item:text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
+  CommandSeparator,
+}
diff --git a/website/components/ui/dialog.tsx b/website/components/ui/dialog.tsx
new file mode 100644
index 0000000..db7393f
--- /dev/null
+++ b/website/components/ui/dialog.tsx
@@ -0,0 +1,160 @@
+"use client"
+
+import * as React from "react"
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { Cancel01Icon } from "@hugeicons/core-free-icons"
+
+function Dialog({ ...props }: DialogPrimitive.Root.Props) {
+  return <DialogPrimitive.Root data-slot="dialog" {...props} />
+}
+
+function DialogTrigger({ ...props }: DialogPrimitive.Trigger.Props) {
+  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />
+}
+
+function DialogPortal({ ...props }: DialogPrimitive.Portal.Props) {
+  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />
+}
+
+function DialogClose({ ...props }: DialogPrimitive.Close.Props) {
+  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />
+}
+
+function DialogOverlay({
+  className,
+  ...props
+}: DialogPrimitive.Backdrop.Props) {
+  return (
+    <DialogPrimitive.Backdrop
+      data-slot="dialog-overlay"
+      className={cn(
+        "fixed inset-0 isolate z-50 bg-black/30 duration-100 supports-backdrop-filter:backdrop-blur-sm data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogContent({
+  className,
+  children,
+  showCloseButton = true,
+  ...props
+}: DialogPrimitive.Popup.Props & {
+  showCloseButton?: boolean
+}) {
+  return (
+    <DialogPortal>
+      <DialogOverlay />
+      <DialogPrimitive.Popup
+        data-slot="dialog-content"
+        className={cn(
+          "fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-6 rounded-[min(var(--radius-4xl),24px)] bg-popover p-6 text-sm text-popover-foreground shadow-xl ring-1 ring-foreground/5 duration-100 outline-none sm:max-w-md dark:ring-foreground/10 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <DialogPrimitive.Close
+            data-slot="dialog-close"
+            render={
+              <Button
+                variant="ghost"
+                className="absolute top-4 right-4 bg-secondary"
+                size="icon-sm"
+              />
+            }
+          >
+            <HugeiconsIcon icon={Cancel01Icon} strokeWidth={2} />
+            <span className="sr-only">Close</span>
+          </DialogPrimitive.Close>
+        )}
+      </DialogPrimitive.Popup>
+    </DialogPortal>
+  )
+}
+
+function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="dialog-header"
+      className={cn("flex flex-col gap-1.5", className)}
+      {...props}
+    />
+  )
+}
+
+function DialogFooter({
+  className,
+  showCloseButton = false,
+  children,
+  ...props
+}: React.ComponentProps<"div"> & {
+  showCloseButton?: boolean
+}) {
+  return (
+    <div
+      data-slot="dialog-footer"
+      className={cn(
+        "flex flex-col-reverse gap-2 sm:flex-row sm:justify-end",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      {showCloseButton && (
+        <DialogPrimitive.Close render={<Button variant="outline" />}>
+          Close
+        </DialogPrimitive.Close>
+      )}
+    </div>
+  )
+}
+
+function DialogTitle({ className, ...props }: DialogPrimitive.Title.Props) {
+  return (
+    <DialogPrimitive.Title
+      data-slot="dialog-title"
+      className={cn(
+        "font-heading text-base leading-none font-medium",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DialogDescription({
+  className,
+  ...props
+}: DialogPrimitive.Description.Props) {
+  return (
+    <DialogPrimitive.Description
+      data-slot="dialog-description"
+      className={cn(
+        "text-sm text-muted-foreground *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+}
diff --git a/website/components/ui/input-group.tsx b/website/components/ui/input-group.tsx
new file mode 100644
index 0000000..3cbad79
--- /dev/null
+++ b/website/components/ui/input-group.tsx
@@ -0,0 +1,157 @@
+"use client"
+
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Textarea } from "@/components/ui/textarea"
+
+function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="input-group"
+      role="group"
+      className={cn(
+        "group/input-group relative flex h-8 w-full min-w-0 items-center rounded-2xl border border-transparent bg-input/50 transition-[color,box-shadow] duration-200 outline-none in-data-[slot=combobox-content]:focus-within:border-inherit in-data-[slot=combobox-content]:focus-within:ring-0 has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-3 has-[[data-slot=input-group-control]:focus-visible]:ring-ring/30 has-[[data-slot][aria-invalid=true]]:border-destructive has-[[data-slot][aria-invalid=true]]:ring-3 has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>textarea]:h-auto dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40 has-[>[data-align=block-end]]:[&>input]:pt-3 has-[>[data-align=block-start]]:[&>input]:pb-3 has-[>[data-align=inline-end]]:[&>input]:pr-1.5 has-[>[data-align=inline-start]]:[&>input]:pl-1.5",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const inputGroupAddonVariants = cva(
+  "flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 **:data-[slot=kbd]:rounded-2xl **:data-[slot=kbd]:bg-muted-foreground/10 **:data-[slot=kbd]:px-1.5 [&>svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      align: {
+        "inline-start":
+          "order-first pl-2 has-[>button]:ml-[-0.3rem] has-[>kbd]:ml-[-0.15rem]",
+        "inline-end":
+          "order-last pr-2 has-[>button]:mr-[-0.3rem] has-[>kbd]:mr-[-0.15rem]",
+        "block-start":
+          "order-first w-full justify-start px-2.5 pt-2 group-has-[>input]/input-group:pt-2 [.border-b]:pb-2",
+        "block-end":
+          "order-last w-full justify-start px-2.5 pb-2 group-has-[>input]/input-group:pb-2 [.border-t]:pt-2",
+      },
+    },
+    defaultVariants: {
+      align: "inline-start",
+    },
+  }
+)
+
+function InputGroupAddon({
+  className,
+  align = "inline-start",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="input-group-addon"
+      data-align={align}
+      className={cn(inputGroupAddonVariants({ align }), className)}
+      onClick={(e) => {
+        if ((e.target as HTMLElement).closest("button")) {
+          return
+        }
+        e.currentTarget.parentElement?.querySelector("input")?.focus()
+      }}
+      {...props}
+    />
+  )
+}
+
+const inputGroupButtonVariants = cva(
+  "flex items-center gap-2 rounded-2xl text-sm shadow-none",
+  {
+    variants: {
+      size: {
+        xs: "h-6 gap-1 rounded-xl px-1.5 [&>svg:not([class*='size-'])]:size-3.5",
+        sm: "",
+        "icon-xs": "size-6 rounded-xl p-0 has-[>svg]:p-0",
+        "icon-sm": "size-8 p-0 has-[>svg]:p-0",
+      },
+    },
+    defaultVariants: {
+      size: "xs",
+    },
+  }
+)
+
+function InputGroupButton({
+  className,
+  type = "button",
+  variant = "ghost",
+  size = "xs",
+  ...props
+}: Omit<React.ComponentProps<typeof Button>, "size" | "type"> &
+  VariantProps<typeof inputGroupButtonVariants> & {
+    type?: "button" | "submit" | "reset"
+  }) {
+  return (
+    <Button
+      type={type}
+      data-size={size}
+      variant={variant}
+      className={cn(inputGroupButtonVariants({ size }), className)}
+      {...props}
+    />
+  )
+}
+
+function InputGroupText({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      className={cn(
+        "flex items-center gap-2 text-sm text-muted-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function InputGroupInput({
+  className,
+  ...props
+}: React.ComponentProps<"input">) {
+  return (
+    <Input
+      data-slot="input-group-control"
+      className={cn(
+        "flex-1 rounded-none border-0 bg-transparent shadow-none ring-0 focus-visible:ring-0 aria-invalid:ring-0 dark:bg-transparent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function InputGroupTextarea({
+  className,
+  ...props
+}: React.ComponentProps<"textarea">) {
+  return (
+    <Textarea
+      data-slot="input-group-control"
+      className={cn(
+        "flex-1 resize-none rounded-none border-0 bg-transparent py-2 shadow-none ring-0 focus-visible:ring-0 aria-invalid:ring-0 dark:bg-transparent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupText,
+  InputGroupInput,
+  InputGroupTextarea,
+}
diff --git a/website/components/ui/input.tsx b/website/components/ui/input.tsx
new file mode 100644
index 0000000..f40013f
--- /dev/null
+++ b/website/components/ui/input.tsx
@@ -0,0 +1,20 @@
+import * as React from "react"
+import { Input as InputPrimitive } from "@base-ui/react/input"
+
+import { cn } from "@/lib/utils"
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <InputPrimitive
+      type={type}
+      data-slot="input"
+      className={cn(
+        "h-8 w-full min-w-0 rounded-2xl border border-transparent bg-input/50 px-2.5 py-1 text-base transition-[color,box-shadow] duration-200 outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input }
diff --git a/website/components/ui/sheet.tsx b/website/components/ui/sheet.tsx
new file mode 100644
index 0000000..281964b
--- /dev/null
+++ b/website/components/ui/sheet.tsx
@@ -0,0 +1,138 @@
+"use client"
+
+import * as React from "react"
+import { Dialog as SheetPrimitive } from "@base-ui/react/dialog"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { Cancel01Icon } from "@hugeicons/core-free-icons"
+
+function Sheet({ ...props }: SheetPrimitive.Root.Props) {
+  return <SheetPrimitive.Root data-slot="sheet" {...props} />
+}
+
+function SheetTrigger({ ...props }: SheetPrimitive.Trigger.Props) {
+  return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />
+}
+
+function SheetClose({ ...props }: SheetPrimitive.Close.Props) {
+  return <SheetPrimitive.Close data-slot="sheet-close" {...props} />
+}
+
+function SheetPortal({ ...props }: SheetPrimitive.Portal.Props) {
+  return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />
+}
+
+function SheetOverlay({ className, ...props }: SheetPrimitive.Backdrop.Props) {
+  return (
+    <SheetPrimitive.Backdrop
+      data-slot="sheet-overlay"
+      className={cn(
+        "fixed inset-0 z-50 bg-black/30 transition-opacity duration-150 data-ending-style:opacity-0 data-starting-style:opacity-0 supports-backdrop-filter:backdrop-blur-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SheetContent({
+  className,
+  children,
+  side = "right",
+  showCloseButton = true,
+  ...props
+}: SheetPrimitive.Popup.Props & {
+  side?: "top" | "right" | "bottom" | "left"
+  showCloseButton?: boolean
+}) {
+  return (
+    <SheetPortal>
+      <SheetOverlay />
+      <SheetPrimitive.Popup
+        data-slot="sheet-content"
+        data-side={side}
+        className={cn(
+          "fixed z-50 flex flex-col bg-popover bg-clip-padding text-sm text-popover-foreground shadow-xl transition duration-200 ease-in-out data-ending-style:opacity-0 data-starting-style:opacity-0 data-[side=bottom]:inset-x-0 data-[side=bottom]:bottom-0 data-[side=bottom]:h-auto data-[side=bottom]:border-t data-[side=bottom]:data-ending-style:translate-y-[2.5rem] data-[side=bottom]:data-starting-style:translate-y-[2.5rem] data-[side=left]:inset-y-0 data-[side=left]:left-0 data-[side=left]:h-full data-[side=left]:w-3/4 data-[side=left]:border-r data-[side=left]:data-ending-style:translate-x-[-2.5rem] data-[side=left]:data-starting-style:translate-x-[-2.5rem] data-[side=right]:inset-y-0 data-[side=right]:right-0 data-[side=right]:h-full data-[side=right]:w-3/4 data-[side=right]:border-l data-[side=right]:data-ending-style:translate-x-[2.5rem] data-[side=right]:data-starting-style:translate-x-[2.5rem] data-[side=top]:inset-x-0 data-[side=top]:top-0 data-[side=top]:h-auto data-[side=top]:border-b data-[side=top]:data-ending-style:translate-y-[-2.5rem] data-[side=top]:data-starting-style:translate-y-[-2.5rem] data-[side=left]:sm:max-w-sm data-[side=right]:sm:max-w-sm",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <SheetPrimitive.Close
+            data-slot="sheet-close"
+            render={
+              <Button
+                variant="ghost"
+                className="absolute top-4 right-4 bg-secondary"
+                size="icon-sm"
+              />
+            }
+          >
+            <HugeiconsIcon icon={Cancel01Icon} strokeWidth={2} />
+            <span className="sr-only">Close</span>
+          </SheetPrimitive.Close>
+        )}
+      </SheetPrimitive.Popup>
+    </SheetPortal>
+  )
+}
+
+function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-header"
+      className={cn("flex flex-col gap-1.5 p-6", className)}
+      {...props}
+    />
+  )
+}
+
+function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-footer"
+      className={cn("mt-auto flex flex-col gap-2 p-6", className)}
+      {...props}
+    />
+  )
+}
+
+function SheetTitle({ className, ...props }: SheetPrimitive.Title.Props) {
+  return (
+    <SheetPrimitive.Title
+      data-slot="sheet-title"
+      className={cn(
+        "font-heading text-base font-medium text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SheetDescription({
+  className,
+  ...props
+}: SheetPrimitive.Description.Props) {
+  return (
+    <SheetPrimitive.Description
+      data-slot="sheet-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Sheet,
+  SheetTrigger,
+  SheetClose,
+  SheetContent,
+  SheetHeader,
+  SheetFooter,
+  SheetTitle,
+  SheetDescription,
+}
diff --git a/website/components/ui/textarea.tsx b/website/components/ui/textarea.tsx
new file mode 100644
index 0000000..f88469f
--- /dev/null
+++ b/website/components/ui/textarea.tsx
@@ -0,0 +1,18 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(
+        "flex field-sizing-content min-h-16 w-full resize-none rounded-2xl border border-transparent bg-input/50 px-2.5 py-2 text-base transition-[color,box-shadow] duration-200 outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/30 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Textarea }
diff --git a/website/lib/docs.ts b/website/lib/docs.ts
new file mode 100644
index 0000000..754fbb0
--- /dev/null
+++ b/website/lib/docs.ts
@@ -0,0 +1,80 @@
+import type { MDXProps } from 'mdx/types';
+import type { JSX } from 'react';
+import * as e2bCompatibility from '@/content/docs/e2b-compatibility.mdx';
+import * as indexDoc from '@/content/docs/index.mdx';
+import * as installation from '@/content/docs/installation.mdx';
+import meta from '@/content/docs/meta.json';
+import * as quickstart from '@/content/docs/quickstart.mdx';
+
+// Server-only registry of every doc. MDX renders as server components, so
+// importing them all here costs the client nothing — pages ship as HTML.
+// meta.json stays the single decision point for order; the assertions below
+// fail the build when the two drift.
+
+interface DocModule {
+  frontmatter: { title: string; description: string };
+  default: (props: MDXProps) => JSX.Element;
+}
+
+// meta.json name -> module ('index' is the /docs landing page, slug '').
+const modules: Record<string, DocModule> = {
+  index: indexDoc,
+  installation,
+  quickstart,
+  'e2b-compatibility': e2bCompatibility,
+};
+
+export interface DocEntry {
+  /** URL path segments below /docs — empty string for the index page. */
+  slug: string;
+  href: string;
+  title: string;
+  description: string;
+}
+
+export const docs: DocEntry[] = meta.pages.map((name) => {
+  const mod = modules[name];
+  if (!mod) {
+    throw new Error(
+      `content/docs/meta.json lists "${name}" but lib/docs.ts does not import it`,
+    );
+  }
+  const slug = name === 'index' ? '' : name;
+  return {
+    slug,
+    href: slug === '' ? '/docs' : `/docs/${slug}`,
+    title: mod.frontmatter.title,
+    description: mod.frontmatter.description,
+  };
+});
+
+for (const name of Object.keys(modules)) {
+  if (!meta.pages.includes(name)) {
+    throw new Error(
+      `lib/docs.ts imports "${name}" but content/docs/meta.json does not list it`,
+    );
+  }
+}
+
+export interface Doc {
+  entry: DocEntry;
+  Content: DocModule['default'];
+  prev: DocEntry | null;
+  next: DocEntry | null;
+}
+
+export function getDoc(slugSegments: string[] | undefined): Doc | null {
+  const slug = (slugSegments ?? []).join('/');
+  const position = docs.findIndex((entry) => entry.slug === slug);
+  if (position === -1) return null;
+  const entry = docs[position];
+  const name = slug === '' ? 'index' : slug;
+  const mod = modules[name];
+  if (!entry || !mod) return null;
+  return {
+    entry,
+    Content: mod.default,
+    prev: docs[position - 1] ?? null,
+    next: docs[position + 1] ?? null,
+  };
+}
diff --git a/website/lib/layout.shared.tsx b/website/lib/layout.shared.tsx
deleted file mode 100644
index a7729ce..0000000
--- a/website/lib/layout.shared.tsx
+++ /dev/null
@@ -1,10 +0,0 @@
-import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
-
-// Chrome shared by every layout (home and docs): title, links, GitHub.
-export function baseOptions(): BaseLayoutProps {
-  return {
-    nav: { title: 'Dormice' },
-    githubUrl: 'https://github.com/BitMiracle-AI/Dormice',
-    links: [{ text: 'Documentation', url: '/docs' }],
-  };
-}
diff --git a/website/lib/source.ts b/website/lib/source.ts
deleted file mode 100644
index 664dcd8..0000000
--- a/website/lib/source.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import { loader } from 'fumadocs-core/source';
-import { docs } from '@/.source/server';
-
-// The one content loader: page tree, slugs and page data all come from here.
-export const source = loader({
-  baseUrl: '/docs',
-  source: docs.toFumadocsSource(),
-});
diff --git a/website/lib/utils.ts b/website/lib/utils.ts
new file mode 100644
index 0000000..bd0c391
--- /dev/null
+++ b/website/lib/utils.ts
@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
diff --git a/website/mdx-components.tsx b/website/mdx-components.tsx
index cf053e1..456e30a 100644
--- a/website/mdx-components.tsx
+++ b/website/mdx-components.tsx
@@ -1,6 +1,7 @@
-import defaultMdxComponents from 'fumadocs-ui/mdx';
 import type { MDXComponents } from 'mdx/types';
 
-export function getMDXComponents(components?: MDXComponents): MDXComponents {
-  return { ...defaultMdxComponents, ...components };
+// Required by @next/mdx: every compiled MDX module resolves its components
+// through this hook. Element overrides shared by all docs go here.
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+  return { ...components };
 }
diff --git a/website/mdx.d.ts b/website/mdx.d.ts
new file mode 100644
index 0000000..219a0d5
--- /dev/null
+++ b/website/mdx.d.ts
@@ -0,0 +1,12 @@
+declare module '*.mdx' {
+  import type { MDXProps } from 'mdx/types';
+  import type { JSX } from 'react';
+
+  // Exported by remark-mdx-frontmatter from each document's YAML header.
+  export const frontmatter: {
+    title: string;
+    description: string;
+  };
+
+  export default function MDXContent(props: MDXProps): JSX.Element;
+}
diff --git a/website/next.config.mjs b/website/next.config.mjs
index 10f08b7..96528a2 100644
--- a/website/next.config.mjs
+++ b/website/next.config.mjs
@@ -1,6 +1,4 @@
-import { createMDX } from 'fumadocs-mdx/next';
-
-const withMDX = createMDX();
+import createMDX from '@next/mdx';
 
 /** @type {import('next').NextConfig} */
 const config = {
@@ -12,4 +10,28 @@ const config = {
   images: { unoptimized: true },
 };
 
+const withMDX = createMDX({
+  options: {
+    // Plugins by package name, not imported functions: Turbopack requires
+    // loader options to be serializable.
+    remarkPlugins: [
+      ['remark-gfm'],
+      ['remark-frontmatter'],
+      ['remark-mdx-frontmatter'],
+    ],
+    rehypePlugins: [
+      ['rehype-slug'],
+      [
+        '@shikijs/rehype',
+        {
+          themes: { light: 'github-light', dark: 'github-dark' },
+          // Emit both palettes as CSS variables; global.css picks one per
+          // color scheme.
+          defaultColor: false,
+        },
+      ],
+    ],
+  },
+});
+
 export default withMDX(config);
diff --git a/website/package.json b/website/package.json
index bfc73bf..815c5e4 100644
--- a/website/package.json
+++ b/website/package.json
@@ -8,24 +8,40 @@
   "scripts": {
     "build": "NEXT_TELEMETRY_DISABLED=1 next build",
     "dev": "NEXT_TELEMETRY_DISABLED=1 next dev",
-    "postinstall": "fumadocs-mdx",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "fumadocs-core": "^16.11.1",
-    "fumadocs-mdx": "^15.1.0",
-    "fumadocs-ui": "^16.11.1",
+    "@base-ui/react": "^1.6.0",
+    "@fontsource-variable/inter": "^5.2.8",
+    "@hugeicons/core-free-icons": "^4.2.2",
+    "@hugeicons/react": "^1.1.9",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
     "next": "^16.2.10",
+    "next-themes": "^0.4.6",
     "react": "^19.2.7",
-    "react-dom": "^19.2.7"
+    "react-dom": "^19.2.7",
+    "tailwind-merge": "^3.6.0",
+    "tw-animate-css": "^1.4.0"
   },
   "devDependencies": {
+    "@mdx-js/loader": "^3.1.1",
+    "@mdx-js/react": "^3.1.1",
+    "@next/mdx": "^16.2.10",
+    "@shikijs/rehype": "^4.3.1",
     "@tailwindcss/postcss": "^4.3.2",
+    "@tailwindcss/typography": "^0.5.20",
     "@types/mdx": "^2.0.14",
     "@types/node": "^26.1.0",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.16",
+    "rehype-slug": "^6.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "shadcn": "^4.13.0",
     "tailwindcss": "^4.3.2",
     "typescript": "^6.0.3"
   }
diff --git a/website/source.config.ts b/website/source.config.ts
deleted file mode 100644
index 0564068..0000000
--- a/website/source.config.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
-
-export const docs = defineDocs({
-  dir: 'content/docs',
-});
-
-export default defineConfig();
diff --git a/website/tsconfig.json b/website/tsconfig.json
index fbe9cee..b8ead68 100644
--- a/website/tsconfig.json
+++ b/website/tsconfig.json
@@ -4,17 +4,12 @@
     "lib": ["ES2023", "DOM", "DOM.Iterable"],
     "jsx": "preserve",
     "allowJs": true,
+    "resolveJsonModule": true,
     "incremental": true,
     "plugins": [{ "name": "next" }],
     "baseUrl": ".",
     "paths": { "@/*": ["./*"] }
   },
-  "include": [
-    "next-env.d.ts",
-    "**/*.ts",
-    "**/*.tsx",
-    ".next/types/**/*.ts",
-    ".source/**/*.ts"
-  ],
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
   "exclude": ["node_modules", "out"]
 }

From 22eb491e61871354cb4c2317208b6db7e6d9b69f Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 20:51:11 +0800
Subject: [PATCH 039/133] The Python SDK becomes a second official client:
 required view fields, gzip uploads, a pytest suite

---
 .gitignore                             |   5 +
 e2e/python/README.md                   |  27 ++
 e2e/python/conftest.py                 | 140 +++++++
 e2e/python/requirements.txt            |   5 +
 e2e/python/support.py                  |  63 ++++
 e2e/python/test_e2b_async.py           |  70 ++++
 e2e/python/test_e2b_sync.py            | 495 +++++++++++++++++++++++++
 packages/server/src/e2b/compat.test.ts |  68 ++++
 packages/server/src/e2b/control.ts     |   8 +
 packages/server/src/e2b/envd/files.ts  |  13 +-
 10 files changed, 893 insertions(+), 1 deletion(-)
 create mode 100644 e2e/python/README.md
 create mode 100644 e2e/python/conftest.py
 create mode 100644 e2e/python/requirements.txt
 create mode 100644 e2e/python/support.py
 create mode 100644 e2e/python/test_e2b_async.py
 create mode 100644 e2e/python/test_e2b_sync.py

diff --git a/.gitignore b/.gitignore
index 389e222..10f3c6f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -42,3 +42,8 @@ coverage/
 
 # Logs
 *.log
+
+# Python e2e suite artifacts
+e2e/python/__pycache__/
+e2e/python/.pytest_cache/
+e2e/python/.venv/
diff --git a/e2e/python/README.md b/e2e/python/README.md
new file mode 100644
index 0000000..ad1c2e0
--- /dev/null
+++ b/e2e/python/README.md
@@ -0,0 +1,27 @@
+# Python SDK e2e suite
+
+Black-box verification of the E2B compat layer under the **official `e2b`
+Python package** — the second official client after the JS SDK the TS suite
+uses. The sync SDK exercises wire paths the JS SDK never touches (the watcher
+polling trio, httpx transport behavior), which is why this suite exists.
+
+Not wired into `pnpm test` or CI: it needs a Python ≥3.10 interpreter, so it
+runs on demand.
+
+```sh
+pnpm build                                  # the daemon under test is dist/main.js
+python3 -m venv .venv                       # or: uv venv .venv
+.venv/bin/pip install -r requirements.txt   # or: uv pip install -r requirements.txt --python .venv/bin/python
+.venv/bin/python -m pytest -q               # fake executor by default
+```
+
+Against the real docker executor (Linux root, same ritual as the TS suite —
+stop the resident daemon first, clean residue after):
+
+```sh
+DORMICE_EXECUTOR=docker DORMICE_BASE_IMAGE=<image> .venv/bin/python -m pytest -q
+```
+
+The conftest boots the daemon exactly like production (`node dist/main.js`
+plus environment variables) on a random port with a throwaway ledger, and
+every test talks to it only through the SDK or plain HTTP.
diff --git a/e2e/python/conftest.py b/e2e/python/conftest.py
new file mode 100644
index 0000000..c185268
--- /dev/null
+++ b/e2e/python/conftest.py
@@ -0,0 +1,140 @@
+"""Boots the daemon the way production does — `node dist/main.js` plus
+environment variables — and hands tests a connection config. The Python twin
+of ../src/setup/daemon.ts: nothing here imports server internals; the suite
+talks to the daemon only over the wire.
+"""
+
+import os
+import secrets
+import shutil
+import socket
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+import httpx
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+MAIN = REPO_ROOT / "packages" / "server" / "dist" / "main.js"
+
+# A wildcard sandbox domain so get_host() and the port proxy are exercised —
+# no DNS needed, tests spoof the Host header locally.
+SANDBOX_DOMAIN = "sbx.dormice.test"
+
+
+def free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+class Daemon:
+    def __init__(self, endpoint: str, token: str):
+        self.endpoint = endpoint
+        self.token = token
+
+    @property
+    def conn(self) -> dict:
+        """The two-URL hookup: kwargs accepted by every SDK entry point.
+
+        The token is hex on purpose — the SDK validates the API key against
+        e2b_[0-9a-f]+ client-side before any request leaves the machine.
+        """
+        return {
+            "api_key": f"e2b_{self.token}",
+            "api_url": f"{self.endpoint}/e2b/api",
+            "sandbox_url": f"{self.endpoint}/e2b/envd",
+        }
+
+
+@pytest.fixture(scope="session")
+def daemon():
+    if not MAIN.exists():
+        raise RuntimeError(
+            f"daemon build not found at {MAIN} — run `pnpm build` first"
+        )
+
+    token = secrets.token_hex(32)
+    data_dir = Path(tempfile.mkdtemp(prefix="dormice-pye2e-"))
+    port = free_port()
+    endpoint = f"http://127.0.0.1:{port}"
+
+    # An explicit allowlist instead of inheriting the whole environment:
+    # stray DORMICE_* exports in the developer's shell must not silently
+    # reconfigure the daemon under test. DORMICE_DATA_DIR defaults into the
+    # throwaway directory so a docker run never drops exam disks into the
+    # resident daemon's /var/lib/dormice; an exported value still wins.
+    env = {"DORMICE_DATA_DIR": str(data_dir)}
+    for name in ("PATH", "DORMICE_EXECUTOR", "DORMICE_BASE_IMAGE", "DORMICE_DATA_DIR"):
+        if name in os.environ:
+            env[name] = os.environ[name]
+    env.update(
+        DORMICE_PORT=str(port),
+        DORMICE_DB_PATH=str(data_dir / "dormice.db"),
+        DORMICE_API_TOKEN=token,
+        # Sweep every second so lifecycle tests run on second-scale deadlines.
+        DORMICE_SCAN_INTERVAL_SECONDS="1",
+        DORMICE_SANDBOX_DOMAIN=SANDBOX_DOMAIN,
+    )
+
+    log_path = data_dir / "daemon.log"
+    with open(log_path, "wb") as log:
+        proc = subprocess.Popen(
+            ["node", str(MAIN)], env=env, stdout=log, stderr=subprocess.STDOUT
+        )
+
+    deadline = time.monotonic() + 10
+    while True:
+        if proc.poll() is not None:
+            raise RuntimeError(
+                f"daemon exited during startup:\n{log_path.read_text()}"
+            )
+        try:
+            if httpx.get(f"{endpoint}/healthz", timeout=1, trust_env=False).status_code == 200:
+                break
+        except httpx.HTTPError:
+            pass
+        if time.monotonic() > deadline:
+            proc.kill()
+            raise RuntimeError(
+                f"daemon did not come up within 10s:\n{log_path.read_text()}"
+            )
+        time.sleep(0.1)
+
+    yield Daemon(endpoint, token)
+
+    proc.terminate()
+    try:
+        proc.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+    # Best effort: in docker mode a leaked loop mount can pin a subtree; the
+    # real-machine cleanup checklist owns that case.
+    shutil.rmtree(data_dir, ignore_errors=True)
+
+
+@pytest.fixture(scope="session")
+def conn(daemon):
+    return daemon.conn
+
+
+@pytest.fixture
+def make_sandbox(conn):
+    """Sandboxes that are always killed at test end, pass or fail."""
+    from e2b import Sandbox
+
+    created = []
+
+    def _make(**kwargs):
+        sbx = Sandbox.create(**{**conn, **kwargs})
+        created.append(sbx)
+        return sbx
+
+    yield _make
+    for sbx in created:
+        try:
+            sbx.kill()
+        except Exception:
+            pass  # already dead — deadline tests kill their own
diff --git a/e2e/python/requirements.txt b/e2e/python/requirements.txt
new file mode 100644
index 0000000..fbb68d8
--- /dev/null
+++ b/e2e/python/requirements.txt
@@ -0,0 +1,5 @@
+# The official E2B Python SDK, pinned to the exact version this suite was
+# written against (same version number as the JS package the TS e2e uses —
+# the two SDKs release in lockstep). Bump deliberately, never implicitly.
+e2b==2.31.0
+pytest==8.4.1
diff --git a/e2e/python/support.py b/e2e/python/support.py
new file mode 100644
index 0000000..6c3c890
--- /dev/null
+++ b/e2e/python/support.py
@@ -0,0 +1,63 @@
+"""Shared helpers for the Python e2e suite."""
+
+import os
+import time
+
+import httpx
+import pytest
+
+EXECUTOR = os.environ.get("DORMICE_EXECUTOR", "fake")
+
+docker_only = pytest.mark.skipif(
+    EXECUTOR != "docker",
+    reason="needs the docker executor (real machine)",
+)
+
+fake_only = pytest.mark.skipif(
+    EXECUTOR == "docker",
+    reason="observes fake-executor internals (the in-memory echo upstream)",
+)
+
+
+def http_get(url: str, **kwargs) -> httpx.Response:
+    """A bare GET that never uses a proxy. trust_env=False matters: on macOS
+    Python's getproxies() reads the *system* proxy settings, so a developer
+    running a local proxy client would have these probes silently relayed —
+    and a spoofed-Host request answered by the proxy client's own 502
+    (measured 2026-07-10). The SDK is immune (it builds explicit transports);
+    only the suite's raw probes need this.
+    """
+    return httpx.get(url, trust_env=False, **kwargs)
+
+
+def http_post(url: str, **kwargs) -> httpx.Response:
+    """A bare POST that never uses a proxy; see http_get."""
+    return httpx.post(url, trust_env=False, **kwargs)
+
+
+def poll_until(check, deadline_s: float = 15.0, interval: float = 0.25, what: str = "condition"):
+    """Poll `check` until it returns a truthy value; the truthy value is
+    returned. Real wall-clock polling with a deadline instead of fixed naps —
+    a slow machine stretches schedules, and fixed naps are flaky-red bait.
+    """
+    deadline = time.monotonic() + deadline_s
+    while True:
+        value = check()
+        if value:
+            return value
+        if time.monotonic() > deadline:
+            raise AssertionError(f"timed out after {deadline_s}s waiting for {what}")
+        time.sleep(interval)
+
+
+def poll_until_raises(exc_type, fn, deadline_s: float = 15.0, interval: float = 0.25, what: str = "exception"):
+    """Poll until `fn()` raises `exc_type`; returns the exception."""
+    deadline = time.monotonic() + deadline_s
+    while True:
+        try:
+            fn()
+        except exc_type as e:  # noqa: PERF203 — polling loop
+            return e
+        if time.monotonic() > deadline:
+            raise AssertionError(f"timed out after {deadline_s}s waiting for {what}")
+        time.sleep(interval)
diff --git a/e2e/python/test_e2b_async.py b/e2e/python/test_e2b_async.py
new file mode 100644
index 0000000..f9ae2d1
--- /dev/null
+++ b/e2e/python/test_e2b_async.py
@@ -0,0 +1,70 @@
+"""A slim async pass: AsyncSandbox drives the same wire the JS SDK does,
+but through Python's async httpx transport — and its watch_dir consumes the
+**streaming** WatchDir (the sync SDK polls), so this is the one place the
+Python stream parser reads our filesystem event frames.
+
+Wrapped in asyncio.run inside plain test functions on purpose: no
+pytest-asyncio dependency for three tests.
+"""
+
+import asyncio
+
+from e2b import AsyncSandbox, CommandExitException
+
+from support import poll_until
+
+
+def test_async_create_run_kill(conn):
+    async def flow():
+        sbx = await AsyncSandbox.create(**conn)
+        try:
+            result = await sbx.commands.run("echo async hi")
+            assert result.exit_code == 0
+            assert result.stdout == "async hi\n"
+
+            try:
+                await sbx.commands.run("exit 7")
+                raise AssertionError("exit 7 must raise")
+            except CommandExitException as e:
+                assert e.exit_code == 7
+        finally:
+            assert await sbx.kill() is True
+
+    asyncio.run(flow())
+
+
+def test_async_files_roundtrip(conn):
+    async def flow():
+        sbx = await AsyncSandbox.create(**conn)
+        try:
+            await sbx.files.write("async.txt", "written async")
+            assert await sbx.files.read("async.txt") == "written async"
+        finally:
+            await sbx.kill()
+
+    asyncio.run(flow())
+
+
+def test_async_watch_is_streaming(conn):
+    async def flow():
+        sbx = await AsyncSandbox.create(**conn)
+        try:
+            await sbx.files.make_dir("streamwatch")
+            events = []
+            handle = await sbx.files.watch_dir(
+                "streamwatch", on_event=events.append
+            )
+            await sbx.files.write("streamwatch/ping.txt", "x")
+
+            deadline = asyncio.get_event_loop().time() + 15
+            while not any(e.name == "ping.txt" for e in events):
+                if asyncio.get_event_loop().time() > deadline:
+                    raise AssertionError(
+                        f"no streamed event for ping.txt; saw {events}"
+                    )
+                await asyncio.sleep(0.25)
+            await handle.stop()
+        finally:
+            await sbx.kill()
+
+    asyncio.run(flow())
diff --git a/e2e/python/test_e2b_sync.py b/e2e/python/test_e2b_sync.py
new file mode 100644
index 0000000..a388893
--- /dev/null
+++ b/e2e/python/test_e2b_sync.py
@@ -0,0 +1,495 @@
+"""The official Python SDK (sync) against a real daemon.
+
+The sync SDK is the reason this suite exists: unlike the JS SDK (and the
+async Python SDK), its filesystem watch runs on the **polling trio**
+(CreateWatcher / GetWatcherEvents / RemoveWatcher), and its transport is
+httpx — wire paths the TS e2e never exercises.
+"""
+
+import io
+import time
+from datetime import datetime
+
+import pytest
+from e2b import (
+    CommandExitException,
+    FileNotFoundException,
+    FilesystemEventType,
+    FileType,
+    InvalidArgumentException,
+    PtySize,
+    Sandbox,
+    SandboxException,
+    SandboxNotFoundException,
+    SandboxQuery,
+    SandboxState,
+)
+
+from conftest import SANDBOX_DOMAIN
+from support import (
+    docker_only,
+    fake_only,
+    http_get,
+    http_post,
+    poll_until,
+    poll_until_raises,
+)
+
+# ---------------------------------------------------------------- control
+
+
+def test_create_run_kill(make_sandbox):
+    sbx = make_sandbox()
+    assert sbx.sandbox_id
+
+    result = sbx.commands.run("echo hi")
+    assert result.exit_code == 0
+    assert result.stdout == "hi\n"
+
+    assert sbx.is_running() is True
+    assert sbx.kill() is True
+    # Idempotent second kill: the SDK reads the 404 as False.
+    assert sbx.kill() is False
+    assert sbx.is_running() is False
+
+
+def test_get_info_fields(conn, make_sandbox):
+    sbx = make_sandbox(metadata={"purpose": "info-fields"})
+    info = sbx.get_info()
+
+    assert info.sandbox_id == sbx.sandbox_id
+    assert info.state == SandboxState.RUNNING
+    assert info.metadata == {"purpose": "info-fields"}
+    assert info.envd_version == "0.6.1"
+    # The generated client hard-requires these — a missing field is a
+    # KeyError before any assertion runs, which is exactly the regression
+    # this test pins (clientID and diskSizeMB are load-bearing for Python
+    # even though the JS SDK never reads them).
+    assert isinstance(info.started_at, datetime)
+    assert isinstance(info.end_at, datetime)
+    assert info.cpu_count >= 1
+    assert info.memory_mb >= 256
+
+    # The classmethod flavor answers the same.
+    again = Sandbox.get_info(sbx.sandbox_id, **conn)
+    assert again.sandbox_id == info.sandbox_id
+
+    with pytest.raises(SandboxNotFoundException):
+        Sandbox.get_info("00000000-0000-0000-0000-000000000000", **conn)
+
+
+def test_list_filters(conn, make_sandbox):
+    sbx = make_sandbox(metadata={"suite": "py-list"})
+
+    paginator = Sandbox.list(
+        query=SandboxQuery(metadata={"suite": "py-list"}), **conn
+    )
+    found = paginator.next_items()
+    assert [s.sandbox_id for s in found] == [sbx.sandbox_id]
+    assert found[0].metadata == {"suite": "py-list"}
+
+    # State filter: a running sandbox must not show up in a paused-only list.
+    paused_only = Sandbox.list(
+        query=SandboxQuery(
+            metadata={"suite": "py-list"}, state=[SandboxState.PAUSED]
+        ),
+        **conn,
+    ).next_items()
+    assert paused_only == []
+
+
+def test_userkey_extension_is_idempotent(conn, make_sandbox):
+    first = make_sandbox(metadata={"userKey": "py-idem"})
+    second = Sandbox.create(metadata={"userKey": "py-idem"}, **conn)
+    # Same key, same sandbox — the Dormice extension speaks Python too.
+    assert second.sandbox_id == first.sandbox_id
+
+
+def test_timeout_kills_by_default(conn):
+    sbx = Sandbox.create(timeout=1, **conn)
+    # Protocol death is the deadline itself; the physical teardown follows
+    # on the scanner's beat. The SDK sees 404 either way.
+    poll_until_raises(
+        SandboxNotFoundException,
+        lambda: Sandbox.get_info(sbx.sandbox_id, **conn),
+        what="the expired sandbox to answer 404",
+    )
+    assert sbx.is_running() is False
+
+
+def test_timeout_pause_then_connect_resumes(conn):
+    sbx = Sandbox.create(
+        timeout=1, lifecycle={"on_timeout": "pause"}, **conn
+    )
+    try:
+        poll_until(
+            lambda: Sandbox.get_info(sbx.sandbox_id, **conn).state
+            == SandboxState.PAUSED,
+            what="the sandbox to auto-pause at its deadline",
+        )
+        resumed = Sandbox.connect(sbx.sandbox_id, **conn)
+        assert resumed.commands.run("echo back").stdout == "back\n"
+        assert (
+            Sandbox.get_info(sbx.sandbox_id, **conn).state
+            == SandboxState.RUNNING
+        )
+    finally:
+        Sandbox.kill(sbx.sandbox_id, **conn)
+
+
+def test_pause_resume_and_already_paused(conn, make_sandbox):
+    sbx = make_sandbox()
+    assert sbx.pause() is True
+    # Already paused: the SDK reads the 409 as False.
+    assert sbx.pause() is False
+    assert sbx.get_info().state == SandboxState.PAUSED
+
+    resumed = Sandbox.connect(sbx.sandbox_id, **conn)
+    assert resumed.commands.run("echo warm").stdout == "warm\n"
+
+
+def test_pause_without_memory_cold_boots(conn, make_sandbox):
+    sbx = make_sandbox()
+    sbx.files.write("kept.txt", "still here")
+    assert sbx.pause(keep_memory=False) is True
+    assert sbx.get_info().state == SandboxState.PAUSED
+
+    # Resuming a filesystem-only snapshot is a cold boot from disk: the
+    # file must have survived, in a brand-new shell.
+    resumed = Sandbox.connect(sbx.sandbox_id, **conn)
+    assert resumed.files.read("kept.txt") == "still here"
+
+
+def test_set_timeout_extends_life(conn):
+    sbx = Sandbox.create(timeout=2, **conn)
+    try:
+        sbx.set_timeout(3600)
+        time.sleep(3)
+        # Would have expired at 2s; the rewritten deadline keeps it alive.
+        assert Sandbox.get_info(sbx.sandbox_id, **conn).state == SandboxState.RUNNING
+    finally:
+        sbx.kill()
+
+
+def test_get_metrics_single_sample(make_sandbox):
+    sbx = make_sandbox()
+    metrics = sbx.get_metrics()
+    # No metrics history lives in the daemon: the answer is always one
+    # sample, taken now.
+    assert len(metrics) == 1
+    m = metrics[0]
+    assert m.cpu_count >= 1
+    assert m.mem_total > 0
+    assert m.disk_total > 0
+    assert isinstance(m.timestamp, datetime)
+
+
+# ---------------------------------------------------------------- commands
+
+
+def test_nonzero_exit_raises_command_exit(make_sandbox):
+    sbx = make_sandbox()
+    with pytest.raises(CommandExitException) as excinfo:
+        sbx.commands.run("exit 3")
+    assert excinfo.value.exit_code == 3
+
+
+def test_streaming_callbacks_in_order(make_sandbox):
+    sbx = make_sandbox()
+    chunks = []
+    result = sbx.commands.run(
+        "echo first; sleep 1; echo second", on_stdout=chunks.append
+    )
+    assert result.exit_code == 0
+    # The sleep forces two wire chunks: streaming, not one buffered blob.
+    assert len(chunks) >= 2
+    assert "".join(chunks) == "first\nsecond\n"
+
+
+def test_background_list_connect_kill(conn, make_sandbox):
+    sbx = make_sandbox()
+    handle = sbx.commands.run("sleep 30", background=True)
+    assert handle.pid > 0
+
+    listed = sbx.commands.list()
+    mine = [p for p in listed if p.pid == handle.pid]
+    assert len(mine) == 1
+    # config.cmd/args are always present — the SDK dereferences them
+    # unconditionally.
+    assert mine[0].cmd == "/bin/bash"
+    assert mine[0].args[-1] == "sleep 30"
+
+    # Disconnect only drops the stream; the process lives on.
+    handle.disconnect()
+    reconnected = sbx.commands.connect(handle.pid)
+    assert sbx.commands.kill(handle.pid) is True
+    with pytest.raises(CommandExitException) as excinfo:
+        reconnected.wait()
+    assert excinfo.value.exit_code == 137
+
+    # The pid is gone now: kill answers False.
+    assert sbx.commands.kill(handle.pid) is False
+
+
+def test_stdin_echo_and_close(make_sandbox):
+    sbx = make_sandbox()
+    handle = sbx.commands.run("cat", background=True, stdin=True)
+    handle.send_stdin("hello from python\n")
+    handle.close_stdin()
+    result = handle.wait()
+    assert result.exit_code == 0
+    assert result.stdout == "hello from python\n"
+
+
+def test_run_as_root(make_sandbox):
+    sbx = make_sandbox()
+    assert sbx.commands.run("whoami").stdout == "user\n"
+    assert sbx.commands.run("whoami", user="root").stdout == "root\n"
+
+
+def test_envs_and_cwd(conn, make_sandbox):
+    sbx = make_sandbox(envs={"SANDBOX_LEVEL": "floor"})
+    # Sandbox-level envs are the floor; command-level envs override.
+    assert sbx.commands.run("printenv SANDBOX_LEVEL").stdout == "floor\n"
+    assert (
+        sbx.commands.run(
+            "printenv SANDBOX_LEVEL", envs={"SANDBOX_LEVEL": "override"}
+        ).stdout
+        == "override\n"
+    )
+    assert sbx.commands.run("pwd", cwd="/tmp").stdout == "/tmp\n"
+
+
+def test_pty_roundtrip(make_sandbox):
+    sbx = make_sandbox()
+    handle = sbx.pty.create(PtySize(rows=24, cols=80))
+    sbx.pty.send_stdin(handle.pid, b"echo from-pty\n")
+
+    seen = bytearray()
+
+    def collect(data: bytes):
+        seen.extend(data)
+
+    # The pty stream only ends when the process dies, so reap it with a
+    # kill once the echo has had time to arrive.
+    import threading
+
+    waiter = threading.Thread(
+        target=lambda: _swallow_exit(handle, collect), daemon=True
+    )
+    waiter.start()
+    poll_until(lambda: b"from-pty" in seen, what="the pty echo")
+    sbx.pty.resize(handle.pid, PtySize(rows=30, cols=100))
+    assert sbx.pty.kill(handle.pid) is True
+    waiter.join(timeout=10)
+    assert not waiter.is_alive()
+
+
+def _swallow_exit(handle, on_pty):
+    try:
+        handle.wait(on_pty=on_pty)
+    except CommandExitException:
+        pass  # killed on purpose
+
+
+# ---------------------------------------------------------------- files
+
+
+def test_files_write_read_roundtrip(make_sandbox):
+    sbx = make_sandbox()
+    info = sbx.files.write("notes/hello.txt", "hello from python\n")
+    assert info.path == "/home/user/notes/hello.txt"
+    assert info.name == "hello.txt"
+    assert info.type == FileType.FILE
+
+    assert sbx.files.read("notes/hello.txt") == "hello from python\n"
+    raw = sbx.files.read("/home/user/notes/hello.txt", format="bytes")
+    assert bytes(raw) == b"hello from python\n"
+
+    with sbx.files.read("notes/hello.txt", format="stream") as stream:
+        assert b"".join(stream) == b"hello from python\n"
+
+
+def test_files_filelike_uses_octet_stream(make_sandbox):
+    sbx = make_sandbox()
+    payload = bytes(range(256)) * 64
+    # A file-like body routes the SDK onto the octet-stream upload path.
+    sbx.files.write("blob.bin", io.BytesIO(payload))
+    assert bytes(sbx.files.read("blob.bin", format="bytes")) == payload
+
+
+def test_files_gzip_upload(make_sandbox):
+    sbx = make_sandbox()
+    payload = b"compressible " * 1024
+    # gzip=True sends Content-Encoding: gzip over the octet-stream path;
+    # the daemon must store the decoded bytes, not the gzip framing.
+    sbx.files.write("zipped.txt", payload, gzip=True)
+    assert bytes(sbx.files.read("zipped.txt", format="bytes")) == payload
+
+
+def test_files_list_depth_exists_info(make_sandbox):
+    sbx = make_sandbox()
+    sbx.files.write("tree/top.txt", "t")
+    sbx.files.write("tree/sub/deep.txt", "d")
+
+    top = sbx.files.list("tree")
+    assert sorted(e.name for e in top) == ["sub", "top.txt"]
+    deep = sbx.files.list("tree", depth=2)
+    assert "deep.txt" in [e.name for e in deep]
+
+    assert sbx.files.exists("tree/top.txt") is True
+    assert sbx.files.exists("tree/absent.txt") is False
+
+    info = sbx.files.get_info("tree/sub")
+    assert info.type == FileType.DIR
+    assert info.path == "/home/user/tree/sub"
+
+    with pytest.raises(FileNotFoundException):
+        sbx.files.get_info("tree/absent.txt")
+    # Reading a directory is dishonest as file content: typed refusal.
+    with pytest.raises(InvalidArgumentException):
+        sbx.files.read("tree")
+
+
+def test_files_mkdir_rename_remove(make_sandbox):
+    sbx = make_sandbox()
+    assert sbx.files.make_dir("made/dir") is True
+    # Already there: the SDK reads already_exists as False.
+    assert sbx.files.make_dir("made/dir") is False
+
+    sbx.files.write("made/dir/a.txt", "x")
+    moved = sbx.files.rename("made/dir/a.txt", "made/dir/b.txt")
+    assert moved.path == "/home/user/made/dir/b.txt"
+    assert sbx.files.exists("made/dir/a.txt") is False
+
+    sbx.files.remove("made/dir/b.txt")
+    assert sbx.files.exists("made/dir/b.txt") is False
+
+
+# ---------------------------------------------------------------- watch
+# The polling trio is the whole reason this suite exists: the sync SDK is
+# its only official consumer, and the JS e2e can only poke it with raw fetch.
+
+
+def test_watch_polling_trio(make_sandbox):
+    sbx = make_sandbox()
+    sbx.files.make_dir("watched")
+    handle = sbx.files.watch_dir("watched")
+
+    sbx.files.write("watched/one.txt", "1")
+    events = poll_until(
+        lambda: handle.get_new_events(), what="events for the first write"
+    )
+    names = {(e.name, e.type) for e in events}
+    assert (
+        "one.txt",
+        FilesystemEventType.CREATE,
+    ) in names or ("one.txt", FilesystemEventType.WRITE) in names
+
+    # Draining resets the buffer: an immediate second poll is empty.
+    assert handle.get_new_events() == []
+
+    sbx.files.write("watched/two.txt", "2")
+    more = poll_until(
+        lambda: handle.get_new_events(), what="events for the second write"
+    )
+    assert any(e.name == "two.txt" for e in more)
+
+    handle.stop()
+    # The handle refuses further polls once stopped — client-side.
+    with pytest.raises(SandboxException):
+        handle.get_new_events()
+
+
+def test_watch_recursive_sees_subdirs(make_sandbox):
+    sbx = make_sandbox()
+    sbx.files.make_dir("deepwatch")
+    handle = sbx.files.watch_dir("deepwatch", recursive=True)
+    try:
+        sbx.files.write("deepwatch/sub/leaf.txt", "x")
+        events = poll_until(
+            lambda: handle.get_new_events(), what="recursive events"
+        )
+        # Event names are relative to the watched directory.
+        assert any(e.name.startswith("sub") for e in events)
+    finally:
+        handle.stop()
+
+
+def test_watch_missing_dir_is_typed(make_sandbox):
+    sbx = make_sandbox()
+    with pytest.raises(FileNotFoundException):
+        sbx.files.watch_dir("no-such-dir")
+
+
+# ---------------------------------------------------------------- signed URLs
+# Consumed by bare HTTP clients (no SDK headers): the sandbox identity is
+# recovered from the signature itself.
+
+
+def test_signed_download_and_upload(make_sandbox):
+    sbx = make_sandbox()
+    sbx.files.write("public.txt", "published")
+
+    url = sbx.download_url("public.txt")
+    got = http_get(url)
+    assert got.status_code == 200
+    assert got.content == b"published"
+
+    up = sbx.upload_url("incoming.txt")
+    posted = http_post(up, files={"file": ("incoming.txt", b"delivered")})
+    assert posted.status_code == 200
+    assert sbx.files.read("incoming.txt") == "delivered"
+
+
+def test_signed_url_expiration_and_tamper(make_sandbox):
+    sbx = make_sandbox()
+    sbx.files.write("secret.txt", "timed")
+
+    url = sbx.download_url("secret.txt", use_signature_expiration=1)
+    assert http_get(url).status_code == 200
+    time.sleep(2)
+    expired = http_get(url)
+    assert expired.status_code == 401
+    assert "expired" in expired.json()["message"]
+
+    tampered = sbx.download_url("secret.txt").replace(
+        "signature=v1_", "signature=v1_x"
+    )
+    assert http_get(tampered).status_code == 401
+
+
+# ---------------------------------------------------------------- get_host
+
+
+def test_get_host_shape(make_sandbox):
+    sbx = make_sandbox()
+    host = sbx.get_host(8000)
+    assert host == f"8000-{sbx.sandbox_id}.{SANDBOX_DOMAIN}"
+
+
+@fake_only
+def test_proxy_routes_by_host_header(daemon, make_sandbox):
+    # The fake executor answers proxied traffic with an in-memory echo
+    # upstream — the proxy chain is real, only the upstream is fake.
+    sbx = make_sandbox()
+    host = sbx.get_host(8000)
+    res = http_get(f"{daemon.endpoint}/probe", headers={"Host": host})
+    assert res.status_code == 200
+    body = res.json()
+    assert body["sandboxId"] == sbx.sandbox_id
+    assert body["path"] == "/probe"
+
+
+# ---------------------------------------------------------------- docker-only
+
+
+@docker_only
+def test_real_shell_and_root_power(make_sandbox):
+    sbx = make_sandbox()
+    # A real login shell in a real container: the disk's birthmark exists.
+    result = sbx.commands.run("ls /home/user")
+    assert result.exit_code == 0
+    # root's actual power, not just its name: /root is readable.
+    root_ls = sbx.commands.run("ls /root", user="root")
+    assert root_ls.exit_code == 0
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index e13593b..1d1cec4 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { gzipSync } from 'node:zlib';
 import { describe, expect, it } from 'vitest';
 import { buildApp } from '../app';
 import { loadConfig } from '../config';
@@ -232,6 +233,46 @@ describe('E2B control plane', () => {
     expect(endInMs).toBeLessThan(610_000);
   });
 
+  it('info views carry every field the Python SDK hard-requires', async () => {
+    // The JS SDK tolerates missing fields; the Python SDK's generated
+    // models KeyError on them before user code runs (measured 2026-07-10:
+    // absent clientID/diskSizeMB killed its whole suite at create). This
+    // pins the full required set in the CI-run suite.
+    const t = testApp();
+    const create = await control(t, 'POST', '/sandboxes', {
+      templateID: 'base',
+    });
+    expect(create.statusCode).toBe(201);
+    const session = create.json();
+    expect(session.clientID).toBe('node-test');
+    expect(session.sandboxID).toBeDefined();
+    expect(session.templateID).toBeDefined();
+    expect(session.envdVersion).toBeDefined();
+
+    const info = (
+      await control(t, 'GET', `/sandboxes/${session.sandboxID}`)
+    ).json();
+    for (const field of [
+      'clientID',
+      'cpuCount',
+      'diskSizeMB',
+      'endAt',
+      'envdVersion',
+      'memoryMB',
+      'sandboxID',
+      'startedAt',
+      'state',
+      'templateID',
+    ]) {
+      expect(info[field], `info.${field}`).toBeDefined();
+    }
+    expect(info.diskSizeMB).toBe(10 * 1024);
+
+    const listed = (await control(t, 'GET', '/v2/sandboxes')).json();
+    expect(listed[0].clientID).toBe('node-test');
+    expect(listed[0].diskSizeMB).toBe(10 * 1024);
+  });
+
   it('kill destroys for real: container, disk, row — and 404s after', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t);
@@ -575,6 +616,33 @@ describe('E2B envd surface', () => {
     ]);
   });
 
+  it('decodes a gzip content-encoding on octet-stream uploads', async () => {
+    // The SDK's write(gzip=true) compresses the whole body; storing the
+    // gzip framing would deliver a corrupted file (measured 2026-07-10
+    // under the Python SDK, the option's main user).
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const plain = 'compressible '.repeat(64);
+    const res = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/files?path=zipped.txt&username=user',
+      headers: {
+        ...envdHeaders(sandboxID),
+        'content-type': 'application/octet-stream',
+        'content-encoding': 'gzip',
+      },
+      payload: gzipSync(Buffer.from(plain)),
+    });
+    expect(res.statusCode).toBe(200);
+
+    const down = await t.app.inject({
+      method: 'GET',
+      url: '/e2b/envd/files?path=zipped.txt&username=user',
+      headers: envdHeaders(sandboxID),
+    });
+    expect(down.body).toBe(plain);
+  });
+
   it('speaks the filesystem service: Stat, ListDir, MakeDir, Move, Remove', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t);
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index d3e7e56..f97f5c3 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -141,6 +141,11 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   function sessionView(row: SandboxRow) {
     return {
       sandboxID: row.sandboxId,
+      // The node identity. The JS SDK never reads this field, but the
+      // Python SDK's generated models hard-require it on every sandbox
+      // response — its absence is a KeyError before user code runs
+      // (measured 2026-07-10: the whole Python suite died on create).
+      clientID: row.nodeId,
       ...templateFields(row),
       envdVersion: ENVD_VERSION,
       envdAccessToken: mintEnvdToken(config.DORMICE_API_TOKEN, row.sandboxId),
@@ -152,6 +157,8 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   function infoView(row: SandboxRow, state: 'running' | 'paused') {
     return {
       sandboxID: row.sandboxId,
+      // Required by the Python SDK's models, like clientID above.
+      clientID: row.nodeId,
       ...templateFields(row),
       metadata: row.metadata ? JSON.parse(row.metadata) : {},
       state,
@@ -163,6 +170,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString(),
       cpuCount: config.DORMICE_SANDBOX_CPUS,
       memoryMB: Math.round(config.DORMICE_SANDBOX_MEMORY_GB * 1024),
+      diskSizeMB: Math.round(config.DORMICE_SANDBOX_DISK_GB * 1024),
       envdVersion: ENVD_VERSION,
       ...domainField,
     };
diff --git a/packages/server/src/e2b/envd/files.ts b/packages/server/src/e2b/envd/files.ts
index 3f5c65e..3350404 100644
--- a/packages/server/src/e2b/envd/files.ts
+++ b/packages/server/src/e2b/envd/files.ts
@@ -1,3 +1,4 @@
+import { createGunzip } from 'node:zlib';
 import { resolveSandboxPath } from '@dormice/shared';
 import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
 import { touch } from '../../db/ledger';
@@ -170,7 +171,17 @@ export async function serveFileUpload(
       if (!query.path) {
         throw new E2bError(400, 'invalid_argument', 'missing path query');
       }
-      await writeOne(query.path, request.body as NodeJS.ReadableStream);
+      // The SDK's gzip option is a Content-Encoding on the whole body (it
+      // implies octet-stream). The sandbox must receive the decoded bytes —
+      // storing the gzip framing is delivering a corrupted file (measured
+      // 2026-07-10 under the Python SDK, whose write(gzip=True) uses this).
+      let content = request.body as NodeJS.ReadableStream;
+      if (request.headers['content-encoding'] === 'gzip') {
+        const gunzip = createGunzip();
+        content.pipe(gunzip);
+        content = gunzip;
+      }
+      await writeOne(query.path, content);
     }
     return await reply.code(200).send(written);
   } finally {

From c3a92d2455e647e18a74520343b31363ece7c245 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 21:39:22 +0800
Subject: [PATCH 040/133] The website falls in line: src layout, sections, and
 native shadcn parts

---
 biome.json                                    |   7 +-
 website/app/docs/layout.tsx                   |  22 -
 website/app/page.tsx                          |  85 --
 website/components.json                       |   2 +-
 website/components/docs-sidebar.tsx           |  39 -
 website/components/site-header.tsx            |  35 -
 .../{ => src}/app/docs/[[...slug]]/page.tsx   |  31 +-
 website/src/app/docs/layout.tsx               |  34 +
 website/{ => src}/app/global.css              |   0
 website/{ => src}/app/layout.tsx              |  12 +-
 website/src/app/not-found.tsx                 |  21 +
 website/src/app/page.tsx                      |  13 +
 website/{ => src}/app/shadcn.css              |   0
 website/src/components/SiteFooter.tsx         |  20 +
 website/src/components/SiteHeader.tsx         |  40 +
 .../components/ThemeProvider.tsx}             |   0
 .../components/ThemeToggle.tsx}               |   0
 .../components/docs/DocsMobileNav.tsx}        |   7 +-
 .../components/docs/DocsSearch.tsx}           |   5 +-
 website/src/components/docs/DocsSidebar.tsx   |  49 ++
 .../components/docs/DocsToc.tsx}              |   0
 website/src/components/sections/Features.tsx  |  63 ++
 website/src/components/sections/Hero.tsx      |  37 +
 website/src/components/ui/badge.tsx           |  52 ++
 website/{ => src}/components/ui/button.tsx    |   0
 website/src/components/ui/card.tsx            | 100 +++
 website/{ => src}/components/ui/command.tsx   |   0
 website/{ => src}/components/ui/dialog.tsx    |   0
 .../{ => src}/components/ui/input-group.tsx   |   0
 website/{ => src}/components/ui/input.tsx     |   0
 website/src/components/ui/kbd.tsx             |  26 +
 website/src/components/ui/separator.tsx       |  25 +
 website/{ => src}/components/ui/sheet.tsx     |   0
 website/src/components/ui/sidebar.tsx         | 727 ++++++++++++++++++
 website/src/components/ui/skeleton.tsx        |  13 +
 website/{ => src}/components/ui/textarea.tsx  |   0
 website/src/components/ui/tooltip.tsx         |  66 ++
 website/src/hooks/use-mobile.ts               |  19 +
 website/{ => src}/lib/docs.ts                 |  16 +-
 website/src/lib/site.ts                       |  12 +
 website/{ => src}/lib/utils.ts                |   0
 website/{ => src}/mdx-components.tsx          |   0
 website/{ => src}/mdx.d.ts                    |   0
 website/tsconfig.json                         |   2 +-
 44 files changed, 1364 insertions(+), 216 deletions(-)
 delete mode 100644 website/app/docs/layout.tsx
 delete mode 100644 website/app/page.tsx
 delete mode 100644 website/components/docs-sidebar.tsx
 delete mode 100644 website/components/site-header.tsx
 rename website/{ => src}/app/docs/[[...slug]]/page.tsx (65%)
 create mode 100644 website/src/app/docs/layout.tsx
 rename website/{ => src}/app/global.css (100%)
 rename website/{ => src}/app/layout.tsx (68%)
 create mode 100644 website/src/app/not-found.tsx
 create mode 100644 website/src/app/page.tsx
 rename website/{ => src}/app/shadcn.css (100%)
 create mode 100644 website/src/components/SiteFooter.tsx
 create mode 100644 website/src/components/SiteHeader.tsx
 rename website/{components/theme-provider.tsx => src/components/ThemeProvider.tsx} (100%)
 rename website/{components/theme-toggle.tsx => src/components/ThemeToggle.tsx} (100%)
 rename website/{components/docs-mobile-nav.tsx => src/components/docs/DocsMobileNav.tsx} (82%)
 rename website/{components/docs-search.tsx => src/components/docs/DocsSearch.tsx} (94%)
 create mode 100644 website/src/components/docs/DocsSidebar.tsx
 rename website/{components/docs-toc.tsx => src/components/docs/DocsToc.tsx} (100%)
 create mode 100644 website/src/components/sections/Features.tsx
 create mode 100644 website/src/components/sections/Hero.tsx
 create mode 100644 website/src/components/ui/badge.tsx
 rename website/{ => src}/components/ui/button.tsx (100%)
 create mode 100644 website/src/components/ui/card.tsx
 rename website/{ => src}/components/ui/command.tsx (100%)
 rename website/{ => src}/components/ui/dialog.tsx (100%)
 rename website/{ => src}/components/ui/input-group.tsx (100%)
 rename website/{ => src}/components/ui/input.tsx (100%)
 create mode 100644 website/src/components/ui/kbd.tsx
 create mode 100644 website/src/components/ui/separator.tsx
 rename website/{ => src}/components/ui/sheet.tsx (100%)
 create mode 100644 website/src/components/ui/sidebar.tsx
 create mode 100644 website/src/components/ui/skeleton.tsx
 rename website/{ => src}/components/ui/textarea.tsx (100%)
 create mode 100644 website/src/components/ui/tooltip.tsx
 create mode 100644 website/src/hooks/use-mobile.ts
 rename website/{ => src}/lib/docs.ts (75%)
 create mode 100644 website/src/lib/site.ts
 rename website/{ => src}/lib/utils.ts (100%)
 rename website/{ => src}/mdx-components.tsx (100%)
 rename website/{ => src}/mdx.d.ts (100%)

diff --git a/biome.json b/biome.json
index 7a2ff3f..96718dd 100644
--- a/biome.json
+++ b/biome.json
@@ -9,9 +9,10 @@
       "!packages/console/src/lib/utils.ts",
       "!packages/console/src/shadcn.css",
       "!packages/console/src/routeTree.gen.ts",
-      "!website/components/ui",
-      "!website/lib/utils.ts",
-      "!website/app/shadcn.css"
+      "!website/src/components/ui",
+      "!website/src/hooks/use-mobile.ts",
+      "!website/src/lib/utils.ts",
+      "!website/src/app/shadcn.css"
     ]
   },
   "vcs": {
diff --git a/website/app/docs/layout.tsx b/website/app/docs/layout.tsx
deleted file mode 100644
index 475d9aa..0000000
--- a/website/app/docs/layout.tsx
+++ /dev/null
@@ -1,22 +0,0 @@
-import type { ReactNode } from 'react';
-import { DocsMobileNav } from '@/components/docs-mobile-nav';
-import { DocsSidebar } from '@/components/docs-sidebar';
-import { docs } from '@/lib/docs';
-
-export default function Layout({ children }: { children: ReactNode }) {
-  const items = docs.map(({ href, title }) => ({ href, title }));
-
-  return (
-    <div className="mx-auto flex w-full max-w-6xl flex-1 items-start px-4">
-      <aside className="sticky top-14 hidden max-h-[calc(100vh-3.5rem)] w-52 shrink-0 overflow-y-auto border-r py-8 pr-4 md:block">
-        <DocsSidebar items={items} />
-      </aside>
-      <div className="min-w-0 flex-1 md:pl-8">
-        <div className="border-b py-3 md:hidden">
-          <DocsMobileNav items={items} />
-        </div>
-        {children}
-      </div>
-    </div>
-  );
-}
diff --git a/website/app/page.tsx b/website/app/page.tsx
deleted file mode 100644
index fcdd04e..0000000
--- a/website/app/page.tsx
+++ /dev/null
@@ -1,85 +0,0 @@
-import Link from 'next/link';
-import { GITHUB_URL } from '@/components/site-header';
-import { Button } from '@/components/ui/button';
-
-const features = [
-  {
-    title: 'Sandboxes are permanent',
-    body: (
-      <>
-        <code>acquireSandbox(userKey)</code> is the entire mental model — the
-        same key always comes back to the same sandbox: created, woken or
-        restarted as needed.
-      </>
-    ),
-  },
-  {
-    title: 'Idle is free',
-    body: (
-      <>
-        Sandboxes cool down on their own, one rung at a time. Measured on real
-        hardware: 1 GiB of sandbox memory freezes down to ~5 MiB, and waking
-        takes ~50 ms — with every process still running.
-      </>
-    ),
-  },
-  {
-    title: 'Deploys like a single binary',
-    body: (
-      <>
-        One daemon, one SQLite ledger, one port. No Kubernetes, no external
-        database — one install command on a bare Linux host.
-      </>
-    ),
-  },
-  {
-    title: 'E2B compatible',
-    body: (
-      <>
-        The official <code>e2b</code> SDK runs against Dormice by changing two
-        URLs — commands, files, PTY, signed URLs, watch, metrics.
-      </>
-    ),
-  },
-];
-
-export default function HomePage() {
-  return (
-    <main className="flex flex-1 flex-col items-center px-4 py-16 text-center sm:py-24">
-      <h1 className="max-w-3xl text-4xl font-semibold tracking-tight text-balance sm:text-5xl">
-        The SQLite of agent sandboxes
-      </h1>
-      <p className="mt-6 max-w-2xl text-lg text-muted-foreground">
-        A self-hosted sandbox platform for AI agents. One machine, sandboxes
-        that live forever, idle costs nothing.
-      </p>
-      <div className="mt-8 flex items-center gap-3">
-        <Button size="lg" render={<Link href="/docs" />}>
-          Get started
-        </Button>
-        <Button size="lg" variant="outline" render={<a href={GITHUB_URL} />}>
-          GitHub
-        </Button>
-      </div>
-      <p className="mt-4 text-xs text-muted-foreground">
-        Early development: works end to end against real infrastructure, not
-        production-ready yet.
-      </p>
-      <pre className="mt-10 max-w-full overflow-x-auto rounded-lg border bg-card px-5 py-4 text-left text-sm">
-        <code>
-          curl -fsSL
-          https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh
-          | bash
-        </code>
-      </pre>
-      <div className="mt-16 grid w-full max-w-4xl gap-4 text-left sm:grid-cols-2">
-        {features.map((feature) => (
-          <div key={feature.title} className="rounded-lg border bg-card p-6">
-            <h2 className="font-medium">{feature.title}</h2>
-            <p className="mt-2 text-sm text-muted-foreground">{feature.body}</p>
-          </div>
-        ))}
-      </div>
-    </main>
-  );
-}
diff --git a/website/components.json b/website/components.json
index 6f81a57..e8a66b4 100644
--- a/website/components.json
+++ b/website/components.json
@@ -5,7 +5,7 @@
   "tsx": true,
   "tailwind": {
     "config": "",
-    "css": "app/shadcn.css",
+    "css": "src/app/shadcn.css",
     "baseColor": "neutral",
     "cssVariables": true,
     "prefix": ""
diff --git a/website/components/docs-sidebar.tsx b/website/components/docs-sidebar.tsx
deleted file mode 100644
index 3c967b4..0000000
--- a/website/components/docs-sidebar.tsx
+++ /dev/null
@@ -1,39 +0,0 @@
-'use client';
-
-import Link from 'next/link';
-import { usePathname } from 'next/navigation';
-import { cn } from '@/lib/utils';
-
-export interface DocsNavItem {
-  href: string;
-  title: string;
-}
-
-export function DocsSidebar({
-  items,
-  onNavigate,
-}: {
-  items: DocsNavItem[];
-  onNavigate?: () => void;
-}) {
-  const pathname = usePathname();
-
-  return (
-    <nav className="flex flex-col gap-0.5">
-      {items.map((item) => (
-        <Link
-          key={item.href}
-          href={item.href}
-          onClick={onNavigate}
-          className={cn(
-            'rounded-md px-2.5 py-1.5 text-sm text-muted-foreground transition-colors hover:text-foreground',
-            pathname === item.href &&
-              'bg-accent font-medium text-accent-foreground',
-          )}
-        >
-          {item.title}
-        </Link>
-      ))}
-    </nav>
-  );
-}
diff --git a/website/components/site-header.tsx b/website/components/site-header.tsx
deleted file mode 100644
index 4c83f08..0000000
--- a/website/components/site-header.tsx
+++ /dev/null
@@ -1,35 +0,0 @@
-import Link from 'next/link';
-import { DocsSearch, type SearchItem } from '@/components/docs-search';
-import { ThemeToggle } from '@/components/theme-toggle';
-
-export const GITHUB_URL = 'https://github.com/BitMiracle-AI/Dormice';
-
-export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
-  return (
-    <header className="sticky top-0 z-40 border-b bg-background/80 backdrop-blur">
-      <div className="mx-auto flex h-14 w-full max-w-6xl items-center gap-6 px-4">
-        <Link href="/" className="font-semibold">
-          Dormice
-        </Link>
-        <nav className="flex items-center gap-4 text-sm text-muted-foreground">
-          <Link
-            href="/docs"
-            className="transition-colors hover:text-foreground"
-          >
-            Docs
-          </Link>
-          <a
-            href={GITHUB_URL}
-            className="transition-colors hover:text-foreground"
-          >
-            GitHub
-          </a>
-        </nav>
-        <div className="ml-auto flex items-center gap-2">
-          <DocsSearch items={searchItems} />
-          <ThemeToggle />
-        </div>
-      </div>
-    </header>
-  );
-}
diff --git a/website/app/docs/[[...slug]]/page.tsx b/website/src/app/docs/[[...slug]]/page.tsx
similarity index 65%
rename from website/app/docs/[[...slug]]/page.tsx
rename to website/src/app/docs/[[...slug]]/page.tsx
index 2604017..928267b 100644
--- a/website/app/docs/[[...slug]]/page.tsx
+++ b/website/src/app/docs/[[...slug]]/page.tsx
@@ -1,7 +1,10 @@
+import { ArrowLeft01Icon, ArrowRight01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
 import type { Metadata } from 'next';
 import Link from 'next/link';
 import { notFound } from 'next/navigation';
-import { DocsToc } from '@/components/docs-toc';
+import { DocsToc } from '@/components/docs/DocsToc';
+import { Button } from '@/components/ui/button';
 import { docs, getDoc } from '@/lib/docs';
 
 // Static export: every page below /docs is enumerated here, nothing is
@@ -29,24 +32,28 @@ export default async function Page(props: PageProps) {
           <p className="lead">{entry.description}</p>
           <Content />
         </article>
-        <nav className="mt-10 flex justify-between gap-4 border-t pt-6 text-sm">
+        <nav className="mt-10 flex items-center justify-between gap-4 border-t pt-6">
           {prev ? (
-            <Link
-              href={prev.href}
-              className="text-muted-foreground transition-colors hover:text-foreground"
+            <Button
+              variant="ghost"
+              className="text-muted-foreground"
+              render={<Link href={prev.href} />}
             >
-              ← {prev.title}
-            </Link>
+              <HugeiconsIcon icon={ArrowLeft01Icon} data-icon="inline-start" />
+              {prev.title}
+            </Button>
           ) : (
             <span />
           )}
           {next ? (
-            <Link
-              href={next.href}
-              className="text-right text-muted-foreground transition-colors hover:text-foreground"
+            <Button
+              variant="ghost"
+              className="text-muted-foreground"
+              render={<Link href={next.href} />}
             >
-              {next.title} →
-            </Link>
+              {next.title}
+              <HugeiconsIcon icon={ArrowRight01Icon} data-icon="inline-end" />
+            </Button>
           ) : (
             <span />
           )}
diff --git a/website/src/app/docs/layout.tsx b/website/src/app/docs/layout.tsx
new file mode 100644
index 0000000..db939fe
--- /dev/null
+++ b/website/src/app/docs/layout.tsx
@@ -0,0 +1,34 @@
+import type { ReactNode } from 'react';
+import { DocsMobileNav } from '@/components/docs/DocsMobileNav';
+import { DocsSidebar } from '@/components/docs/DocsSidebar';
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarProvider,
+} from '@/components/ui/sidebar';
+import { docs } from '@/lib/docs';
+
+export default function Layout({ children }: { children: ReactNode }) {
+  const items = docs.map(({ href, title }) => ({ href, title }));
+
+  return (
+    // The provider defaults to a full-viewport app shell (min-h-svh); this
+    // page keeps the site header outside it, so those defaults are undone.
+    <SidebarProvider className="mx-auto min-h-0 w-full max-w-6xl flex-1 items-start px-4">
+      <Sidebar
+        collapsible="none"
+        className="sticky top-14 hidden h-[calc(100svh-3.5rem)] w-52 shrink-0 self-start border-r bg-transparent md:flex"
+      >
+        <SidebarContent className="py-4">
+          <DocsSidebar items={items} />
+        </SidebarContent>
+      </Sidebar>
+      <div className="min-w-0 flex-1 md:pl-8">
+        <div className="border-b py-3 md:hidden">
+          <DocsMobileNav items={items} />
+        </div>
+        {children}
+      </div>
+    </SidebarProvider>
+  );
+}
diff --git a/website/app/global.css b/website/src/app/global.css
similarity index 100%
rename from website/app/global.css
rename to website/src/app/global.css
diff --git a/website/app/layout.tsx b/website/src/app/layout.tsx
similarity index 68%
rename from website/app/layout.tsx
rename to website/src/app/layout.tsx
index faab78c..8ddf795 100644
--- a/website/app/layout.tsx
+++ b/website/src/app/layout.tsx
@@ -1,17 +1,18 @@
 import type { Metadata } from 'next';
 import type { ReactNode } from 'react';
-import { SiteHeader } from '@/components/site-header';
-import { ThemeProvider } from '@/components/theme-provider';
+import { SiteFooter } from '@/components/SiteFooter';
+import { SiteHeader } from '@/components/SiteHeader';
+import { ThemeProvider } from '@/components/ThemeProvider';
 import { docs } from '@/lib/docs';
+import { SITE_DESCRIPTION, SITE_TITLE } from '@/lib/site';
 import './global.css';
 
 export const metadata: Metadata = {
   title: {
-    default: 'Dormice — the SQLite of agent sandboxes',
+    default: SITE_TITLE,
     template: '%s | Dormice',
   },
-  description:
-    'A self-hosted sandbox platform for AI agents. One machine, sandboxes that live forever, idle costs nothing.',
+  description: SITE_DESCRIPTION,
 };
 
 export default function Layout({ children }: { children: ReactNode }) {
@@ -27,6 +28,7 @@ export default function Layout({ children }: { children: ReactNode }) {
         <ThemeProvider>
           <SiteHeader searchItems={searchItems} />
           {children}
+          <SiteFooter />
         </ThemeProvider>
       </body>
     </html>
diff --git a/website/src/app/not-found.tsx b/website/src/app/not-found.tsx
new file mode 100644
index 0000000..6033e08
--- /dev/null
+++ b/website/src/app/not-found.tsx
@@ -0,0 +1,21 @@
+import Link from 'next/link';
+import { Button } from '@/components/ui/button';
+
+// Static export writes this as out/404.html, which GitHub Pages and most
+// static hosts serve for unknown paths automatically.
+export default function NotFound() {
+  return (
+    <main className="flex flex-1 flex-col items-center justify-center gap-4 px-4 py-24 text-center">
+      <h1 className="text-4xl font-semibold tracking-tight">Page not found</h1>
+      <p className="text-muted-foreground">
+        The page you are looking for does not exist.
+      </p>
+      <div className="flex items-center gap-3">
+        <Button render={<Link href="/" />}>Home</Button>
+        <Button variant="outline" render={<Link href="/docs" />}>
+          Docs
+        </Button>
+      </div>
+    </main>
+  );
+}
diff --git a/website/src/app/page.tsx b/website/src/app/page.tsx
new file mode 100644
index 0000000..431a767
--- /dev/null
+++ b/website/src/app/page.tsx
@@ -0,0 +1,13 @@
+import { Features } from '@/components/sections/Features';
+import { Hero } from '@/components/sections/Hero';
+
+// Landing narrative: hero (pitch + install command) → feature cards.
+// Site chrome (header, footer) lives in the root layout.
+export default function HomePage() {
+  return (
+    <main className="flex-1">
+      <Hero />
+      <Features />
+    </main>
+  );
+}
diff --git a/website/app/shadcn.css b/website/src/app/shadcn.css
similarity index 100%
rename from website/app/shadcn.css
rename to website/src/app/shadcn.css
diff --git a/website/src/components/SiteFooter.tsx b/website/src/components/SiteFooter.tsx
new file mode 100644
index 0000000..cdb3556
--- /dev/null
+++ b/website/src/components/SiteFooter.tsx
@@ -0,0 +1,20 @@
+import { GITHUB_URL } from '@/lib/site';
+
+export function SiteFooter() {
+  return (
+    <footer className="border-t py-6">
+      <div className="mx-auto flex w-full max-w-6xl flex-col items-center justify-between gap-2 px-4 text-xs text-muted-foreground sm:flex-row">
+        <p>
+          Apache-2.0. E2B is a trademark of its owner; Dormice is not affiliated
+          with or endorsed by E2B.
+        </p>
+        <a
+          href={GITHUB_URL}
+          className="transition-colors hover:text-foreground"
+        >
+          GitHub
+        </a>
+      </div>
+    </footer>
+  );
+}
diff --git a/website/src/components/SiteHeader.tsx b/website/src/components/SiteHeader.tsx
new file mode 100644
index 0000000..8c1d652
--- /dev/null
+++ b/website/src/components/SiteHeader.tsx
@@ -0,0 +1,40 @@
+import { GithubIcon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import Link from 'next/link';
+import { DocsSearch, type SearchItem } from '@/components/docs/DocsSearch';
+import { ThemeToggle } from '@/components/ThemeToggle';
+import { Button } from '@/components/ui/button';
+import { GITHUB_URL } from '@/lib/site';
+
+export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
+  return (
+    <header className="sticky top-0 z-40 border-b bg-background/80 backdrop-blur">
+      <div className="mx-auto flex h-14 w-full max-w-6xl items-center px-4">
+        <Link href="/" className="mr-4 font-semibold">
+          Dormice
+        </Link>
+        <nav className="flex items-center">
+          <Button
+            variant="ghost"
+            size="sm"
+            className="text-muted-foreground"
+            render={<Link href="/docs" />}
+          >
+            Docs
+          </Button>
+        </nav>
+        <div className="ml-auto flex items-center gap-1">
+          <DocsSearch items={searchItems} />
+          <Button
+            variant="ghost"
+            size="icon"
+            render={<a href={GITHUB_URL} aria-label="GitHub" />}
+          >
+            <HugeiconsIcon icon={GithubIcon} />
+          </Button>
+          <ThemeToggle />
+        </div>
+      </div>
+    </header>
+  );
+}
diff --git a/website/components/theme-provider.tsx b/website/src/components/ThemeProvider.tsx
similarity index 100%
rename from website/components/theme-provider.tsx
rename to website/src/components/ThemeProvider.tsx
diff --git a/website/components/theme-toggle.tsx b/website/src/components/ThemeToggle.tsx
similarity index 100%
rename from website/components/theme-toggle.tsx
rename to website/src/components/ThemeToggle.tsx
diff --git a/website/components/docs-mobile-nav.tsx b/website/src/components/docs/DocsMobileNav.tsx
similarity index 82%
rename from website/components/docs-mobile-nav.tsx
rename to website/src/components/docs/DocsMobileNav.tsx
index 4d42c4f..1921cf6 100644
--- a/website/components/docs-mobile-nav.tsx
+++ b/website/src/components/docs/DocsMobileNav.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { useState } from 'react';
-import { type DocsNavItem, DocsSidebar } from '@/components/docs-sidebar';
+import { type DocsNavItem, DocsSidebar } from '@/components/docs/DocsSidebar';
 import { Button } from '@/components/ui/button';
 import {
   Sheet,
@@ -20,10 +20,11 @@ export function DocsMobileNav({ items }: { items: DocsNavItem[] }) {
         Menu
       </SheetTrigger>
       <SheetContent side="left">
-        <SheetHeader>
+        {/* The visible label comes from the menu's own group label. */}
+        <SheetHeader className="sr-only">
           <SheetTitle>Documentation</SheetTitle>
         </SheetHeader>
-        <div className="px-4">
+        <div className="px-2">
           <DocsSidebar items={items} onNavigate={() => setOpen(false)} />
         </div>
       </SheetContent>
diff --git a/website/components/docs-search.tsx b/website/src/components/docs/DocsSearch.tsx
similarity index 94%
rename from website/components/docs-search.tsx
rename to website/src/components/docs/DocsSearch.tsx
index eddff3a..e432df0 100644
--- a/website/components/docs-search.tsx
+++ b/website/src/components/docs/DocsSearch.tsx
@@ -11,6 +11,7 @@ import {
   CommandItem,
   CommandList,
 } from '@/components/ui/command';
+import { Kbd } from '@/components/ui/kbd';
 
 export interface SearchItem {
   href: string;
@@ -45,9 +46,7 @@ export function DocsSearch({ items }: { items: SearchItem[] }) {
         onClick={() => setOpen(true)}
       >
         Search docs…
-        <kbd className="rounded border bg-muted px-1 font-sans text-[0.7rem] text-muted-foreground">
-          ⌘K
-        </kbd>
+        <Kbd>⌘K</Kbd>
       </Button>
       <CommandDialog
         open={open}
diff --git a/website/src/components/docs/DocsSidebar.tsx b/website/src/components/docs/DocsSidebar.tsx
new file mode 100644
index 0000000..8edd3dd
--- /dev/null
+++ b/website/src/components/docs/DocsSidebar.tsx
@@ -0,0 +1,49 @@
+'use client';
+
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+import {
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+} from '@/components/ui/sidebar';
+
+export interface DocsNavItem {
+  href: string;
+  title: string;
+}
+
+// Menu content only — it must live inside a <SidebarProvider> (the docs
+// layout provides one; the mobile Sheet sits inside the same provider).
+export function DocsSidebar({
+  items,
+  onNavigate,
+}: {
+  items: DocsNavItem[];
+  onNavigate?: () => void;
+}) {
+  const pathname = usePathname();
+
+  return (
+    <SidebarGroup>
+      <SidebarGroupLabel>Documentation</SidebarGroupLabel>
+      <SidebarGroupContent>
+        <SidebarMenu>
+          {items.map((item) => (
+            <SidebarMenuItem key={item.href}>
+              <SidebarMenuButton
+                isActive={pathname === item.href}
+                render={<Link href={item.href} onClick={onNavigate} />}
+              >
+                {item.title}
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      </SidebarGroupContent>
+    </SidebarGroup>
+  );
+}
diff --git a/website/components/docs-toc.tsx b/website/src/components/docs/DocsToc.tsx
similarity index 100%
rename from website/components/docs-toc.tsx
rename to website/src/components/docs/DocsToc.tsx
diff --git a/website/src/components/sections/Features.tsx b/website/src/components/sections/Features.tsx
new file mode 100644
index 0000000..e854e42
--- /dev/null
+++ b/website/src/components/sections/Features.tsx
@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react';
+import {
+  Card,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+
+const features: { title: string; body: ReactNode }[] = [
+  {
+    title: 'Sandboxes are permanent',
+    body: (
+      <>
+        <code>acquireSandbox(userKey)</code> is the entire mental model — the
+        same key always comes back to the same sandbox: created, woken or
+        restarted as needed.
+      </>
+    ),
+  },
+  {
+    title: 'Idle is free',
+    body: (
+      <>
+        Sandboxes cool down on their own, one rung at a time. Measured on real
+        hardware: 1 GiB of sandbox memory freezes down to ~5 MiB, and waking
+        takes ~50 ms — with every process still running.
+      </>
+    ),
+  },
+  {
+    title: 'Deploys like a single binary',
+    body: (
+      <>
+        One daemon, one SQLite ledger, one port. No Kubernetes, no external
+        database — one install command on a bare Linux host.
+      </>
+    ),
+  },
+  {
+    title: 'E2B compatible',
+    body: (
+      <>
+        The official <code>e2b</code> SDK runs against Dormice by changing two
+        URLs — commands, files, PTY, signed URLs, watch, metrics.
+      </>
+    ),
+  },
+];
+
+export function Features() {
+  return (
+    <section className="mx-auto grid w-full max-w-4xl gap-4 px-4 pb-16 text-left sm:grid-cols-2 sm:pb-24">
+      {features.map((feature) => (
+        <Card key={feature.title}>
+          <CardHeader>
+            <CardTitle>{feature.title}</CardTitle>
+            <CardDescription>{feature.body}</CardDescription>
+          </CardHeader>
+        </Card>
+      ))}
+    </section>
+  );
+}
diff --git a/website/src/components/sections/Hero.tsx b/website/src/components/sections/Hero.tsx
new file mode 100644
index 0000000..5b9bcb5
--- /dev/null
+++ b/website/src/components/sections/Hero.tsx
@@ -0,0 +1,37 @@
+import Link from 'next/link';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { GITHUB_URL } from '@/lib/site';
+
+export function Hero() {
+  return (
+    <section className="flex flex-col items-center px-4 py-16 text-center sm:py-24">
+      <Badge variant="secondary">Early development</Badge>
+      <h1 className="mt-4 max-w-3xl text-4xl font-semibold tracking-tight text-balance sm:text-5xl">
+        The SQLite of agent sandboxes
+      </h1>
+      <p className="mt-6 max-w-2xl text-lg text-muted-foreground">
+        A self-hosted sandbox platform for AI agents. One machine, sandboxes
+        that live forever, idle costs nothing.
+      </p>
+      <div className="mt-8 flex items-center gap-3">
+        <Button size="lg" render={<Link href="/docs" />}>
+          Get started
+        </Button>
+        <Button size="lg" variant="outline" render={<a href={GITHUB_URL} />}>
+          GitHub
+        </Button>
+      </div>
+      <p className="mt-4 text-xs text-muted-foreground">
+        Works end to end against real infrastructure, not production-ready yet.
+      </p>
+      <pre className="mt-10 max-w-full overflow-x-auto rounded-lg border bg-card px-5 py-4 text-left text-sm">
+        <code>
+          curl -fsSL
+          https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh
+          | bash
+        </code>
+      </pre>
+    </section>
+  );
+}
diff --git a/website/src/components/ui/badge.tsx b/website/src/components/ui/badge.tsx
new file mode 100644
index 0000000..6d49b91
--- /dev/null
+++ b/website/src/components/ui/badge.tsx
@@ -0,0 +1,52 @@
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const badgeVariants = cva(
+  "group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-2xl border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-all focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3!",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground [a]:hover:bg-primary/80",
+        secondary:
+          "bg-secondary text-secondary-foreground [a]:hover:bg-secondary/80",
+        destructive:
+          "bg-destructive/10 text-destructive focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:focus-visible:ring-destructive/40 [a]:hover:bg-destructive/20",
+        outline:
+          "border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground",
+        ghost:
+          "hover:bg-muted hover:text-muted-foreground dark:hover:bg-muted/50",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function Badge({
+  className,
+  variant = "default",
+  render,
+  ...props
+}: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>) {
+  return useRender({
+    defaultTagName: "span",
+    props: mergeProps<"span">(
+      {
+        className: cn(badgeVariants({ variant }), className),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "badge",
+      variant,
+    },
+  })
+}
+
+export { Badge, badgeVariants }
diff --git a/website/components/ui/button.tsx b/website/src/components/ui/button.tsx
similarity index 100%
rename from website/components/ui/button.tsx
rename to website/src/components/ui/button.tsx
diff --git a/website/src/components/ui/card.tsx b/website/src/components/ui/card.tsx
new file mode 100644
index 0000000..1137b40
--- /dev/null
+++ b/website/src/components/ui/card.tsx
@@ -0,0 +1,100 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Card({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<"div"> & { size?: "default" | "sm" }) {
+  return (
+    <div
+      data-slot="card"
+      data-size={size}
+      className={cn(
+        "group/card flex flex-col gap-(--card-spacing) overflow-hidden rounded-[min(var(--radius-4xl),24px)] bg-card py-(--card-spacing) text-sm text-card-foreground shadow-sm ring-1 ring-foreground/5 [--card-spacing:--spacing(5)] has-[>img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(4)] dark:ring-foreground/10 *:[img:first-child]:rounded-t-[min(var(--radius-4xl),24px)] *:[img:last-child]:rounded-b-[min(var(--radius-4xl),24px)]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "group/card-header @container/card-header grid auto-rows-min items-start gap-1.5 rounded-t-[min(var(--radius-4xl),24px)] px-(--card-spacing) has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-(--card-spacing)",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn("font-heading text-base font-medium", className)}
+      {...props}
+    />
+  )
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn(
+        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-(--card-spacing)", className)}
+      {...props}
+    />
+  )
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn(
+        "flex items-center rounded-b-[min(var(--radius-4xl),24px)] px-(--card-spacing) [.border-t]:pt-(--card-spacing)",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardAction,
+  CardDescription,
+  CardContent,
+}
diff --git a/website/components/ui/command.tsx b/website/src/components/ui/command.tsx
similarity index 100%
rename from website/components/ui/command.tsx
rename to website/src/components/ui/command.tsx
diff --git a/website/components/ui/dialog.tsx b/website/src/components/ui/dialog.tsx
similarity index 100%
rename from website/components/ui/dialog.tsx
rename to website/src/components/ui/dialog.tsx
diff --git a/website/components/ui/input-group.tsx b/website/src/components/ui/input-group.tsx
similarity index 100%
rename from website/components/ui/input-group.tsx
rename to website/src/components/ui/input-group.tsx
diff --git a/website/components/ui/input.tsx b/website/src/components/ui/input.tsx
similarity index 100%
rename from website/components/ui/input.tsx
rename to website/src/components/ui/input.tsx
diff --git a/website/src/components/ui/kbd.tsx b/website/src/components/ui/kbd.tsx
new file mode 100644
index 0000000..53819c3
--- /dev/null
+++ b/website/src/components/ui/kbd.tsx
@@ -0,0 +1,26 @@
+import { cn } from "@/lib/utils"
+
+function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {
+  return (
+    <kbd
+      data-slot="kbd"
+      className={cn(
+        "pointer-events-none inline-flex h-5 w-fit min-w-5 items-center justify-center gap-1 rounded-lg bg-muted px-1 font-sans text-xs font-medium text-muted-foreground select-none in-data-[slot=input-group]:bg-input in-data-[slot=tooltip-content]:bg-background/20 in-data-[slot=tooltip-content]:text-background dark:in-data-[slot=tooltip-content]:bg-background/10 [&_svg:not([class*='size-'])]:size-3",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function KbdGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <kbd
+      data-slot="kbd-group"
+      className={cn("inline-flex items-center gap-1", className)}
+      {...props}
+    />
+  )
+}
+
+export { Kbd, KbdGroup }
diff --git a/website/src/components/ui/separator.tsx b/website/src/components/ui/separator.tsx
new file mode 100644
index 0000000..6e1369e
--- /dev/null
+++ b/website/src/components/ui/separator.tsx
@@ -0,0 +1,25 @@
+"use client"
+
+import { Separator as SeparatorPrimitive } from "@base-ui/react/separator"
+
+import { cn } from "@/lib/utils"
+
+function Separator({
+  className,
+  orientation = "horizontal",
+  ...props
+}: SeparatorPrimitive.Props) {
+  return (
+    <SeparatorPrimitive
+      data-slot="separator"
+      orientation={orientation}
+      className={cn(
+        "shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Separator }
diff --git a/website/components/ui/sheet.tsx b/website/src/components/ui/sheet.tsx
similarity index 100%
rename from website/components/ui/sheet.tsx
rename to website/src/components/ui/sheet.tsx
diff --git a/website/src/components/ui/sidebar.tsx b/website/src/components/ui/sidebar.tsx
new file mode 100644
index 0000000..13323df
--- /dev/null
+++ b/website/src/components/ui/sidebar.tsx
@@ -0,0 +1,727 @@
+"use client"
+
+import * as React from "react"
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { useIsMobile } from "@/hooks/use-mobile"
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Separator } from "@/components/ui/separator"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet"
+import { Skeleton } from "@/components/ui/skeleton"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
+import { HugeiconsIcon } from "@hugeicons/react"
+import { SidebarLeftIcon } from "@hugeicons/core-free-icons"
+
+const SIDEBAR_COOKIE_NAME = "sidebar_state"
+const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7
+const SIDEBAR_WIDTH = "16rem"
+const SIDEBAR_WIDTH_MOBILE = "18rem"
+const SIDEBAR_WIDTH_ICON = "3rem"
+const SIDEBAR_KEYBOARD_SHORTCUT = "b"
+
+type SidebarContextProps = {
+  state: "expanded" | "collapsed"
+  open: boolean
+  setOpen: (open: boolean) => void
+  openMobile: boolean
+  setOpenMobile: (open: boolean) => void
+  isMobile: boolean
+  toggleSidebar: () => void
+}
+
+const SidebarContext = React.createContext<SidebarContextProps | null>(null)
+
+function useSidebar() {
+  const context = React.useContext(SidebarContext)
+  if (!context) {
+    throw new Error("useSidebar must be used within a SidebarProvider.")
+  }
+
+  return context
+}
+
+function SidebarProvider({
+  defaultOpen = true,
+  open: openProp,
+  onOpenChange: setOpenProp,
+  className,
+  style,
+  children,
+  ...props
+}: React.ComponentProps<"div"> & {
+  defaultOpen?: boolean
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+}) {
+  const isMobile = useIsMobile()
+  const [openMobile, setOpenMobile] = React.useState(false)
+
+  // This is the internal state of the sidebar.
+  // We use openProp and setOpenProp for control from outside the component.
+  const [_open, _setOpen] = React.useState(defaultOpen)
+  const open = openProp ?? _open
+  const setOpen = React.useCallback(
+    (value: boolean | ((value: boolean) => boolean)) => {
+      const openState = typeof value === "function" ? value(open) : value
+      if (setOpenProp) {
+        setOpenProp(openState)
+      } else {
+        _setOpen(openState)
+      }
+
+      // This sets the cookie to keep the sidebar state.
+      document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`
+    },
+    [setOpenProp, open]
+  )
+
+  // Helper to toggle the sidebar.
+  const toggleSidebar = React.useCallback(() => {
+    return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open)
+  }, [isMobile, setOpen, setOpenMobile])
+
+  // Adds a keyboard shortcut to toggle the sidebar.
+  React.useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (
+        event.key === SIDEBAR_KEYBOARD_SHORTCUT &&
+        (event.metaKey || event.ctrlKey)
+      ) {
+        event.preventDefault()
+        toggleSidebar()
+      }
+    }
+
+    window.addEventListener("keydown", handleKeyDown)
+    return () => window.removeEventListener("keydown", handleKeyDown)
+  }, [toggleSidebar])
+
+  // We add a state so that we can do data-state="expanded" or "collapsed".
+  // This makes it easier to style the sidebar with Tailwind classes.
+  const state = open ? "expanded" : "collapsed"
+
+  const contextValue = React.useMemo<SidebarContextProps>(
+    () => ({
+      state,
+      open,
+      setOpen,
+      isMobile,
+      openMobile,
+      setOpenMobile,
+      toggleSidebar,
+    }),
+    [state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar]
+  )
+
+  return (
+    <SidebarContext.Provider value={contextValue}>
+      <div
+        data-slot="sidebar-wrapper"
+        style={
+          {
+            "--sidebar-width": SIDEBAR_WIDTH,
+            "--sidebar-width-icon": SIDEBAR_WIDTH_ICON,
+            ...style,
+          } as React.CSSProperties
+        }
+        className={cn(
+          "group/sidebar-wrapper flex min-h-svh w-full has-data-[variant=inset]:bg-sidebar",
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    </SidebarContext.Provider>
+  )
+}
+
+function Sidebar({
+  side = "left",
+  variant = "sidebar",
+  collapsible = "offcanvas",
+  className,
+  children,
+  dir,
+  ...props
+}: React.ComponentProps<"div"> & {
+  side?: "left" | "right"
+  variant?: "sidebar" | "floating" | "inset"
+  collapsible?: "offcanvas" | "icon" | "none"
+}) {
+  const { isMobile, state, openMobile, setOpenMobile } = useSidebar()
+
+  if (collapsible === "none") {
+    return (
+      <div
+        data-slot="sidebar"
+        className={cn(
+          "flex h-full w-(--sidebar-width) flex-col bg-sidebar text-sidebar-foreground",
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    )
+  }
+
+  if (isMobile) {
+    return (
+      <Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}>
+        <SheetContent
+          dir={dir}
+          data-sidebar="sidebar"
+          data-slot="sidebar"
+          data-mobile="true"
+          className="w-(--sidebar-width) bg-sidebar p-0 text-sidebar-foreground [&>button]:hidden"
+          style={
+            {
+              "--sidebar-width": SIDEBAR_WIDTH_MOBILE,
+            } as React.CSSProperties
+          }
+          side={side}
+        >
+          <SheetHeader className="sr-only">
+            <SheetTitle>Sidebar</SheetTitle>
+            <SheetDescription>Displays the mobile sidebar.</SheetDescription>
+          </SheetHeader>
+          <div className="flex h-full w-full flex-col">{children}</div>
+        </SheetContent>
+      </Sheet>
+    )
+  }
+
+  return (
+    <div
+      className="group peer hidden text-sidebar-foreground md:block"
+      data-state={state}
+      data-collapsible={state === "collapsed" ? collapsible : ""}
+      data-variant={variant}
+      data-side={side}
+      data-slot="sidebar"
+    >
+      {/* This is what handles the sidebar gap on desktop */}
+      <div
+        data-slot="sidebar-gap"
+        className={cn(
+          "relative w-(--sidebar-width) bg-transparent transition-[width] duration-200 ease-linear",
+          "group-data-[collapsible=offcanvas]:w-0",
+          "group-data-[side=right]:rotate-180",
+          variant === "floating" || variant === "inset"
+            ? "group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4)))]"
+            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon)"
+        )}
+      />
+      <div
+        data-slot="sidebar-container"
+        data-side={side}
+        className={cn(
+          "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear data-[side=left]:left-0 data-[side=left]:group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)] data-[side=right]:right-0 data-[side=right]:group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)] md:flex",
+          // Adjust the padding for floating and inset variants.
+          variant === "floating" || variant === "inset"
+            ? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]"
+            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon) group-data-[side=left]:border-r group-data-[side=right]:border-l",
+          className
+        )}
+        {...props}
+      >
+        <div
+          data-sidebar="sidebar"
+          data-slot="sidebar-inner"
+          className="flex size-full flex-col bg-sidebar group-data-[variant=floating]:rounded-2xl group-data-[variant=floating]:shadow-sm group-data-[variant=floating]:ring-1 group-data-[variant=floating]:ring-sidebar-border"
+        >
+          {children}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function SidebarTrigger({
+  className,
+  onClick,
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  const { toggleSidebar } = useSidebar()
+
+  return (
+    <Button
+      data-sidebar="trigger"
+      data-slot="sidebar-trigger"
+      variant="ghost"
+      size="icon-sm"
+      className={cn(className)}
+      onClick={(event) => {
+        onClick?.(event)
+        toggleSidebar()
+      }}
+      {...props}
+    >
+      <HugeiconsIcon icon={SidebarLeftIcon} strokeWidth={2} />
+      <span className="sr-only">Toggle Sidebar</span>
+    </Button>
+  )
+}
+
+function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
+  const { toggleSidebar } = useSidebar()
+
+  return (
+    <button
+      data-sidebar="rail"
+      data-slot="sidebar-rail"
+      aria-label="Toggle Sidebar"
+      tabIndex={-1}
+      onClick={toggleSidebar}
+      title="Toggle Sidebar"
+      className={cn(
+        "absolute inset-y-0 z-20 hidden w-4 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:start-1/2 after:w-[2px] hover:after:bg-sidebar-border sm:flex ltr:-translate-x-1/2 rtl:-translate-x-1/2",
+        "in-data-[side=left]:cursor-w-resize in-data-[side=right]:cursor-e-resize",
+        "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize",
+        "group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full hover:group-data-[collapsible=offcanvas]:bg-sidebar",
+        "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2",
+        "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
+  return (
+    <main
+      data-slot="sidebar-inset"
+      className={cn(
+        "relative flex w-full flex-1 flex-col bg-background md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-2xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarInput({
+  className,
+  ...props
+}: React.ComponentProps<typeof Input>) {
+  return (
+    <Input
+      data-slot="sidebar-input"
+      data-sidebar="input"
+      className={cn("h-8 w-full bg-input/50 shadow-none", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-header"
+      data-sidebar="header"
+      className={cn(
+        "flex flex-col gap-2 p-2 [--radius:var(--radius-xl)]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-footer"
+      data-sidebar="footer"
+      className={cn("flex flex-col gap-2 p-2", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof Separator>) {
+  return (
+    <Separator
+      data-slot="sidebar-separator"
+      data-sidebar="separator"
+      className={cn("mx-2 w-auto bg-sidebar-border", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-content"
+      data-sidebar="content"
+      className={cn(
+        "no-scrollbar flex min-h-0 flex-1 flex-col gap-2 overflow-auto [--radius:var(--radius-xl)] group-data-[collapsible=icon]:overflow-hidden",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-group"
+      data-sidebar="group"
+      className={cn("relative flex w-full min-w-0 flex-col p-2", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarGroupLabel({
+  className,
+  render,
+  ...props
+}: useRender.ComponentProps<"div"> & React.ComponentProps<"div">) {
+  return useRender({
+    defaultTagName: "div",
+    props: mergeProps<"div">(
+      {
+        className: cn(
+          "flex h-8 shrink-0 items-center rounded-xl px-3 text-xs font-medium text-sidebar-foreground/70 ring-sidebar-ring outline-hidden transition-[margin,opacity] duration-200 ease-linear group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-3 [&>svg]:size-4 [&>svg]:shrink-0",
+          className
+        ),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "sidebar-group-label",
+      sidebar: "group-label",
+    },
+  })
+}
+
+function SidebarGroupAction({
+  className,
+  render,
+  ...props
+}: useRender.ComponentProps<"button"> & React.ComponentProps<"button">) {
+  return useRender({
+    defaultTagName: "button",
+    props: mergeProps<"button">(
+      {
+        className: cn(
+          "absolute top-3.5 right-3 flex aspect-square w-5 items-center justify-center rounded-xl p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden after:absolute after:-inset-2 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-3 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0",
+          className
+        ),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "sidebar-group-action",
+      sidebar: "group-action",
+    },
+  })
+}
+
+function SidebarGroupContent({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-group-content"
+      data-sidebar="group-content"
+      className={cn("w-full text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">) {
+  return (
+    <ul
+      data-slot="sidebar-menu"
+      data-sidebar="menu"
+      className={cn("flex w-full min-w-0 flex-col gap-0.5", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="sidebar-menu-item"
+      data-sidebar="menu-item"
+      className={cn("group/menu-item relative", className)}
+      {...props}
+    />
+  )
+}
+
+const sidebarMenuButtonVariants = cva(
+  "peer/menu-button group/menu-button flex w-full items-center gap-2 overflow-hidden rounded-xl px-3 py-2 text-left text-sm whitespace-nowrap ring-sidebar-ring outline-hidden transition-[width,height,padding] duration-200 group-has-data-[sidebar=menu-action]/menu-item:pr-8 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-3 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 has-[>svg:first-child]:pl-2.5 has-[>svg:last-child]:pr-2.5 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground data-active:bg-sidebar-accent data-active:font-medium data-active:text-sidebar-accent-foreground [&_svg]:size-4 [&_svg]:shrink-0 [&>span:last-child]:truncate",
+  {
+    variants: {
+      variant: {
+        default: "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+        outline:
+          "bg-background shadow-[0_0_0_1px_hsl(var(--sidebar-border))] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground hover:shadow-[0_0_0_1px_hsl(var(--sidebar-accent))]",
+      },
+      size: {
+        default: "h-8 text-sm",
+        sm: "h-7 text-xs",
+        lg: "h-12 px-3 text-sm group-data-[collapsible=icon]:p-0!",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function SidebarMenuButton({
+  render,
+  isActive = false,
+  variant = "default",
+  size = "default",
+  tooltip,
+  className,
+  ...props
+}: useRender.ComponentProps<"button"> &
+  React.ComponentProps<"button"> & {
+    isActive?: boolean
+    tooltip?: string | React.ComponentProps<typeof TooltipContent>
+  } & VariantProps<typeof sidebarMenuButtonVariants>) {
+  const { isMobile, state } = useSidebar()
+  const comp = useRender({
+    defaultTagName: "button",
+    props: mergeProps<"button">(
+      {
+        className: cn(sidebarMenuButtonVariants({ variant, size }), className),
+      },
+      props
+    ),
+    render: !tooltip ? render : <TooltipTrigger render={render} />,
+    state: {
+      slot: "sidebar-menu-button",
+      sidebar: "menu-button",
+      size,
+      active: isActive,
+    },
+  })
+
+  if (!tooltip) {
+    return comp
+  }
+
+  if (typeof tooltip === "string") {
+    tooltip = {
+      children: tooltip,
+    }
+  }
+
+  return (
+    <Tooltip>
+      {comp}
+      <TooltipContent
+        side="right"
+        align="center"
+        hidden={state !== "collapsed" || isMobile}
+        {...tooltip}
+      />
+    </Tooltip>
+  )
+}
+
+function SidebarMenuAction({
+  className,
+  render,
+  showOnHover = false,
+  ...props
+}: useRender.ComponentProps<"button"> &
+  React.ComponentProps<"button"> & {
+    showOnHover?: boolean
+  }) {
+  return useRender({
+    defaultTagName: "button",
+    props: mergeProps<"button">(
+      {
+        className: cn(
+          "absolute top-1.5 right-1 flex aspect-square w-5 items-center justify-center rounded-xl p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 after:absolute after:-inset-2 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-3 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0",
+          showOnHover &&
+            "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 peer-data-active/menu-button:text-sidebar-accent-foreground aria-expanded:opacity-100 md:opacity-0",
+          className
+        ),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "sidebar-menu-action",
+      sidebar: "menu-action",
+    },
+  })
+}
+
+function SidebarMenuBadge({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-menu-badge"
+      data-sidebar="menu-badge"
+      className={cn(
+        "pointer-events-none absolute right-1 flex h-5 min-w-5 items-center justify-center rounded-xl px-1 text-xs font-medium text-sidebar-foreground tabular-nums select-none group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 peer-data-active/menu-button:text-sidebar-accent-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuSkeleton({
+  className,
+  showIcon = false,
+  ...props
+}: React.ComponentProps<"div"> & {
+  showIcon?: boolean
+}) {
+  // Random width between 50 to 90%.
+  const [width] = React.useState(() => {
+    return `${Math.floor(Math.random() * 40) + 50}%`
+  })
+
+  return (
+    <div
+      data-slot="sidebar-menu-skeleton"
+      data-sidebar="menu-skeleton"
+      className={cn("flex h-8 items-center gap-2 rounded-xl px-2", className)}
+      {...props}
+    >
+      {showIcon && (
+        <Skeleton
+          className="size-4 rounded-xl"
+          data-sidebar="menu-skeleton-icon"
+        />
+      )}
+      <Skeleton
+        className="h-4 max-w-(--skeleton-width) flex-1"
+        data-sidebar="menu-skeleton-text"
+        style={
+          {
+            "--skeleton-width": width,
+          } as React.CSSProperties
+        }
+      />
+    </div>
+  )
+}
+
+function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">) {
+  return (
+    <ul
+      data-slot="sidebar-menu-sub"
+      data-sidebar="menu-sub"
+      className={cn(
+        "mx-3.5 flex min-w-0 translate-x-px flex-col gap-1 border-l border-sidebar-border px-2.5 py-0.5 group-data-[collapsible=icon]:hidden",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuSubItem({
+  className,
+  ...props
+}: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="sidebar-menu-sub-item"
+      data-sidebar="menu-sub-item"
+      className={cn("group/menu-sub-item relative", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuSubButton({
+  render,
+  size = "md",
+  isActive = false,
+  className,
+  ...props
+}: useRender.ComponentProps<"a"> &
+  React.ComponentProps<"a"> & {
+    size?: "sm" | "md"
+    isActive?: boolean
+  }) {
+  return useRender({
+    defaultTagName: "a",
+    props: mergeProps<"a">(
+      {
+        className: cn(
+          "flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-xl px-3 text-sidebar-foreground ring-sidebar-ring outline-hidden group-data-[collapsible=icon]:hidden hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-3 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[size=md]:text-sm data-[size=sm]:text-xs data-active:bg-sidebar-accent data-active:text-sidebar-accent-foreground [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-sidebar-accent-foreground",
+          className
+        ),
+      },
+      props
+    ),
+    render,
+    state: {
+      slot: "sidebar-menu-sub-button",
+      sidebar: "menu-sub-button",
+      size,
+      active: isActive,
+    },
+  })
+}
+
+export {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupAction,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarInput,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuAction,
+  SidebarMenuBadge,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSkeleton,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarProvider,
+  SidebarRail,
+  SidebarSeparator,
+  SidebarTrigger,
+  useSidebar,
+}
diff --git a/website/src/components/ui/skeleton.tsx b/website/src/components/ui/skeleton.tsx
new file mode 100644
index 0000000..d598583
--- /dev/null
+++ b/website/src/components/ui/skeleton.tsx
@@ -0,0 +1,13 @@
+import { cn } from "@/lib/utils"
+
+function Skeleton({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="skeleton"
+      className={cn("animate-pulse rounded-2xl bg-muted", className)}
+      {...props}
+    />
+  )
+}
+
+export { Skeleton }
diff --git a/website/components/ui/textarea.tsx b/website/src/components/ui/textarea.tsx
similarity index 100%
rename from website/components/ui/textarea.tsx
rename to website/src/components/ui/textarea.tsx
diff --git a/website/src/components/ui/tooltip.tsx b/website/src/components/ui/tooltip.tsx
new file mode 100644
index 0000000..bc2c8d0
--- /dev/null
+++ b/website/src/components/ui/tooltip.tsx
@@ -0,0 +1,66 @@
+"use client"
+
+import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip"
+
+import { cn } from "@/lib/utils"
+
+function TooltipProvider({
+  delay = 0,
+  ...props
+}: TooltipPrimitive.Provider.Props) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delay={delay}
+      {...props}
+    />
+  )
+}
+
+function Tooltip({ ...props }: TooltipPrimitive.Root.Props) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+}
+
+function TooltipTrigger({ ...props }: TooltipPrimitive.Trigger.Props) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+  className,
+  side = "top",
+  sideOffset = 4,
+  align = "center",
+  alignOffset = 0,
+  children,
+  ...props
+}: TooltipPrimitive.Popup.Props &
+  Pick<
+    TooltipPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset"
+  >) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+        className="isolate z-50"
+      >
+        <TooltipPrimitive.Popup
+          data-slot="tooltip-content"
+          className={cn(
+            "z-50 inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-xl bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-lg data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            className
+          )}
+          {...props}
+        >
+          {children}
+          <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground data-[side=bottom]:top-1 data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:translate-x-[1.5px] data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:translate-x-[-1.5px] data-[side=inline-start]:-translate-y-1/2 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:translate-x-[-1.5px] data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:translate-x-[1.5px] data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5" />
+        </TooltipPrimitive.Popup>
+      </TooltipPrimitive.Positioner>
+    </TooltipPrimitive.Portal>
+  )
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }
diff --git a/website/src/hooks/use-mobile.ts b/website/src/hooks/use-mobile.ts
new file mode 100644
index 0000000..2b0fe1d
--- /dev/null
+++ b/website/src/hooks/use-mobile.ts
@@ -0,0 +1,19 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}
diff --git a/website/lib/docs.ts b/website/src/lib/docs.ts
similarity index 75%
rename from website/lib/docs.ts
rename to website/src/lib/docs.ts
index 754fbb0..9d98373 100644
--- a/website/lib/docs.ts
+++ b/website/src/lib/docs.ts
@@ -1,10 +1,12 @@
 import type { MDXProps } from 'mdx/types';
 import type { JSX } from 'react';
-import * as e2bCompatibility from '@/content/docs/e2b-compatibility.mdx';
-import * as indexDoc from '@/content/docs/index.mdx';
-import * as installation from '@/content/docs/installation.mdx';
-import meta from '@/content/docs/meta.json';
-import * as quickstart from '@/content/docs/quickstart.mdx';
+// Relative imports: content/ lives beside src/ on purpose — it is authored
+// content, not source, and stays portable across doc-shell rewrites.
+import * as e2bCompatibility from '../../content/docs/e2b-compatibility.mdx';
+import * as indexDoc from '../../content/docs/index.mdx';
+import * as installation from '../../content/docs/installation.mdx';
+import meta from '../../content/docs/meta.json';
+import * as quickstart from '../../content/docs/quickstart.mdx';
 
 // Server-only registry of every doc. MDX renders as server components, so
 // importing them all here costs the client nothing — pages ship as HTML.
@@ -36,7 +38,7 @@ export const docs: DocEntry[] = meta.pages.map((name) => {
   const mod = modules[name];
   if (!mod) {
     throw new Error(
-      `content/docs/meta.json lists "${name}" but lib/docs.ts does not import it`,
+      `content/docs/meta.json lists "${name}" but src/lib/docs.ts does not import it`,
     );
   }
   const slug = name === 'index' ? '' : name;
@@ -51,7 +53,7 @@ export const docs: DocEntry[] = meta.pages.map((name) => {
 for (const name of Object.keys(modules)) {
   if (!meta.pages.includes(name)) {
     throw new Error(
-      `lib/docs.ts imports "${name}" but content/docs/meta.json does not list it`,
+      `src/lib/docs.ts imports "${name}" but content/docs/meta.json does not list it`,
     );
   }
 }
diff --git a/website/src/lib/site.ts b/website/src/lib/site.ts
new file mode 100644
index 0000000..9639586
--- /dev/null
+++ b/website/src/lib/site.ts
@@ -0,0 +1,12 @@
+// Site-wide constants, collected in one place so the layout metadata, the
+// landing sections and the chrome never drift apart. Page-local copy stays
+// in its section component; only text used from more than one place lives
+// here. SITE_URL (canonical/OG/sitemap) is deliberately absent until the
+// deployment target — GitHub Pages vs a domain — is decided.
+export const GITHUB_URL = 'https://github.com/BitMiracle-AI/Dormice';
+
+export const SITE_TITLE = 'Dormice — the SQLite of agent sandboxes';
+
+export const SITE_DESCRIPTION =
+  'A self-hosted sandbox platform for AI agents. One machine, sandboxes ' +
+  'that live forever, idle costs nothing.';
diff --git a/website/lib/utils.ts b/website/src/lib/utils.ts
similarity index 100%
rename from website/lib/utils.ts
rename to website/src/lib/utils.ts
diff --git a/website/mdx-components.tsx b/website/src/mdx-components.tsx
similarity index 100%
rename from website/mdx-components.tsx
rename to website/src/mdx-components.tsx
diff --git a/website/mdx.d.ts b/website/src/mdx.d.ts
similarity index 100%
rename from website/mdx.d.ts
rename to website/src/mdx.d.ts
diff --git a/website/tsconfig.json b/website/tsconfig.json
index b8ead68..898dd95 100644
--- a/website/tsconfig.json
+++ b/website/tsconfig.json
@@ -8,7 +8,7 @@
     "incremental": true,
     "plugins": [{ "name": "next" }],
     "baseUrl": ".",
-    "paths": { "@/*": ["./*"] }
+    "paths": { "@/*": ["./src/*"] }
   },
   "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
   "exclude": ["node_modules", "out"]

From 1e2d57860d1b346ddb8812bebdab4e62cb68b159 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 21:56:54 +0800
Subject: [PATCH 041/133] Link-rendering buttons declare nativeButton false

---
 .../console/src/features/connect/pages/ConnectPage.tsx |  1 +
 .../src/features/sandboxes/pages/SandboxDetailPage.tsx |  8 +++++++-
 .../src/features/sandboxes/pages/SandboxesPage.tsx     |  7 ++++++-
 website/src/app/docs/[[...slug]]/page.tsx              |  2 ++
 website/src/app/not-found.tsx                          | 10 ++++++++--
 website/src/components/SiteHeader.tsx                  |  2 ++
 website/src/components/sections/Hero.tsx               |  9 +++++++--
 7 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/packages/console/src/features/connect/pages/ConnectPage.tsx b/packages/console/src/features/connect/pages/ConnectPage.tsx
index f069967..38af80a 100644
--- a/packages/console/src/features/connect/pages/ConnectPage.tsx
+++ b/packages/console/src/features/connect/pages/ConnectPage.tsx
@@ -99,6 +99,7 @@ dor sandbox exec my-project 'uname -r'`;
         <Button
           variant="ghost"
           size="icon-sm"
+          nativeButton={false}
           render={<Link to="/" aria-label="Back to sandboxes" />}
         >
           <HugeiconsIcon icon={ArrowLeft01Icon} />
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index 8b38d2f..aab5159 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -49,7 +49,12 @@ export function SandboxDetailPage() {
               </EmptyDescription>
             </EmptyHeader>
             <EmptyContent>
-              <Button variant="outline" size="sm" render={<Link to="/" />}>
+              <Button
+                variant="outline"
+                size="sm"
+                nativeButton={false}
+                render={<Link to="/" />}
+              >
                 Back to sandboxes
               </Button>
             </EmptyContent>
@@ -66,6 +71,7 @@ export function SandboxDetailPage() {
           <Button
             variant="ghost"
             size="icon-sm"
+            nativeButton={false}
             render={<Link to="/" aria-label="Back to sandboxes" />}
           >
             <HugeiconsIcon icon={ArrowLeft01Icon} />
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index a77e7ca..f0c4b49 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -48,7 +48,12 @@ export function SandboxesPage() {
           </span>
         </div>
         <div className="flex items-center gap-2">
-          <Button variant="ghost" size="sm" render={<Link to="/connect" />}>
+          <Button
+            variant="ghost"
+            size="sm"
+            nativeButton={false}
+            render={<Link to="/connect" />}
+          >
             Connect
           </Button>
           <CreateSandboxDialog />
diff --git a/website/src/app/docs/[[...slug]]/page.tsx b/website/src/app/docs/[[...slug]]/page.tsx
index 928267b..c107e26 100644
--- a/website/src/app/docs/[[...slug]]/page.tsx
+++ b/website/src/app/docs/[[...slug]]/page.tsx
@@ -37,6 +37,7 @@ export default async function Page(props: PageProps) {
             <Button
               variant="ghost"
               className="text-muted-foreground"
+              nativeButton={false}
               render={<Link href={prev.href} />}
             >
               <HugeiconsIcon icon={ArrowLeft01Icon} data-icon="inline-start" />
@@ -49,6 +50,7 @@ export default async function Page(props: PageProps) {
             <Button
               variant="ghost"
               className="text-muted-foreground"
+              nativeButton={false}
               render={<Link href={next.href} />}
             >
               {next.title}
diff --git a/website/src/app/not-found.tsx b/website/src/app/not-found.tsx
index 6033e08..51d91cc 100644
--- a/website/src/app/not-found.tsx
+++ b/website/src/app/not-found.tsx
@@ -11,8 +11,14 @@ export default function NotFound() {
         The page you are looking for does not exist.
       </p>
       <div className="flex items-center gap-3">
-        <Button render={<Link href="/" />}>Home</Button>
-        <Button variant="outline" render={<Link href="/docs" />}>
+        <Button nativeButton={false} render={<Link href="/" />}>
+          Home
+        </Button>
+        <Button
+          variant="outline"
+          nativeButton={false}
+          render={<Link href="/docs" />}
+        >
           Docs
         </Button>
       </div>
diff --git a/website/src/components/SiteHeader.tsx b/website/src/components/SiteHeader.tsx
index 8c1d652..4fd7a9a 100644
--- a/website/src/components/SiteHeader.tsx
+++ b/website/src/components/SiteHeader.tsx
@@ -18,6 +18,7 @@ export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
             variant="ghost"
             size="sm"
             className="text-muted-foreground"
+            nativeButton={false}
             render={<Link href="/docs" />}
           >
             Docs
@@ -28,6 +29,7 @@ export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
           <Button
             variant="ghost"
             size="icon"
+            nativeButton={false}
             render={<a href={GITHUB_URL} aria-label="GitHub" />}
           >
             <HugeiconsIcon icon={GithubIcon} />
diff --git a/website/src/components/sections/Hero.tsx b/website/src/components/sections/Hero.tsx
index 5b9bcb5..8e50ceb 100644
--- a/website/src/components/sections/Hero.tsx
+++ b/website/src/components/sections/Hero.tsx
@@ -15,10 +15,15 @@ export function Hero() {
         that live forever, idle costs nothing.
       </p>
       <div className="mt-8 flex items-center gap-3">
-        <Button size="lg" render={<Link href="/docs" />}>
+        <Button size="lg" nativeButton={false} render={<Link href="/docs" />}>
           Get started
         </Button>
-        <Button size="lg" variant="outline" render={<a href={GITHUB_URL} />}>
+        <Button
+          size="lg"
+          variant="outline"
+          nativeButton={false}
+          render={<a href={GITHUB_URL} />}
+        >
           GitHub
         </Button>
       </div>

From bdb9775fed8e576f498a9e5b0248f4a4ef604343 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 23:16:38 +0800
Subject: [PATCH 042/133] A host observation window: getHostMetrics, the
 diskUsage verb, console overview cards

---
 e2e/src/native.test.ts                        |  19 ++
 .../overview/components/OverviewCards.tsx     | 229 ++++++++++++++++++
 .../console/src/features/overview/format.ts   |  24 ++
 .../features/overview/hooks/useHostMetrics.ts |  14 ++
 .../sandboxes/pages/SandboxesPage.tsx         |   5 +
 packages/console/src/lib/api.ts               |   5 +
 packages/console/vite.config.ts               |   3 +
 packages/sdk/src/client.test.ts               |  13 +
 packages/sdk/src/client.ts                    |  14 ++
 packages/server/src/app.test.ts               |  79 ++++++
 packages/server/src/app.ts                    |   2 +
 .../server/src/executor/contract/metrics.ts   |  72 ++++++
 packages/server/src/executor/docker.ts        |  35 +++
 packages/server/src/executor/executor.ts      |  20 ++
 packages/server/src/executor/fake.ts          |  43 +++-
 packages/server/src/host-metrics.test.ts      |  96 ++++++++
 packages/server/src/host-metrics.ts           | 124 ++++++++++
 packages/server/src/routes/host.ts            |  67 +++++
 packages/shared/src/host.ts                   |  81 +++++++
 packages/shared/src/index.ts                  |   1 +
 20 files changed, 937 insertions(+), 9 deletions(-)
 create mode 100644 packages/console/src/features/overview/components/OverviewCards.tsx
 create mode 100644 packages/console/src/features/overview/format.ts
 create mode 100644 packages/console/src/features/overview/hooks/useHostMetrics.ts
 create mode 100644 packages/server/src/host-metrics.test.ts
 create mode 100644 packages/server/src/host-metrics.ts
 create mode 100644 packages/server/src/routes/host.ts
 create mode 100644 packages/shared/src/host.ts

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index f2470d9..e0854b1 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -380,4 +380,23 @@ describe('native API over a real daemon', () => {
     );
     expect(observed?.state).toBe('active');
   });
+
+  it('reports host metrics: the machine and the fleet in one snapshot', async () => {
+    await client().acquireSandbox('host-metrics-key');
+    // The SDK already validates the response against the shared schema;
+    // assertions stay >= because other test files share this daemon.
+    const metrics = await client().getHostMetrics();
+    expect(metrics.host.cpuCount).toBeGreaterThan(0);
+    expect(metrics.host.memTotalBytes).toBeGreaterThan(0);
+    expect(metrics.sandboxes.total).toBeGreaterThanOrEqual(1);
+    expect(metrics.sandboxes.maxSandboxes).toBeGreaterThan(0);
+    expect(metrics.sandboxDisks.count).toBeGreaterThanOrEqual(1);
+    expect(metrics.sandboxDisks.actualBytes).toBeGreaterThan(0);
+    // Disks are sparse: the fleet is promised more than it occupies —
+    // the overcommit this window exists to watch.
+    expect(metrics.sandboxDisks.nominalBytes).toBeGreaterThan(
+      metrics.sandboxDisks.actualBytes,
+    );
+    await client().releaseSandbox('host-metrics-key');
+  });
 });
diff --git a/packages/console/src/features/overview/components/OverviewCards.tsx b/packages/console/src/features/overview/components/OverviewCards.tsx
new file mode 100644
index 0000000..81953cf
--- /dev/null
+++ b/packages/console/src/features/overview/components/OverviewCards.tsx
@@ -0,0 +1,229 @@
+import type { HostMetricsResponse } from '@dormice/shared';
+import {
+  CpuIcon,
+  Database01Icon,
+  HardDriveIcon,
+  PackageIcon,
+  RamMemoryIcon,
+  SnowIcon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
+import type { ReactNode } from 'react';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Card, CardContent } from '@/components/ui/card';
+import { Skeleton } from '@/components/ui/skeleton';
+import { cn } from '@/lib/utils';
+import { formatBytes, pctOf } from '../format';
+import { useHostMetrics } from '../hooks/useHostMetrics';
+
+/**
+ * Usage meter: the fill carries severity (quiet below 75%, amber to 90%,
+ * red past it) and the unfilled track is a lighter step of the same color,
+ * so state reads across the whole bar. Null means "no reading yet" — an
+ * empty quiet track, never a fake zero fill.
+ */
+function Meter({ pct }: { pct: number | null }) {
+  const clamped = pct === null ? 0 : Math.min(100, Math.max(0, pct));
+  const [fill, track] =
+    clamped >= 90
+      ? ['bg-red-500', 'bg-red-500/15']
+      : clamped >= 75
+        ? ['bg-amber-500', 'bg-amber-500/15']
+        : ['bg-primary', 'bg-primary/10'];
+  return (
+    <div className={cn('h-1.5 w-full overflow-hidden rounded-full', track)}>
+      <div
+        className={cn('h-full rounded-full transition-[width]', fill)}
+        style={{ width: `${clamped}%` }}
+      />
+    </div>
+  );
+}
+
+function StatCard({
+  icon,
+  label,
+  value,
+  hint,
+  pct,
+}: {
+  icon: NonNullable<HugeiconsProps['icon']>;
+  label: string;
+  value: string;
+  hint: ReactNode;
+  /** Meter percentage; null renders an empty track, undefined no meter. */
+  pct?: number | null;
+}) {
+  return (
+    <Card size="sm">
+      <CardContent className="flex flex-col gap-2">
+        <div className="flex items-center gap-1.5 text-sm text-muted-foreground">
+          <HugeiconsIcon icon={icon} className="size-4" strokeWidth={1.8} />
+          {label}
+        </div>
+        <div className="text-2xl font-semibold">{value}</div>
+        <div className="text-xs text-muted-foreground">{hint}</div>
+        {pct !== undefined && <Meter pct={pct} />}
+      </CardContent>
+    </Card>
+  );
+}
+
+// The lifecycle rungs shown in the fleet card, coldest last — same hues as
+// SandboxStateBadge so the two read as one system. archived and restoring
+// only appear once they exist (no archiver yet — nothing is promised).
+const STATE_DOTS: Array<{
+  key: keyof HostMetricsResponse['sandboxes']['byState'];
+  dot: string;
+  alwaysShown: boolean;
+}> = [
+  { key: 'active', dot: 'bg-emerald-500', alwaysShown: true },
+  { key: 'frozen', dot: 'bg-sky-500', alwaysShown: true },
+  { key: 'stopped', dot: 'bg-muted-foreground/50', alwaysShown: true },
+  { key: 'archived', dot: 'bg-violet-500', alwaysShown: false },
+  { key: 'restoring', dot: 'bg-amber-500', alwaysShown: false },
+];
+
+function StateCounts({
+  byState,
+}: {
+  byState: HostMetricsResponse['sandboxes']['byState'];
+}) {
+  return (
+    <span className="flex flex-wrap gap-x-3 gap-y-1">
+      {STATE_DOTS.filter((s) => s.alwaysShown || byState[s.key] > 0).map(
+        (s) => (
+          <span key={s.key} className="inline-flex items-center gap-1.5">
+            <span className={cn('size-2 rounded-full', s.dot)} />
+            <span className="font-medium text-foreground">
+              {byState[s.key]}
+            </span>
+            {s.key}
+          </span>
+        ),
+      )}
+    </span>
+  );
+}
+
+/**
+ * The dashboard's card row: is the host healthy, and what does the fleet
+ * cost it? Swap and the data disk get equal billing with CPU and memory
+ * because on this platform they are the two that kill: full swap ends
+ * "idle is free", a full data disk ends creation entirely.
+ */
+export function OverviewCards() {
+  const query = useHostMetrics();
+
+  if (query.isError) {
+    return (
+      <Alert variant="destructive">
+        <AlertDescription>{query.error.message}</AlertDescription>
+      </Alert>
+    );
+  }
+
+  if (!query.data) {
+    // One placeholder per card in the top row, keyed by what will load there.
+    return (
+      <div className="grid gap-4 sm:grid-cols-2 xl:grid-cols-4">
+        {['cpu', 'memory', 'swap', 'data-disk'].map((slot) => (
+          <Skeleton
+            key={slot}
+            className="h-28 rounded-[min(var(--radius-4xl),24px)]"
+          />
+        ))}
+      </div>
+    );
+  }
+
+  const { host, dataDisk, sandboxes, sandboxDisks } = query.data;
+  const memUsed = host.memTotalBytes - host.memAvailableBytes;
+
+  return (
+    <section className="flex flex-col gap-4">
+      <div className="grid gap-4 sm:grid-cols-2 xl:grid-cols-4">
+        <StatCard
+          icon={CpuIcon}
+          label="CPU"
+          value={
+            host.cpuUsedPct === null ? '—' : `${Math.round(host.cpuUsedPct)}%`
+          }
+          hint={`${host.cpuCount} core${host.cpuCount === 1 ? '' : 's'}`}
+          pct={host.cpuUsedPct}
+        />
+        <StatCard
+          icon={RamMemoryIcon}
+          label="Memory"
+          value={formatBytes(memUsed)}
+          hint={`of ${formatBytes(host.memTotalBytes)} · ${formatBytes(host.memAvailableBytes)} available`}
+          pct={pctOf(memUsed, host.memTotalBytes)}
+        />
+        {host.swap === null ? (
+          <StatCard
+            icon={SnowIcon}
+            label="Swap"
+            value="—"
+            hint="no reading on this platform"
+          />
+        ) : host.swap.totalBytes === 0 ? (
+          <StatCard
+            icon={SnowIcon}
+            label="Swap"
+            value="none"
+            hint={
+              <span className="text-amber-600 dark:text-amber-500">
+                freezing needs swap — see dor doctor
+              </span>
+            }
+          />
+        ) : (
+          <StatCard
+            icon={SnowIcon}
+            label="Swap"
+            value={formatBytes(host.swap.usedBytes)}
+            hint={`of ${formatBytes(host.swap.totalBytes)} · frozen sandboxes live here`}
+            pct={pctOf(host.swap.usedBytes, host.swap.totalBytes)}
+          />
+        )}
+        {dataDisk === null ? (
+          <StatCard
+            icon={HardDriveIcon}
+            label="Data disk"
+            value="—"
+            hint="no data directory on this host"
+          />
+        ) : (
+          <StatCard
+            icon={HardDriveIcon}
+            label="Data disk"
+            value={formatBytes(dataDisk.usedBytes)}
+            hint={
+              <span title={dataDisk.path}>
+                {`of ${formatBytes(dataDisk.totalBytes)} · ${formatBytes(dataDisk.availableBytes)} free`}
+              </span>
+            }
+            pct={pctOf(dataDisk.usedBytes, dataDisk.totalBytes)}
+          />
+        )}
+      </div>
+
+      <div className="grid gap-4 md:grid-cols-2">
+        <StatCard
+          icon={PackageIcon}
+          label="Sandboxes"
+          value={`${sandboxes.total} / ${sandboxes.maxSandboxes}`}
+          hint={<StateCounts byState={sandboxes.byState} />}
+          pct={pctOf(sandboxes.total, sandboxes.maxSandboxes)}
+        />
+        <StatCard
+          icon={Database01Icon}
+          label="Sandbox disks"
+          value={formatBytes(sandboxDisks.actualBytes)}
+          hint={`promised ${formatBytes(sandboxDisks.nominalBytes)} across ${sandboxDisks.count} disk${sandboxDisks.count === 1 ? '' : 's'} — sparse images only cost what they hold`}
+          pct={pctOf(sandboxDisks.actualBytes, sandboxDisks.nominalBytes)}
+        />
+      </div>
+    </section>
+  );
+}
diff --git a/packages/console/src/features/overview/format.ts b/packages/console/src/features/overview/format.ts
new file mode 100644
index 0000000..3805e21
--- /dev/null
+++ b/packages/console/src/features/overview/format.ts
@@ -0,0 +1,24 @@
+/**
+ * Bytes in binary units, auto-compact: 512 B, 24.5 MiB, 1.02 TiB. Binary
+ * because that is what the numbers physically are (disk images, meminfo) —
+ * a 16 GiB swap must read as 16, not 17.2.
+ */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes)) return '—';
+  if (bytes < 0) return '—';
+  const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB'];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  const digits = value >= 100 || unit === 0 ? 0 : value >= 10 ? 1 : 2;
+  return `${value.toFixed(digits)} ${units[unit]}`;
+}
+
+/** A used/total pair as a percentage, clamped into [0, 100]. */
+export function pctOf(used: number, total: number): number {
+  if (total <= 0) return 0;
+  return Math.min(100, Math.max(0, (used / total) * 100));
+}
diff --git a/packages/console/src/features/overview/hooks/useHostMetrics.ts b/packages/console/src/features/overview/hooks/useHostMetrics.ts
new file mode 100644
index 0000000..1b9597d
--- /dev/null
+++ b/packages/console/src/features/overview/hooks/useHostMetrics.ts
@@ -0,0 +1,14 @@
+import { useQuery } from '@tanstack/react-query';
+import { getHostMetrics } from '@/lib/api';
+
+export function useHostMetrics() {
+  return useQuery({
+    queryKey: ['hostMetrics'],
+    queryFn: getHostMetrics,
+    // Slower than the sandbox list on purpose: CPU usage is a delta between
+    // consecutive requests, and a 5s interval keeps that reading meaningful
+    // where a 2s one would mostly sample noise.
+    refetchInterval: 5000,
+    retry: false,
+  });
+}
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index f0c4b49..e16d943 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -18,6 +18,7 @@ import {
   TableHeader,
   TableRow,
 } from '@/components/ui/table';
+import { OverviewCards } from '@/features/overview/components/OverviewCards';
 import { logout } from '@/lib/api';
 import { clearSessionMarker } from '@/lib/session';
 import { CreateSandboxDialog } from '../components/CreateSandboxDialog';
@@ -63,6 +64,10 @@ export function SandboxesPage() {
         </div>
       </header>
 
+      <div className="mb-6">
+        <OverviewCards />
+      </div>
+
       {query.isError && (
         <Alert variant="destructive" className="mb-4">
           <AlertDescription>{query.error.message}</AlertDescription>
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 267f904..702bd1e 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -1,6 +1,7 @@
 import type {
   AcquireRequest,
   AcquireResponse,
+  HostMetricsResponse,
   Sandbox,
   Template,
 } from '@dormice/shared';
@@ -81,6 +82,10 @@ export const logout = () =>
 export const listSandboxes = () =>
   rpc<{ sandboxes: Sandbox[] }>('/listSandboxes');
 
+// The host-level observation window: machine health plus fleet aggregates.
+// Pure observation — the daemon wakes nothing to answer it.
+export const getHostMetrics = () => rpc<HostMetricsResponse>('/getHostMetrics');
+
 export const listTemplates = () =>
   rpc<{ templates: Template[] }>('/listTemplates');
 
diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index 3fbb09a..9413651 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -27,6 +27,9 @@ export default defineConfig({
       '/listSandboxes': 'http://127.0.0.1:3676',
       '/releaseSandbox': 'http://127.0.0.1:3676',
       '/acquireSandbox': 'http://127.0.0.1:3676',
+      '/rebuildSandbox': 'http://127.0.0.1:3676',
+      '/listTemplates': 'http://127.0.0.1:3676',
+      '/getHostMetrics': 'http://127.0.0.1:3676',
       // The terminal speaks the envd surface directly, like the e2b SDK.
       '/e2b': 'http://127.0.0.1:3676',
     },
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 3a683d0..683152b 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -157,6 +157,19 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
     expect(erin?.state).toBe('active');
   });
 
+  it('reads host metrics: real host numbers, ledger aggregates in step', async () => {
+    await client.acquireSandbox('metrics-watcher');
+    const metrics = await client.getHostMetrics();
+    expect(metrics.host.cpuCount).toBeGreaterThan(0);
+    expect(metrics.host.memTotalBytes).toBeGreaterThan(0);
+    const listed = await client.listSandboxes();
+    expect(metrics.sandboxes.total).toBe(listed.length);
+    expect(metrics.sandboxDisks.count).toBeGreaterThanOrEqual(1);
+    expect(metrics.sandboxDisks.nominalBytes).toBeGreaterThan(
+      metrics.sandboxDisks.actualBytes,
+    );
+  });
+
   it('runs a command in the sandbox and returns the buffered result', async () => {
     await client.acquireSandbox('grace');
     const result = await client.execCommand('grace', 'echo hi');
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 204a753..1a5fb74 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -4,6 +4,8 @@ import {
   DEFAULT_EXEC_TIMEOUT_SECONDS,
   type ExecCommandResponse,
   execCommandResponseSchema,
+  type HostMetricsResponse,
+  hostMetricsResponseSchema,
   type LifecyclePolicyOverride,
   listSandboxesResponseSchema,
   listTemplatesResponseSchema,
@@ -128,6 +130,18 @@ export class Dormice {
     return listSandboxesResponseSchema.parse(data).sandboxes;
   }
 
+  /**
+   * The daemon host's own health in one snapshot: CPU, memory and swap
+   * (the freeze mechanism's fuel), the data disk, ledger aggregates, and
+   * what the sparse sandbox disks nominally promise versus actually occupy.
+   * Pure observation — never wakes a sandbox. Readings the platform cannot
+   * produce come back null, never invented.
+   */
+  async getHostMetrics(): Promise<HostMetricsResponse> {
+    const data = await this.rpc('getHostMetrics', {});
+    return hostMetricsResponseSchema.parse(data);
+  }
+
   /**
    * Swaps the sandbox's container while keeping its disk: /home/user is
    * untouched, and the next use builds a fresh container from the current
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index 358f6b9..6ad1115 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -1,7 +1,9 @@
+import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import {
   DEFAULT_LIFECYCLE_POLICY,
   FILE_SIZE_LIMIT_BYTES,
+  hostMetricsResponseSchema,
 } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { buildApp } from './app';
@@ -992,3 +994,80 @@ describe('templates', () => {
     expect(executor.imageOf(created.sandboxId)).toBe('img-v2');
   });
 });
+
+describe('POST /getHostMetrics', () => {
+  it('sits behind the token like every API verb', async () => {
+    const res = await testApp().app.inject({
+      method: 'POST',
+      url: '/getHostMetrics',
+      payload: {},
+    });
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('answers a schema-valid snapshot with honest host readings', async () => {
+    // tmpdir() exists on every platform, so the data-disk reading is real.
+    const { app } = testApp(new FakeExecutor(), {
+      DORMICE_DATA_DIR: tmpdir(),
+    });
+    const res = await rpc(app, '/getHostMetrics');
+    expect(res.statusCode).toBe(200);
+    const body = hostMetricsResponseSchema.parse(res.json());
+    expect(body.host.cpuCount).toBeGreaterThan(0);
+    expect(body.host.memTotalBytes).toBeGreaterThan(0);
+    expect(body.host.memAvailableBytes).toBeGreaterThan(0);
+    expect(body.dataDisk?.path).toBe(tmpdir());
+    expect(body.dataDisk?.totalBytes).toBeGreaterThan(0);
+    expect(body.sandboxes).toEqual({
+      total: 0,
+      maxSandboxes: 100,
+      byState: { active: 0, frozen: 0, stopped: 0, archived: 0, restoring: 0 },
+    });
+    expect(body.sandboxDisks).toEqual({
+      count: 0,
+      nominalBytes: 0,
+      actualBytes: 0,
+    });
+  });
+
+  it('reports a missing data dir as null — absent, not invented', async () => {
+    const { app } = testApp(new FakeExecutor(), {
+      DORMICE_DATA_DIR: '/no/such/dormice-data',
+    });
+    const res = await rpc(app, '/getHostMetrics');
+    expect(res.statusCode).toBe(200);
+    expect(res.json().dataDisk).toBeNull();
+  });
+
+  it('aggregates follow the ledger, and observing changes nothing', async () => {
+    const { app, db, executor, locks } = testApp();
+    // alice freezes after 60s, bob keeps the 600s default: time-traveling
+    // to alice+60 freezes exactly one of them.
+    const created = (
+      await acquire(app, {
+        userKey: 'alice',
+        policy: { freezeAfterSeconds: 60 },
+      })
+    ).json();
+    await acquire(app, { userKey: 'bob' });
+
+    let body = (await rpc(app, '/getHostMetrics')).json();
+    expect(body.sandboxes.total).toBe(2);
+    expect(body.sandboxes.byState.active).toBe(2);
+    expect(body.sandboxDisks.count).toBe(2);
+    expect(body.sandboxDisks.nominalBytes).toBeGreaterThan(0);
+    expect(body.sandboxDisks.actualBytes).toBeGreaterThan(0);
+
+    await scanOnce(
+      db,
+      executor,
+      locks,
+      after(created.sandbox.lastActiveAt, 60),
+    );
+    body = (await rpc(app, '/getHostMetrics')).json();
+    expect(body.sandboxes.byState.active).toBe(1);
+    expect(body.sandboxes.byState.frozen).toBe(1);
+    // Observation is not activity: reading metrics woke nothing.
+    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+  });
+});
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index bf1127c..eadc9b9 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -17,6 +17,7 @@ import { WatcherTable } from './e2b/watcher-table';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
 import { consoleRoutes } from './routes/console';
+import { hostRoutes } from './routes/host';
 import { sandboxRoutes } from './routes/sandboxes';
 import { templateRoutes } from './routes/templates';
 import { createSandboxProxy } from './sandbox-proxy';
@@ -135,6 +136,7 @@ export function buildApp({
     api.addHook('onRequest', requireApiAuth(config.DORMICE_API_TOKEN));
     await api.register(sandboxRoutes, { config, db, executor, locks });
     await api.register(templateRoutes, { db });
+    await api.register(hostRoutes, { config, db, executor });
   });
 
   // The web console: session endpoints (open — login carries the token
diff --git a/packages/server/src/executor/contract/metrics.ts b/packages/server/src/executor/contract/metrics.ts
index 863f607..62ae0db 100644
--- a/packages/server/src/executor/contract/metrics.ts
+++ b/packages/server/src/executor/contract/metrics.ts
@@ -83,4 +83,76 @@ export function metricsTests(ctx: ContractContext) {
       timeoutMs,
     );
   });
+
+  describe('diskUsage', () => {
+    it(
+      'starts at zero and counts each disk once',
+      async () => {
+        expect(await ctx.executor.diskUsage()).toEqual({
+          count: 0,
+          nominalBytes: 0,
+          actualBytes: 0,
+        });
+        const first = await ctx.fresh();
+        const one = await ctx.executor.diskUsage();
+        expect(one.count).toBe(1);
+        expect(one.nominalBytes).toBeGreaterThan(0);
+        await ctx.fresh();
+        const two = await ctx.executor.diskUsage();
+        expect(two.count).toBe(2);
+        // Every disk is promised the same size, so two disks cost exactly
+        // twice the nominal — an invariant that holds whatever the size is.
+        expect(two.nominalBytes).toBe(2 * one.nominalBytes);
+        await ctx.executor.destroy(first);
+        expect((await ctx.executor.diskUsage()).count).toBe(1);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a fresh disk occupies far less than its nominal size — sparseness is the overcommit',
+      async () => {
+        await ctx.fresh();
+        const usage = await ctx.executor.diskUsage();
+        expect(usage.actualBytes).toBeGreaterThan(0);
+        expect(usage.actualBytes).toBeLessThan(usage.nominalBytes);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'actual usage grows after writing a file',
+      async () => {
+        const id = await ctx.fresh();
+        const before = await ctx.executor.diskUsage();
+        await ctx.executor.writeFiles(id, [
+          { path: 'usage-blob.bin', content: Buffer.alloc(2 * 1024 ** 2, 7) },
+        ]);
+        // Same patience as the metrics growth test: ext4 may settle the
+        // sparse image's newly allocated blocks a beat after the write.
+        let after = await ctx.executor.diskUsage();
+        const deadline = Date.now() + timeoutMs - 1_000;
+        while (
+          after.actualBytes <= before.actualBytes &&
+          Date.now() < deadline
+        ) {
+          await new Promise((resolve) => setTimeout(resolve, 100));
+          after = await ctx.executor.diskUsage();
+        }
+        expect(after.actualBytes).toBeGreaterThan(before.actualBytes);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'a stopped sandbox and a vanished container still count — the disk is the body',
+      async () => {
+        const id = await ctx.freshStopped();
+        expect((await ctx.executor.diskUsage()).count).toBe(1);
+        await ctx.subject.vanishContainer(id);
+        expect((await ctx.executor.diskUsage()).count).toBe(1);
+      },
+      timeoutMs,
+    );
+  });
 }
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index faa1469..8bfdc09 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -7,6 +7,7 @@ import {
   readdir,
   readFile,
   rm,
+  stat,
   statfs,
 } from 'node:fs/promises';
 import path from 'node:path';
@@ -47,6 +48,7 @@ import { CallbackSink, CappedBuffer } from './docker-streams';
 import {
   type ContainerState,
   DiskFullError,
+  type DiskUsage,
   type ExecOptions,
   type ExecResult,
   type ExecStreamHandle,
@@ -298,6 +300,39 @@ export class DockerExecutor implements Executor {
     await this.teardownDisk(sandboxId);
   }
 
+  async diskUsage(): Promise<DiskUsage> {
+    const disksDir = path.join(this.opts.dataDir, 'disks');
+    let entries: string[];
+    try {
+      entries = await readdir(disksDir);
+    } catch (err) {
+      // No disks directory yet — no sandbox has ever been created here.
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        return { count: 0, nominalBytes: 0, actualBytes: 0 };
+      }
+      throw err;
+    }
+    const usage: DiskUsage = { count: 0, nominalBytes: 0, actualBytes: 0 };
+    for (const name of entries) {
+      if (!name.endsWith('.img')) continue;
+      let s: Awaited<ReturnType<typeof stat>>;
+      try {
+        s = await stat(path.join(disksDir, name));
+      } catch (err) {
+        // Torn down by a concurrent release between readdir and stat —
+        // a snapshot simply does not count what is no longer there.
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw err;
+      }
+      usage.count += 1;
+      // size is what truncate promised; blocks (always 512-byte units) is
+      // what the sparse image really occupies. Their gap is the overcommit.
+      usage.nominalBytes += s.size;
+      usage.actualBytes += s.blocks * 512;
+    }
+    return usage;
+  }
+
   async resolvePortTarget(
     sandboxId: string,
     port: number,
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index 7d5c1e8..5a9201d 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -192,6 +192,19 @@ export interface SandboxMetrics {
   diskTotalBytes: number;
 }
 
+/**
+ * What every sandbox disk on this host adds up to — the host-level
+ * complement to SandboxMetrics' per-sandbox view. Nominal is the summed
+ * promised sizes; actual is what the sparse images really occupy. The gap
+ * is the disk overcommit, and watching it is the only cap there is.
+ */
+export interface DiskUsage {
+  /** Disk images present, with or without a container — disks are the bodies. */
+  count: number;
+  nominalBytes: number;
+  actualBytes: number;
+}
+
 /**
  * The file-op error taxonomy, shared by both executors down to the message
  * (the contract exam holds them to it) and mapped to HTTP statuses by the
@@ -304,6 +317,13 @@ export interface Executor {
    * running to measure — the route above answers [] for those on its own.
    */
   metrics(sandboxId: string): Promise<SandboxMetrics>;
+  /**
+   * Every sandbox disk on this host, summed: how many, what they were
+   * promised, what they actually occupy. A snapshot like listDisks —
+   * a disk torn down mid-scan is simply not counted. Never touches disk
+   * contents and never wakes anything: observation is not activity.
+   */
+  diskUsage(): Promise<DiskUsage>;
   /**
    * Runs a shell command inside a running container and returns the fully
    * buffered result. Requires state `running` — a paused container cannot
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index 6d3bb42..b942cd7 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -7,6 +7,7 @@ import {
 } from '@dormice/shared';
 import {
   type ContainerState,
+  type DiskUsage,
   type ExecOptions,
   type ExecResult,
   type ExecStreamHandle,
@@ -29,6 +30,9 @@ import {
 /** The image the fake's shells boot from when no other image is asked for. */
 export const FAKE_BASE_IMAGE = 'fake-base';
 
+/** The fake disk's promised size — metrics' diskTotalBytes and diskUsage's nominal, one number. */
+const FAKE_DISK_NOMINAL_BYTES = 10 * 1024 ** 3;
+
 /**
  * Directories every real sandbox is born with, with the owner and mode
  * reality gives them: the image's skeleton plus lost+found — the mkfs.ext4
@@ -64,6 +68,19 @@ function seededDisk(): Map<string, FakeNode> {
   );
 }
 
+/**
+ * Disk usage computed from the file table — the one number the contract
+ * can watch move (write a file, usage grows) on both executors. Shared by
+ * metrics (one sandbox) and diskUsage (every disk on the host).
+ */
+function diskUsedBytes(files: Map<string, FakeNode>): number {
+  let used = 0;
+  for (const node of files.values()) {
+    used += node.type === 'file' ? node.content.length : 4096;
+  }
+  return used;
+}
+
 /**
  * Node -> entry, with the metadata reality would report: files land as
  * uid 1000 with the default umask (644), created directories as 755, and
@@ -387,21 +404,29 @@ export class FakeExecutor implements Executor {
         `container ${sandboxId} is ${actual ?? 'absent'}, expected running or paused`,
       );
     }
-    // Disk usage is computed from the file table — the one number the
-    // contract can watch move (write a file, usage grows) on both
-    // executors; the rest are plausible constants in honest proportions.
-    let diskUsedBytes = 0;
-    for (const node of this.disk(sandboxId).values()) {
-      diskUsedBytes += node.type === 'file' ? node.content.length : 4096;
-    }
     return {
       cpuCount: 1,
       cpuUsedPct: 0,
       memUsedBytes: 64 * 1024 ** 2,
       memTotalBytes: 2 * 1024 ** 3,
       memCacheBytes: 0,
-      diskUsedBytes,
-      diskTotalBytes: 10 * 1024 ** 3,
+      diskUsedBytes: diskUsedBytes(this.disk(sandboxId)),
+      diskTotalBytes: FAKE_DISK_NOMINAL_BYTES,
+    };
+  }
+
+  async diskUsage(): Promise<DiskUsage> {
+    // Keyed off the disks set, not containers: a stopped or vanished shell
+    // still has a disk, and the disk is what costs the host.
+    let actualBytes = 0;
+    for (const sandboxId of this.disks) {
+      const files = this.fs.get(sandboxId);
+      if (files) actualBytes += diskUsedBytes(files);
+    }
+    return {
+      count: this.disks.size,
+      nominalBytes: this.disks.size * FAKE_DISK_NOMINAL_BYTES,
+      actualBytes,
     };
   }
 
diff --git a/packages/server/src/host-metrics.test.ts b/packages/server/src/host-metrics.test.ts
new file mode 100644
index 0000000..c2a2b13
--- /dev/null
+++ b/packages/server/src/host-metrics.test.ts
@@ -0,0 +1,96 @@
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  CpuSampler,
+  parseMeminfo,
+  readDiskSpace,
+  readHostMemory,
+} from './host-metrics';
+
+// A real Ubuntu 24.04 /proc/meminfo, truncated to the fields that matter
+// plus neighbors that must not confuse the parser (SwapCached vs SwapTotal).
+const MEMINFO = `MemTotal:       32496460 kB
+MemFree:         1652948 kB
+MemAvailable:   24493736 kB
+Buffers:         1585796 kB
+Cached:         20655944 kB
+SwapCached:        11492 kB
+SwapTotal:      16777212 kB
+SwapFree:       15728640 kB
+Dirty:               396 kB
+`;
+
+describe('parseMeminfo', () => {
+  it('reads totals, MemAvailable and swap in bytes', () => {
+    const memory = parseMeminfo(MEMINFO);
+    expect(memory).toEqual({
+      memTotalBytes: 32496460 * 1024,
+      memAvailableBytes: 24493736 * 1024,
+      swap: {
+        totalBytes: 16777212 * 1024,
+        usedBytes: (16777212 - 15728640) * 1024,
+      },
+    });
+  });
+
+  it('reports a swapless machine as an honest zero, not null', () => {
+    const memory = parseMeminfo(
+      'MemTotal: 1024 kB\nMemAvailable: 512 kB\nSwapTotal: 0 kB\nSwapFree: 0 kB\n',
+    );
+    expect(memory?.swap).toEqual({ totalBytes: 0, usedBytes: 0 });
+  });
+
+  it('answers null for text that is not a meminfo', () => {
+    expect(parseMeminfo('not a meminfo')).toBeNull();
+  });
+});
+
+describe('CpuSampler', () => {
+  it('answers null on the first sample — no interval to report on', () => {
+    expect(new CpuSampler().sample()).toBeNull();
+  });
+
+  it('answers a percentage in [0, 100] once an interval exists', async () => {
+    const sampler = new CpuSampler();
+    sampler.sample();
+    // Let the kernel's counters tick; busy-spin a little so the delta is
+    // not all idle on a quiet CI machine.
+    const until = Date.now() + 60;
+    while (Date.now() < until) {
+      /* spin */
+    }
+    const pct = sampler.sample();
+    // The counters' granularity can still round the interval to zero on a
+    // fast machine — null stays an honest answer; a number must be sane.
+    if (pct !== null) {
+      expect(pct).toBeGreaterThanOrEqual(0);
+      expect(pct).toBeLessThanOrEqual(100);
+    }
+  });
+});
+
+describe('readHostMemory', () => {
+  it('reports positive totals on whatever platform runs the tests', async () => {
+    const memory = await readHostMemory();
+    expect(memory.memTotalBytes).toBeGreaterThan(0);
+    expect(memory.memAvailableBytes).toBeGreaterThan(0);
+    expect(memory.memAvailableBytes).toBeLessThanOrEqual(memory.memTotalBytes);
+  });
+});
+
+describe('readDiskSpace', () => {
+  it('reports df-style numbers for an existing directory', async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), 'dormice-host-'));
+    const space = await readDiskSpace(dir);
+    expect(space).not.toBeNull();
+    expect(space?.totalBytes).toBeGreaterThan(0);
+    expect(space?.usedBytes).toBeGreaterThanOrEqual(0);
+    expect(space?.availableBytes).toBeGreaterThan(0);
+  });
+
+  it('answers null for a directory that does not exist', async () => {
+    expect(await readDiskSpace('/no/such/dormice/dir')).toBeNull();
+  });
+});
diff --git a/packages/server/src/host-metrics.ts b/packages/server/src/host-metrics.ts
new file mode 100644
index 0000000..4843a52
--- /dev/null
+++ b/packages/server/src/host-metrics.ts
@@ -0,0 +1,124 @@
+import { readFile, statfs } from 'node:fs/promises';
+import os from 'node:os';
+
+/**
+ * Host-side readings for getHostMetrics — the machine's own health, which
+ * no executor can know (executors know sandboxes; the daemon lives on the
+ * host). Every reading is a point-in-time snapshot; anything the platform
+ * cannot produce is null, never invented — swap and MemAvailable are
+ * /proc/meminfo facts, and a Mac dev machine has neither.
+ */
+
+export interface HostMemory {
+  memTotalBytes: number;
+  memAvailableBytes: number;
+  swap: { totalBytes: number; usedBytes: number } | null;
+}
+
+/**
+ * Whole-machine CPU usage as a delta between two samples of the kernel's
+ * cumulative per-CPU time counters. One sampler instance per daemon: the
+ * delta spans "since the last request", and the very first call honestly
+ * answers null — a single sample has no denominator.
+ */
+export class CpuSampler {
+  private last: { idleMs: number; totalMs: number } | null = null;
+
+  /** Percent of the whole machine, 0-100, or null until a delta exists. */
+  sample(): number | null {
+    let idleMs = 0;
+    let totalMs = 0;
+    for (const cpu of os.cpus()) {
+      idleMs += cpu.times.idle;
+      totalMs +=
+        cpu.times.user +
+        cpu.times.nice +
+        cpu.times.sys +
+        cpu.times.idle +
+        cpu.times.irq;
+    }
+    const prev = this.last;
+    this.last = { idleMs, totalMs };
+    // No previous sample, or none of the counters moved yet (two calls
+    // inside the same tick) — there is no interval to report on.
+    if (!prev || totalMs <= prev.totalMs) return null;
+    const busy = totalMs - prev.totalMs - (idleMs - prev.idleMs);
+    // Clamp into the reading's own domain: per-CPU counters are sampled
+    // one after another, so rounding can push the ratio a hair outside it.
+    return Math.min(100, Math.max(0, (busy / (totalMs - prev.totalMs)) * 100));
+  }
+}
+
+/**
+ * /proc/meminfo -> HostMemory, exported for tests. Null when the text does
+ * not carry the fields (not a Linux meminfo): the caller falls back to the
+ * portable reading.
+ */
+export function parseMeminfo(text: string): HostMemory | null {
+  const kb = (key: string): number | null => {
+    const match = text.match(new RegExp(`^${key}: +(\\d+) kB$`, 'm'));
+    return match ? Number(match[1]) * 1024 : null;
+  };
+  const memTotal = kb('MemTotal');
+  const memAvailable = kb('MemAvailable');
+  if (memTotal === null || memAvailable === null) return null;
+  const swapTotal = kb('SwapTotal');
+  const swapFree = kb('SwapFree');
+  return {
+    memTotalBytes: memTotal,
+    memAvailableBytes: memAvailable,
+    swap:
+      swapTotal !== null && swapFree !== null
+        ? { totalBytes: swapTotal, usedBytes: swapTotal - swapFree }
+        : null,
+  };
+}
+
+/**
+ * On Linux, /proc/meminfo: MemAvailable counts reclaimable page cache
+ * (os.freemem() does not — it would cry wolf on any healthy box), and swap
+ * lives nowhere else. Elsewhere, the portable os numbers and an honest
+ * null for swap.
+ */
+export async function readHostMemory(): Promise<HostMemory> {
+  try {
+    const parsed = parseMeminfo(await readFile('/proc/meminfo', 'utf8'));
+    if (parsed) return parsed;
+  } catch {
+    // No /proc here — not a Linux host.
+  }
+  return {
+    memTotalBytes: os.totalmem(),
+    memAvailableBytes: os.freemem(),
+    swap: null,
+  };
+}
+
+export interface DiskSpace {
+  totalBytes: number;
+  usedBytes: number;
+  availableBytes: number;
+}
+
+/**
+ * The filesystem holding `dirPath`, df semantics: available is what a
+ * non-root writer can still use (bavail, not bfree). Null when the
+ * directory does not exist — the fake executor never creates the data
+ * dir, and a missing reading must not invent one.
+ */
+export async function readDiskSpace(
+  dirPath: string,
+): Promise<DiskSpace | null> {
+  let s: Awaited<ReturnType<typeof statfs>>;
+  try {
+    s = await statfs(dirPath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw err;
+  }
+  return {
+    totalBytes: s.blocks * s.bsize,
+    usedBytes: (s.blocks - s.bfree) * s.bsize,
+    availableBytes: s.bavail * s.bsize,
+  };
+}
diff --git a/packages/server/src/routes/host.ts b/packages/server/src/routes/host.ts
new file mode 100644
index 0000000..7cce607
--- /dev/null
+++ b/packages/server/src/routes/host.ts
@@ -0,0 +1,67 @@
+import os from 'node:os';
+import { hostMetricsResponseSchema, SANDBOX_STATES } from '@dormice/shared';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import type { Config } from '../config';
+import type { Db } from '../db/db';
+import { listSandboxes } from '../db/ledger';
+import type { Executor } from '../executor/executor';
+import { CpuSampler, readDiskSpace, readHostMemory } from '../host-metrics';
+
+export interface HostRoutesOptions {
+  config: Config;
+  db: Db;
+  executor: Executor;
+}
+
+/**
+ * The observation window into the machine itself — the host-level sibling
+ * of listSandboxes. Read-only by construction: it reads the ledger, /proc,
+ * statfs and the disk images' metadata, and touches no sandbox and no
+ * lifecycle state (observation is not activity — the same principle that
+ * keeps listing and metrics from waking anything).
+ */
+export const hostRoutes: FastifyPluginAsyncZod<HostRoutesOptions> = async (
+  app,
+  { config, db, executor },
+) => {
+  // One sampler per app: CPU usage is a delta between two samples, so it
+  // spans "since the previous request". Primed at build time so the first
+  // request usually has an interval to report on already.
+  const cpu = new CpuSampler();
+  cpu.sample();
+
+  app.post(
+    '/getHostMetrics',
+    {
+      schema: {
+        response: { 200: hostMetricsResponseSchema },
+      },
+    },
+    async () => {
+      const rows = listSandboxes(db);
+      const byState = Object.fromEntries(
+        SANDBOX_STATES.map((state) => [state, 0]),
+      ) as Record<(typeof SANDBOX_STATES)[number], number>;
+      for (const row of rows) byState[row.state] += 1;
+
+      const memory = await readHostMemory();
+      const dataDisk = await readDiskSpace(config.DORMICE_DATA_DIR);
+      return {
+        host: {
+          cpuCount: os.cpus().length,
+          cpuUsedPct: cpu.sample(),
+          ...memory,
+        },
+        dataDisk: dataDisk
+          ? { path: config.DORMICE_DATA_DIR, ...dataDisk }
+          : null,
+        sandboxes: {
+          total: rows.length,
+          maxSandboxes: config.DORMICE_MAX_SANDBOXES,
+          byState,
+        },
+        sandboxDisks: await executor.diskUsage(),
+      };
+    },
+  );
+};
diff --git a/packages/shared/src/host.ts b/packages/shared/src/host.ts
new file mode 100644
index 0000000..f0393fc
--- /dev/null
+++ b/packages/shared/src/host.ts
@@ -0,0 +1,81 @@
+import { z } from 'zod';
+
+/**
+ * getHostMetrics() — the observation window into the machine itself: is the
+ * host healthy, and what do the sandboxes collectively cost it? A single
+ * point-in-time snapshot, deliberately not a metrics history (that is a
+ * monitoring system's job — point Prometheus at the box for trends).
+ * Observation never wakes a sandbox and never touches lifecycle.
+ *
+ * Readings a platform cannot produce are null, honestly — never zero, never
+ * invented: swap and /proc are Linux facts, and the data directory only
+ * exists where the docker executor runs.
+ */
+export const hostMetricsResponseSchema = z.object({
+  host: z.object({
+    cpuCount: z.number().int().positive(),
+    /**
+     * Percent of the whole machine, 0-100. Null until the sampler has two
+     * samples to take a delta between — the first request after daemon
+     * start reports "don't know yet", not a made-up 0.
+     */
+    cpuUsedPct: z.number().nullable(),
+    memTotalBytes: z.number(),
+    /**
+     * What could still be allocated without swapping — /proc/meminfo's
+     * MemAvailable (counts reclaimable page cache), not the naive "free".
+     */
+    memAvailableBytes: z.number(),
+    /**
+     * Swap is the freeze mechanism's fuel: frozen sandboxes live there, and
+     * a full swap means "idle is free" stops being true. totalBytes of 0 is
+     * an honest reading of a machine with no swap configured (doctor warns
+     * about it); null means the platform offers no reading at all.
+     */
+    swap: z
+      .object({
+        totalBytes: z.number(),
+        usedBytes: z.number(),
+      })
+      .nullable(),
+  }),
+  /**
+   * The filesystem holding DORMICE_DATA_DIR — where sandbox disks live. A
+   * full data disk is the real capacity ceiling (past it, even the ledger
+   * cannot write). Null when the directory does not exist (fake executor,
+   * fresh install).
+   */
+  dataDisk: z
+    .object({
+      path: z.string(),
+      totalBytes: z.number(),
+      usedBytes: z.number(),
+      availableBytes: z.number(),
+    })
+    .nullable(),
+  /** Ledger aggregates: what the daemon believes it is running. */
+  sandboxes: z.object({
+    total: z.number().int(),
+    maxSandboxes: z.number().int(),
+    byState: z.object({
+      active: z.number().int(),
+      frozen: z.number().int(),
+      stopped: z.number().int(),
+      archived: z.number().int(),
+      restoring: z.number().int(),
+    }),
+  }),
+  /**
+   * What the sandbox disks cost, from the executor: nominal is the summed
+   * promised sizes, actual is what the sparse images really occupy. The gap
+   * is the overcommit — the number an operator watches close as the host
+   * fills, because nothing else caps it.
+   */
+  sandboxDisks: z.object({
+    count: z.number().int(),
+    nominalBytes: z.number(),
+    actualBytes: z.number(),
+  }),
+});
+
+export type HostMetricsResponse = z.infer<typeof hostMetricsResponseSchema>;
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index b322f12..ab8e23e 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -1,6 +1,7 @@
 export * from './acquire';
 export * from './exec';
 export * from './files';
+export * from './host';
 export * from './list';
 export * from './policy';
 export * from './rebuild';

From 2477b5540eca6126e5e34dfd3ca3b9a12e4baca5 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 10 Jul 2026 23:48:57 +0800
Subject: [PATCH 043/133] install.sh builds what a daemon host runs, not the
 website

---
 deploy/install.sh | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/deploy/install.sh b/deploy/install.sh
index 0c252aa..dc897e6 100644
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -266,7 +266,11 @@ if [ "$MIRROR" = cn ]; then
 else
   pnpm install --frozen-lockfile
 fi
-pnpm build
+# Build only what a daemon host runs: the server (plus its workspace deps),
+# the CLI, and the console SPA. The website package is the project's Next.js
+# marketing site — building it here would cost minutes and import a frontend
+# toolchain's failure modes into an installer whose job is the daemon.
+pnpm --filter "@dormice/server..." --filter "@dormice/cli..." --filter "@dormice/console" build
 ln -sf "$INSTALL_DIR/packages/cli/dist/main.js" /usr/local/bin/dormice
 ln -sf "$INSTALL_DIR/packages/cli/dist/main.js" /usr/local/bin/dor
 note "built; \`dormice\` and \`dor\` linked into /usr/local/bin"

From 3ee64ef5dde05b3a2663b6f82ba2cc9194c7a01a Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 11 Jul 2026 02:13:43 +0800
Subject: [PATCH 044/133] The console becomes a platform: sidebar shell,
 sandbox workspace tabs, template management, a Chinese face

---
 packages/console/index.html                   |   4 +-
 packages/console/package.json                 |   1 +
 packages/console/scripts/seed.mjs             | 143 ++++++
 packages/console/src/components/AppShell.tsx  |  81 +++
 .../console/src/components/AppSidebar.tsx     | 156 ++++++
 .../src/components/SampleDataBadge.tsx        |  17 +
 .../console/src/features/activity/fixtures.ts | 111 +++++
 .../features/activity/pages/ActivityPage.tsx  | 124 +++++
 .../src/features/auth/pages/LoginPage.tsx     |   4 +-
 .../features/connect/pages/ConnectPage.tsx    |  54 +-
 .../console/src/features/doctor/fixtures.ts   | 152 ++++++
 .../src/features/doctor/pages/DoctorPage.tsx  | 181 +++++++
 .../overview/components/OverviewCards.tsx     |  33 +-
 .../features/overview/pages/OverviewPage.tsx  |  19 +
 .../components/CreateSandboxDialog.tsx        |  43 +-
 .../sandboxes/components/FilesPanel.tsx       | 467 ++++++++++++++++++
 .../sandboxes/components/MetricsPanel.tsx     | 145 ++++++
 .../sandboxes/components/ProcessesPanel.tsx   | 151 ++++++
 .../components/RebuildSandboxButton.tsx       |  15 +-
 .../components/ReleaseSandboxButton.tsx       |  14 +-
 .../components/SandboxStateBadge.tsx          |   3 +-
 .../sandboxes/components/SandboxTerminal.tsx  |  12 +-
 .../src/features/sandboxes/envd-client.ts     | 170 +++++++
 .../src/features/sandboxes/envd-pty.ts        |  14 +-
 .../console/src/features/sandboxes/format.ts  |  47 +-
 .../src/features/sandboxes/hooks/useEnvd.ts   | 135 +++++
 .../features/sandboxes/hooks/useTemplates.ts  |  16 -
 .../sandboxes/pages/SandboxDetailPage.tsx     | 191 ++++---
 .../sandboxes/pages/SandboxesPage.tsx         | 273 ++++++++--
 .../console/src/features/settings/fixtures.ts |  79 +++
 .../features/settings/pages/SettingsPage.tsx  |  95 ++++
 .../features/templates/hooks/useTemplates.ts  |  33 ++
 .../templates/pages/TemplatesPage.tsx         | 321 ++++++++++++
 packages/console/src/lib/api.ts               |  11 +
 .../src/{features/overview => lib}/format.ts  |  10 +-
 packages/console/src/lib/mock.ts              |   9 +
 packages/console/src/routeTree.gen.ts         | 117 ++++-
 packages/console/src/routes/_app.tsx          |   5 +
 packages/console/src/routes/_app/activity.tsx |   6 +
 packages/console/src/routes/_app/doctor.tsx   |   6 +
 packages/console/src/routes/_app/index.tsx    |   4 +-
 .../src/routes/_app/sandboxes/$userKey.tsx    |  12 +-
 .../src/routes/_app/sandboxes/index.tsx       |   6 +
 packages/console/src/routes/_app/settings.tsx |   6 +
 .../console/src/routes/_app/templates.tsx     |   6 +
 packages/console/vite.config.ts               |   2 +
 46 files changed, 3238 insertions(+), 266 deletions(-)
 create mode 100644 packages/console/scripts/seed.mjs
 create mode 100644 packages/console/src/components/AppShell.tsx
 create mode 100644 packages/console/src/components/AppSidebar.tsx
 create mode 100644 packages/console/src/components/SampleDataBadge.tsx
 create mode 100644 packages/console/src/features/activity/fixtures.ts
 create mode 100644 packages/console/src/features/activity/pages/ActivityPage.tsx
 create mode 100644 packages/console/src/features/doctor/fixtures.ts
 create mode 100644 packages/console/src/features/doctor/pages/DoctorPage.tsx
 create mode 100644 packages/console/src/features/overview/pages/OverviewPage.tsx
 create mode 100644 packages/console/src/features/sandboxes/components/FilesPanel.tsx
 create mode 100644 packages/console/src/features/sandboxes/components/MetricsPanel.tsx
 create mode 100644 packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
 create mode 100644 packages/console/src/features/sandboxes/envd-client.ts
 create mode 100644 packages/console/src/features/sandboxes/hooks/useEnvd.ts
 delete mode 100644 packages/console/src/features/sandboxes/hooks/useTemplates.ts
 create mode 100644 packages/console/src/features/settings/fixtures.ts
 create mode 100644 packages/console/src/features/settings/pages/SettingsPage.tsx
 create mode 100644 packages/console/src/features/templates/hooks/useTemplates.ts
 create mode 100644 packages/console/src/features/templates/pages/TemplatesPage.tsx
 rename packages/console/src/{features/overview => lib}/format.ts (62%)
 create mode 100644 packages/console/src/lib/mock.ts
 create mode 100644 packages/console/src/routes/_app/activity.tsx
 create mode 100644 packages/console/src/routes/_app/doctor.tsx
 create mode 100644 packages/console/src/routes/_app/sandboxes/index.tsx
 create mode 100644 packages/console/src/routes/_app/settings.tsx
 create mode 100644 packages/console/src/routes/_app/templates.tsx

diff --git a/packages/console/index.html b/packages/console/index.html
index 7918003..199ebb8 100644
--- a/packages/console/index.html
+++ b/packages/console/index.html
@@ -1,9 +1,9 @@
 <!doctype html>
-<html lang="en">
+<html lang="zh-CN">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Dormice</title>
+    <title>Dormice 控制台</title>
   </head>
   <body>
     <div id="root"></div>
diff --git a/packages/console/package.json b/packages/console/package.json
index 3da3b17..595d375 100644
--- a/packages/console/package.json
+++ b/packages/console/package.json
@@ -8,6 +8,7 @@
   "scripts": {
     "build": "vite build",
     "dev": "vite",
+    "seed": "node scripts/seed.mjs",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
diff --git a/packages/console/scripts/seed.mjs b/packages/console/scripts/seed.mjs
new file mode 100644
index 0000000..0246b59
--- /dev/null
+++ b/packages/console/scripts/seed.mjs
@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * 给本地开发的 daemon 填一份生动的演示数据:3 个模板、8 个策略各异的
+ * 沙箱、若干文件 — 让 console 一打开就有东西可看、可点。裸 fetch 打
+ * 原生 RPC,零依赖;沙箱状态的多样性(冻结/停止)靠 daemon 的空闲扫描
+ * 器降温,所以 dev daemon 要把扫描间隔拧到 1 秒(见下)。
+ *
+ * 用法(fake 执行器即可,勿对生产 daemon 跑;token 要求 ≥32 字符):
+ *   0) export DORMICE_API_TOKEN=$(openssl rand -hex 32)
+ *   1) DORMICE_SCAN_INTERVAL_SECONDS=1 pnpm --filter @dormice/server dev
+ *   2) pnpm --filter @dormice/console seed
+ *   3) pnpm --filter @dormice/console dev  →  http://localhost:5173/console
+ *
+ * 注:模板指向的镜像名在 fake 模式下随意;对 docker 执行器跑时镜像必须
+ * 真的在宿主机上,否则用这些模板创建会得到点名的报错(那也是诚实)。
+ */
+
+const endpoint = process.env.DORMICE_ENDPOINT ?? 'http://127.0.0.1:3676';
+const token = process.env.DORMICE_API_TOKEN;
+if (!token) {
+  console.error('缺 DORMICE_API_TOKEN — 与 dev daemon 用同一个值');
+  process.exit(1);
+}
+
+async function rpc(path, body = {}) {
+  const res = await fetch(`${endpoint}${path}`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const detail = await res.json().catch(() => ({}));
+    throw new Error(`${path} → ${res.status}:${detail.message ?? '(无信息)'}`);
+  }
+  return res.json();
+}
+
+const write = (userKey, files) =>
+  rpc('/writeFiles', {
+    userKey,
+    files: files.map(([path, text]) => ({
+      path,
+      contentBase64: Buffer.from(text, 'utf8').toString('base64'),
+    })),
+  });
+
+// ---- 模板 -------------------------------------------------------------
+const templates = [
+  ['python-ml', 'python-ml:v2'],
+  ['node-agent', 'node-agent:v1'],
+  ['claude-code', 'dormice-base:20260710b'],
+];
+for (const [name, image] of templates) {
+  await rpc('/registerTemplate', { name, image });
+  console.log(`模板  ${name} → ${image}`);
+}
+
+// ---- 沙箱 -------------------------------------------------------------
+// freeze/stop 阈值都是秒级,好让 1 秒间隔的扫描器几秒内演完降温;
+// stopAfterSeconds: null 是常驻 agent 档,永远停在 frozen。
+const sandboxes = [
+  {
+    userKey: 'demo-agent',
+    policy: { freezeAfterSeconds: 300, stopAfterSeconds: null },
+    template: 'claude-code',
+  },
+  {
+    userKey: 'web-scraper',
+    policy: { freezeAfterSeconds: 5 },
+    template: 'python-ml',
+  },
+  {
+    userKey: 'build-runner',
+    policy: { freezeAfterSeconds: 3, stopAfterSeconds: 8 },
+  },
+  {
+    userKey: 'docs-writer',
+    policy: { freezeAfterSeconds: 5 },
+    template: 'node-agent',
+  },
+  {
+    userKey: 'email-triage',
+    policy: { freezeAfterSeconds: 600, stopAfterSeconds: null },
+  },
+  {
+    userKey: 'ci-check',
+    policy: { freezeAfterSeconds: 4, stopAfterSeconds: 10 },
+  },
+  {
+    userKey: 'data-pipeline',
+    policy: { freezeAfterSeconds: 900 },
+    template: 'python-ml',
+  },
+  { userKey: 'scratch' },
+];
+for (const { userKey, policy, template } of sandboxes) {
+  await rpc('/acquireSandbox', {
+    userKey,
+    ...(policy ? { policy } : {}),
+    ...(template ? { template } : {}),
+  });
+  console.log(`沙箱  ${userKey}`);
+}
+
+// ---- 文件(给文件浏览器一些可看的内容)---------------------------------
+await write('demo-agent', [
+  [
+    'README.md',
+    '# demo-agent\n\n常驻 agent 的工作目录 — 冻结时住在 swap 里,唤醒约 50ms。\n',
+  ],
+  ['main.py', 'import json\n\nprint(json.dumps({"answer": 42}))\n'],
+  ['data/notes.txt', '盘是本体:容器随便换,/home/user 一直在。\n'],
+]);
+await write('docs-writer', [
+  ['drafts/quickstart.md', '# Quickstart\n\nacquire → exec → release。\n'],
+]);
+console.log('文件  demo-agent(3 个)、docs-writer(1 个)');
+
+// ---- 等扫描器把状态演出来 -----------------------------------------------
+console.log('\n等扫描器降温(最多 20 秒)…');
+const deadline = Date.now() + 20_000;
+let last = '';
+while (Date.now() < deadline) {
+  const { sandboxes: rows } = await rpc('/listSandboxes');
+  const counts = {};
+  for (const row of rows) counts[row.state] = (counts[row.state] ?? 0) + 1;
+  last = Object.entries(counts)
+    .map(([state, n]) => `${state} ${n}`)
+    .join(' · ');
+  if ((counts.frozen ?? 0) >= 2 && (counts.stopped ?? 0) >= 2) break;
+  await new Promise((resolve) => setTimeout(resolve, 2000));
+}
+console.log(`状态  ${last}`);
+if (!last.includes('frozen')) {
+  console.log(
+    '(全都还是 active?dev daemon 大概没开 DORMICE_SCAN_INTERVAL_SECONDS=1,' +
+      '等它的下一轮扫描即可)',
+  );
+}
+console.log('\n完成。打开 console 看看吧。');
diff --git a/packages/console/src/components/AppShell.tsx b/packages/console/src/components/AppShell.tsx
new file mode 100644
index 0000000..75a7111
--- /dev/null
+++ b/packages/console/src/components/AppShell.tsx
@@ -0,0 +1,81 @@
+import { Outlet, useRouterState } from '@tanstack/react-router';
+import { Fragment } from 'react';
+import { AppSidebar } from '@/components/AppSidebar';
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@/components/ui/breadcrumb';
+import { Separator } from '@/components/ui/separator';
+import {
+  SidebarInset,
+  SidebarProvider,
+  SidebarTrigger,
+} from '@/components/ui/sidebar';
+
+// 路径段 → 中文名。没在表里的段(比如 userKey)原样展示 — 它就是名字本身。
+const SEGMENT_LABELS: Record<string, string> = {
+  sandboxes: '沙箱',
+  templates: '模板',
+  activity: '活动',
+  doctor: '体检',
+  settings: '设置',
+  connect: '连接',
+};
+
+function crumbsOf(pathname: string): string[] {
+  const segments = pathname.split('/').filter(Boolean);
+  if (segments.length === 0) return ['总览'];
+  return segments.map(
+    (segment) => SEGMENT_LABELS[segment] ?? decodeURIComponent(segment),
+  );
+}
+
+/**
+ * 登录后的应用外壳:侧边栏 + 顶栏(开关 + 面包屑)+ 页面内容。页面自己
+ * 不再各画返回箭头和站名 — 导航是外壳的职责,页面只管自己的内容区。
+ */
+export function AppShell() {
+  const pathname = useRouterState({
+    select: (state) => state.location.pathname,
+  });
+  const crumbs = crumbsOf(pathname);
+
+  return (
+    <SidebarProvider>
+      <AppSidebar />
+      <SidebarInset>
+        <header className="flex h-14 shrink-0 items-center gap-2 border-b px-4">
+          <SidebarTrigger className="-ml-1" />
+          <Separator orientation="vertical" className="mr-2 !h-4" />
+          <Breadcrumb>
+            <BreadcrumbList>
+              {crumbs.map((crumb, index) => (
+                // biome-ignore lint/suspicious/noArrayIndexKey: 面包屑是纯位置序列,段文本可重复
+                <Fragment key={index}>
+                  {index > 0 && <BreadcrumbSeparator />}
+                  <BreadcrumbItem>
+                    <BreadcrumbPage
+                      className={
+                        index < crumbs.length - 1
+                          ? 'font-normal text-muted-foreground'
+                          : undefined
+                      }
+                    >
+                      {crumb}
+                    </BreadcrumbPage>
+                  </BreadcrumbItem>
+                </Fragment>
+              ))}
+            </BreadcrumbList>
+          </Breadcrumb>
+        </header>
+        <div className="flex flex-1 flex-col gap-4 p-4 md:p-6">
+          <Outlet />
+        </div>
+      </SidebarInset>
+    </SidebarProvider>
+  );
+}
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
new file mode 100644
index 0000000..0e4f536
--- /dev/null
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -0,0 +1,156 @@
+import {
+  Activity01Icon,
+  DashboardSquare01Icon,
+  Layers01Icon,
+  Logout01Icon,
+  Moon02Icon,
+  PackageIcon,
+  PlugSocketIcon,
+  Settings01Icon,
+  StethoscopeIcon,
+  Sun02Icon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
+import { Link, useRouterState } from '@tanstack/react-router';
+import { useTheme } from 'next-themes';
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuBadge,
+  SidebarMenuButton,
+  SidebarMenuItem,
+} from '@/components/ui/sidebar';
+import { logout } from '@/lib/api';
+import { MOCK_PAGES_ENABLED } from '@/lib/mock';
+import { clearSessionMarker } from '@/lib/session';
+
+interface NavItem {
+  to: string;
+  label: string;
+  icon: NonNullable<HugeiconsProps['icon']>;
+  /** 服务端还没有的页面:dev 里带"预览"角标,生产构建整个隐藏。 */
+  mock?: boolean;
+}
+
+// 平台 = 管的对象(沙箱/模板),运维 = 管这台机器;连接页是给要接 SDK 的人。
+const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
+  {
+    label: '平台',
+    items: [
+      { to: '/', label: '总览', icon: DashboardSquare01Icon },
+      { to: '/sandboxes', label: '沙箱', icon: PackageIcon },
+      { to: '/templates', label: '模板', icon: Layers01Icon },
+    ],
+  },
+  {
+    label: '运维',
+    items: [
+      { to: '/activity', label: '活动', icon: Activity01Icon, mock: true },
+      { to: '/doctor', label: '体检', icon: StethoscopeIcon, mock: true },
+      { to: '/settings', label: '设置', icon: Settings01Icon, mock: true },
+    ],
+  },
+  {
+    label: '接入',
+    items: [{ to: '/connect', label: '连接', icon: PlugSocketIcon }],
+  },
+];
+
+async function signOut() {
+  // 尽力而为:cookie 可能已经死了,无所谓 — 清掉标记回登录页才是正事。
+  await logout().catch(() => undefined);
+  clearSessionMarker();
+  window.location.href = '/console/login';
+}
+
+function isActivePath(pathname: string, to: string): boolean {
+  if (to === '/') return pathname === '/';
+  return pathname === to || pathname.startsWith(`${to}/`);
+}
+
+export function AppSidebar() {
+  const pathname = useRouterState({
+    select: (state) => state.location.pathname,
+  });
+  const { resolvedTheme, setTheme } = useTheme();
+
+  return (
+    <Sidebar>
+      <SidebarHeader>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton size="lg" render={<Link to="/" />}>
+              <div className="flex size-8 items-center justify-center rounded-lg bg-primary text-primary-foreground">
+                <HugeiconsIcon icon={PackageIcon} className="size-4" />
+              </div>
+              <div className="grid leading-tight">
+                <span className="font-semibold">Dormice</span>
+                <span className="text-xs text-muted-foreground">控制台</span>
+              </div>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarHeader>
+
+      <SidebarContent>
+        {NAV_GROUPS.map((group) => {
+          const items = group.items.filter(
+            (item) => !item.mock || MOCK_PAGES_ENABLED,
+          );
+          if (items.length === 0) return null;
+          return (
+            <SidebarGroup key={group.label}>
+              <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
+              <SidebarGroupContent>
+                <SidebarMenu>
+                  {items.map((item) => (
+                    <SidebarMenuItem key={item.to}>
+                      <SidebarMenuButton
+                        isActive={isActivePath(pathname, item.to)}
+                        render={<Link to={item.to} />}
+                      >
+                        <HugeiconsIcon icon={item.icon} strokeWidth={1.8} />
+                        <span>{item.label}</span>
+                      </SidebarMenuButton>
+                      {item.mock && <SidebarMenuBadge>预览</SidebarMenuBadge>}
+                    </SidebarMenuItem>
+                  ))}
+                </SidebarMenu>
+              </SidebarGroupContent>
+            </SidebarGroup>
+          );
+        })}
+      </SidebarContent>
+
+      <SidebarFooter>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton
+              onClick={() =>
+                setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')
+              }
+            >
+              <HugeiconsIcon
+                icon={resolvedTheme === 'dark' ? Sun02Icon : Moon02Icon}
+                strokeWidth={1.8}
+              />
+              <span>{resolvedTheme === 'dark' ? '浅色模式' : '深色模式'}</span>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+          <SidebarMenuItem>
+            <SidebarMenuButton onClick={signOut}>
+              <HugeiconsIcon icon={Logout01Icon} strokeWidth={1.8} />
+              <span>退出登录</span>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarFooter>
+    </Sidebar>
+  );
+}
diff --git a/packages/console/src/components/SampleDataBadge.tsx b/packages/console/src/components/SampleDataBadge.tsx
new file mode 100644
index 0000000..9459401
--- /dev/null
+++ b/packages/console/src/components/SampleDataBadge.tsx
@@ -0,0 +1,17 @@
+import { Badge } from '@/components/ui/badge';
+
+/**
+ * 挂在 mock 页面标题旁的诚实声明:这一页还没有服务端,数据是设计期的
+ * 示例。生产构建里这些页面整个不出现(lib/mock.ts),这枚徽章管的是
+ * dev 里看着它的人。
+ */
+export function SampleDataBadge() {
+  return (
+    <Badge
+      variant="outline"
+      className="border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400"
+    >
+      示例数据
+    </Badge>
+  );
+}
diff --git a/packages/console/src/features/activity/fixtures.ts b/packages/console/src/features/activity/fixtures.ts
new file mode 100644
index 0000000..3d63b7d
--- /dev/null
+++ b/packages/console/src/features/activity/fixtures.ts
@@ -0,0 +1,111 @@
+/**
+ * 提案中的 wire 形状:POST /listActivity 的响应行。事件将来自账本状态
+ * 迁移处的单点埋点(transition/对账/扫描器),存 SQLite 有界环形表
+ * (最近 N 条,溢出丢最老)— 是账本的历史,不是监控系统。落地时这些
+ * 类型进 @dormice/shared,本文件只剩删除。
+ */
+export type ActivityKind =
+  | 'created'
+  | 'woken'
+  | 'frozen'
+  | 'stopped'
+  | 'rebuilt'
+  | 'released'
+  | 'reconciled'
+  | 'expired-killed';
+
+export interface ActivityEvent {
+  id: string;
+  at: string;
+  kind: ActivityKind;
+  userKey: string | null;
+  /** 一句话补充:谁干的、为什么、修了什么。 */
+  detail: string;
+}
+
+export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
+  created: '创建',
+  woken: '唤醒',
+  frozen: '冻结',
+  stopped: '停止',
+  rebuilt: '重建',
+  released: '释放',
+  reconciled: '对账修复',
+  'expired-killed': '到期销毁',
+};
+
+const minutesAgo = (n: number) =>
+  new Date(Date.now() - n * 60_000).toISOString();
+
+export const SAMPLE_ACTIVITY: ActivityEvent[] = [
+  {
+    id: 'evt-01',
+    at: minutesAgo(1),
+    kind: 'frozen',
+    userKey: 'web-scraper',
+    detail: '空闲 5 分钟到阈值,内存挤入 swap(扫描器)',
+  },
+  {
+    id: 'evt-02',
+    at: minutesAgo(3),
+    kind: 'woken',
+    userKey: 'demo-agent',
+    detail: 'execCommand 触达,~50ms 从 frozen 恢复',
+  },
+  {
+    id: 'evt-03',
+    at: minutesAgo(12),
+    kind: 'created',
+    userKey: 'demo-agent',
+    detail: 'acquire 新建,模板 python-ml,策略 冻结 10分钟 · 停止 永不',
+  },
+  {
+    id: 'evt-04',
+    at: minutesAgo(25),
+    kind: 'rebuilt',
+    userKey: 'build-runner',
+    detail: '换壳保盘:下次唤醒用 daemon 当前基础镜像',
+  },
+  {
+    id: 'evt-05',
+    at: minutesAgo(41),
+    kind: 'stopped',
+    userKey: 'docs-writer',
+    detail: '空闲 30 分钟到阈值,容器拆除、磁盘保留(扫描器)',
+  },
+  {
+    id: 'evt-06',
+    at: minutesAgo(58),
+    kind: 'reconciled',
+    userKey: 'email-triage',
+    detail: '容器消失但磁盘还在(疑似 docker prune),账本改记 stopped',
+  },
+  {
+    id: 'evt-07',
+    at: minutesAgo(95),
+    kind: 'expired-killed',
+    userKey: 'ci-check-4821',
+    detail: 'E2B deadline(kill 型)到点,连盘一起销毁',
+  },
+  {
+    id: 'evt-08',
+    at: minutesAgo(130),
+    kind: 'released',
+    userKey: 'scratch-1',
+    detail: 'releaseSandbox:先拆容器再删账本行',
+  },
+  {
+    id: 'evt-09',
+    at: minutesAgo(178),
+    kind: 'created',
+    userKey: 'web-scraper',
+    detail: 'acquire 新建,基础镜像,默认策略',
+  },
+  {
+    id: 'evt-10',
+    at: minutesAgo(240),
+    kind: 'woken',
+    userKey: 'build-runner',
+    detail: '同 key acquire 从 stopped 冷启动重建(盘是本体)',
+  },
+];
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
new file mode 100644
index 0000000..aef335b
--- /dev/null
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -0,0 +1,124 @@
+import { Link } from '@tanstack/react-router';
+import { SampleDataBadge } from '@/components/SampleDataBadge';
+import { Badge } from '@/components/ui/badge';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { since } from '@/features/sandboxes/format';
+import { MOCK_PAGES_ENABLED } from '@/lib/mock';
+import { cn } from '@/lib/utils';
+import {
+  ACTIVITY_KIND_LABELS,
+  type ActivityKind,
+  SAMPLE_ACTIVITY,
+} from '../fixtures';
+
+// 事件色与沙箱状态徽章同一色系:落到哪个状态就穿哪个颜色。
+const KIND_STYLES: Record<ActivityKind, string> = {
+  created:
+    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+  woken:
+    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+  frozen: 'border-sky-500/40 bg-sky-500/10 text-sky-600 dark:text-sky-400',
+  stopped: 'border-border bg-muted text-muted-foreground',
+  rebuilt:
+    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  released: 'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
+  reconciled:
+    'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
+  'expired-killed':
+    'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
+};
+
+/**
+ * 「我不在的时候发生了什么」。生产里等 /listActivity 落地(账本迁移处
+ * 单点埋点 + 有界环形表);眼下用示例数据把版式定下来,生产构建整页隐藏。
+ */
+export function ActivityPage() {
+  if (!MOCK_PAGES_ENABLED) {
+    return (
+      <Empty className="border border-dashed">
+        <EmptyHeader>
+          <EmptyTitle>尚未接入</EmptyTitle>
+          <EmptyDescription>
+            活动流等 listActivity 端点落地后可用。
+          </EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    );
+  }
+
+  return (
+    <>
+      <div className="flex flex-wrap items-center gap-3">
+        <div>
+          <h1 className="flex items-center gap-2 text-lg font-semibold">
+            活动 <SampleDataBadge />
+          </h1>
+          <p className="text-sm text-muted-foreground">
+            账本的历史:谁被创建、冻结、停止、销毁,对账修了什么。 将来自
+            transition() 单点埋点的有界环形记录。
+          </p>
+        </div>
+      </div>
+
+      <div className="overflow-x-auto rounded-lg border">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead className="w-28">时间</TableHead>
+              <TableHead className="w-28">事件</TableHead>
+              <TableHead className="w-40">userKey</TableHead>
+              <TableHead>详情</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {SAMPLE_ACTIVITY.map((event) => (
+              <TableRow key={event.id}>
+                <TableCell className="tabular-nums text-muted-foreground">
+                  {since(event.at)}前
+                </TableCell>
+                <TableCell>
+                  <Badge
+                    variant="outline"
+                    className={cn('font-medium', KIND_STYLES[event.kind])}
+                  >
+                    {ACTIVITY_KIND_LABELS[event.kind]}
+                  </Badge>
+                </TableCell>
+                <TableCell>
+                  {event.userKey ? (
+                    <Link
+                      to="/sandboxes/$userKey"
+                      params={{ userKey: event.userKey }}
+                      search={{ tab: 'overview' as const }}
+                      className="font-mono hover:underline"
+                    >
+                      {event.userKey}
+                    </Link>
+                  ) : (
+                    <span className="text-muted-foreground">—</span>
+                  )}
+                </TableCell>
+                <TableCell className="text-muted-foreground">
+                  {event.detail}
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+    </>
+  );
+}
diff --git a/packages/console/src/features/auth/pages/LoginPage.tsx b/packages/console/src/features/auth/pages/LoginPage.tsx
index 0ff9200..573913d 100644
--- a/packages/console/src/features/auth/pages/LoginPage.tsx
+++ b/packages/console/src/features/auth/pages/LoginPage.tsx
@@ -38,7 +38,7 @@ export function LoginPage() {
         <CardHeader>
           <CardTitle className="text-2xl">Dormice</CardTitle>
           <CardDescription>
-            Paste the daemon's API token to open the console.
+            粘贴 daemon 的 API token 进入控制台。
           </CardDescription>
         </CardHeader>
         <CardContent>
@@ -71,7 +71,7 @@ export function LoginPage() {
               className="w-full"
             >
               {mutation.isPending && <Spinner />}
-              Sign in
+              登录
             </Button>
           </form>
         </CardContent>
diff --git a/packages/console/src/features/connect/pages/ConnectPage.tsx b/packages/console/src/features/connect/pages/ConnectPage.tsx
index 38af80a..5b0f3fb 100644
--- a/packages/console/src/features/connect/pages/ConnectPage.tsx
+++ b/packages/console/src/features/connect/pages/ConnectPage.tsx
@@ -1,6 +1,5 @@
-import { ArrowLeft01Icon, Copy01Icon } from '@hugeicons/core-free-icons';
+import { Copy01Icon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
-import { Link } from '@tanstack/react-router';
 import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
 import {
@@ -38,11 +37,11 @@ function Snippet({ code }: { code: string }) {
         variant="ghost"
         size="icon-sm"
         className="absolute top-1.5 right-1.5"
-        aria-label="Copy to clipboard"
+        aria-label="复制到剪贴板"
         onClick={() =>
           copyText(code).then(
-            () => toast.success('Copied'),
-            () => toast.error('Copy failed — select the text manually'),
+            () => toast.success('已复制'),
+            () => toast.error('复制失败 — 请手动选中文本'),
           )
         }
       >
@@ -71,7 +70,7 @@ const sandbox = await Sandbox.create({
   apiKey: 'e2b_<your API token>',
   apiUrl: '${origin}/e2b/api',
   sandboxUrl: '${origin}/e2b/envd',
-  // Dormice extension: the same userKey always returns the same sandbox.
+  // Dormice 扩展:同一个 userKey 永远回到同一个沙箱。
   metadata: { userKey: 'my-project' },
 });
 
@@ -94,24 +93,14 @@ dor sandbox ls
 dor sandbox exec my-project 'uname -r'`;
 
   return (
-    <main className="mx-auto min-h-screen w-full max-w-3xl px-6 pb-10">
-      <header className="flex items-center gap-3 py-5">
-        <Button
-          variant="ghost"
-          size="icon-sm"
-          nativeButton={false}
-          render={<Link to="/" aria-label="Back to sandboxes" />}
-        >
-          <HugeiconsIcon icon={ArrowLeft01Icon} />
-        </Button>
-        <h1 className="text-lg font-semibold">Connect</h1>
-      </header>
-
+    <div className="mx-auto w-full max-w-3xl">
+      <div className="mb-1">
+        <h1 className="text-lg font-semibold">连接</h1>
+      </div>
       <p className="mb-6 text-sm text-muted-foreground">
-        This daemon is reachable at <code className="font-mono">{origin}</code>{' '}
-        — the address you are reading this page from. Every snippet needs the
-        daemon's API token; the console never stores it, so read it on the
-        daemon host:{' '}
+        这个 daemon 的地址是 <code className="font-mono">{origin}</code> —
+        就是你此刻打开本页用的地址。每段代码都需要 daemon 的 API token;
+        控制台从不保存它,去 daemon 主机上读:{' '}
         <code className="font-mono">
           grep ^DORMICE_API_TOKEN /etc/dormice/env
         </code>
@@ -122,9 +111,9 @@ dor sandbox exec my-project 'uname -r'`;
           <CardHeader>
             <CardTitle>E2B SDK</CardTitle>
             <CardDescription>
-              The official <code className="font-mono">e2b</code> package works
-              as-is — point its two URLs here and prefix your token with{' '}
-              <code className="font-mono">e2b_</code>. No other code changes.
+              官方 <code className="font-mono">e2b</code> 包原样可用 — 把两个
+              URL 指到这里,token 加 <code className="font-mono">e2b_</code>{' '}
+              前缀,别的代码一行不改。
             </CardDescription>
           </CardHeader>
           <CardContent>
@@ -134,11 +123,10 @@ dor sandbox exec my-project 'uname -r'`;
 
         <Card>
           <CardHeader>
-            <CardTitle>Native SDK</CardTitle>
+            <CardTitle>原生 SDK</CardTitle>
             <CardDescription>
-              <code className="font-mono">@dormice/sdk</code> speaks the
-              daemon's native RPC — acquire is idempotent by design. Not
-              published to npm yet; build it from the repository workspace.
+              <code className="font-mono">@dormice/sdk</code> 说 daemon 的 原生
+              RPC — acquire 天生幂等。尚未发布到 npm,从仓库 workspace 构建使用。
             </CardDescription>
           </CardHeader>
           <CardContent>
@@ -150,8 +138,8 @@ dor sandbox exec my-project 'uname -r'`;
           <CardHeader>
             <CardTitle>CLI</CardTitle>
             <CardDescription>
-              <code className="font-mono">dor</code> (installed alongside the
-              daemon by install.sh) reads these two environment variables.
+              <code className="font-mono">dor</code>(install.sh 随 daemon
+              一起装的)读这两个环境变量。
             </CardDescription>
           </CardHeader>
           <CardContent>
@@ -159,6 +147,6 @@ dor sandbox exec my-project 'uname -r'`;
           </CardContent>
         </Card>
       </div>
-    </main>
+    </div>
   );
 }
diff --git a/packages/console/src/features/doctor/fixtures.ts b/packages/console/src/features/doctor/fixtures.ts
new file mode 100644
index 0000000..0edb703
--- /dev/null
+++ b/packages/console/src/features/doctor/fixtures.ts
@@ -0,0 +1,152 @@
+/**
+ * 提案中的 wire 形状:POST /runDoctor 的响应(daemon 内跑 CLI 同一套
+ * 只读检查,规则单一来源在 packages/cli/src/doctor.ts)。检查 ID 与真
+ * doctor 一比一 — 版式对着真实的 20 项设计,不发明假检查。落地时类型
+ * 进 shared,本文件只剩删除。
+ */
+export type DoctorStatus = 'pass' | 'warn' | 'fail' | 'skip';
+
+export interface DoctorCheck {
+  id: string;
+  title: string;
+  status: DoctorStatus;
+  /** 检查到的事实,一句话。 */
+  detail: string;
+  /** fail/warn 时点名的修复命令(doctor 只读不代修,修是 install.sh 的活)。 */
+  fix?: string;
+}
+
+export interface DoctorReport {
+  ranAt: string;
+  durationMs: number;
+  checks: DoctorCheck[];
+}
+
+export const SAMPLE_DOCTOR: DoctorReport = {
+  ranAt: new Date(Date.now() - 42_000).toISOString(),
+  durationMs: 4213,
+  checks: [
+    {
+      id: 'os-linux',
+      title: 'Linux x86_64',
+      status: 'pass',
+      detail: 'Ubuntu 24.04,内核 6.8.0',
+    },
+    {
+      id: 'node-version',
+      title: 'Node ≥ 22',
+      status: 'pass',
+      detail: 'v24.18.0',
+    },
+    {
+      id: 'root',
+      title: 'root 权限',
+      status: 'pass',
+      detail: 'uid 0 — loop 挂载与 cgroup 写入可用',
+    },
+    {
+      id: 'cgroup-v2',
+      title: 'cgroup v2 + memory 控制器',
+      status: 'pass',
+      detail: '冻结要写 memory.reclaim',
+    },
+    {
+      id: 'docker-daemon',
+      title: 'Docker daemon 可达',
+      status: 'pass',
+      detail: 'dockerd 29.6.1 应答正常',
+    },
+    {
+      id: 'gvisor-runtime',
+      title: 'runsc 已注册为 Docker runtime',
+      status: 'pass',
+      detail: 'gVisor release-20260622.0',
+    },
+    {
+      id: 'icc-disabled',
+      title: '容器间通信已关(icc: false)',
+      status: 'pass',
+      detail: '沙箱之间互相不可达',
+    },
+    {
+      id: 'log-rotation',
+      title: 'Docker 日志轮转',
+      status: 'pass',
+      detail: 'json-file,10m × 3',
+    },
+    {
+      id: 'swap',
+      title: 'swap 存在',
+      status: 'pass',
+      detail: '16 GiB /swapfile — 冻结的内存要有地方去',
+    },
+    {
+      id: 'swappiness',
+      title: 'vm.swappiness = 100',
+      status: 'pass',
+      detail:
+        '直读 /proc/sys/vm/swappiness 的生效值 — gVisor 的共享内存低于 100 挤不出去',
+    },
+    {
+      id: 'metadata-firewall',
+      title: '云元数据防火墙',
+      status: 'pass',
+      detail: 'DOCKER-USER 链 DROP 169.254.0.0/16 与 100.100.100.200',
+    },
+    {
+      id: 'metadata-persisted',
+      title: '防火墙规则已持久化',
+      status: 'pass',
+      detail: '/etc/iptables/rules.v4 在,重启不丢',
+    },
+    {
+      id: 'api-token',
+      title: 'DORMICE_API_TOKEN 已配置',
+      status: 'pass',
+      detail: '存在且非空(不显示内容)',
+    },
+    {
+      id: 'base-image',
+      title: '基础镜像存在',
+      status: 'pass',
+      detail: 'dormice-base:20260710b 在本机镜像库',
+    },
+    {
+      id: 'absolute-paths',
+      title: 'DB/数据目录是绝对路径',
+      status: 'pass',
+      detail: '相对路径离"空账本撞真沙箱"只差一次走错目录',
+    },
+    {
+      id: 'disk-space',
+      title: '数据盘余量',
+      status: 'pass',
+      detail: '/var/lib/dormice 所在盘剩 162.4 GiB',
+    },
+    {
+      id: 'probe-gvisor',
+      title: '探针:假内核',
+      status: 'pass',
+      detail: '起真 runsc 容器,uname -r = 4.19.0-gvisor(宿主 6.8.0)',
+    },
+    {
+      id: 'probe-metadata',
+      title: '探针:元数据被封',
+      status: 'pass',
+      detail: '沙箱内 curl 169.254.169.254 超时 — BLOCKED',
+    },
+    {
+      id: 'probe-image-user',
+      title: '探针:默认身份 uid 1000',
+      status: 'pass',
+      detail: '沙箱内 id -u = 1000,非 root',
+    },
+    {
+      id: 'probe-image-inotify',
+      title: '探针:镜像带 inotify-tools',
+      status: 'warn',
+      detail: '镜像里没找到 inotifywait — E2B watch 功能会诚实报错',
+      fix: '重建基础镜像(images/Dockerfile 已含 inotify-tools),更新 /etc/dormice/env 后重启 daemon',
+    },
+  ],
+};
diff --git a/packages/console/src/features/doctor/pages/DoctorPage.tsx b/packages/console/src/features/doctor/pages/DoctorPage.tsx
new file mode 100644
index 0000000..4c54a5f
--- /dev/null
+++ b/packages/console/src/features/doctor/pages/DoctorPage.tsx
@@ -0,0 +1,181 @@
+import {
+  Alert02Icon,
+  CancelCircleIcon,
+  CheckmarkCircle02Icon,
+  MinusSignIcon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
+import { SampleDataBadge } from '@/components/SampleDataBadge';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent } from '@/components/ui/card';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@/components/ui/tooltip';
+import { since } from '@/features/sandboxes/format';
+import { MOCK_PAGES_ENABLED } from '@/lib/mock';
+import { cn } from '@/lib/utils';
+import { type DoctorStatus, SAMPLE_DOCTOR } from '../fixtures';
+
+const STATUS_META: Record<
+  DoctorStatus,
+  {
+    icon: NonNullable<HugeiconsProps['icon']>;
+    className: string;
+    label: string;
+  }
+> = {
+  pass: {
+    icon: CheckmarkCircle02Icon,
+    className: 'text-emerald-600 dark:text-emerald-400',
+    label: '通过',
+  },
+  warn: {
+    icon: Alert02Icon,
+    className: 'text-amber-600 dark:text-amber-400',
+    label: '警告',
+  },
+  fail: {
+    icon: CancelCircleIcon,
+    className: 'text-red-600 dark:text-red-400',
+    label: '失败',
+  },
+  skip: {
+    icon: MinusSignIcon,
+    className: 'text-muted-foreground',
+    label: '跳过',
+  },
+};
+
+/**
+ * `dor doctor` 的浏览器版:同一套只读检查(规则单一来源在 CLI),回答
+ * "这台机器能不能跑 daemon"。生产里等 /runDoctor 端点落地 — 它要在
+ * daemon 里起真探针容器,不是纯前端能演的;眼下示例数据定版式。
+ */
+export function DoctorPage() {
+  if (!MOCK_PAGES_ENABLED) {
+    return (
+      <Empty className="border border-dashed">
+        <EmptyHeader>
+          <EmptyTitle>尚未接入</EmptyTitle>
+          <EmptyDescription>
+            浏览器里跑体检要等 runDoctor 端点落地;现在请在主机上执行{' '}
+            <code className="font-mono">dor doctor</code>。
+          </EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    );
+  }
+
+  const report = SAMPLE_DOCTOR;
+  const counts = report.checks.reduce(
+    (acc, check) => {
+      acc[check.status] += 1;
+      return acc;
+    },
+    { pass: 0, warn: 0, fail: 0, skip: 0 } as Record<DoctorStatus, number>,
+  );
+
+  return (
+    <>
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div>
+          <h1 className="flex items-center gap-2 text-lg font-semibold">
+            体检 <SampleDataBadge />
+          </h1>
+          <p className="text-sm text-muted-foreground">
+            与 <code className="font-mono">dor doctor</code> 同一套只读检查:
+            这台机器能不能跑 daemon。只查不修,修是 install.sh 的活。
+          </p>
+        </div>
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <span>
+                <Button size="sm" disabled>
+                  重新体检
+                </Button>
+              </span>
+            }
+          />
+          <TooltipContent>接入 runDoctor 端点后可用</TooltipContent>
+        </Tooltip>
+      </div>
+
+      <div className="flex flex-wrap items-center gap-2 text-sm">
+        <Badge
+          variant="outline"
+          className="border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400"
+        >
+          {counts.pass} 通过
+        </Badge>
+        {counts.warn > 0 && (
+          <Badge
+            variant="outline"
+            className="border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400"
+          >
+            {counts.warn} 警告
+          </Badge>
+        )}
+        {counts.fail > 0 && (
+          <Badge
+            variant="outline"
+            className="border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400"
+          >
+            {counts.fail} 失败
+          </Badge>
+        )}
+        <span className="text-muted-foreground">
+          {since(report.ranAt)}前跑完,耗时{' '}
+          {(report.durationMs / 1000).toFixed(1)}s(含 3 个真容器探针)
+        </span>
+      </div>
+
+      <Card>
+        <CardContent>
+          <ul className="divide-y">
+            {report.checks.map((check) => {
+              const meta = STATUS_META[check.status];
+              return (
+                <li key={check.id} className="flex items-start gap-3 py-3">
+                  <HugeiconsIcon
+                    icon={meta.icon}
+                    className={cn('mt-0.5 size-4 shrink-0', meta.className)}
+                    strokeWidth={2}
+                  />
+                  <div className="min-w-0 flex-1">
+                    <div className="flex flex-wrap items-baseline gap-x-2">
+                      <span className="text-sm font-medium">{check.title}</span>
+                      <span className="font-mono text-xs text-muted-foreground">
+                        {check.id}
+                      </span>
+                    </div>
+                    <p className="text-sm text-muted-foreground">
+                      {check.detail}
+                    </p>
+                    {check.fix && (
+                      <p className={cn('mt-1 text-sm', meta.className)}>
+                        修复:{check.fix}
+                      </p>
+                    )}
+                  </div>
+                  <span className={cn('text-xs', meta.className)}>
+                    {meta.label}
+                  </span>
+                </li>
+              );
+            })}
+          </ul>
+        </CardContent>
+      </Card>
+    </>
+  );
+}
diff --git a/packages/console/src/features/overview/components/OverviewCards.tsx b/packages/console/src/features/overview/components/OverviewCards.tsx
index 81953cf..bdea545 100644
--- a/packages/console/src/features/overview/components/OverviewCards.tsx
+++ b/packages/console/src/features/overview/components/OverviewCards.tsx
@@ -12,8 +12,9 @@ import type { ReactNode } from 'react';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import { Card, CardContent } from '@/components/ui/card';
 import { Skeleton } from '@/components/ui/skeleton';
+import { STATE_LABELS } from '@/features/sandboxes/format';
+import { formatBytes, pctOf } from '@/lib/format';
 import { cn } from '@/lib/utils';
-import { formatBytes, pctOf } from '../format';
 import { useHostMetrics } from '../hooks/useHostMetrics';
 
 /**
@@ -98,7 +99,7 @@ function StateCounts({
             <span className="font-medium text-foreground">
               {byState[s.key]}
             </span>
-            {s.key}
+            {STATE_LABELS[s.key]}
           </span>
         ),
       )}
@@ -149,14 +150,14 @@ export function OverviewCards() {
           value={
             host.cpuUsedPct === null ? '—' : `${Math.round(host.cpuUsedPct)}%`
           }
-          hint={`${host.cpuCount} core${host.cpuCount === 1 ? '' : 's'}`}
+          hint={`${host.cpuCount} 核`}
           pct={host.cpuUsedPct}
         />
         <StatCard
           icon={RamMemoryIcon}
-          label="Memory"
+          label="内存"
           value={formatBytes(memUsed)}
-          hint={`of ${formatBytes(host.memTotalBytes)} · ${formatBytes(host.memAvailableBytes)} available`}
+          hint={`共 ${formatBytes(host.memTotalBytes)} · 可用 ${formatBytes(host.memAvailableBytes)}`}
           pct={pctOf(memUsed, host.memTotalBytes)}
         />
         {host.swap === null ? (
@@ -164,16 +165,16 @@ export function OverviewCards() {
             icon={SnowIcon}
             label="Swap"
             value="—"
-            hint="no reading on this platform"
+            hint="此平台读不到 swap"
           />
         ) : host.swap.totalBytes === 0 ? (
           <StatCard
             icon={SnowIcon}
             label="Swap"
-            value="none"
+            value="未配置"
             hint={
               <span className="text-amber-600 dark:text-amber-500">
-                freezing needs swap — see dor doctor
+                冻结依赖 swap — 见 dor doctor
               </span>
             }
           />
@@ -182,25 +183,25 @@ export function OverviewCards() {
             icon={SnowIcon}
             label="Swap"
             value={formatBytes(host.swap.usedBytes)}
-            hint={`of ${formatBytes(host.swap.totalBytes)} · frozen sandboxes live here`}
+            hint={`共 ${formatBytes(host.swap.totalBytes)} · 冻结的沙箱住在这里`}
             pct={pctOf(host.swap.usedBytes, host.swap.totalBytes)}
           />
         )}
         {dataDisk === null ? (
           <StatCard
             icon={HardDriveIcon}
-            label="Data disk"
+            label="数据盘"
             value="—"
-            hint="no data directory on this host"
+            hint="这台主机没有数据目录"
           />
         ) : (
           <StatCard
             icon={HardDriveIcon}
-            label="Data disk"
+            label="数据盘"
             value={formatBytes(dataDisk.usedBytes)}
             hint={
               <span title={dataDisk.path}>
-                {`of ${formatBytes(dataDisk.totalBytes)} · ${formatBytes(dataDisk.availableBytes)} free`}
+                {`共 ${formatBytes(dataDisk.totalBytes)} · 剩 ${formatBytes(dataDisk.availableBytes)}`}
               </span>
             }
             pct={pctOf(dataDisk.usedBytes, dataDisk.totalBytes)}
@@ -211,16 +212,16 @@ export function OverviewCards() {
       <div className="grid gap-4 md:grid-cols-2">
         <StatCard
           icon={PackageIcon}
-          label="Sandboxes"
+          label="沙箱"
           value={`${sandboxes.total} / ${sandboxes.maxSandboxes}`}
           hint={<StateCounts byState={sandboxes.byState} />}
           pct={pctOf(sandboxes.total, sandboxes.maxSandboxes)}
         />
         <StatCard
           icon={Database01Icon}
-          label="Sandbox disks"
+          label="沙箱磁盘"
           value={formatBytes(sandboxDisks.actualBytes)}
-          hint={`promised ${formatBytes(sandboxDisks.nominalBytes)} across ${sandboxDisks.count} disk${sandboxDisks.count === 1 ? '' : 's'} — sparse images only cost what they hold`}
+          hint={`${sandboxDisks.count} 块盘共许诺 ${formatBytes(sandboxDisks.nominalBytes)} — 稀疏镜像只为真实内容付费`}
           pct={pctOf(sandboxDisks.actualBytes, sandboxDisks.nominalBytes)}
         />
       </div>
diff --git a/packages/console/src/features/overview/pages/OverviewPage.tsx b/packages/console/src/features/overview/pages/OverviewPage.tsx
new file mode 100644
index 0000000..ff26a2f
--- /dev/null
+++ b/packages/console/src/features/overview/pages/OverviewPage.tsx
@@ -0,0 +1,19 @@
+import { OverviewCards } from '../components/OverviewCards';
+
+/**
+ * 回答两个问题:这台机器还好吗、这群沙箱花了它多少。数字全部来自
+ * /getHostMetrics 单次快照 — 观察窗,不是监控系统。
+ */
+export function OverviewPage() {
+  return (
+    <>
+      <div>
+        <h1 className="text-lg font-semibold">总览</h1>
+        <p className="text-sm text-muted-foreground">
+          这台机器的健康状况,与沙箱群花掉的资源。
+        </p>
+      </div>
+      <OverviewCards />
+    </>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
index cb4a641..5d4deaf 100644
--- a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
+++ b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
@@ -27,8 +27,8 @@ import {
 } from '@/components/ui/native-select';
 import { Spinner } from '@/components/ui/spinner';
 import { Switch } from '@/components/ui/switch';
+import { useTemplates } from '@/features/templates/hooks/useTemplates';
 import { useAcquireSandbox } from '../hooks/useSandboxes';
-import { useTemplates } from '../hooks/useTemplates';
 
 /**
  * The console speaks the same verb as everyone else: acquire. Same key,
@@ -72,7 +72,7 @@ export function CreateSandboxDialog() {
       },
       {
         onSuccess: ({ sandbox }) => {
-          toast.success(`Sandbox ready for “${sandbox.userKey}”`);
+          toast.success(`「${sandbox.userKey}」的沙箱已就绪`);
           setOpen(false);
           reset();
         },
@@ -92,16 +92,16 @@ export function CreateSandboxDialog() {
         render={
           <Button size="sm">
             <HugeiconsIcon icon={Add01Icon} />
-            Create sandbox
+            创建沙箱
           </Button>
         }
       />
       <DialogContent className="sm:max-w-md">
         <DialogHeader>
-          <DialogTitle>Create a sandbox</DialogTitle>
+          <DialogTitle>创建沙箱</DialogTitle>
           <DialogDescription>
-            Acquire is idempotent: if this key already has a sandbox, you get
-            that one back and the policy below is ignored.
+            acquire 是幂等的:这个 key 已经有沙箱时,拿回的是原来那个,
+            下面的策略会被忽略。
           </DialogDescription>
         </DialogHeader>
         <form
@@ -112,7 +112,7 @@ export function CreateSandboxDialog() {
         >
           <FieldGroup>
             <Field>
-              <FieldLabel htmlFor="create-user-key">User key</FieldLabel>
+              <FieldLabel htmlFor="create-user-key">userKey</FieldLabel>
               <Input
                 id="create-user-key"
                 value={userKey}
@@ -122,20 +122,20 @@ export function CreateSandboxDialog() {
                 className="font-mono"
               />
               <FieldDescription>
-                The caller-chosen identity acquire is idempotent on — the same
-                key always comes back to the same sandbox.
+                调用方自选的身份,acquire 对它幂等 — 同一个 key 永远回到
+                同一个沙箱。
               </FieldDescription>
             </Field>
             {templates.length > 0 && (
               <Field>
-                <FieldLabel htmlFor="create-template">Template</FieldLabel>
+                <FieldLabel htmlFor="create-template">模板</FieldLabel>
                 <NativeSelect
                   id="create-template"
                   className="w-full"
                   value={template}
                   onChange={(event) => setTemplate(event.target.value)}
                 >
-                  <NativeSelectOption value="">Base image</NativeSelectOption>
+                  <NativeSelectOption value="">基础镜像</NativeSelectOption>
                   {templates.map((t) => (
                     <NativeSelectOption key={t.name} value={t.name}>
                       {t.name} ({t.image})
@@ -143,14 +143,13 @@ export function CreateSandboxDialog() {
                   ))}
                 </NativeSelect>
                 <FieldDescription>
-                  Applied only when this key creates a new sandbox. Register
-                  templates with `dor template add`.
+                  只在这个 key 真正新建沙箱时生效;对已有沙箱静默不应用。
                 </FieldDescription>
               </Field>
             )}
             <Field>
               <FieldLabel htmlFor="create-freeze-after">
-                Freeze after idle (seconds)
+                空闲多久后冻结(秒)
               </FieldLabel>
               <Input
                 id="create-freeze-after"
@@ -158,11 +157,10 @@ export function CreateSandboxDialog() {
                 min={1}
                 value={freezeAfter}
                 onChange={(event) => setFreezeAfter(event.target.value)}
-                placeholder="600 (daemon default)"
+                placeholder="600(daemon 默认)"
               />
               <FieldDescription>
-                Idle time until active → frozen: memory squeezed to swap, ~50ms
-                to wake.
+                运行中 → 已冻结的空闲阈值:内存挤入 swap,唤醒约 50ms。
               </FieldDescription>
             </Field>
             <Field orientation="horizontal">
@@ -172,13 +170,13 @@ export function CreateSandboxDialog() {
                 onCheckedChange={setNeverStop}
               />
               <FieldLabel htmlFor="create-never-stop">
-                Never stop (resident agent)
+                永不停止(常驻 agent)
               </FieldLabel>
             </Field>
             {!neverStop && (
               <Field>
                 <FieldLabel htmlFor="create-stop-after">
-                  Stop after idle (seconds)
+                  空闲多久后停止(秒)
                 </FieldLabel>
                 <Input
                   id="create-stop-after"
@@ -186,11 +184,10 @@ export function CreateSandboxDialog() {
                   min={1}
                   value={stopAfter}
                   onChange={(event) => setStopAfter(event.target.value)}
-                  placeholder="259200 (daemon default)"
+                  placeholder="259200(daemon 默认)"
                 />
                 <FieldDescription>
-                  Idle time until frozen → stopped: only the disk stays, waking
-                  is a cold start.
+                  已冻结 → 已停止的空闲阈值:只留磁盘,唤醒是冷启动。
                 </FieldDescription>
               </Field>
             )}
@@ -204,7 +201,7 @@ export function CreateSandboxDialog() {
               disabled={userKey.length === 0 || mutation.isPending}
             >
               {mutation.isPending && <Spinner />}
-              Create
+              创建
             </Button>
           </DialogFooter>
         </form>
diff --git a/packages/console/src/features/sandboxes/components/FilesPanel.tsx b/packages/console/src/features/sandboxes/components/FilesPanel.tsx
new file mode 100644
index 0000000..a417ddc
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/FilesPanel.tsx
@@ -0,0 +1,467 @@
+import type { Sandbox } from '@dormice/shared';
+import {
+  Delete02Icon,
+  Download01Icon,
+  Edit02Icon,
+  File01Icon,
+  Folder01Icon,
+  FolderAddIcon,
+  MoreVerticalIcon,
+  RefreshIcon,
+  Upload01Icon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { Fragment, useRef, useState } from 'react';
+import { toast } from 'sonner';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@/components/ui/alert-dialog';
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@/components/ui/breadcrumb';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { formatBytes } from '@/lib/format';
+import type { EnvdEntry } from '../envd-client';
+import { STATE_LABELS } from '../format';
+import { useDirectory, useEnvdAuth, useFileMutations } from '../hooks/useEnvd';
+
+const HOME = '/home/user';
+
+/** /home/user 下的面包屑段;根显示为 ~。 */
+function segmentsOf(path: string): Array<{ label: string; path: string }> {
+  const crumbs = [{ label: '~', path: HOME }];
+  if (path === HOME) return crumbs;
+  let acc = HOME;
+  for (const segment of path.slice(HOME.length + 1).split('/')) {
+    acc = `${acc}/${segment}`;
+    crumbs.push({ label: segment, path: acc });
+  }
+  return crumbs;
+}
+
+function sortEntries(entries: EnvdEntry[]): EnvdEntry[] {
+  return [...entries].sort((a, b) => {
+    const aDir = a.type === 'FILE_TYPE_DIRECTORY' ? 0 : 1;
+    const bDir = b.type === 'FILE_TYPE_DIRECTORY' ? 0 : 1;
+    return aDir - bDir || a.name.localeCompare(b.name);
+  });
+}
+
+/**
+ * 沙箱内 /home/user 的文件浏览器,走 envd 的 Filesystem RPC 与文件面 —
+ * 与官方 e2b SDK 同一条 wire。文件动词会唤醒冻结的沙箱,所以非 active
+ * 状态下第一步是一次显式的"打开"(与终端同一条纪律:看不解冻,用才解冻)。
+ */
+export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
+  const [unlocked, setUnlocked] = useState(sandbox.state === 'active');
+  const [path, setPath] = useState(HOME);
+  const auth = useEnvdAuth(sandbox.sandboxId);
+  const directory = useDirectory(auth.data, path, unlocked);
+  const mutations = useFileMutations(auth.data);
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+
+  // 对话框状态:新建文件夹 / 重命名 / 删除,一次只开一个。
+  const [mkdirOpen, setMkdirOpen] = useState(false);
+  const [mkdirName, setMkdirName] = useState('');
+  const [renaming, setRenaming] = useState<EnvdEntry | null>(null);
+  const [renameTo, setRenameTo] = useState('');
+  const [deleting, setDeleting] = useState<EnvdEntry | null>(null);
+
+  if (!unlocked) {
+    return (
+      <Empty className="border border-dashed">
+        <EmptyHeader>
+          <EmptyMedia variant="icon">
+            <HugeiconsIcon icon={Folder01Icon} />
+          </EmptyMedia>
+          <EmptyTitle>文件浏览器</EmptyTitle>
+          <EmptyDescription>
+            沙箱当前是「{STATE_LABELS[sandbox.state]}」— 浏览文件会唤醒它
+            (冻结约 50ms,停止需要几秒冷启动)。看这一页本身不会。
+          </EmptyDescription>
+        </EmptyHeader>
+        <Button size="sm" onClick={() => setUnlocked(true)}>
+          打开文件浏览器
+        </Button>
+      </Empty>
+    );
+  }
+
+  const entries = sortEntries(directory.data ?? []);
+
+  const upload = (file: File) => {
+    mutations.upload.mutate(
+      { path: `${path}/${file.name}`, file },
+      {
+        onSuccess: () => toast.success(`已上传 ${file.name}`),
+        onError: (error) => toast.error(error.message),
+      },
+    );
+  };
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <Breadcrumb>
+          <BreadcrumbList>
+            {segmentsOf(path).map((crumb, index, all) => (
+              <Fragment key={crumb.path}>
+                {index > 0 && <BreadcrumbSeparator />}
+                <BreadcrumbItem>
+                  {index === all.length - 1 ? (
+                    <BreadcrumbPage className="font-mono">
+                      {crumb.label}
+                    </BreadcrumbPage>
+                  ) : (
+                    <button
+                      type="button"
+                      className="font-mono transition-colors hover:text-foreground"
+                      onClick={() => setPath(crumb.path)}
+                    >
+                      {crumb.label}
+                    </button>
+                  )}
+                </BreadcrumbItem>
+              </Fragment>
+            ))}
+          </BreadcrumbList>
+        </Breadcrumb>
+        <div className="flex items-center gap-2">
+          <input
+            ref={fileInputRef}
+            type="file"
+            className="hidden"
+            onChange={(event) => {
+              const file = event.target.files?.[0];
+              if (file) upload(file);
+              event.target.value = '';
+            }}
+          />
+          <Button
+            variant="outline"
+            size="sm"
+            disabled={mutations.upload.isPending}
+            onClick={() => fileInputRef.current?.click()}
+          >
+            {mutations.upload.isPending ? (
+              <Spinner />
+            ) : (
+              <HugeiconsIcon icon={Upload01Icon} />
+            )}
+            上传
+          </Button>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => {
+              setMkdirName('');
+              setMkdirOpen(true);
+            }}
+          >
+            <HugeiconsIcon icon={FolderAddIcon} />
+            新建文件夹
+          </Button>
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            aria-label="刷新"
+            onClick={() => void directory.refetch()}
+          >
+            <HugeiconsIcon icon={RefreshIcon} />
+          </Button>
+        </div>
+      </div>
+
+      {(directory.isError || auth.isError) && (
+        <Alert variant="destructive">
+          <AlertDescription>
+            {directory.error?.message ?? auth.error?.message}
+          </AlertDescription>
+        </Alert>
+      )}
+
+      {directory.isLoading && (
+        <div className="flex items-center gap-2 rounded-lg border p-4 text-sm text-muted-foreground">
+          <Spinner /> 读取目录(沉睡的沙箱会先被唤醒)
+        </div>
+      )}
+
+      {directory.isSuccess && entries.length === 0 && (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyTitle>空目录</EmptyTitle>
+            <EmptyDescription>上传一个文件试试。</EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      )}
+
+      {entries.length > 0 && (
+        <div className="overflow-x-auto rounded-lg border">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>名称</TableHead>
+                <TableHead>大小</TableHead>
+                <TableHead>权限</TableHead>
+                <TableHead>修改时间</TableHead>
+                <TableHead className="w-12" />
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {entries.map((entry) => {
+                const isDir = entry.type === 'FILE_TYPE_DIRECTORY';
+                return (
+                  <TableRow key={entry.path}>
+                    <TableCell>
+                      {isDir ? (
+                        <button
+                          type="button"
+                          className="inline-flex items-center gap-2 font-medium hover:underline"
+                          onClick={() => setPath(entry.path)}
+                        >
+                          <HugeiconsIcon
+                            icon={Folder01Icon}
+                            className="size-4 text-sky-500"
+                          />
+                          {entry.name}
+                        </button>
+                      ) : (
+                        <span className="inline-flex items-center gap-2">
+                          <HugeiconsIcon
+                            icon={File01Icon}
+                            className="size-4 text-muted-foreground"
+                          />
+                          {entry.name}
+                        </span>
+                      )}
+                    </TableCell>
+                    <TableCell className="tabular-nums text-muted-foreground">
+                      {isDir ? '—' : formatBytes(Number(entry.size))}
+                    </TableCell>
+                    <TableCell className="font-mono text-xs text-muted-foreground">
+                      {entry.permissions}
+                    </TableCell>
+                    <TableCell className="text-muted-foreground">
+                      {new Date(entry.modifiedTime).toLocaleString()}
+                    </TableCell>
+                    <TableCell>
+                      <DropdownMenu>
+                        <DropdownMenuTrigger
+                          render={
+                            <Button
+                              variant="ghost"
+                              size="icon-sm"
+                              aria-label={`${entry.name} 的操作`}
+                            >
+                              <HugeiconsIcon icon={MoreVerticalIcon} />
+                            </Button>
+                          }
+                        />
+                        <DropdownMenuContent align="end">
+                          {!isDir && (
+                            <DropdownMenuItem
+                              onClick={() =>
+                                mutations.download.mutate(
+                                  { path: entry.path, name: entry.name },
+                                  {
+                                    onError: (error) =>
+                                      toast.error(error.message),
+                                  },
+                                )
+                              }
+                            >
+                              <HugeiconsIcon icon={Download01Icon} />
+                              下载
+                            </DropdownMenuItem>
+                          )}
+                          <DropdownMenuItem
+                            onClick={() => {
+                              setRenaming(entry);
+                              setRenameTo(entry.name);
+                            }}
+                          >
+                            <HugeiconsIcon icon={Edit02Icon} />
+                            重命名
+                          </DropdownMenuItem>
+                          <DropdownMenuItem
+                            variant="destructive"
+                            onClick={() => setDeleting(entry)}
+                          >
+                            <HugeiconsIcon icon={Delete02Icon} />
+                            删除
+                          </DropdownMenuItem>
+                        </DropdownMenuContent>
+                      </DropdownMenu>
+                    </TableCell>
+                  </TableRow>
+                );
+              })}
+            </TableBody>
+          </Table>
+        </div>
+      )}
+
+      {/* 新建文件夹 */}
+      <Dialog open={mkdirOpen} onOpenChange={setMkdirOpen}>
+        <DialogContent className="sm:max-w-sm">
+          <DialogHeader>
+            <DialogTitle>新建文件夹</DialogTitle>
+          </DialogHeader>
+          <form
+            onSubmit={(event) => {
+              event.preventDefault();
+              mutations.mkdir.mutate(`${path}/${mkdirName}`, {
+                onSuccess: () => setMkdirOpen(false),
+                onError: (error) => toast.error(error.message),
+              });
+            }}
+          >
+            <Input
+              autoFocus
+              value={mkdirName}
+              onChange={(event) => setMkdirName(event.target.value)}
+              placeholder="文件夹名"
+              className="font-mono"
+            />
+            <DialogFooter className="mt-4">
+              <Button
+                type="submit"
+                disabled={mkdirName === '' || mutations.mkdir.isPending}
+              >
+                {mutations.mkdir.isPending && <Spinner />}
+                创建
+              </Button>
+            </DialogFooter>
+          </form>
+        </DialogContent>
+      </Dialog>
+
+      {/* 重命名 */}
+      <Dialog
+        open={renaming !== null}
+        onOpenChange={(open) => {
+          if (!open) setRenaming(null);
+        }}
+      >
+        <DialogContent className="sm:max-w-sm">
+          <DialogHeader>
+            <DialogTitle>重命名「{renaming?.name}」</DialogTitle>
+          </DialogHeader>
+          <form
+            onSubmit={(event) => {
+              event.preventDefault();
+              if (!renaming) return;
+              mutations.move.mutate(
+                {
+                  source: renaming.path,
+                  destination: `${path}/${renameTo}`,
+                },
+                {
+                  onSuccess: () => setRenaming(null),
+                  onError: (error) => toast.error(error.message),
+                },
+              );
+            }}
+          >
+            <Input
+              autoFocus
+              value={renameTo}
+              onChange={(event) => setRenameTo(event.target.value)}
+              className="font-mono"
+            />
+            <DialogFooter className="mt-4">
+              <Button
+                type="submit"
+                disabled={
+                  renameTo === '' ||
+                  renameTo === renaming?.name ||
+                  mutations.move.isPending
+                }
+              >
+                {mutations.move.isPending && <Spinner />}
+                重命名
+              </Button>
+            </DialogFooter>
+          </form>
+        </DialogContent>
+      </Dialog>
+
+      {/* 删除 */}
+      <AlertDialog
+        open={deleting !== null}
+        onOpenChange={(open) => {
+          if (!open) setDeleting(null);
+        }}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>删除「{deleting?.name}」?</AlertDialogTitle>
+            <AlertDialogDescription>
+              {deleting?.type === 'FILE_TYPE_DIRECTORY'
+                ? '整个目录连同里面的一切一起删除,'
+                : ''}
+              删了就没有了 — 沙箱里没有回收站。
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>先留着</AlertDialogCancel>
+            <AlertDialogAction
+              variant="destructive"
+              onClick={() => {
+                if (!deleting) return;
+                mutations.remove.mutate(deleting.path, {
+                  onSuccess: () => setDeleting(null),
+                  onError: (error) => toast.error(error.message),
+                });
+              }}
+            >
+              删除
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
new file mode 100644
index 0000000..1ef608e
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
@@ -0,0 +1,145 @@
+import type { Sandbox } from '@dormice/shared';
+import {
+  CpuIcon,
+  HardDriveIcon,
+  RamMemoryIcon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
+import { SampleDataBadge } from '@/components/SampleDataBadge';
+import { Card, CardContent } from '@/components/ui/card';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import { formatBytes, pctOf } from '@/lib/format';
+import { MOCK_PAGES_ENABLED } from '@/lib/mock';
+import { cn } from '@/lib/utils';
+
+/**
+ * 提案中的 wire 形状:原生 POST /getSandboxMetrics { userKey } 的响应。
+ * 单次快照,与 getHostMetrics/E2B getMetrics 同一原则 — 观察窗不是监控
+ * 系统;执行器的 metrics() 动词已经存在,服务端落地时这个类型进 shared。
+ */
+interface SandboxMetricsSample {
+  timestamp: string;
+  cpuCount: number;
+  cpuUsedPct: number;
+  memUsedBytes: number;
+  memTotalBytes: number;
+  diskUsedBytes: number;
+  diskTotalBytes: number;
+}
+
+const SAMPLE: SandboxMetricsSample = {
+  timestamp: new Date().toISOString(),
+  cpuCount: 2,
+  cpuUsedPct: 23.4,
+  memUsedBytes: 412 * 1024 * 1024,
+  memTotalBytes: 2 * 1024 * 1024 * 1024,
+  diskUsedBytes: 68.2 * 1024 * 1024,
+  diskTotalBytes: 10 * 1024 * 1024 * 1024,
+};
+
+function Meter({ pct }: { pct: number }) {
+  const clamped = Math.min(100, Math.max(0, pct));
+  const [fill, track] =
+    clamped >= 90
+      ? ['bg-red-500', 'bg-red-500/15']
+      : clamped >= 75
+        ? ['bg-amber-500', 'bg-amber-500/15']
+        : ['bg-primary', 'bg-primary/10'];
+  return (
+    <div className={cn('h-1.5 w-full overflow-hidden rounded-full', track)}>
+      <div
+        className={cn('h-full rounded-full', fill)}
+        style={{ width: `${clamped}%` }}
+      />
+    </div>
+  );
+}
+
+function MetricCard({
+  icon,
+  label,
+  value,
+  hint,
+  pct,
+}: {
+  icon: NonNullable<HugeiconsProps['icon']>;
+  label: string;
+  value: string;
+  hint: string;
+  pct: number;
+}) {
+  return (
+    <Card size="sm">
+      <CardContent className="flex flex-col gap-2">
+        <div className="flex items-center gap-1.5 text-sm text-muted-foreground">
+          <HugeiconsIcon icon={icon} className="size-4" strokeWidth={1.8} />
+          {label}
+        </div>
+        <div className="text-2xl font-semibold">{value}</div>
+        <div className="text-xs text-muted-foreground">{hint}</div>
+        <Meter pct={pct} />
+      </CardContent>
+    </Card>
+  );
+}
+
+/**
+ * 单沙箱指标。控制台走 cookie,而 E2B 的 metrics 端点只认 API key,
+ * 浏览器刻意拿不到 — 所以这一面要等原生 /getSandboxMetrics 动词落地,
+ * 眼下先用示例数据把版式定下来(执行器侧 metrics() 已经存在,缺的只是
+ * 一个原生路由)。
+ */
+export function MetricsPanel(_props: { sandbox: Sandbox }) {
+  if (!MOCK_PAGES_ENABLED) {
+    return (
+      <Empty className="border border-dashed">
+        <EmptyHeader>
+          <EmptyTitle>尚未接入</EmptyTitle>
+          <EmptyDescription>
+            单沙箱指标等原生 getSandboxMetrics 动词落地后可用。
+          </EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-center gap-2">
+        <SampleDataBadge />
+        <span className="text-sm text-muted-foreground">
+          版式预览 — 接入原生 getSandboxMetrics 后换真数据(单次快照,
+          观察不唤醒)。
+        </span>
+      </div>
+      <div className="grid gap-4 sm:grid-cols-2 xl:grid-cols-3">
+        <MetricCard
+          icon={CpuIcon}
+          label="CPU"
+          value={`${Math.round(SAMPLE.cpuUsedPct)}%`}
+          hint={`${SAMPLE.cpuCount} 核`}
+          pct={SAMPLE.cpuUsedPct}
+        />
+        <MetricCard
+          icon={RamMemoryIcon}
+          label="内存"
+          value={formatBytes(SAMPLE.memUsedBytes)}
+          hint={`共 ${formatBytes(SAMPLE.memTotalBytes)}`}
+          pct={pctOf(SAMPLE.memUsedBytes, SAMPLE.memTotalBytes)}
+        />
+        <MetricCard
+          icon={HardDriveIcon}
+          label="磁盘"
+          value={formatBytes(SAMPLE.diskUsedBytes)}
+          hint={`名义 ${formatBytes(SAMPLE.diskTotalBytes)} — 稀疏镜像只为真实内容付费`}
+          pct={pctOf(SAMPLE.diskUsedBytes, SAMPLE.diskTotalBytes)}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx b/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
new file mode 100644
index 0000000..02f9ddf
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
@@ -0,0 +1,151 @@
+import type { Sandbox } from '@dormice/shared';
+import { ListViewIcon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { toast } from 'sonner';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Button } from '@/components/ui/button';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { STATE_LABELS } from '../format';
+import { useEnvdAuth, useKillProcess, useProcesses } from '../hooks/useEnvd';
+
+/**
+ * daemon 进程表的观察窗:列的是经由 E2B 进程面(SDK 的 background 命令、
+ * 在线终端的 bash)启动、还活着的进程。List 在服务端刻意不唤醒 — 冻结的
+ * 沙箱进程还在(SIGSTOP 挂起,唤醒续跑),这正是值得看的招牌能力。
+ */
+export function ProcessesPanel({ sandbox }: { sandbox: Sandbox }) {
+  // 只有物理容器在(active/frozen)才有进程表;停机沙箱只剩磁盘。
+  const hasContainer = sandbox.state === 'active' || sandbox.state === 'frozen';
+  const auth = useEnvdAuth(sandbox.sandboxId);
+  const processes = useProcesses(auth.data, hasContainer);
+  const kill = useKillProcess(auth.data);
+
+  if (!hasContainer) {
+    return (
+      <Empty className="border border-dashed">
+        <EmptyHeader>
+          <EmptyMedia variant="icon">
+            <HugeiconsIcon icon={ListViewIcon} />
+          </EmptyMedia>
+          <EmptyTitle>没有进程表</EmptyTitle>
+          <EmptyDescription>
+            沙箱当前是「{STATE_LABELS[sandbox.state]}」— 只有磁盘还在,
+            进程要等下次唤醒才会有。
+          </EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    );
+  }
+
+  const list = processes.data ?? [];
+
+  const sendSignal = (
+    pid: number,
+    signal: 'SIGNAL_SIGTERM' | 'SIGNAL_SIGKILL',
+  ) => {
+    kill.mutate(
+      { pid, signal },
+      {
+        onSuccess: () =>
+          toast.success(
+            `已向 ${pid} 发送 ${signal === 'SIGNAL_SIGKILL' ? 'SIGKILL' : 'SIGTERM'}`,
+          ),
+        onError: (error) => toast.error(error.message),
+      },
+    );
+  };
+
+  return (
+    <div className="flex flex-col gap-3">
+      <p className="text-sm text-muted-foreground">
+        经由 E2B 进程面或在线终端启动的存活进程。冻结时进程被整体挂起、 不丢 —
+        唤醒后从暂停处继续跑。
+      </p>
+
+      {(processes.isError || auth.isError) && (
+        <Alert variant="destructive">
+          <AlertDescription>
+            {processes.error?.message ?? auth.error?.message}
+          </AlertDescription>
+        </Alert>
+      )}
+
+      {processes.isSuccess && list.length === 0 && (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyMedia variant="icon">
+              <HugeiconsIcon icon={ListViewIcon} />
+            </EmptyMedia>
+            <EmptyTitle>没有存活的进程</EmptyTitle>
+            <EmptyDescription>
+              用 SDK 跑一个 background 命令,或在「终端」页开一个 bash,
+              它就会出现在这里。
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      )}
+
+      {list.length > 0 && (
+        <div className="overflow-x-auto rounded-lg border">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead className="w-20">PID</TableHead>
+                <TableHead>命令</TableHead>
+                <TableHead className="text-right">操作</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {list.map((process) => (
+                <TableRow key={process.pid}>
+                  <TableCell className="tabular-nums">{process.pid}</TableCell>
+                  <TableCell className="max-w-md truncate font-mono text-xs">
+                    {[process.config.cmd, ...process.config.args].join(' ')}
+                  </TableCell>
+                  <TableCell className="text-right">
+                    <div className="inline-flex gap-1">
+                      <Button
+                        variant="outline"
+                        size="sm"
+                        disabled={kill.isPending}
+                        onClick={() =>
+                          sendSignal(process.pid, 'SIGNAL_SIGTERM')
+                        }
+                      >
+                        SIGTERM
+                      </Button>
+                      <Button
+                        variant="destructive"
+                        size="sm"
+                        disabled={kill.isPending}
+                        onClick={() =>
+                          sendSignal(process.pid, 'SIGNAL_SIGKILL')
+                        }
+                      >
+                        SIGKILL
+                      </Button>
+                    </div>
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx b/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx
index 939d47d..0876a2c 100644
--- a/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx
+++ b/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx
@@ -26,7 +26,7 @@ export function RebuildSandboxButton({ userKey }: { userKey: string }) {
     mutation.mutate(userKey, {
       onSuccess: () =>
         toast.success(
-          `Rebuilt ${userKey} — /home/user kept; its next use starts on the current base image`,
+          `已重建 ${userKey} — /home/user 保留,下次使用跑在当前镜像上`,
         ),
       onError: (error) => toast.error(error.message),
     });
@@ -37,22 +37,21 @@ export function RebuildSandboxButton({ userKey }: { userKey: string }) {
         render={
           <Button variant="outline" size="sm" disabled={mutation.isPending}>
             {mutation.isPending && <Spinner />}
-            Rebuild
+            重建
           </Button>
         }
       />
       <AlertDialogContent>
         <AlertDialogHeader>
-          <AlertDialogTitle>Rebuild “{userKey}”?</AlertDialogTitle>
+          <AlertDialogTitle>重建「{userKey}」?</AlertDialogTitle>
           <AlertDialogDescription>
-            Swaps the container so the next use starts on the daemon’s current
-            base image. Everything in /home/user is kept; running processes and
-            changes outside it are gone.
+            换壳保盘:下次使用跑在 daemon 当前的镜像上。/home/user 一字节
+            不丢;正在跑的进程和家目录之外的改动随旧壳蒸发。
           </AlertDialogDescription>
         </AlertDialogHeader>
         <AlertDialogFooter>
-          <AlertDialogCancel>Keep it</AlertDialogCancel>
-          <AlertDialogAction onClick={rebuild}>Rebuild</AlertDialogAction>
+          <AlertDialogCancel>先留着</AlertDialogCancel>
+          <AlertDialogAction onClick={rebuild}>重建</AlertDialogAction>
         </AlertDialogFooter>
       </AlertDialogContent>
     </AlertDialog>
diff --git a/packages/console/src/features/sandboxes/components/ReleaseSandboxButton.tsx b/packages/console/src/features/sandboxes/components/ReleaseSandboxButton.tsx
index a75702d..6d6ede2 100644
--- a/packages/console/src/features/sandboxes/components/ReleaseSandboxButton.tsx
+++ b/packages/console/src/features/sandboxes/components/ReleaseSandboxButton.tsx
@@ -31,7 +31,7 @@ export function ReleaseSandboxButton({
     mutation.mutate(userKey, {
       onSuccess: ({ released }) => {
         toast.success(
-          released ? `Released ${userKey}` : `${userKey} was already gone`,
+          released ? `已释放 ${userKey}` : `${userKey} 本来就不存在`,
         );
         onReleased?.();
       },
@@ -44,22 +44,22 @@ export function ReleaseSandboxButton({
         render={
           <Button variant="destructive" size="sm" disabled={mutation.isPending}>
             {mutation.isPending && <Spinner />}
-            Release
+            释放
           </Button>
         }
       />
       <AlertDialogContent>
         <AlertDialogHeader>
-          <AlertDialogTitle>Release “{userKey}”?</AlertDialogTitle>
+          <AlertDialogTitle>释放「{userKey}」?</AlertDialogTitle>
           <AlertDialogDescription>
-            This destroys the sandbox and its disk. The key stays valid — the
-            next acquire starts from a blank sandbox.
+            沙箱连同磁盘一起销毁,不可恢复。key 依然有效 — 下次 acquire
+            会得到一个全新的空白沙箱。
           </AlertDialogDescription>
         </AlertDialogHeader>
         <AlertDialogFooter>
-          <AlertDialogCancel>Keep it</AlertDialogCancel>
+          <AlertDialogCancel>先留着</AlertDialogCancel>
           <AlertDialogAction variant="destructive" onClick={release}>
-            Release
+            释放
           </AlertDialogAction>
         </AlertDialogFooter>
       </AlertDialogContent>
diff --git a/packages/console/src/features/sandboxes/components/SandboxStateBadge.tsx b/packages/console/src/features/sandboxes/components/SandboxStateBadge.tsx
index 0fee679..c81b18d 100644
--- a/packages/console/src/features/sandboxes/components/SandboxStateBadge.tsx
+++ b/packages/console/src/features/sandboxes/components/SandboxStateBadge.tsx
@@ -1,6 +1,7 @@
 import type { SandboxState } from '@dormice/shared';
 import { Badge } from '@/components/ui/badge';
 import { cn } from '@/lib/utils';
+import { STATE_LABELS } from '../format';
 
 // Lifecycle rungs, coldest last — one hue per rung so the list reads at a
 // glance: green is paying for RAM, blue is parked in swap, grey is disk-only.
@@ -18,7 +19,7 @@ const STATE_STYLES: Record<SandboxState, string> = {
 export function SandboxStateBadge({ state }: { state: SandboxState }) {
   return (
     <Badge variant="outline" className={cn('font-medium', STATE_STYLES[state])}>
-      {state}
+      {STATE_LABELS[state]}
     </Badge>
   );
 }
diff --git a/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx b/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
index 6f2f09f..7492599 100644
--- a/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
+++ b/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
@@ -35,7 +35,7 @@ function LiveTerminal({ sandboxId }: { sandboxId: string }) {
     fit.fit();
     // Waking a stopped sandbox is a cold start — seconds, not ms. Say so
     // in the terminal itself instead of leaving a dead black box.
-    term.writeln('\x1b[2mconnecting — a sleeping sandbox wakes first…\x1b[0m');
+    term.writeln('\x1b[2m连接中 — 沉睡的沙箱会先被唤醒…\x1b[0m');
 
     let session: PtySession | undefined;
     let cancelled = false;
@@ -93,7 +93,7 @@ function LiveTerminal({ sandboxId }: { sandboxId: string }) {
               setGeneration((n) => n + 1);
             }}
           >
-            Reconnect
+            重新连接
           </Button>
         </div>
       )}
@@ -112,10 +112,10 @@ export function SandboxTerminalCard({ sandboxId }: { sandboxId: string }) {
   return (
     <Card>
       <CardHeader>
-        <CardTitle>Terminal</CardTitle>
+        <CardTitle>终端</CardTitle>
         <CardDescription>
-          An interactive bash inside the sandbox — opening it wakes a sleeping
-          sandbox, closing it lets the idle countdown resume.
+          沙箱里的交互式 bash — 打开会唤醒沉睡的沙箱,关掉后空闲倒计时
+          恢复。看这一页本身不会解冻任何东西。
         </CardDescription>
         <CardAction>
           <Button
@@ -123,7 +123,7 @@ export function SandboxTerminalCard({ sandboxId }: { sandboxId: string }) {
             size="sm"
             onClick={() => setOpen((value) => !value)}
           >
-            {open ? 'Close terminal' : 'Open terminal'}
+            {open ? '关闭终端' : '打开终端'}
           </Button>
         </CardAction>
       </CardHeader>
diff --git a/packages/console/src/features/sandboxes/envd-client.ts b/packages/console/src/features/sandboxes/envd-client.ts
new file mode 100644
index 0000000..b647303
--- /dev/null
+++ b/packages/console/src/features/sandboxes/envd-client.ts
@@ -0,0 +1,170 @@
+/**
+ * Browser-side client for the daemon's envd surface beyond the PTY: the
+ * unary Filesystem/Process RPCs and the plain-HTTP file faces — the exact
+ * wire the official e2b SDK speaks (see envd-pty.ts for why: a console-only
+ * endpoint would be a second truth). Everything authenticates with the
+ * per-sandbox envd access token minted via /console/envdToken.
+ *
+ * Waking: the unary filesystem verbs wake a frozen sandbox (using files IS
+ * using the sandbox); Process/List is read-only and never wakes. Callers
+ * gate the first filesystem call behind an explicit user action.
+ */
+
+const ENVD = '/e2b/envd';
+
+export interface EnvdAuth {
+  sandboxId: string;
+  envdAccessToken: string;
+}
+
+function headersOf(auth: EnvdAuth): Record<string, string> {
+  return {
+    'e2b-sandbox-id': auth.sandboxId,
+    'x-access-token': auth.envdAccessToken,
+  };
+}
+
+export class EnvdError extends Error {
+  constructor(
+    message: string,
+    readonly code: string | undefined,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}
+
+async function unary<T>(
+  auth: EnvdAuth,
+  rpc: string,
+  body: unknown,
+): Promise<T> {
+  const res = await fetch(`${ENVD}/${rpc}`, {
+    method: 'POST',
+    headers: { ...headersOf(auth), 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const detail = (await res.json().catch(() => undefined)) as
+      | { code?: string; message?: string }
+      | undefined;
+    throw new EnvdError(
+      detail?.message ?? `${rpc} 请求失败(${res.status})`,
+      detail?.code,
+      res.status,
+    );
+  }
+  return res.json() as Promise<T>;
+}
+
+// ---- Filesystem(unary Connect RPC,JSON 编码)---------------------------
+
+/** proto3-JSON 的 EntryInfo:int64 的 size 在 wire 上是字符串。 */
+export interface EnvdEntry {
+  name: string;
+  type: 'FILE_TYPE_FILE' | 'FILE_TYPE_DIRECTORY' | 'FILE_TYPE_UNSPECIFIED';
+  path: string;
+  size: string;
+  mode: number;
+  permissions: string;
+  owner: string;
+  group: string;
+  modifiedTime: string;
+}
+
+export const listDir = (auth: EnvdAuth, path: string) =>
+  unary<{ entries: EnvdEntry[] }>(auth, 'filesystem.Filesystem/ListDir', {
+    path,
+  }).then((r) => r.entries);
+
+export const makeDir = (auth: EnvdAuth, path: string) =>
+  unary<{ entry: EnvdEntry }>(auth, 'filesystem.Filesystem/MakeDir', { path });
+
+export const moveEntry = (
+  auth: EnvdAuth,
+  source: string,
+  destination: string,
+) =>
+  unary<{ entry: EnvdEntry }>(auth, 'filesystem.Filesystem/Move', {
+    source,
+    destination,
+  });
+
+export const removeEntry = (auth: EnvdAuth, path: string) =>
+  unary<Record<string, never>>(auth, 'filesystem.Filesystem/Remove', { path });
+
+// ---- 文件本体进出(纯 HTTP 面,流式无大小上限)---------------------------
+
+/** 下载整个文件为 Blob,交给浏览器落盘。 */
+export async function downloadFile(
+  auth: EnvdAuth,
+  path: string,
+): Promise<Blob> {
+  const query = new URLSearchParams({ path, username: 'user' });
+  const res = await fetch(`${ENVD}/files?${query}`, {
+    headers: headersOf(auth),
+  });
+  if (!res.ok) {
+    const detail = (await res.json().catch(() => undefined)) as
+      | { message?: string }
+      | undefined;
+    throw new EnvdError(
+      detail?.message ?? `下载失败(${res.status})`,
+      undefined,
+      res.status,
+    );
+  }
+  return res.blob();
+}
+
+/** octet-stream 直传:目标路径在 query,body 就是文件字节。 */
+export async function uploadFile(
+  auth: EnvdAuth,
+  path: string,
+  file: File,
+): Promise<void> {
+  const query = new URLSearchParams({ path, username: 'user' });
+  const res = await fetch(`${ENVD}/files?${query}`, {
+    method: 'POST',
+    headers: { ...headersOf(auth), 'content-type': 'application/octet-stream' },
+    body: file,
+  });
+  if (!res.ok) {
+    const detail = (await res.json().catch(() => undefined)) as
+      | { message?: string }
+      | undefined;
+    throw new EnvdError(
+      detail?.message ?? `上传失败(${res.status})`,
+      undefined,
+      res.status,
+    );
+  }
+}
+
+// ---- Process(unary 部分;流式的 Start 归 envd-pty.ts)--------------------
+
+export interface EnvdProcess {
+  pid: number;
+  config: {
+    cmd: string;
+    args: string[];
+    envs?: Record<string, string>;
+    cwd?: string;
+  };
+}
+
+/** 只读不唤醒:看进程表绝不解冻沙箱。 */
+export const listProcesses = (auth: EnvdAuth) =>
+  unary<{ processes: EnvdProcess[] }>(auth, 'process.Process/List', {}).then(
+    (r) => r.processes,
+  );
+
+export const killProcess = (
+  auth: EnvdAuth,
+  pid: number,
+  signal: 'SIGNAL_SIGTERM' | 'SIGNAL_SIGKILL',
+) =>
+  unary<Record<string, never>>(auth, 'process.Process/SendSignal', {
+    process: { pid },
+    signal,
+  });
diff --git a/packages/console/src/features/sandboxes/envd-pty.ts b/packages/console/src/features/sandboxes/envd-pty.ts
index cad153b..9fd053f 100644
--- a/packages/console/src/features/sandboxes/envd-pty.ts
+++ b/packages/console/src/features/sandboxes/envd-pty.ts
@@ -95,7 +95,7 @@ export async function openPty(options: {
       const detail = (await res.json().catch(() => undefined)) as
         | { message?: string }
         | undefined;
-      throw new Error(detail?.message ?? `${rpc} failed with ${res.status}`);
+      throw new Error(detail?.message ?? `${rpc} 请求失败(${res.status})`);
     }
   }
 
@@ -119,7 +119,7 @@ export async function openPty(options: {
     const detail = (await res.json().catch(() => undefined)) as
       | { message?: string }
       | undefined;
-    throw new Error(detail?.message ?? `terminal failed with ${res.status}`);
+    throw new Error(detail?.message ?? `终端连接失败(${res.status})`);
   }
 
   let closed = false;
@@ -137,14 +137,14 @@ export async function openPty(options: {
     frame: StreamFrame,
   ): number | undefined => {
     if (flags & FLAG_END_STREAM) {
-      closeOnce(frame.error?.message ?? 'connection closed');
+      closeOnce(frame.error?.message ?? '连接已断开');
       return;
     }
     if (frame.event?.data?.pty) {
       callbacks.onData(fromBase64(frame.event.data.pty));
     }
     if (frame.event?.end) {
-      closeOnce(`shell exited (code ${frame.event.end.exitCode ?? '?'})`);
+      closeOnce(`shell 已退出(码 ${frame.event.end.exitCode ?? '?'})`);
     }
     return frame.event?.start?.pid;
   };
@@ -171,7 +171,7 @@ export async function openPty(options: {
       }
       const { done, value } = await reader.read();
       if (done) {
-        closeOnce('connection closed');
+        closeOnce('连接已断开');
         return undefined;
       }
       const grown = new Uint8Array(buffer.length + value.length);
@@ -190,7 +190,7 @@ export async function openPty(options: {
     closeOnce(error instanceof Error ? error.message : String(error));
   }
   if (pid === undefined) {
-    throw new Error('terminal did not start');
+    throw new Error('终端没有启动');
   }
   const startedPid = pid;
 
@@ -235,7 +235,7 @@ export async function openPty(options: {
         process: { pid: startedPid },
         signal: 'SIGNAL_SIGKILL',
       }).catch(() => undefined);
-      closeOnce('terminal closed');
+      closeOnce('终端已关闭');
     },
   };
 }
diff --git a/packages/console/src/features/sandboxes/format.ts b/packages/console/src/features/sandboxes/format.ts
index 70c91ee..ab2dc58 100644
--- a/packages/console/src/features/sandboxes/format.ts
+++ b/packages/console/src/features/sandboxes/format.ts
@@ -1,30 +1,53 @@
-import type { Sandbox } from '@dormice/shared';
+import type { Sandbox, SandboxState } from '@dormice/shared';
 
+/** 中文状态名 — 徽章、筛选器、总览统计共用一份,不各自翻译。 */
+export const STATE_LABELS: Record<SandboxState, string> = {
+  active: '运行中',
+  frozen: '已冻结',
+  stopped: '已停止',
+  archived: '已归档',
+  restoring: '恢复中',
+};
+
+/** 时长的中文写法:45秒 / 5分12秒 / 3小时20分 / 2天4小时,最多两段。 */
 export function formatDuration(totalSeconds: number): string {
   const s = Math.max(0, Math.floor(totalSeconds));
-  if (s < 60) return `${s}s`;
-  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
-  if (s < 86400)
-    return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
-  return `${Math.floor(s / 86400)}d ${Math.floor((s % 86400) / 3600)}h`;
+  if (s < 60) return `${s}秒`;
+  if (s < 3600) {
+    const rest = s % 60;
+    return rest === 0
+      ? `${Math.floor(s / 60)}分钟`
+      : `${Math.floor(s / 60)}分${rest}秒`;
+  }
+  if (s < 86400) {
+    const rest = Math.floor((s % 3600) / 60);
+    return rest === 0
+      ? `${Math.floor(s / 3600)}小时`
+      : `${Math.floor(s / 3600)}小时${rest}分`;
+  }
+  const rest = Math.floor((s % 86400) / 3600);
+  return rest === 0
+    ? `${Math.floor(s / 86400)}天`
+    : `${Math.floor(s / 86400)}天${rest}小时`;
 }
 
+/** 距离某时刻过去了多久:"3分12秒"(调用方自己加"前")。 */
 export function since(iso: string): string {
   return formatDuration((Date.now() - Date.parse(iso)) / 1000);
 }
 
-/** One knob as text: "freeze 5m" / "stop never". */
+/** 一个旋钮的文字形:"冻结 5分钟" / "停止 永不"。 */
 export function policyStep(label: string, seconds: number | null): string {
   return seconds === null
-    ? `${label} never`
+    ? `${label} 永不`
     : `${label} ${formatDuration(seconds)}`;
 }
 
-/** The three knobs in one line: how this sandbox cools down when idle. */
+/** 三个旋钮一行:这个沙箱闲下来之后怎么降温。 */
 export function policyLine(policy: Sandbox['policy']): string {
   return [
-    policyStep('freeze', policy.freezeAfterSeconds),
-    policyStep('stop', policy.stopAfterSeconds),
-    policyStep('archive', policy.archiveAfterSeconds),
+    policyStep('冻结', policy.freezeAfterSeconds),
+    policyStep('停止', policy.stopAfterSeconds),
+    policyStep('归档', policy.archiveAfterSeconds),
   ].join(' · ');
 }
diff --git a/packages/console/src/features/sandboxes/hooks/useEnvd.ts b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
new file mode 100644
index 0000000..1e98e1d
--- /dev/null
+++ b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
@@ -0,0 +1,135 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { mintEnvdToken } from '@/lib/api';
+import {
+  downloadFile,
+  type EnvdAuth,
+  killProcess,
+  listDir,
+  listProcesses,
+  makeDir,
+  moveEntry,
+  removeEntry,
+  uploadFile,
+} from '../envd-client';
+
+/**
+ * 一个沙箱的 envd 面数据层:token、文件、进程。token 是无状态 HMAC,
+ * 不过期 — 铸一次缓存整个会话(轮换 API token 才作废,那时 401 拦截兜底)。
+ */
+export function useEnvdAuth(sandboxId: string) {
+  return useQuery({
+    queryKey: ['envdToken', sandboxId],
+    queryFn: async (): Promise<EnvdAuth> => {
+      const { envdAccessToken } = await mintEnvdToken(sandboxId);
+      return { sandboxId, envdAccessToken };
+    },
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false,
+  });
+}
+
+/**
+ * 目录列表。enabled 由调用方裁决:文件动词会唤醒冻结沙箱,所以第一次
+ * 浏览必须站在一次显式点击后面(与终端同一条纪律)。
+ */
+export function useDirectory(
+  auth: EnvdAuth | undefined,
+  path: string,
+  enabled: boolean,
+) {
+  return useQuery({
+    queryKey: ['envdDir', auth?.sandboxId, path],
+    queryFn: () => {
+      if (!auth) throw new Error('缺少 envd 凭证');
+      return listDir(auth, path);
+    },
+    enabled: enabled && auth !== undefined,
+    retry: false,
+  });
+}
+
+/** 文件动词的 mutation 家族,成功后重扫当前目录。 */
+export function useFileMutations(auth: EnvdAuth | undefined) {
+  const queryClient = useQueryClient();
+  const invalidate = () => {
+    if (auth) {
+      void queryClient.invalidateQueries({
+        queryKey: ['envdDir', auth.sandboxId],
+      });
+    }
+  };
+  const requireAuth = (): EnvdAuth => {
+    if (!auth) throw new Error('缺少 envd 凭证');
+    return auth;
+  };
+
+  const mkdir = useMutation({
+    mutationFn: (path: string) => makeDir(requireAuth(), path),
+    onSuccess: invalidate,
+  });
+  const move = useMutation({
+    mutationFn: (args: { source: string; destination: string }) =>
+      moveEntry(requireAuth(), args.source, args.destination),
+    onSuccess: invalidate,
+  });
+  const remove = useMutation({
+    mutationFn: (path: string) => removeEntry(requireAuth(), path),
+    onSuccess: invalidate,
+  });
+  const upload = useMutation({
+    mutationFn: (args: { path: string; file: File }) =>
+      uploadFile(requireAuth(), args.path, args.file),
+    onSuccess: invalidate,
+  });
+  const download = useMutation({
+    mutationFn: async (args: { path: string; name: string }) => {
+      const blob = await downloadFile(requireAuth(), args.path);
+      // 浏览器侧落盘:临时 object URL + 隐形 <a download>。
+      const url = URL.createObjectURL(blob);
+      const anchor = document.createElement('a');
+      anchor.href = url;
+      anchor.download = args.name;
+      anchor.click();
+      URL.revokeObjectURL(url);
+    },
+  });
+
+  return { mkdir, move, remove, upload, download };
+}
+
+/**
+ * 进程表。List 在服务端刻意不唤醒(读 daemon 内存),所以这里可以放心
+ * 轮询;只在沙箱有物理容器时开启(active/frozen),停机沙箱没有进程表。
+ */
+export function useProcesses(auth: EnvdAuth | undefined, enabled: boolean) {
+  return useQuery({
+    queryKey: ['envdProcesses', auth?.sandboxId],
+    queryFn: () => {
+      if (!auth) throw new Error('缺少 envd 凭证');
+      return listProcesses(auth);
+    },
+    enabled: enabled && auth !== undefined,
+    refetchInterval: 2000,
+    retry: false,
+  });
+}
+
+export function useKillProcess(auth: EnvdAuth | undefined) {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (args: {
+      pid: number;
+      signal: 'SIGNAL_SIGTERM' | 'SIGNAL_SIGKILL';
+    }) => {
+      if (!auth) throw new Error('缺少 envd 凭证');
+      return killProcess(auth, args.pid, args.signal);
+    },
+    onSettled: () => {
+      if (auth) {
+        void queryClient.invalidateQueries({
+          queryKey: ['envdProcesses', auth.sandboxId],
+        });
+      }
+    },
+  });
+}
diff --git a/packages/console/src/features/sandboxes/hooks/useTemplates.ts b/packages/console/src/features/sandboxes/hooks/useTemplates.ts
deleted file mode 100644
index bdcf9ba..0000000
--- a/packages/console/src/features/sandboxes/hooks/useTemplates.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-import { useQuery } from '@tanstack/react-query';
-import { listTemplates } from '@/lib/api';
-
-/**
- * The console only consumes templates (the create form's dropdown, the
- * detail row); registration lives in the CLI (`dor template add`). No
- * polling: templates change at operator speed, a mount-time read is honest
- * enough.
- */
-export function useTemplates() {
-  return useQuery({
-    queryKey: ['templates'],
-    queryFn: listTemplates,
-    retry: false,
-  });
-}
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index aab5159..c940d38 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -1,6 +1,9 @@
-import { ArrowLeft01Icon } from '@hugeicons/core-free-icons';
-import { HugeiconsIcon } from '@hugeicons/react';
-import { Link, useNavigate, useParams } from '@tanstack/react-router';
+import {
+  Link,
+  useNavigate,
+  useParams,
+  useSearch,
+} from '@tanstack/react-router';
 import type { ReactNode } from 'react';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent } from '@/components/ui/card';
@@ -11,6 +14,11 @@ import {
   EmptyHeader,
   EmptyTitle,
 } from '@/components/ui/empty';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { MOCK_PAGES_ENABLED } from '@/lib/mock';
+import { FilesPanel } from '../components/FilesPanel';
+import { MetricsPanel } from '../components/MetricsPanel';
+import { ProcessesPanel } from '../components/ProcessesPanel';
 import { RebuildSandboxButton } from '../components/RebuildSandboxButton';
 import { ReleaseSandboxButton } from '../components/ReleaseSandboxButton';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
@@ -18,6 +26,15 @@ import { SandboxTerminalCard } from '../components/SandboxTerminal';
 import { formatDuration, since } from '../format';
 import { useSandbox } from '../hooks/useSandboxes';
 
+export const DETAIL_TABS = [
+  'overview',
+  'terminal',
+  'files',
+  'processes',
+  'metrics',
+] as const;
+export type DetailTab = (typeof DETAIL_TABS)[number];
+
 function Row({ label, children }: { label: string; children: ReactNode }) {
   return (
     <div className="flex items-baseline justify-between gap-6 border-b py-3 text-sm last:border-b-0">
@@ -28,54 +45,44 @@ function Row({ label, children }: { label: string; children: ReactNode }) {
 }
 
 /**
- * Everything /listSandboxes knows about one key. The list is the only read
- * the daemon offers, so this page selects from the same 2s-polled cache —
- * no second endpoint, no second truth.
+ * 一个沙箱的工作区。基础信息仍从 2 秒轮询的列表缓存里选(列表是 daemon
+ * 唯一的读,不发明第二个端点);文件/进程/终端走 envd 面 — 与官方 e2b
+ * SDK 同一条 wire。tab 记在 URL 里,刷新与分享都停在原面板。
  */
 export function SandboxDetailPage() {
   const { userKey } = useParams({ from: '/_app/sandboxes/$userKey' });
-  const navigate = useNavigate();
+  const { tab } = useSearch({ from: '/_app/sandboxes/$userKey' });
+  const navigate = useNavigate({ from: '/sandboxes/$userKey' });
   const { sandbox, isSuccess } = useSandbox(userKey);
 
   if (!sandbox) {
-    return (
-      <main className="mx-auto min-h-screen w-full max-w-3xl px-6 py-10">
-        {isSuccess && (
-          <Empty className="border border-dashed">
-            <EmptyHeader>
-              <EmptyTitle>No sandbox for “{userKey}”</EmptyTitle>
-              <EmptyDescription>
-                It may have been released — the key is free to acquire again.
-              </EmptyDescription>
-            </EmptyHeader>
-            <EmptyContent>
-              <Button
-                variant="outline"
-                size="sm"
-                nativeButton={false}
-                render={<Link to="/" />}
-              >
-                Back to sandboxes
-              </Button>
-            </EmptyContent>
-          </Empty>
-        )}
-      </main>
-    );
-  }
-
-  return (
-    <main className="mx-auto min-h-screen w-full max-w-3xl px-6">
-      <header className="flex items-center justify-between py-5">
-        <div className="flex items-center gap-3">
+    return isSuccess ? (
+      <Empty className="border border-dashed">
+        <EmptyHeader>
+          <EmptyTitle>没有叫「{userKey}」的沙箱</EmptyTitle>
+          <EmptyDescription>
+            可能已被释放 — 这个 key 依然有效,下次 acquire 会得到一个
+            全新的沙箱。
+          </EmptyDescription>
+        </EmptyHeader>
+        <EmptyContent>
           <Button
-            variant="ghost"
-            size="icon-sm"
+            variant="outline"
+            size="sm"
             nativeButton={false}
-            render={<Link to="/" aria-label="Back to sandboxes" />}
+            render={<Link to="/sandboxes" />}
           >
-            <HugeiconsIcon icon={ArrowLeft01Icon} />
+            回到沙箱列表
           </Button>
+        </EmptyContent>
+      </Empty>
+    ) : null;
+  }
+
+  return (
+    <>
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div className="flex items-center gap-3">
           <h1 className="font-mono text-lg font-semibold">{sandbox.userKey}</h1>
           <SandboxStateBadge state={sandbox.state} />
         </div>
@@ -83,43 +90,77 @@ export function SandboxDetailPage() {
           <RebuildSandboxButton userKey={sandbox.userKey} />
           <ReleaseSandboxButton
             userKey={sandbox.userKey}
-            onReleased={() => navigate({ to: '/' })}
+            onReleased={() => navigate({ to: '/sandboxes' })}
           />
         </div>
-      </header>
-
-      <div className="mb-6">
-        <SandboxTerminalCard sandboxId={sandbox.sandboxId} />
       </div>
 
-      <Card>
-        <CardContent>
-          <dl>
-            <Row label="Sandbox ID">{sandbox.sandboxId}</Row>
-            <Row label="Template">{sandbox.template ?? 'base image'}</Row>
-            <Row label="Node">{sandbox.nodeId}</Row>
-            <Row label="Endpoint">{sandbox.endpoint}</Row>
-            <Row label="Created">
-              {new Date(sandbox.createdAt).toLocaleString()} ·{' '}
-              {since(sandbox.createdAt)} ago
-            </Row>
-            <Row label="Last active">{since(sandbox.lastActiveAt)} ago</Row>
-            <Row label="Freeze after">
-              {formatDuration(sandbox.policy.freezeAfterSeconds)} idle
-            </Row>
-            <Row label="Stop after">
-              {sandbox.policy.stopAfterSeconds === null
-                ? 'never (resident agent)'
-                : `${formatDuration(sandbox.policy.stopAfterSeconds)} idle`}
-            </Row>
-            <Row label="Archive after">
-              {sandbox.policy.archiveAfterSeconds === null
-                ? 'never'
-                : `${formatDuration(sandbox.policy.archiveAfterSeconds)} idle`}
-            </Row>
-          </dl>
-        </CardContent>
-      </Card>
-    </main>
+      <Tabs
+        value={tab}
+        onValueChange={(next) =>
+          navigate({
+            search: { tab: next as DetailTab },
+            replace: true,
+          })
+        }
+      >
+        <TabsList>
+          <TabsTrigger value="overview">概览</TabsTrigger>
+          <TabsTrigger value="terminal">终端</TabsTrigger>
+          <TabsTrigger value="files">文件</TabsTrigger>
+          <TabsTrigger value="processes">进程</TabsTrigger>
+          {MOCK_PAGES_ENABLED && (
+            <TabsTrigger value="metrics">指标</TabsTrigger>
+          )}
+        </TabsList>
+
+        <TabsContent value="overview">
+          <Card>
+            <CardContent>
+              <dl>
+                <Row label="沙箱 ID">{sandbox.sandboxId}</Row>
+                <Row label="模板">{sandbox.template ?? '基础镜像'}</Row>
+                <Row label="节点">{sandbox.nodeId}</Row>
+                <Row label="端点">{sandbox.endpoint}</Row>
+                <Row label="创建于">
+                  {new Date(sandbox.createdAt).toLocaleString()} ·{' '}
+                  {since(sandbox.createdAt)}前
+                </Row>
+                <Row label="最近活动">{since(sandbox.lastActiveAt)}前</Row>
+                <Row label="冻结阈值">
+                  空闲 {formatDuration(sandbox.policy.freezeAfterSeconds)}
+                </Row>
+                <Row label="停止阈值">
+                  {sandbox.policy.stopAfterSeconds === null
+                    ? '永不(常驻 agent)'
+                    : `空闲 ${formatDuration(sandbox.policy.stopAfterSeconds)}`}
+                </Row>
+                <Row label="归档阈值">
+                  {sandbox.policy.archiveAfterSeconds === null
+                    ? '永不'
+                    : `空闲 ${formatDuration(sandbox.policy.archiveAfterSeconds)}`}
+                </Row>
+              </dl>
+            </CardContent>
+          </Card>
+        </TabsContent>
+
+        <TabsContent value="terminal">
+          <SandboxTerminalCard sandboxId={sandbox.sandboxId} />
+        </TabsContent>
+
+        <TabsContent value="files">
+          <FilesPanel sandbox={sandbox} />
+        </TabsContent>
+
+        <TabsContent value="processes">
+          <ProcessesPanel sandbox={sandbox} />
+        </TabsContent>
+
+        <TabsContent value="metrics">
+          <MetricsPanel sandbox={sandbox} />
+        </TabsContent>
+      </Tabs>
+    </>
   );
 }
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index e16d943..9e7fb3d 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -1,8 +1,23 @@
-import { PackageIcon } from '@hugeicons/core-free-icons';
+import type { Sandbox, SandboxState } from '@dormice/shared';
+import { PackageIcon, Search01Icon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
 import { Link } from '@tanstack/react-router';
+import { useMemo, useState } from 'react';
+import { toast } from 'sonner';
 import { Alert, AlertDescription } from '@/components/ui/alert';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@/components/ui/alert-dialog';
 import { Button } from '@/components/ui/button';
+import { Checkbox } from '@/components/ui/checkbox';
 import {
   Empty,
   EmptyDescription,
@@ -10,6 +25,16 @@ import {
   EmptyMedia,
   EmptyTitle,
 } from '@/components/ui/empty';
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupInput,
+} from '@/components/ui/input-group';
+import {
+  NativeSelect,
+  NativeSelectOption,
+} from '@/components/ui/native-select';
+import { Spinner } from '@/components/ui/spinner';
 import {
   Table,
   TableBody,
@@ -18,58 +43,176 @@ import {
   TableHeader,
   TableRow,
 } from '@/components/ui/table';
-import { OverviewCards } from '@/features/overview/components/OverviewCards';
-import { logout } from '@/lib/api';
-import { clearSessionMarker } from '@/lib/session';
+import { releaseSandbox } from '@/lib/api';
+import { queryClient } from '@/lib/queryClient';
 import { CreateSandboxDialog } from '../components/CreateSandboxDialog';
 import { ReleaseSandboxButton } from '../components/ReleaseSandboxButton';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
-import { policyLine, since } from '../format';
+import { policyLine, STATE_LABELS, since } from '../format';
 import { useSandboxes } from '../hooks/useSandboxes';
 
-async function signOut() {
-  // Best effort: the cookie may already be dead, and that's fine — what
-  // matters is clearing the marker and starting over from the login page.
-  await logout().catch(() => undefined);
-  clearSessionMarker();
-  window.location.href = '/console/login';
+const STATE_FILTERS: Array<SandboxState> = [
+  'active',
+  'frozen',
+  'stopped',
+  'archived',
+  'restoring',
+];
+
+/**
+ * 批量释放:逐个调用 releaseSandbox(daemon 的 per-key 锁本来就是逐个
+ * 裁决的,并发只是把失败搅在一起),结束后一次性汇报成败。
+ */
+function BulkReleaseButton({
+  userKeys,
+  onDone,
+}: {
+  userKeys: string[];
+  onDone: () => void;
+}) {
+  const [pending, setPending] = useState(false);
+
+  const releaseAll = async () => {
+    setPending(true);
+    const failures: string[] = [];
+    for (const userKey of userKeys) {
+      try {
+        await releaseSandbox(userKey);
+      } catch {
+        failures.push(userKey);
+      }
+    }
+    setPending(false);
+    void queryClient.invalidateQueries({ queryKey: ['sandboxes'] });
+    if (failures.length === 0) {
+      toast.success(`已释放 ${userKeys.length} 个沙箱`);
+    } else {
+      toast.error(`${failures.length} 个释放失败:${failures.join('、')}`);
+    }
+    onDone();
+  };
+
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger
+        render={
+          <Button variant="destructive" size="sm" disabled={pending}>
+            {pending && <Spinner />}
+            释放选中({userKeys.length})
+          </Button>
+        }
+      />
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>释放 {userKeys.length} 个沙箱?</AlertDialogTitle>
+          <AlertDialogDescription>
+            沙箱连同磁盘一起销毁,不可恢复。key 依然有效 — 下次 acquire
+            会得到一个全新的空白沙箱。
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>先留着</AlertDialogCancel>
+          <AlertDialogAction variant="destructive" onClick={releaseAll}>
+            释放
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
 }
 
 export function SandboxesPage() {
   const query = useSandboxes();
   const sandboxes = query.data?.sandboxes ?? [];
+  const [search, setSearch] = useState('');
+  const [stateFilter, setStateFilter] = useState<'all' | SandboxState>('all');
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+
+  const filtered = useMemo(
+    () =>
+      sandboxes.filter(
+        (sandbox) =>
+          (stateFilter === 'all' || sandbox.state === stateFilter) &&
+          (search === '' ||
+            sandbox.userKey.toLowerCase().includes(search.toLowerCase())),
+      ),
+    [sandboxes, stateFilter, search],
+  );
+
+  // 选中集随现实收敛:被别处释放的沙箱不该留在选中里撑数字。
+  const selectedVisible = filtered.filter((s) => selected.has(s.userKey));
+  const allVisibleSelected =
+    filtered.length > 0 && selectedVisible.length === filtered.length;
+
+  const toggleAll = () => {
+    setSelected(
+      allVisibleSelected ? new Set() : new Set(filtered.map((s) => s.userKey)),
+    );
+  };
+  const toggleOne = (userKey: string) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(userKey)) next.delete(userKey);
+      else next.add(userKey);
+      return next;
+    });
+  };
 
   return (
-    <main className="mx-auto min-h-screen w-full max-w-5xl px-6">
-      <header className="flex items-center justify-between py-5">
-        <div className="flex items-baseline gap-3">
-          <h1 className="text-lg font-semibold">Dormice</h1>
-          <span className="text-sm text-muted-foreground">
-            {sandboxes.length} sandbox{sandboxes.length === 1 ? '' : 'es'}
-          </span>
+    <>
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div>
+          <h1 className="text-lg font-semibold">沙箱</h1>
+          <p className="text-sm text-muted-foreground">
+            账本里的全部沙箱,每 2 秒刷新 — 看着不会吵醒任何一个。
+          </p>
         </div>
-        <div className="flex items-center gap-2">
-          <Button
-            variant="ghost"
-            size="sm"
-            nativeButton={false}
-            render={<Link to="/connect" />}
-          >
-            Connect
-          </Button>
-          <CreateSandboxDialog />
-          <Button variant="ghost" size="sm" onClick={signOut}>
-            Sign out
-          </Button>
-        </div>
-      </header>
+        <CreateSandboxDialog />
+      </div>
 
-      <div className="mb-6">
-        <OverviewCards />
+      <div className="flex flex-wrap items-center gap-2">
+        <InputGroup className="w-64">
+          <InputGroupAddon>
+            <HugeiconsIcon
+              icon={Search01Icon}
+              className="size-4 text-muted-foreground"
+            />
+          </InputGroupAddon>
+          <InputGroupInput
+            value={search}
+            onChange={(event) => setSearch(event.target.value)}
+            placeholder="按 userKey 搜索"
+          />
+        </InputGroup>
+        <NativeSelect
+          aria-label="按状态筛选"
+          value={stateFilter}
+          onChange={(event) =>
+            setStateFilter(event.target.value as 'all' | SandboxState)
+          }
+        >
+          <NativeSelectOption value="all">全部状态</NativeSelectOption>
+          {STATE_FILTERS.map((state) => (
+            <NativeSelectOption key={state} value={state}>
+              {STATE_LABELS[state]}
+            </NativeSelectOption>
+          ))}
+        </NativeSelect>
+        <span className="text-sm text-muted-foreground">
+          {filtered.length} / {sandboxes.length} 个
+        </span>
+        {selectedVisible.length > 0 && (
+          <div className="ml-auto">
+            <BulkReleaseButton
+              userKeys={selectedVisible.map((s) => s.userKey)}
+              onDone={() => setSelected(new Set())}
+            />
+          </div>
+        )}
       </div>
 
       {query.isError && (
-        <Alert variant="destructive" className="mb-4">
+        <Alert variant="destructive">
           <AlertDescription>{query.error.message}</AlertDescription>
         </Alert>
       )}
@@ -80,35 +223,64 @@ export function SandboxesPage() {
             <EmptyMedia variant="icon">
               <HugeiconsIcon icon={PackageIcon} />
             </EmptyMedia>
-            <EmptyTitle>No sandboxes yet</EmptyTitle>
+            <EmptyTitle>还没有沙箱</EmptyTitle>
             <EmptyDescription>
-              Create one here, or acquire one via the SDK — it appears within
-              two seconds either way.
+              在这里创建一个,或者用 SDK acquire — 两秒内都会出现在这张表里。
             </EmptyDescription>
           </EmptyHeader>
         </Empty>
       )}
 
-      {sandboxes.length > 0 && (
+      {query.isSuccess && sandboxes.length > 0 && filtered.length === 0 && (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyTitle>没有匹配的沙箱</EmptyTitle>
+            <EmptyDescription>换个关键词或状态试试。</EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      )}
+
+      {filtered.length > 0 && (
         <div className="overflow-x-auto rounded-lg border">
           <Table>
             <TableHeader>
               <TableRow>
-                <TableHead>User key</TableHead>
-                <TableHead>State</TableHead>
-                <TableHead>Idle</TableHead>
-                <TableHead>Lifecycle policy</TableHead>
-                <TableHead>Age</TableHead>
-                <TableHead className="text-right">Actions</TableHead>
+                <TableHead className="w-10">
+                  <Checkbox
+                    aria-label="全选"
+                    checked={allVisibleSelected}
+                    onCheckedChange={toggleAll}
+                  />
+                </TableHead>
+                <TableHead>userKey</TableHead>
+                <TableHead>状态</TableHead>
+                <TableHead>模板</TableHead>
+                <TableHead>空闲</TableHead>
+                <TableHead>生命周期策略</TableHead>
+                <TableHead>存活</TableHead>
+                <TableHead className="text-right">操作</TableHead>
               </TableRow>
             </TableHeader>
             <TableBody>
-              {sandboxes.map((sandbox) => (
-                <TableRow key={sandbox.sandboxId}>
+              {filtered.map((sandbox: Sandbox) => (
+                <TableRow
+                  key={sandbox.sandboxId}
+                  data-state={
+                    selected.has(sandbox.userKey) ? 'selected' : undefined
+                  }
+                >
+                  <TableCell>
+                    <Checkbox
+                      aria-label={`选中 ${sandbox.userKey}`}
+                      checked={selected.has(sandbox.userKey)}
+                      onCheckedChange={() => toggleOne(sandbox.userKey)}
+                    />
+                  </TableCell>
                   <TableCell>
                     <Link
                       to="/sandboxes/$userKey"
                       params={{ userKey: sandbox.userKey }}
+                      search={{ tab: 'overview' }}
                       className="font-mono font-medium hover:underline"
                     >
                       {sandbox.userKey}
@@ -117,6 +289,9 @@ export function SandboxesPage() {
                   <TableCell>
                     <SandboxStateBadge state={sandbox.state} />
                   </TableCell>
+                  <TableCell className="text-muted-foreground">
+                    {sandbox.template ?? '基础镜像'}
+                  </TableCell>
                   <TableCell className="tabular-nums text-muted-foreground">
                     {since(sandbox.lastActiveAt)}
                   </TableCell>
@@ -135,6 +310,6 @@ export function SandboxesPage() {
           </Table>
         </div>
       )}
-    </main>
+    </>
   );
 }
diff --git a/packages/console/src/features/settings/fixtures.ts b/packages/console/src/features/settings/fixtures.ts
new file mode 100644
index 0000000..3687c05
--- /dev/null
+++ b/packages/console/src/features/settings/fixtures.ts
@@ -0,0 +1,79 @@
+/**
+ * 提案中的 wire 形状:POST /getConfig 的响应行 — daemon 生效配置的只读
+ * 快照(查生效值,与 doctor 同一条纪律)。敏感值只报"已设置",绝不回传
+ * 内容。落地时类型进 shared,本文件只剩删除。
+ */
+export interface ConfigEntry {
+  key: string;
+  /** 生效值;敏感项为 null,配 redacted: true。 */
+  value: string | null;
+  /** 值从哪来:环境变量显式给的,还是代码里的默认值。 */
+  source: 'env' | 'default';
+  redacted?: boolean;
+  /** 这个旋钮管什么,一句话。 */
+  hint: string;
+}
+
+export const SAMPLE_CONFIG: ConfigEntry[] = [
+  {
+    key: 'DORMICE_API_TOKEN',
+    value: null,
+    source: 'env',
+    redacted: true,
+    hint: '唯一的 API 凭证;控制台登录时换成 httpOnly cookie,页面永远读不到它',
+  },
+  {
+    key: 'DORMICE_EXECUTOR',
+    value: 'docker',
+    source: 'env',
+    hint: '执行器:docker 是真沙箱,fake 是内存假执行器(开发/测试用)',
+  },
+  {
+    key: 'DORMICE_BASE_IMAGE',
+    value: 'dormice-base:20260710b',
+    source: 'env',
+    hint: '沙箱的默认镜像;docker 模式必填,启动即校验存在',
+  },
+  {
+    key: 'DORMICE_DB_PATH',
+    value: '/var/lib/dormice/dormice.db',
+    source: 'env',
+    hint: 'SQLite 账本;docker 模式强制绝对路径',
+  },
+  {
+    key: 'DORMICE_DATA_DIR',
+    value: '/var/lib/dormice',
+    source: 'env',
+    hint: '沙箱磁盘镜像的家(disks/*.img)',
+  },
+  {
+    key: 'DORMICE_PORT',
+    value: '3676',
+    source: 'default',
+    hint: 'daemon 端口;只绑 127.0.0.1,对外暴露是反向代理的活',
+  },
+  {
+    key: 'DORMICE_MAX_SANDBOXES',
+    value: '100',
+    source: 'default',
+    hint: '创建上限(撞上回 429);唤醒永不受限 — 磁盘才是真瓶颈',
+  },
+  {
+    key: 'DORMICE_SCAN_INTERVAL_SECONDS',
+    value: '60',
+    source: 'default',
+    hint: '空闲扫描周期:每一轮把到阈值的沙箱降一格温度',
+  },
+  {
+    key: 'DORMICE_SANDBOX_MEMORY_GB',
+    value: '2',
+    source: 'default',
+    hint: '每个沙箱的内存上限;沙箱内 OOM 会让 gVisor 整箱退出(对账救回)',
+  },
+  {
+    key: 'DORMICE_SANDBOX_DOMAIN',
+    value: null,
+    source: 'default',
+    hint: '端口预览域名(getHost);不配则响应里诚实缺席,代理层不启用',
+  },
+];
diff --git a/packages/console/src/features/settings/pages/SettingsPage.tsx b/packages/console/src/features/settings/pages/SettingsPage.tsx
new file mode 100644
index 0000000..934136f
--- /dev/null
+++ b/packages/console/src/features/settings/pages/SettingsPage.tsx
@@ -0,0 +1,95 @@
+import { SampleDataBadge } from '@/components/SampleDataBadge';
+import { Badge } from '@/components/ui/badge';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { MOCK_PAGES_ENABLED } from '@/lib/mock';
+import { SAMPLE_CONFIG } from '../fixtures';
+
+/**
+ * daemon 生效配置的只读观察窗:回答"这台 daemon 开了哪些旋钮"。刻意
+ * 只读 — 配置的真身在 /etc/dormice/env,改完重启 daemon 生效;网页里
+ * 改配置意味着 daemon 要能写自己的配置文件,那是另一个安全等级的决定。
+ */
+export function SettingsPage() {
+  if (!MOCK_PAGES_ENABLED) {
+    return (
+      <Empty className="border border-dashed">
+        <EmptyHeader>
+          <EmptyTitle>尚未接入</EmptyTitle>
+          <EmptyDescription>
+            生效配置视图等 getConfig 端点落地后可用;现在请看主机上的{' '}
+            <code className="font-mono">/etc/dormice/env</code>。
+          </EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    );
+  }
+
+  return (
+    <>
+      <div>
+        <h1 className="flex items-center gap-2 text-lg font-semibold">
+          设置 <SampleDataBadge />
+        </h1>
+        <p className="text-sm text-muted-foreground">
+          daemon 的生效配置,只读。改配置在主机的{' '}
+          <code className="font-mono">/etc/dormice/env</code>,改完{' '}
+          <code className="font-mono">systemctl restart dormice</code>。
+        </p>
+      </div>
+
+      <div className="overflow-x-auto rounded-lg border">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>旋钮</TableHead>
+              <TableHead>生效值</TableHead>
+              <TableHead>来源</TableHead>
+              <TableHead>说明</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {SAMPLE_CONFIG.map((entry) => (
+              <TableRow key={entry.key}>
+                <TableCell className="font-mono text-xs font-medium">
+                  {entry.key}
+                </TableCell>
+                <TableCell className="font-mono text-xs">
+                  {entry.redacted ? (
+                    <Badge variant="secondary">已设置,不显示</Badge>
+                  ) : entry.value === null ? (
+                    <span className="text-muted-foreground">未配置</span>
+                  ) : (
+                    entry.value
+                  )}
+                </TableCell>
+                <TableCell>
+                  <Badge
+                    variant={entry.source === 'env' ? 'outline' : 'secondary'}
+                  >
+                    {entry.source === 'env' ? '环境变量' : '默认值'}
+                  </Badge>
+                </TableCell>
+                <TableCell className="text-sm text-muted-foreground">
+                  {entry.hint}
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+    </>
+  );
+}
diff --git a/packages/console/src/features/templates/hooks/useTemplates.ts b/packages/console/src/features/templates/hooks/useTemplates.ts
new file mode 100644
index 0000000..8e87daf
--- /dev/null
+++ b/packages/console/src/features/templates/hooks/useTemplates.ts
@@ -0,0 +1,33 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { listTemplates, registerTemplate, removeTemplate } from '@/lib/api';
+
+/**
+ * 模板实体的数据层,一个文件聚合。模板变化在操作员速度(注册/删除都在
+ * 眼前发生,mutation 自己失效缓存),不需要像沙箱那样轮询。
+ */
+export function useTemplates() {
+  return useQuery({
+    queryKey: ['templates'],
+    queryFn: listTemplates,
+    retry: false,
+  });
+}
+
+/** 注册即 upsert:对已有名字重新注册 = 指向新镜像 = 模板升级的正门。 */
+export function useRegisterTemplate() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (args: { name: string; image: string }) =>
+      registerTemplate(args.name, args.image),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['templates'] }),
+  });
+}
+
+/** 删除由 daemon 裁决:还有沙箱引用时它回 409 并点名,这里只如实转达。 */
+export function useRemoveTemplate() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (name: string) => removeTemplate(name),
+    onSettled: () => queryClient.invalidateQueries({ queryKey: ['templates'] }),
+  });
+}
diff --git a/packages/console/src/features/templates/pages/TemplatesPage.tsx b/packages/console/src/features/templates/pages/TemplatesPage.tsx
new file mode 100644
index 0000000..ed0c47b
--- /dev/null
+++ b/packages/console/src/features/templates/pages/TemplatesPage.tsx
@@ -0,0 +1,321 @@
+import type { Template } from '@dormice/shared';
+import { Add01Icon, Layers01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { Link } from '@tanstack/react-router';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '@/components/ui/alert-dialog';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@/components/ui/dialog';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+} from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { since } from '@/features/sandboxes/format';
+import { useSandboxes } from '@/features/sandboxes/hooks/useSandboxes';
+import {
+  useRegisterTemplate,
+  useRemoveTemplate,
+  useTemplates,
+} from '../hooks/useTemplates';
+
+/**
+ * 注册/升级共用一个对话框:模板是 upsert,对已有名字注册就是把它指向
+ * 新镜像 — 那正是升级的正门(升级完对引用它的沙箱逐个 rebuild)。
+ */
+function RegisterTemplateDialog({
+  trigger,
+  initial,
+}: {
+  trigger: React.ReactElement;
+  initial?: Template;
+}) {
+  const [open, setOpen] = useState(false);
+  const [name, setName] = useState(initial?.name ?? '');
+  const [image, setImage] = useState(initial?.image ?? '');
+  const mutation = useRegisterTemplate();
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (next) {
+          setName(initial?.name ?? '');
+          setImage(initial?.image ?? '');
+          mutation.reset();
+        }
+      }}
+    >
+      <DialogTrigger render={trigger} />
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>
+            {initial ? `更新「${initial.name}」指向的镜像` : '注册模板'}
+          </DialogTitle>
+          <DialogDescription>
+            模板 = 一个名字 + 宿主机上已有的 Docker 镜像。注册是配置,
+            镜像可以晚点再 build — 缺席时创建沙箱会得到点名的报错。
+          </DialogDescription>
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            mutation.mutate(
+              { name, image },
+              {
+                onSuccess: ({ template }) => {
+                  toast.success(
+                    `模板「${template.name}」→ ${template.image}` +
+                      (initial
+                        ? ' — 存量沙箱要吃到新镜像,去详情页 Rebuild'
+                        : ''),
+                  );
+                  setOpen(false);
+                },
+              },
+            );
+          }}
+        >
+          <FieldGroup>
+            <Field>
+              <FieldLabel htmlFor="template-name">名字</FieldLabel>
+              <Input
+                id="template-name"
+                value={name}
+                onChange={(event) => setName(event.target.value)}
+                placeholder="python-ml"
+                className="font-mono"
+                disabled={initial !== undefined}
+              />
+              <FieldDescription>
+                同时也是 E2B 的 templateID;「base」保留,恒指基础镜像。
+              </FieldDescription>
+            </Field>
+            <Field>
+              <FieldLabel htmlFor="template-image">镜像</FieldLabel>
+              <Input
+                id="template-image"
+                value={image}
+                onChange={(event) => setImage(event.target.value)}
+                placeholder="python-ml:v2"
+                className="font-mono"
+              />
+              <FieldDescription>
+                宿主机 Docker 里的镜像引用。重新注册同名模板 = 指向新镜像 =
+                模板升级。
+              </FieldDescription>
+            </Field>
+            {mutation.isError && (
+              <FieldError>{mutation.error.message}</FieldError>
+            )}
+          </FieldGroup>
+          <DialogFooter className="mt-6">
+            <Button
+              type="submit"
+              disabled={name === '' || image === '' || mutation.isPending}
+            >
+              {mutation.isPending && <Spinner />}
+              {initial ? '更新' : '注册'}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function RemoveTemplateButton({ name }: { name: string }) {
+  const mutation = useRemoveTemplate();
+
+  const remove = () =>
+    mutation.mutate(name, {
+      onSuccess: ({ removed }) =>
+        toast.success(
+          removed ? `已删除「${name}」` : `「${name}」本来就不存在`,
+        ),
+      // 还有沙箱引用时 daemon 回 409 并点名 userKey — 原文转达。
+      onError: (error) => toast.error(error.message),
+    });
+
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger
+        render={
+          <Button variant="destructive" size="sm" disabled={mutation.isPending}>
+            {mutation.isPending && <Spinner />}
+            删除
+          </Button>
+        }
+      />
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>删除模板「{name}」?</AlertDialogTitle>
+          <AlertDialogDescription>
+            只删注册项,不动镜像本身。还有沙箱引用时 daemon 会拒绝并点名。
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>先留着</AlertDialogCancel>
+          <AlertDialogAction variant="destructive" onClick={remove}>
+            删除
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
+
+/**
+ * 模板注册表:名字 → 镜像的账本行。宿主机的 Docker daemon 就是镜像库,
+ * 这一页管的只是指向;引用数从 2 秒轮询的沙箱列表现算,不发明新端点。
+ */
+export function TemplatesPage() {
+  const templates = useTemplates();
+  const sandboxes = useSandboxes().data?.sandboxes ?? [];
+  const list = templates.data?.templates ?? [];
+
+  const referenceCount = (name: string) =>
+    sandboxes.filter((sandbox) => sandbox.template === name).length;
+
+  return (
+    <>
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div>
+          <h1 className="text-lg font-semibold">模板</h1>
+          <p className="text-sm text-muted-foreground">
+            模板 = 命名的 Docker 镜像。名字即 E2B 的 templateID,重新注册
+            即升级。
+          </p>
+        </div>
+        <RegisterTemplateDialog
+          trigger={
+            <Button size="sm">
+              <HugeiconsIcon icon={Add01Icon} />
+              注册模板
+            </Button>
+          }
+        />
+      </div>
+
+      {templates.isError && (
+        <Alert variant="destructive">
+          <AlertDescription>{templates.error.message}</AlertDescription>
+        </Alert>
+      )}
+
+      {templates.isSuccess && list.length === 0 && (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyMedia variant="icon">
+              <HugeiconsIcon icon={Layers01Icon} />
+            </EmptyMedia>
+            <EmptyTitle>还没有注册模板</EmptyTitle>
+            <EmptyDescription>
+              没有模板时沙箱一律用 daemon 的基础镜像。在宿主机 build 一个
+              镜像,再到这里给它起个名字。
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      )}
+
+      {list.length > 0 && (
+        <div className="overflow-x-auto rounded-lg border">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead>名字</TableHead>
+                <TableHead>镜像</TableHead>
+                <TableHead>引用沙箱</TableHead>
+                <TableHead>注册于</TableHead>
+                <TableHead className="text-right">操作</TableHead>
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {list.map((template) => {
+                const references = referenceCount(template.name);
+                return (
+                  <TableRow key={template.name}>
+                    <TableCell className="font-mono font-medium">
+                      {template.name}
+                    </TableCell>
+                    <TableCell className="font-mono text-muted-foreground">
+                      {template.image}
+                    </TableCell>
+                    <TableCell className="tabular-nums">
+                      {references > 0 ? (
+                        <Link
+                          to="/sandboxes"
+                          className="text-foreground hover:underline"
+                        >
+                          {references} 个
+                        </Link>
+                      ) : (
+                        <span className="text-muted-foreground">0 个</span>
+                      )}
+                    </TableCell>
+                    <TableCell className="tabular-nums text-muted-foreground">
+                      {since(template.createdAt)}前
+                    </TableCell>
+                    <TableCell className="text-right">
+                      <div className="inline-flex gap-2">
+                        <RegisterTemplateDialog
+                          initial={template}
+                          trigger={
+                            <Button variant="outline" size="sm">
+                              更新镜像
+                            </Button>
+                          }
+                        />
+                        <RemoveTemplateButton name={template.name} />
+                      </div>
+                    </TableCell>
+                  </TableRow>
+                );
+              })}
+            </TableBody>
+          </Table>
+        </div>
+      )}
+    </>
+  );
+}
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 702bd1e..75d0fa3 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -2,6 +2,7 @@ import type {
   AcquireRequest,
   AcquireResponse,
   HostMetricsResponse,
+  RegisterTemplateResponse,
   Sandbox,
   Template,
 } from '@dormice/shared';
@@ -89,6 +90,16 @@ export const getHostMetrics = () => rpc<HostMetricsResponse>('/getHostMetrics');
 export const listTemplates = () =>
   rpc<{ templates: Template[] }>('/listTemplates');
 
+// An upsert: re-registering a name points it at a new image — that IS the
+// template upgrade front door (then rebuild the sandboxes that should move).
+export const registerTemplate = (name: string, image: string) =>
+  rpc<RegisterTemplateResponse>('/registerTemplate', { name, image });
+
+// Refused with 409 while sandboxes still use the template — the daemon is
+// the arbiter and its message names the keys; the console just relays it.
+export const removeTemplate = (name: string) =>
+  rpc<{ removed: boolean }>('/removeTemplate', { name });
+
 export const acquireSandbox = (request: AcquireRequest) =>
   rpc<AcquireResponse>('/acquireSandbox', request);
 
diff --git a/packages/console/src/features/overview/format.ts b/packages/console/src/lib/format.ts
similarity index 62%
rename from packages/console/src/features/overview/format.ts
rename to packages/console/src/lib/format.ts
index 3805e21..f670d5b 100644
--- a/packages/console/src/features/overview/format.ts
+++ b/packages/console/src/lib/format.ts
@@ -1,7 +1,9 @@
 /**
- * Bytes in binary units, auto-compact: 512 B, 24.5 MiB, 1.02 TiB. Binary
- * because that is what the numbers physically are (disk images, meminfo) —
- * a 16 GiB swap must read as 16, not 17.2.
+ * 跨域的数字格式化(总览卡片、文件浏览器、指标面板共用)。
+ *
+ * 字节用二进制单位、自动收敛位数:512 B、24.5 MiB、1.02 TiB。用二进制
+ * 是因为这些数字物理上就是二进制的(磁盘镜像、meminfo)— 16 GiB 的
+ * swap 必须读作 16,不是 17.2。
  */
 export function formatBytes(bytes: number): string {
   if (!Number.isFinite(bytes)) return '—';
@@ -17,7 +19,7 @@ export function formatBytes(bytes: number): string {
   return `${value.toFixed(digits)} ${units[unit]}`;
 }
 
-/** A used/total pair as a percentage, clamped into [0, 100]. */
+/** used/total 化成百分比,钳在 [0, 100]。 */
 export function pctOf(used: number, total: number): number {
   if (total <= 0) return 0;
   return Math.min(100, Math.max(0, (used / total) * 100));
diff --git a/packages/console/src/lib/mock.ts b/packages/console/src/lib/mock.ts
new file mode 100644
index 0000000..f5b0376
--- /dev/null
+++ b/packages/console/src/lib/mock.ts
@@ -0,0 +1,9 @@
+/**
+ * The mock gate for pages whose server side does not exist yet (activity,
+ * doctor, settings, per-sandbox metrics). In dev they render typed sample
+ * data so the UI can be designed first; a production build hides them
+ * entirely — a real deployment must never show a fake all-green health
+ * report. The fixtures' TYPES are the proposed wire shapes: when the server
+ * side lands, they graduate into @dormice/shared and the pages keep working.
+ */
+export const MOCK_PAGES_ENABLED = import.meta.env.DEV;
diff --git a/packages/console/src/routeTree.gen.ts b/packages/console/src/routeTree.gen.ts
index d4bf369..441847c 100644
--- a/packages/console/src/routeTree.gen.ts
+++ b/packages/console/src/routeTree.gen.ts
@@ -12,7 +12,12 @@ import { Route as rootRouteImport } from './routes/__root'
 import { Route as LoginRouteImport } from './routes/login'
 import { Route as AppRouteImport } from './routes/_app'
 import { Route as AppIndexRouteImport } from './routes/_app/index'
+import { Route as AppTemplatesRouteImport } from './routes/_app/templates'
+import { Route as AppSettingsRouteImport } from './routes/_app/settings'
+import { Route as AppDoctorRouteImport } from './routes/_app/doctor'
 import { Route as AppConnectRouteImport } from './routes/_app/connect'
+import { Route as AppActivityRouteImport } from './routes/_app/activity'
+import { Route as AppSandboxesIndexRouteImport } from './routes/_app/sandboxes/index'
 import { Route as AppSandboxesUserKeyRouteImport } from './routes/_app/sandboxes/$userKey'
 
 const LoginRoute = LoginRouteImport.update({
@@ -29,11 +34,36 @@ const AppIndexRoute = AppIndexRouteImport.update({
   path: '/',
   getParentRoute: () => AppRoute,
 } as any)
+const AppTemplatesRoute = AppTemplatesRouteImport.update({
+  id: '/templates',
+  path: '/templates',
+  getParentRoute: () => AppRoute,
+} as any)
+const AppSettingsRoute = AppSettingsRouteImport.update({
+  id: '/settings',
+  path: '/settings',
+  getParentRoute: () => AppRoute,
+} as any)
+const AppDoctorRoute = AppDoctorRouteImport.update({
+  id: '/doctor',
+  path: '/doctor',
+  getParentRoute: () => AppRoute,
+} as any)
 const AppConnectRoute = AppConnectRouteImport.update({
   id: '/connect',
   path: '/connect',
   getParentRoute: () => AppRoute,
 } as any)
+const AppActivityRoute = AppActivityRouteImport.update({
+  id: '/activity',
+  path: '/activity',
+  getParentRoute: () => AppRoute,
+} as any)
+const AppSandboxesIndexRoute = AppSandboxesIndexRouteImport.update({
+  id: '/sandboxes/',
+  path: '/sandboxes/',
+  getParentRoute: () => AppRoute,
+} as any)
 const AppSandboxesUserKeyRoute = AppSandboxesUserKeyRouteImport.update({
   id: '/sandboxes/$userKey',
   path: '/sandboxes/$userKey',
@@ -43,35 +73,73 @@ const AppSandboxesUserKeyRoute = AppSandboxesUserKeyRouteImport.update({
 export interface FileRoutesByFullPath {
   '/': typeof AppIndexRoute
   '/login': typeof LoginRoute
+  '/activity': typeof AppActivityRoute
   '/connect': typeof AppConnectRoute
+  '/doctor': typeof AppDoctorRoute
+  '/settings': typeof AppSettingsRoute
+  '/templates': typeof AppTemplatesRoute
   '/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
+  '/sandboxes/': typeof AppSandboxesIndexRoute
 }
 export interface FileRoutesByTo {
   '/login': typeof LoginRoute
+  '/activity': typeof AppActivityRoute
   '/connect': typeof AppConnectRoute
+  '/doctor': typeof AppDoctorRoute
+  '/settings': typeof AppSettingsRoute
+  '/templates': typeof AppTemplatesRoute
   '/': typeof AppIndexRoute
   '/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
+  '/sandboxes': typeof AppSandboxesIndexRoute
 }
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/_app': typeof AppRouteWithChildren
   '/login': typeof LoginRoute
+  '/_app/activity': typeof AppActivityRoute
   '/_app/connect': typeof AppConnectRoute
+  '/_app/doctor': typeof AppDoctorRoute
+  '/_app/settings': typeof AppSettingsRoute
+  '/_app/templates': typeof AppTemplatesRoute
   '/_app/': typeof AppIndexRoute
   '/_app/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
+  '/_app/sandboxes/': typeof AppSandboxesIndexRoute
 }
 export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
-  fullPaths: '/' | '/login' | '/connect' | '/sandboxes/$userKey'
+  fullPaths:
+    | '/'
+    | '/login'
+    | '/activity'
+    | '/connect'
+    | '/doctor'
+    | '/settings'
+    | '/templates'
+    | '/sandboxes/$userKey'
+    | '/sandboxes/'
   fileRoutesByTo: FileRoutesByTo
-  to: '/login' | '/connect' | '/' | '/sandboxes/$userKey'
+  to:
+    | '/login'
+    | '/activity'
+    | '/connect'
+    | '/doctor'
+    | '/settings'
+    | '/templates'
+    | '/'
+    | '/sandboxes/$userKey'
+    | '/sandboxes'
   id:
     | '__root__'
     | '/_app'
     | '/login'
+    | '/_app/activity'
     | '/_app/connect'
+    | '/_app/doctor'
+    | '/_app/settings'
+    | '/_app/templates'
     | '/_app/'
     | '/_app/sandboxes/$userKey'
+    | '/_app/sandboxes/'
   fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
@@ -102,6 +170,27 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AppIndexRouteImport
       parentRoute: typeof AppRoute
     }
+    '/_app/templates': {
+      id: '/_app/templates'
+      path: '/templates'
+      fullPath: '/templates'
+      preLoaderRoute: typeof AppTemplatesRouteImport
+      parentRoute: typeof AppRoute
+    }
+    '/_app/settings': {
+      id: '/_app/settings'
+      path: '/settings'
+      fullPath: '/settings'
+      preLoaderRoute: typeof AppSettingsRouteImport
+      parentRoute: typeof AppRoute
+    }
+    '/_app/doctor': {
+      id: '/_app/doctor'
+      path: '/doctor'
+      fullPath: '/doctor'
+      preLoaderRoute: typeof AppDoctorRouteImport
+      parentRoute: typeof AppRoute
+    }
     '/_app/connect': {
       id: '/_app/connect'
       path: '/connect'
@@ -109,6 +198,20 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AppConnectRouteImport
       parentRoute: typeof AppRoute
     }
+    '/_app/activity': {
+      id: '/_app/activity'
+      path: '/activity'
+      fullPath: '/activity'
+      preLoaderRoute: typeof AppActivityRouteImport
+      parentRoute: typeof AppRoute
+    }
+    '/_app/sandboxes/': {
+      id: '/_app/sandboxes/'
+      path: '/sandboxes'
+      fullPath: '/sandboxes/'
+      preLoaderRoute: typeof AppSandboxesIndexRouteImport
+      parentRoute: typeof AppRoute
+    }
     '/_app/sandboxes/$userKey': {
       id: '/_app/sandboxes/$userKey'
       path: '/sandboxes/$userKey'
@@ -120,15 +223,25 @@ declare module '@tanstack/react-router' {
 }
 
 interface AppRouteChildren {
+  AppActivityRoute: typeof AppActivityRoute
   AppConnectRoute: typeof AppConnectRoute
+  AppDoctorRoute: typeof AppDoctorRoute
+  AppSettingsRoute: typeof AppSettingsRoute
+  AppTemplatesRoute: typeof AppTemplatesRoute
   AppIndexRoute: typeof AppIndexRoute
   AppSandboxesUserKeyRoute: typeof AppSandboxesUserKeyRoute
+  AppSandboxesIndexRoute: typeof AppSandboxesIndexRoute
 }
 
 const AppRouteChildren: AppRouteChildren = {
+  AppActivityRoute: AppActivityRoute,
   AppConnectRoute: AppConnectRoute,
+  AppDoctorRoute: AppDoctorRoute,
+  AppSettingsRoute: AppSettingsRoute,
+  AppTemplatesRoute: AppTemplatesRoute,
   AppIndexRoute: AppIndexRoute,
   AppSandboxesUserKeyRoute: AppSandboxesUserKeyRoute,
+  AppSandboxesIndexRoute: AppSandboxesIndexRoute,
 }
 
 const AppRouteWithChildren = AppRoute._addFileChildren(AppRouteChildren)
diff --git a/packages/console/src/routes/_app.tsx b/packages/console/src/routes/_app.tsx
index 31fbb82..76e50b0 100644
--- a/packages/console/src/routes/_app.tsx
+++ b/packages/console/src/routes/_app.tsx
@@ -1,4 +1,5 @@
 import { createFileRoute, redirect } from '@tanstack/react-router';
+import { AppShell } from '@/components/AppShell';
 import { hasSessionMarker } from '@/lib/session';
 
 /**
@@ -8,6 +9,9 @@ import { hasSessionMarker } from '@/lib/session';
  * api.ts on the first request. What the guard buys is the common case:
  * a signed-out visitor never sees a protected page flash before the
  * redirect, and the deep link they wanted survives the trip through login.
+ *
+ * The layout is also written once: AppShell renders the sidebar, the top
+ * bar and the page Outlet for every signed-in route.
  */
 export const Route = createFileRoute('/_app')({
   beforeLoad: ({ location }) => {
@@ -15,4 +19,5 @@ export const Route = createFileRoute('/_app')({
       throw redirect({ to: '/login', search: { redirect: location.href } });
     }
   },
+  component: AppShell,
 });
diff --git a/packages/console/src/routes/_app/activity.tsx b/packages/console/src/routes/_app/activity.tsx
new file mode 100644
index 0000000..a69a966
--- /dev/null
+++ b/packages/console/src/routes/_app/activity.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { ActivityPage } from '@/features/activity/pages/ActivityPage';
+
+export const Route = createFileRoute('/_app/activity')({
+  component: ActivityPage,
+});
diff --git a/packages/console/src/routes/_app/doctor.tsx b/packages/console/src/routes/_app/doctor.tsx
new file mode 100644
index 0000000..133caa8
--- /dev/null
+++ b/packages/console/src/routes/_app/doctor.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { DoctorPage } from '@/features/doctor/pages/DoctorPage';
+
+export const Route = createFileRoute('/_app/doctor')({
+  component: DoctorPage,
+});
diff --git a/packages/console/src/routes/_app/index.tsx b/packages/console/src/routes/_app/index.tsx
index 90ed5a9..cd51d19 100644
--- a/packages/console/src/routes/_app/index.tsx
+++ b/packages/console/src/routes/_app/index.tsx
@@ -1,6 +1,6 @@
 import { createFileRoute } from '@tanstack/react-router';
-import { SandboxesPage } from '@/features/sandboxes/pages/SandboxesPage';
+import { OverviewPage } from '@/features/overview/pages/OverviewPage';
 
 export const Route = createFileRoute('/_app/')({
-  component: SandboxesPage,
+  component: OverviewPage,
 });
diff --git a/packages/console/src/routes/_app/sandboxes/$userKey.tsx b/packages/console/src/routes/_app/sandboxes/$userKey.tsx
index fd4ba9f..92996a6 100644
--- a/packages/console/src/routes/_app/sandboxes/$userKey.tsx
+++ b/packages/console/src/routes/_app/sandboxes/$userKey.tsx
@@ -1,6 +1,16 @@
 import { createFileRoute } from '@tanstack/react-router';
-import { SandboxDetailPage } from '@/features/sandboxes/pages/SandboxDetailPage';
+import {
+  DETAIL_TABS,
+  type DetailTab,
+  SandboxDetailPage,
+} from '@/features/sandboxes/pages/SandboxDetailPage';
 
+// tab 进 URL:刷新、分享、返回键都停在同一个工作区面板上。
 export const Route = createFileRoute('/_app/sandboxes/$userKey')({
+  validateSearch: (search: Record<string, unknown>): { tab: DetailTab } => ({
+    tab: DETAIL_TABS.includes(search.tab as DetailTab)
+      ? (search.tab as DetailTab)
+      : 'overview',
+  }),
   component: SandboxDetailPage,
 });
diff --git a/packages/console/src/routes/_app/sandboxes/index.tsx b/packages/console/src/routes/_app/sandboxes/index.tsx
new file mode 100644
index 0000000..2760445
--- /dev/null
+++ b/packages/console/src/routes/_app/sandboxes/index.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { SandboxesPage } from '@/features/sandboxes/pages/SandboxesPage';
+
+export const Route = createFileRoute('/_app/sandboxes/')({
+  component: SandboxesPage,
+});
diff --git a/packages/console/src/routes/_app/settings.tsx b/packages/console/src/routes/_app/settings.tsx
new file mode 100644
index 0000000..d5b27d7
--- /dev/null
+++ b/packages/console/src/routes/_app/settings.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { SettingsPage } from '@/features/settings/pages/SettingsPage';
+
+export const Route = createFileRoute('/_app/settings')({
+  component: SettingsPage,
+});
diff --git a/packages/console/src/routes/_app/templates.tsx b/packages/console/src/routes/_app/templates.tsx
new file mode 100644
index 0000000..c409bcc
--- /dev/null
+++ b/packages/console/src/routes/_app/templates.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { TemplatesPage } from '@/features/templates/pages/TemplatesPage';
+
+export const Route = createFileRoute('/_app/templates')({
+  component: TemplatesPage,
+});
diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index 9413651..d56323f 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -29,6 +29,8 @@ export default defineConfig({
       '/acquireSandbox': 'http://127.0.0.1:3676',
       '/rebuildSandbox': 'http://127.0.0.1:3676',
       '/listTemplates': 'http://127.0.0.1:3676',
+      '/registerTemplate': 'http://127.0.0.1:3676',
+      '/removeTemplate': 'http://127.0.0.1:3676',
       '/getHostMetrics': 'http://127.0.0.1:3676',
       // The terminal speaks the envd surface directly, like the e2b SDK.
       '/e2b': 'http://127.0.0.1:3676',

From 6d60245d2d4b535c67280c3e8cceaaa21e24aba6 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 11 Jul 2026 02:15:40 +0800
Subject: [PATCH 045/133] The console e2e follows the Chinese title

---
 e2e/src/console.test.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/e2e/src/console.test.ts b/e2e/src/console.test.ts
index 3ddbf3d..654bdc7 100644
--- a/e2e/src/console.test.ts
+++ b/e2e/src/console.test.ts
@@ -28,7 +28,7 @@ describe('web console over a real daemon', () => {
     expect(res.status).toBe(200);
     expect(res.headers.get('content-type')).toContain('text/html');
     const html = await res.text();
-    expect(html).toContain('<title>Dormice</title>');
+    expect(html).toContain('<title>Dormice 控制台</title>');
     // The base path is baked in at build time — a bare /assets reference
     // would 404 behind the daemon's /console prefix.
     expect(html).toContain('/console/assets/');
@@ -37,7 +37,7 @@ describe('web console over a real daemon', () => {
   it('falls back to the SPA for client-side routes', async () => {
     const res = await fetch(`${endpoint()}/console/login`);
     expect(res.status).toBe(200);
-    expect(await res.text()).toContain('<title>Dormice</title>');
+    expect(await res.text()).toContain('<title>Dormice 控制台</title>');
   });
 
   it('rejects a login with the wrong token', async () => {

From 8f41c087502809a4d5e9e46fa0e95985236d7b8d Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 11 Jul 2026 02:30:32 +0800
Subject: [PATCH 046/133] The seed recipe names commands that exist

---
 packages/console/scripts/seed.mjs | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/packages/console/scripts/seed.mjs b/packages/console/scripts/seed.mjs
index 0246b59..413a65e 100644
--- a/packages/console/scripts/seed.mjs
+++ b/packages/console/scripts/seed.mjs
@@ -5,11 +5,14 @@
  * 原生 RPC,零依赖;沙箱状态的多样性(冻结/停止)靠 daemon 的空闲扫描
  * 器降温,所以 dev daemon 要把扫描间隔拧到 1 秒(见下)。
  *
- * 用法(fake 执行器即可,勿对生产 daemon 跑;token 要求 ≥32 字符):
+ * 用法(fake 执行器即可,勿对生产 daemon 跑;token 要求 ≥32 字符;
+ * server 包刻意没有 dev 脚本 — daemon 跑的永远是构建产物):
  *   0) export DORMICE_API_TOKEN=$(openssl rand -hex 32)
- *   1) DORMICE_SCAN_INTERVAL_SECONDS=1 pnpm --filter @dormice/server dev
- *   2) pnpm --filter @dormice/console seed
- *   3) pnpm --filter @dormice/console dev  →  http://localhost:5173/console
+ *   1) pnpm --filter @dormice/server... --filter @dormice/console... build
+ *   2) DORMICE_SCAN_INTERVAL_SECONDS=1 node packages/server/dist/main.js
+ *   3) pnpm --filter @dormice/console seed
+ *   4) 直接看:daemon 自己托管 http://127.0.0.1:3676/console(登录 token 即上面那个);
+ *      要改前端代码带热更新,才需要 pnpm --filter @dormice/console dev → http://localhost:5173/console
  *
  * 注:模板指向的镜像名在 fake 模式下随意;对 docker 执行器跑时镜像必须
  * 真的在宿主机上,否则用这些模板创建会得到点名的报错(那也是诚实)。

From 0e9348e37f61f740a8cd60fbf2a31e3851ecb4ec Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 11 Jul 2026 02:38:02 +0800
Subject: [PATCH 047/133] The S3 archiver closes the lifecycle: stopped disks
 ship to a bucket, acquire restores them with progress
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

stopped -> archived -> restoring -> active, end to end and with zero DB
migration — the states and the restoring response were carved out long
ago. The archive is a tar.zst of the mounted tree, uploaded before the
ledger records archived and destroyed locally only after (disk present
means upload unconfirmed, so every crash retries); restore runs without
the key lock, reports real download/extract progress through acquire's
restoring union, and reverts to archived on failure. The executor grows
exactly two verbs (exportDisk/importDisk, round-trip pinned by a new
contract chapter); S3 stays outside it, behind an ArchiveStore with an
aws-sdk implementation whose WHEN_REQUIRED checksum setting is pinned
forever by a mini S3 that refuses checksum negotiation the way OSS does.
The scanner sweeps in two phases so serial archives never starve the
heartbeat; the reconciler sweeps stale local copies of archived rows and
repairs restoring zombies reality-first; the startup guard no longer
counts rows whose bodies live in S3. The E2B surface blocks through
restores (that protocol has no restoring concept), gated behind the
logical-state check so a paused-archived sandbox refuses without paying
for a restore first. Restore deletes the object afterwards: an object
exists exactly while its row is archived, so release never chases stale
copies.
---
 README.md                                     |  36 +-
 deploy/install.sh                             |  14 +-
 e2e/package.json                              |   3 +
 e2e/src/archive.test.ts                       | 101 +++++
 e2e/src/native.test.ts                        |   7 +-
 e2e/src/setup/daemon.ts                       |  16 +
 packages/cli/src/doctor.test.ts               |  64 ++++
 packages/cli/src/doctor.ts                    |  46 +++
 packages/sdk/src/client.test.ts               |  15 +-
 packages/server/package.json                  |   8 +-
 packages/server/src/app.test.ts               | 238 +++++++++++-
 packages/server/src/app.ts                    |  26 +-
 packages/server/src/archive/archiver.test.ts  | 237 ++++++++++++
 packages/server/src/archive/archiver.ts       | 249 +++++++++++++
 packages/server/src/archive/mem-store.ts      |  44 +++
 packages/server/src/archive/mini-s3.ts        | 123 +++++++
 packages/server/src/archive/s3-store.ts       | 106 ++++++
 .../server/src/archive/store.contract.test.ts | 169 +++++++++
 packages/server/src/archive/store.ts          |  32 ++
 packages/server/src/config.test.ts            |  61 ++-
 packages/server/src/config.ts                 |  69 +++-
 packages/server/src/db/ledger.ts              |   4 +-
 packages/server/src/e2b/compat.test.ts        | 198 ++++++++++
 packages/server/src/e2b/control.ts            |  61 ++-
 packages/server/src/e2b/deps.ts               |   9 +
 packages/server/src/e2b/envd/shared.ts        |  37 +-
 .../src/executor/contract/disk-transfer.ts    | 124 +++++++
 .../server/src/executor/contract/index.ts     |   2 +
 packages/server/src/executor/docker.ts        |  72 +++-
 packages/server/src/executor/executor.ts      |  24 ++
 packages/server/src/executor/fake.ts          |  61 +++
 packages/server/src/lifecycle.ts              |  34 +-
 packages/server/src/main.ts                   |  43 ++-
 packages/server/src/policy.test.ts            |  83 ++++-
 packages/server/src/policy.ts                 |  50 ++-
 packages/server/src/reconciler.test.ts        | 113 +++++-
 packages/server/src/reconciler.ts             |  61 ++-
 packages/server/src/routes/sandboxes.ts       | 109 +++++-
 packages/server/src/scanner.test.ts           | 224 ++++++++++-
 packages/server/src/scanner.ts                |  81 +++-
 packages/server/src/startup-guard.test.ts     |  36 +-
 packages/server/src/startup-guard.ts          |  15 +
 pnpm-lock.yaml                                | 347 ++++++++++++++++++
 43 files changed, 3355 insertions(+), 97 deletions(-)
 create mode 100644 e2e/src/archive.test.ts
 create mode 100644 packages/server/src/archive/archiver.test.ts
 create mode 100644 packages/server/src/archive/archiver.ts
 create mode 100644 packages/server/src/archive/mem-store.ts
 create mode 100644 packages/server/src/archive/mini-s3.ts
 create mode 100644 packages/server/src/archive/s3-store.ts
 create mode 100644 packages/server/src/archive/store.contract.test.ts
 create mode 100644 packages/server/src/archive/store.ts
 create mode 100644 packages/server/src/executor/contract/disk-transfer.ts

diff --git a/README.md b/README.md
index 18303c1..31aa15b 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 **The SQLite of agent sandboxes** — a self-hosted sandbox platform for AI agents. One machine, sandboxes that live forever, idle costs nothing.
 
-> **Status: early development.** The daemon, its lifecycle engine, the SDK, the CLI, the web console, the real Docker + gVisor executor, and the E2B-compatible API work end to end — the full create → freeze → stop → wake cycle, command execution, file I/O, and the official `e2b` SDK against real infrastructure. Nothing here is ready for production yet.
+> **Status: early development.** The daemon, its lifecycle engine, the SDK, the CLI, the web console, the real Docker + gVisor executor, the S3 archiver, and the E2B-compatible API work end to end — the full create → freeze → stop → archive → restore cycle, command execution, file I/O, and the official `e2b` SDK against real infrastructure. Nothing here is ready for production yet.
 
 ## The idea
 
@@ -98,9 +98,10 @@ official package*, and has passed against a real Docker + gVisor daemon:
 
 Deliberate deltas from the hosted product:
 
-- **No template builds.** Every sandbox runs the daemon's single base
-  image (`DORMICE_BASE_IMAGE`); the `template` argument is accepted and
-  ignored.
+- **No template builds.** Templates are named images: build one with
+  docker, register it with `dor template add`, and `Sandbox.create('name')`
+  resolves it (an unregistered name is an honest 404). The hosted
+  product's build pipeline (`e2b template build`) is not implemented.
 - **Freezing keeps processes.** A frozen sandbox's processes suspend and
   resume mid-flight — any touch wakes the sandbox in ~50 ms.
 - **Permanence stays the default.** Sandboxes created through the E2B
@@ -147,6 +148,30 @@ is a choice you make explicitly, one of two ways:
   Anything exposed beyond localhost should be HTTPS — the API token and the
   session cookie travel in every request.
 
+## Cold archive (S3, optional)
+
+Set the four `DORMICE_S3_*` variables and idle sandboxes take the last
+step down: a week after stopping (tunable per sandbox via
+`archiveAfterSeconds`), the disk is packed with `tar` + `zstd`, shipped to
+any S3-compatible bucket (AWS, Cloudflare R2, MinIO, Alibaba OSS in
+S3-compat mode), and freed locally. The next `acquireSandbox` answers
+`{ status: 'restoring', progress }` immediately and flips to `ready` once
+the disk is back — slow wake-ups are honest, never a silent hang.
+
+```sh
+DORMICE_S3_ENDPOINT=https://s3.example.com   # full URL; MinIO speaks http
+DORMICE_S3_BUCKET=dormice-archive
+DORMICE_S3_ACCESS_KEY_ID=...
+DORMICE_S3_SECRET_ACCESS_KEY=...
+# DORMICE_S3_REGION=us-east-1
+# DORMICE_S3_FORCE_PATH_STYLE=true           # MinIO needs this
+```
+
+Unset, the feature is honestly absent: sandboxes park at `stopped`
+forever, and a policy asking to archive is refused rather than silently
+stored. The bucket must exist; the host needs `zstd` (`install.sh`
+installs it, `dor doctor` checks it).
+
 ## Host prerequisites (docker executor)
 
 The daemon itself runs anywhere Node 22+ runs, with an in-memory fake
@@ -186,9 +211,6 @@ Pick something else if:
   requires sandboxes to be processes, and "installs anywhere" rules out
   requiring KVM. If only Firecracker-class VM isolation will do, this
   trade is not for you.
-- **You need cold archive today.** The `archived` state exists in the
-  protocol, but the S3 archiver is not built yet; the knob defaults to off
-  and nothing pretends otherwise.
 - **Your workloads aren't Linux.** Sandboxes are Linux containers.
 
 ## Repository layout
diff --git a/deploy/install.sh b/deploy/install.sh
index dc897e6..a76ee48 100644
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -71,9 +71,10 @@ grep -qw memory /sys/fs/cgroup/cgroup.controllers 2>/dev/null \
 note "Linux x86_64, root, cgroup v2 — ok"
 
 # ---- base packages ---------------------------------------------------------
-log 'base packages (git, curl, openssl)'
+log 'base packages (git, curl, openssl, zstd)'
 missing=''
-for tool in git curl openssl; do
+# zstd: the archiver's tar -I zstd runs on the host at every archive/restore.
+for tool in git curl openssl zstd; do
   command -v "$tool" >/dev/null || missing="$missing $tool"
 done
 if [ -n "$missing" ]; then
@@ -326,6 +327,15 @@ DORMICE_EXECUTOR=docker
 DORMICE_BASE_IMAGE=$base_image
 DORMICE_DB_PATH=$DATA_DIR/dormice.db
 DORMICE_DATA_DIR=$DATA_DIR
+# Optional: the S3 archiver. Set all four to archive idle sandboxes' disks
+# to any S3-compatible store (AWS, R2, MinIO, OSS in S3-compat mode) after
+# a week of idleness — and restore them on the next acquire. Endpoint is a
+# full URL; MinIO needs DORMICE_S3_FORCE_PATH_STYLE=true.
+#DORMICE_S3_ENDPOINT=
+#DORMICE_S3_BUCKET=
+#DORMICE_S3_ACCESS_KEY_ID=
+#DORMICE_S3_SECRET_ACCESS_KEY=
+#DORMICE_S3_FORCE_PATH_STYLE=false
 EOF
   chmod 600 "$ENV_FILE"
   note "wrote $ENV_FILE (mode 600) with a fresh API token"
diff --git a/e2e/package.json b/e2e/package.json
index 4f97a8c..9d104a0 100644
--- a/e2e/package.json
+++ b/e2e/package.json
@@ -12,5 +12,8 @@
   "dependencies": {
     "@dormice/sdk": "workspace:*",
     "e2b": "^2.31.0"
+  },
+  "devDependencies": {
+    "@dormice/server": "workspace:*"
   }
 }
diff --git a/e2e/src/archive.test.ts b/e2e/src/archive.test.ts
new file mode 100644
index 0000000..476d85f
--- /dev/null
+++ b/e2e/src/archive.test.ts
@@ -0,0 +1,101 @@
+import { Dormice } from '@dormice/sdk';
+import { describe, expect, inject, it } from 'vitest';
+
+// The archive lifecycle, black-box: the daemon runs against the exam's
+// mini S3 (see setup/daemon.ts), so the whole cold path — idle down to
+// archived, the disk gone from the host, then a poll-until-ready restore —
+// runs over the real wire in every mode. Fake mode ships JSON archives,
+// docker mode real tar.zst; the protocol is identical.
+
+function client() {
+  return new Dormice({
+    endpoint: inject('dormiceEndpoint'),
+    token: inject('dormiceToken'),
+  });
+}
+
+function sleep(seconds: number) {
+  return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+}
+
+describe('the archive lifecycle over a real daemon', () => {
+  it('archives by idleness, restores by acquire, data intact', async () => {
+    const dormice = client();
+    const first = await dormice.acquireSandbox('archive-key', {
+      policy: {
+        freezeAfterSeconds: 1,
+        stopAfterSeconds: 2,
+        archiveAfterSeconds: 3,
+      },
+    });
+    const id = first.sandbox.sandboxId;
+    await dormice.writeFiles('archive-key', [
+      { path: 'kept.txt', content: 'survived the bucket' },
+    ]);
+
+    // Poll the observation window — never acquire, which would touch the
+    // idle clock and keep the sandbox warm forever.
+    const deadline = Date.now() + 15_000;
+    for (;;) {
+      const sandboxes = await dormice.listSandboxes();
+      const mine = sandboxes.find((s) => s.userKey === 'archive-key');
+      if (mine?.state === 'archived') break;
+      if (Date.now() > deadline) {
+        throw new Error(`never archived; last observed: ${mine?.state}`);
+      }
+      await sleep(0.25);
+    }
+
+    // The re-acquire may answer `restoring` with progress or — the exam's
+    // archives are tiny — already `ready`; either way polling acquire is
+    // the documented way back, and the union is the wire contract.
+    let outcome = await dormice.acquireSandbox('archive-key');
+    const restoreDeadline = Date.now() + 15_000;
+    while (outcome.status !== 'ready') {
+      expect(outcome.status).toBe('restoring');
+      if (outcome.status === 'restoring') {
+        expect(['downloading', 'extracting']).toContain(outcome.progress.phase);
+      }
+      if (Date.now() > restoreDeadline) {
+        throw new Error('restore never finished');
+      }
+      await sleep(0.25);
+      outcome = await dormice.acquireSandbox('archive-key');
+    }
+
+    expect(outcome.sandbox.sandboxId).toBe(id);
+    expect(outcome.sandbox.state).toBe('active');
+    const read = await dormice.readFile('archive-key', 'kept.txt');
+    expect(Buffer.from(read.content).toString()).toBe('survived the bucket');
+
+    await dormice.releaseSandbox('archive-key');
+  });
+
+  it('a released archived sandbox is gone for good', async () => {
+    const dormice = client();
+    await dormice.acquireSandbox('archive-release-key', {
+      policy: {
+        freezeAfterSeconds: 1,
+        stopAfterSeconds: 2,
+        archiveAfterSeconds: 3,
+      },
+    });
+    const deadline = Date.now() + 15_000;
+    for (;;) {
+      const sandboxes = await dormice.listSandboxes();
+      const mine = sandboxes.find((s) => s.userKey === 'archive-release-key');
+      if (mine?.state === 'archived') break;
+      if (Date.now() > deadline) {
+        throw new Error(`never archived; last observed: ${mine?.state}`);
+      }
+      await sleep(0.25);
+    }
+
+    const released = await dormice.releaseSandbox('archive-release-key');
+    expect(released.released).toBe(true);
+    // The key is free again: the next acquire is a brand-new sandbox.
+    const fresh = await dormice.acquireSandbox('archive-release-key');
+    expect(fresh.status).toBe('ready');
+    await dormice.releaseSandbox('archive-release-key');
+  });
+});
diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index e0854b1..1f820bd 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -31,7 +31,12 @@ describe('native API over a real daemon', () => {
     expect(res.status).toBe('ready');
     expect(res.sandbox.state).toBe('active');
     expect(res.sandbox.userKey).toBe('fresh-key');
-    expect(res.sandbox.policy).toEqual(DEFAULT_LIFECYCLE_POLICY);
+    // The exam daemon runs with S3 configured (see setup/daemon.ts), so the
+    // archive default is live: a week from stopped to archived.
+    expect(res.sandbox.policy).toEqual({
+      ...DEFAULT_LIFECYCLE_POLICY,
+      archiveAfterSeconds: 7 * 24 * 60 * 60,
+    });
     expect(res.sandbox.endpoint).toBe(inject('dormiceEndpoint'));
   });
 
diff --git a/e2e/src/setup/daemon.ts b/e2e/src/setup/daemon.ts
index 9521bd4..af9c095 100644
--- a/e2e/src/setup/daemon.ts
+++ b/e2e/src/setup/daemon.ts
@@ -5,6 +5,7 @@ import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { startMiniS3 } from '@dormice/server/mini-s3';
 import type { TestProject } from 'vitest/node';
 
 declare module 'vitest' {
@@ -36,6 +37,12 @@ export default async function setup(project: TestProject) {
   const port = 20000 + Math.floor(Math.random() * 20000);
   const endpoint = `http://127.0.0.1:${port}`;
 
+  // The exam's own S3 (in-process, test-only): the archive lifecycle runs
+  // black-box in every mode — the fake executor exports real files, the
+  // store speaks real HTTP. It also mimics OSS's checksum strictness, so a
+  // daemon that regressed pit #8 fails here too.
+  const miniS3 = await startMiniS3();
+
   // An explicit allowlist instead of inheriting the whole environment:
   // whatever DORMICE_* knobs happen to be exported in the developer's shell
   // must not silently reconfigure the daemon under test. The three docker
@@ -72,6 +79,14 @@ export default async function setup(project: TestProject) {
       // A wildcard sandbox domain so getHost() and the port proxy are
       // exercised — no DNS needed, tests spoof the Host header locally.
       DORMICE_SANDBOX_DOMAIN: 'sbx.dormice.test',
+      // The archiver, pointed at the exam's mini S3. Deliberately NOT in
+      // the inherited allowlist: a developer's real DORMICE_S3_* exports
+      // must never leak an exam's archives into a production bucket.
+      DORMICE_S3_ENDPOINT: miniS3.url,
+      DORMICE_S3_BUCKET: 'e2e-archive',
+      DORMICE_S3_ACCESS_KEY_ID: 'e2e-key',
+      DORMICE_S3_SECRET_ACCESS_KEY: 'e2e-secret',
+      DORMICE_S3_FORCE_PATH_STYLE: 'true',
     },
     stdio: ['ignore', 'pipe', 'pipe'],
   });
@@ -108,6 +123,7 @@ export default async function setup(project: TestProject) {
 
   return async () => {
     child.kill();
+    await miniS3.close();
     await rm(dataDir, { recursive: true, force: true });
   };
 }
diff --git a/packages/cli/src/doctor.test.ts b/packages/cli/src/doctor.test.ts
index bacff58..a548074 100644
--- a/packages/cli/src/doctor.test.ts
+++ b/packages/cli/src/doctor.test.ts
@@ -68,6 +68,7 @@ function fakeHost(
     [`docker run --rm --runtime=runsc ${IMAGE} id -u`]: ok('1000\n'),
     [`docker run --rm --runtime=runsc ${IMAGE} bash -c command -v inotifywait || echo MISSING`]:
       ok('/usr/bin/inotifywait\n'),
+    'zstd --version': ok('zstd command line interface v1.5.5\n'),
     ...overrides.commands,
   };
   const calls: string[] = [];
@@ -81,6 +82,10 @@ function fakeHost(
       DORMICE_BASE_IMAGE: IMAGE,
       DORMICE_DB_PATH: '/var/lib/dormice/dormice.db',
       DORMICE_DATA_DIR: '/var/lib/dormice',
+      DORMICE_S3_ENDPOINT: 'http://127.0.0.1:9000',
+      DORMICE_S3_BUCKET: 'dormice-archive',
+      DORMICE_S3_ACCESS_KEY_ID: 'minio-user',
+      DORMICE_S3_SECRET_ACCESS_KEY: 'minio-secret',
     },
     calls,
     run: async (cmd, args) => {
@@ -347,3 +352,62 @@ describe('container probes', () => {
     });
   });
 });
+
+describe('the S3 archive checks', () => {
+  // fakeHost's env override replaces wholesale; this is the healthy host's
+  // env WITHOUT the S3 set — the archiver-less operator.
+  const NO_S3_ENV = {
+    DORMICE_API_TOKEN: TOKEN,
+    DORMICE_EXECUTOR: 'docker',
+    DORMICE_BASE_IMAGE: IMAGE,
+    DORMICE_DB_PATH: '/var/lib/dormice/dormice.db',
+    DORMICE_DATA_DIR: '/var/lib/dormice',
+  };
+
+  it('skips both checks when no S3 is configured', async () => {
+    const { results, failed } = await runDoctor(fakeHost({ env: NO_S3_ENV }));
+    expect(results['s3-config']).toMatchObject({
+      status: 'skip',
+      detail: expect.stringContaining('archiver is disabled'),
+    });
+    // zstd is gated on s3-config passing, and skips are not failures.
+    expect(results.zstd).toMatchObject({ status: 'skip' });
+    expect(failed).toBe(false);
+  });
+
+  it('fails a partial S3 set, naming the missing variables', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        env: {
+          ...NO_S3_ENV,
+          DORMICE_S3_ENDPOINT: 'http://127.0.0.1:9000',
+          DORMICE_S3_BUCKET: 'dormice-archive',
+        },
+      }),
+    );
+    expect(results['s3-config']).toMatchObject({
+      status: 'fail',
+      detail: expect.stringContaining('DORMICE_S3_ACCESS_KEY_ID'),
+    });
+  });
+
+  it('passes a full set and checks zstd on the docker executor', async () => {
+    // The healthy default host carries the full S3 set and zstd.
+    const { results } = await runDoctor(fakeHost());
+    expect(results['s3-config']).toMatchObject({ status: 'pass' });
+    expect(results.zstd).toMatchObject({
+      status: 'pass',
+      detail: expect.stringContaining('zstd'),
+    });
+  });
+
+  it('fails when zstd is missing on a docker host with S3 configured', async () => {
+    const { results } = await runDoctor(
+      fakeHost({ commands: { 'zstd --version': boom('not found') } }),
+    );
+    expect(results.zstd).toMatchObject({
+      status: 'fail',
+      fix: 'apt-get install -y zstd',
+    });
+  });
+});
diff --git a/packages/cli/src/doctor.ts b/packages/cli/src/doctor.ts
index 9b2d8b2..6c291ac 100644
--- a/packages/cli/src/doctor.ts
+++ b/packages/cli/src/doctor.ts
@@ -353,6 +353,52 @@ const CHECKS: DoctorCheck[] = [
           );
     },
   },
+  {
+    id: 's3-config',
+    title: 'S3 archive configuration',
+    run: async (ctx) => {
+      const wanted = [
+        'DORMICE_S3_ENDPOINT',
+        'DORMICE_S3_BUCKET',
+        'DORMICE_S3_ACCESS_KEY_ID',
+        'DORMICE_S3_SECRET_ACCESS_KEY',
+      ];
+      const missing = wanted.filter((name) => !ctx.env[name]);
+      if (missing.length === wanted.length) {
+        return skip(
+          'DORMICE_S3_* not set — the archiver is disabled; sandboxes park at stopped forever',
+        );
+      }
+      if (missing.length > 0) {
+        // The daemon's config schema refuses this too; naming it here saves
+        // one failed boot.
+        return fail(
+          `partial S3 set: ${missing.join(', ')} missing — the daemon refuses a half-configured archiver`,
+          'set all four DORMICE_S3_* variables (endpoint, bucket, key id, secret) or none',
+        );
+      }
+      return pass('all four DORMICE_S3_* variables set — archiver enabled');
+    },
+  },
+  {
+    id: 'zstd',
+    title: 'zstd available',
+    needs: ['s3-config'],
+    run: async (ctx) => {
+      // Only the docker executor shells out to tar/zstd; the archiver runs
+      // `tar -I zstd` on the host at every archive and restore.
+      if (ctx.env.DORMICE_EXECUTOR !== 'docker') {
+        return skip('only the docker executor archives with host tar+zstd');
+      }
+      const res = await ctx.run('zstd', ['--version']);
+      return res.ok
+        ? pass(res.stdout.trim().split('\n')[0] ?? 'present')
+        : fail(
+            'zstd is not installed — every archive attempt will fail at tar',
+            'apt-get install -y zstd',
+          );
+    },
+  },
   {
     id: 'base-image',
     title: 'base image available',
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 683152b..1191fab 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -96,11 +96,24 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
   });
 
   it("surfaces the server's message for an invalid policy", async () => {
+    await expect(
+      client.acquireSandbox('carol', {
+        policy: { freezeAfterSeconds: 61, stopAfterSeconds: 60 },
+      }),
+    ).rejects.toMatchObject({
+      status: 400,
+      message: expect.stringMatching(/freezeAfterSeconds/),
+    });
+  });
+
+  it("surfaces the server's refusal of archiving without S3", async () => {
+    // This test server has no archiver; the union's `restoring` arm is
+    // exercised end-to-end by the e2e archive suite instead.
     await expect(
       client.acquireSandbox('carol', { policy: { archiveAfterSeconds: 1 } }),
     ).rejects.toMatchObject({
       status: 400,
-      message: expect.stringMatching(/stopAfterSeconds/),
+      message: expect.stringMatching(/archiving requires S3/),
     });
   });
 
diff --git a/packages/server/package.json b/packages/server/package.json
index db08d0e..2937f9e 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./mini-s3": {
+      "types": "./dist/archive/mini-s3.d.ts",
+      "default": "./dist/archive/mini-s3.js"
     }
   },
   "files": [
@@ -16,11 +20,13 @@
     "drizzle"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/main.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/main.ts src/archive/mini-s3.ts --format esm --dts --clean",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1083.0",
+    "@aws-sdk/lib-storage": "^3.1083.0",
     "@dormice/shared": "workspace:*",
     "@fastify/cookie": "^11.0.2",
     "@fastify/multipart": "^10.0.0",
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index 6ad1115..c860dd1 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -1,4 +1,6 @@
+import { mkdtempSync } from 'node:fs';
 import { tmpdir } from 'node:os';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   DEFAULT_LIFECYCLE_POLICY,
@@ -7,10 +9,15 @@ import {
 } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { buildApp } from './app';
+import { Archiver } from './archive/archiver';
+import { MemStore } from './archive/mem-store';
+import { objectKey } from './archive/store';
 import { loadConfig } from './config';
 import { migrateDb, openDb } from './db/db';
+import { transition } from './db/ledger';
 import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
+import { ARCHIVE_DEFAULT_SECONDS } from './policy';
 import { reconcile } from './reconciler';
 import { scanOnce } from './scanner';
 
@@ -129,10 +136,23 @@ describe('POST /acquireSandbox', () => {
   it('rejects an override whose merged result breaks the ordering rule', async () => {
     const res = await acquire(testApp().app, {
       userKey: 'alice',
-      policy: { archiveAfterSeconds: 1 },
+      policy: { freezeAfterSeconds: 61, stopAfterSeconds: 60 },
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().message).toMatch(/freezeAfterSeconds/);
+  });
+
+  it('refuses an archive-asking policy when no S3 is configured', async () => {
+    // Without an archiver a stored archive threshold would be a standing
+    // lie; the daemon refuses rather than nodding along.
+    const res = await acquire(testApp().app, {
+      userKey: 'alice',
+      policy: { archiveAfterSeconds: 3600 },
     });
     expect(res.statusCode).toBe(400);
-    expect(res.json().message).toMatch(/stopAfterSeconds/);
+    expect(res.json().message).toMatch(
+      /archiving requires S3 \(DORMICE_S3_\*\)/,
+    );
   });
 
   it('rejects a malformed body', async () => {
@@ -862,6 +882,220 @@ describe('POST /releaseSandbox', () => {
   });
 });
 
+describe('the archiver through the app', () => {
+  /** testApp plus a MemStore-backed archiver — the S3-configured daemon. */
+  function archiverTestApp(executor: FakeExecutor = new FakeExecutor()) {
+    const db = openDb(':memory:');
+    migrateDb(db, MIGRATIONS);
+    const config = loadConfig({
+      DORMICE_DB_PATH: ':memory:',
+      DORMICE_NODE_ID: 'node-test',
+      DORMICE_API_TOKEN: TOKEN,
+    });
+    const locks = new KeyedQueue();
+    const store = new MemStore();
+    const archiver = new Archiver({
+      db,
+      executor,
+      locks,
+      store,
+      tmpDir: mkdtempSync(path.join(tmpdir(), 'dormice-app-')),
+    });
+    const app = buildApp({
+      config,
+      db,
+      executor,
+      locks,
+      logger: false,
+      archiver,
+    });
+    return { app, db, executor, locks, store, archiver };
+  }
+
+  /** Polls acquire until the union flips to ready; the whole restore path. */
+  async function acquireUntilReady(
+    app: ReturnType<typeof testApp>['app'],
+    userKey: string,
+  ) {
+    const deadline = Date.now() + 5_000;
+    while (true) {
+      const body = (await acquire(app, { userKey })).json();
+      if (body.status === 'ready') return body;
+      expect(body.status).toBe('restoring');
+      expect(body.progress.phase).toMatch(/downloading|extracting/);
+      if (Date.now() > deadline) {
+        throw new Error(`still restoring: ${JSON.stringify(body)}`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+  }
+
+  it('runs the full cold cycle: archive by idleness, restore by acquire', async () => {
+    const { app, db, executor, locks, store, archiver } = archiverTestApp();
+    const created = (
+      await acquire(app, {
+        userKey: 'alice',
+        policy: {
+          freezeAfterSeconds: 1,
+          stopAfterSeconds: 2,
+          archiveAfterSeconds: 3,
+        },
+      })
+    ).json();
+    const id = created.sandbox.sandboxId;
+    await rpc(app, '/writeFiles', {
+      userKey: 'alice',
+      files: [
+        {
+          path: 'kept.txt',
+          contentBase64: Buffer.from('through the archive').toString('base64'),
+        },
+      ],
+    });
+    const { lastActiveAt } = (await rpc(app, '/listSandboxes')).json()
+      .sandboxes[0];
+
+    // Three sweeps, one rung each: frozen, stopped, archived.
+    await scanOnce(db, executor, locks, after(lastActiveAt, 1), archiver);
+    await scanOnce(db, executor, locks, after(lastActiveAt, 2), archiver);
+    await scanOnce(db, executor, locks, after(lastActiveAt, 3), archiver);
+    const listed = (await rpc(app, '/listSandboxes')).json().sandboxes[0];
+    expect(listed.state).toBe('archived');
+    expect(store.has(objectKey(id))).toBe(true);
+    expect(executor.stateOf(id)).toBeUndefined();
+    expect(await executor.listDisks()).not.toContain(id);
+
+    // The re-acquire begins the restore and answers restoring immediately;
+    // polling lands on ready with the same sandbox and its data intact.
+    const ready = await acquireUntilReady(app, 'alice');
+    expect(ready.sandbox.sandboxId).toBe(id);
+    expect(ready.sandbox.state).toBe('active');
+    const read = (
+      await rpc(app, '/readFile', { userKey: 'alice', path: 'kept.txt' })
+    ).json();
+    expect(Buffer.from(read.contentBase64, 'base64').toString()).toBe(
+      'through the archive',
+    );
+  });
+
+  it('stores the 7-day archive default when S3 is configured', async () => {
+    const { app } = archiverTestApp();
+    const res = await acquire(app, { userKey: 'alice' });
+    expect(res.json().sandbox.policy.archiveAfterSeconds).toBe(
+      ARCHIVE_DEFAULT_SECONDS,
+    );
+  });
+
+  it('answers 503 for an archived sandbox on a daemon without S3', async () => {
+    // The operator archived with S3 configured, then rebooted without it:
+    // the rows are honest, the restore is impossible, the error names it.
+    const executor = new FakeExecutor();
+    const { app, db } = testApp(executor);
+    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const id = created.sandbox.sandboxId;
+    transition(db, id, 'frozen');
+    transition(db, id, 'stopped');
+    transition(db, id, 'archived');
+    await executor.destroy(id);
+
+    const res = await acquire(app, { userKey: 'alice' });
+    expect(res.statusCode).toBe(503);
+    expect(res.json().message).toMatch(/no S3 configured \(DORMICE_S3_\*\)/);
+  });
+
+  it('release of an archived sandbox deletes the S3 object and the row', async () => {
+    const { app, db, executor, locks, store, archiver } = archiverTestApp();
+    const created = (
+      await acquire(app, {
+        userKey: 'alice',
+        policy: {
+          freezeAfterSeconds: 1,
+          stopAfterSeconds: 2,
+          archiveAfterSeconds: 3,
+        },
+      })
+    ).json();
+    const id = created.sandbox.sandboxId;
+    const stamp = created.sandbox.lastActiveAt;
+    await scanOnce(db, executor, locks, after(stamp, 1), archiver);
+    await scanOnce(db, executor, locks, after(stamp, 2), archiver);
+    await scanOnce(db, executor, locks, after(stamp, 3), archiver);
+    expect(store.has(objectKey(id))).toBe(true);
+
+    const res = await rpc(app, '/releaseSandbox', { userKey: 'alice' });
+    expect(res.json()).toEqual({ released: true });
+    expect(store.has(objectKey(id))).toBe(false);
+    expect((await rpc(app, '/listSandboxes')).json().sandboxes).toEqual([]);
+  });
+
+  it('answers 409 for a release while the restore runs', async () => {
+    const { app, db, executor, locks, store, archiver } = archiverTestApp();
+    const created = (
+      await acquire(app, {
+        userKey: 'alice',
+        policy: {
+          freezeAfterSeconds: 1,
+          stopAfterSeconds: 2,
+          archiveAfterSeconds: 3,
+        },
+      })
+    ).json();
+    const stamp = created.sandbox.lastActiveAt;
+    await scanOnce(db, executor, locks, after(stamp, 1), archiver);
+    await scanOnce(db, executor, locks, after(stamp, 2), archiver);
+    await scanOnce(db, executor, locks, after(stamp, 3), archiver);
+    // Hold the download open so the sandbox is mid-restoring for the test.
+    let releaseDownload!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      releaseDownload = resolve;
+    });
+    const innerGet = store.get.bind(store);
+    store.get = async (key, dest, onProgress) => {
+      await gate;
+      return innerGet(key, dest, onProgress);
+    };
+
+    const restoring = (await acquire(app, { userKey: 'alice' })).json();
+    expect(restoring.status).toBe('restoring');
+    const res = await rpc(app, '/releaseSandbox', { userKey: 'alice' });
+    expect(res.statusCode).toBe(409);
+    expect(res.json().message).toMatch(/restoring; retry/);
+
+    releaseDownload();
+    await acquireUntilReady(app, 'alice');
+  });
+
+  it('answers 409 for exec and file verbs on an archived sandbox', async () => {
+    const { app, db, executor, locks, archiver } = archiverTestApp();
+    const created = (
+      await acquire(app, {
+        userKey: 'alice',
+        policy: {
+          freezeAfterSeconds: 1,
+          stopAfterSeconds: 2,
+          archiveAfterSeconds: 3,
+        },
+      })
+    ).json();
+    const stamp = created.sandbox.lastActiveAt;
+    await scanOnce(db, executor, locks, after(stamp, 1), archiver);
+    await scanOnce(db, executor, locks, after(stamp, 2), archiver);
+    await scanOnce(db, executor, locks, after(stamp, 3), archiver);
+
+    const exec = await rpc(app, '/execCommand', {
+      userKey: 'alice',
+      command: 'echo hi',
+    });
+    expect(exec.statusCode).toBe(409);
+    expect(exec.json().message).toMatch(/call acquireSandbox and poll/);
+    const read = await rpc(app, '/readFile', {
+      userKey: 'alice',
+      path: 'kept.txt',
+    });
+    expect(read.statusCode).toBe(409);
+  });
+});
+
 describe('templates', () => {
   it('registers, lists and requires auth like every native verb', async () => {
     const { app } = testApp();
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index eadc9b9..c6e0aa1 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -8,6 +8,7 @@ import {
 } from 'fastify-type-provider-zod';
 import { type Logger, pino } from 'pino';
 import { z } from 'zod';
+import type { Archiver } from './archive/archiver';
 import { requireApiAuth } from './auth';
 import type { Config } from './config';
 import type { Db } from './db/db';
@@ -16,6 +17,7 @@ import { ProcessTable } from './e2b/process-table';
 import { WatcherTable } from './e2b/watcher-table';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
+import { ARCHIVE_DEFAULT_SECONDS } from './policy';
 import { consoleRoutes } from './routes/console';
 import { hostRoutes } from './routes/host';
 import { sandboxRoutes } from './routes/sandboxes';
@@ -44,6 +46,14 @@ export interface AppDeps {
    * honest 404.
    */
   consoleDistDir?: string;
+  /**
+   * The archive/restore engine, present exactly when S3 is configured.
+   * Absent, the daemon is byte-for-byte the archive-less daemon: the
+   * scanner never moves the archive rung and archive-asking policies are
+   * refused (the SANDBOX_DOMAIN precedent — an unconfigured feature is
+   * honestly absent, never half-present).
+   */
+  archiver?: Archiver;
 }
 
 /**
@@ -62,7 +72,12 @@ export function buildApp({
   locks,
   logger = true,
   consoleDistDir,
+  archiver,
 }: AppDeps) {
+  // The archive default is adjudicated once, here, by the archiver's
+  // presence: with one, new sandboxes archive after a week of idleness;
+  // without one, never — and asking is a 400.
+  const archiveDefaultSeconds = archiver ? ARCHIVE_DEFAULT_SECONDS : null;
   // Always a pino instance (booleans are normalized into one): two fastify()
   // call shapes would give the instance two different types.
   const loggerInstance =
@@ -134,7 +149,14 @@ export function buildApp({
 
   app.register(async (api) => {
     api.addHook('onRequest', requireApiAuth(config.DORMICE_API_TOKEN));
-    await api.register(sandboxRoutes, { config, db, executor, locks });
+    await api.register(sandboxRoutes, {
+      config,
+      db,
+      executor,
+      locks,
+      archiver,
+      archiveDefaultSeconds,
+    });
     await api.register(templateRoutes, { db });
     await api.register(hostRoutes, { config, db, executor });
   });
@@ -159,6 +181,8 @@ export function buildApp({
       locks,
       processes,
       watchers,
+      archiver,
+      archiveDefaultSeconds,
     });
   });
 
diff --git a/packages/server/src/archive/archiver.test.ts b/packages/server/src/archive/archiver.test.ts
new file mode 100644
index 0000000..783f2cc
--- /dev/null
+++ b/packages/server/src/archive/archiver.test.ts
@@ -0,0 +1,237 @@
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DEFAULT_LIFECYCLE_POLICY } from '@dormice/shared';
+import { describe, expect, it } from 'vitest';
+import { type Db, migrateDb, openDb } from '../db/db';
+import { createSandbox, findByUserKey, transition } from '../db/ledger';
+import type { SandboxRow } from '../db/schema';
+import { FakeExecutor } from '../executor/fake';
+import { KeyedQueue } from '../keyed-queue';
+import { Archiver } from './archiver';
+import { MemStore } from './mem-store';
+import { objectKey } from './store';
+
+const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
+
+function setup() {
+  const db = openDb(':memory:');
+  migrateDb(db, MIGRATIONS);
+  const executor = new FakeExecutor();
+  const locks = new KeyedQueue();
+  const store = new MemStore();
+  const tmpDir = mkdtempSync(path.join(tmpdir(), 'dormice-archiver-'));
+  const archiver = new Archiver({ db, executor, locks, store, tmpDir });
+  return { db, executor, locks, store, tmpDir, archiver };
+}
+
+/** A stopped sandbox with a marker file — the archiver's raw material. */
+async function seedStopped(
+  db: Db,
+  executor: FakeExecutor,
+  userKey: string,
+): Promise<SandboxRow> {
+  const sandboxId = randomUUID();
+  await executor.create(sandboxId);
+  await executor.writeFiles(sandboxId, [
+    { path: 'kept.txt', content: Buffer.from(`data of ${userKey}`) },
+  ]);
+  createSandbox(db, {
+    sandboxId,
+    userKey,
+    nodeId: 'node-test',
+    policy: DEFAULT_LIFECYCLE_POLICY,
+  });
+  await executor.freeze(sandboxId);
+  await executor.stop(sandboxId);
+  transition(db, sandboxId, 'frozen');
+  return transition(db, sandboxId, 'stopped');
+}
+
+describe('Archiver.archive', () => {
+  it('uploads, records archived, and frees the local copy', async () => {
+    const { db, executor, store, tmpDir, archiver } = setup();
+    const row = await seedStopped(db, executor, 'alice');
+
+    await archiver.archive(row);
+
+    expect(store.has(objectKey(row.sandboxId))).toBe(true);
+    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    // "Local copy freed" includes the shell: destroy, not just the disk.
+    expect(executor.stateOf(row.sandboxId)).toBeUndefined();
+    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+    expect(readdirSync(tmpDir)).toEqual([]);
+  });
+
+  it('uploads before recording, records before destroying', async () => {
+    // The order IS the crash safety: flip any two steps and some crash
+    // window loses data (upload after transition -> a crash strands an
+    // archived row with no object; destroy before transition -> the
+    // reconciler deletes the "stopped" row whose reality vanished). Each
+    // observed step records the ledger state at its own moment, so the
+    // transition is pinned BETWEEN them, not merely somewhere.
+    const { db, tmpDir } = setup();
+    const events: string[] = [];
+    const watchingStore = new (class extends MemStore {
+      override async put(key: string, filePath: string): Promise<void> {
+        events.push(`put while ${findByUserKey(db, 'alice')?.state}`);
+        await super.put(key, filePath);
+      }
+    })();
+    const watchingExecutor = new (class extends FakeExecutor {
+      override async destroy(sandboxId: string): Promise<void> {
+        events.push(`destroy while ${findByUserKey(db, 'alice')?.state}`);
+        await super.destroy(sandboxId);
+      }
+    })();
+    const archiver = new Archiver({
+      db,
+      executor: watchingExecutor,
+      locks: new KeyedQueue(),
+      store: watchingStore,
+      tmpDir,
+    });
+    const row = await seedStopped(db, watchingExecutor, 'alice');
+
+    await archiver.archive(row);
+
+    expect(events).toEqual(['put while stopped', 'destroy while archived']);
+  });
+
+  it('a failed upload leaves a retryable stopped sandbox', async () => {
+    const { db, executor, tmpDir } = setup();
+    const failingStore = new (class extends MemStore {
+      override async put(): Promise<void> {
+        throw new Error('the bucket said no');
+      }
+    })();
+    const archiver = new Archiver({
+      db,
+      executor,
+      locks: new KeyedQueue(),
+      store: failingStore,
+      tmpDir,
+    });
+    const row = await seedStopped(db, executor, 'alice');
+
+    await expect(archiver.archive(row)).rejects.toThrow('the bucket said no');
+    // The invariant as behavior: disk still present <=> upload unconfirmed,
+    // so the row stays stopped and the next sweep retries the whole thing.
+    expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
+    expect(await executor.listDisks()).toContain(row.sandboxId);
+    expect(readdirSync(tmpDir)).toEqual([]);
+  });
+
+  it('refuses a row that is not stopped', async () => {
+    const { db, executor, archiver } = setup();
+    const sandboxId = randomUUID();
+    await executor.create(sandboxId);
+    const row = createSandbox(db, {
+      sandboxId,
+      userKey: 'alice',
+      nodeId: 'node-test',
+      policy: DEFAULT_LIFECYCLE_POLICY,
+    });
+    await expect(archiver.archive(row)).rejects.toThrow(
+      `sandbox ${sandboxId} is active, expected stopped`,
+    );
+  });
+});
+
+describe('Archiver.beginRestore', () => {
+  it('flips to restoring at once and lands active with the data back', async () => {
+    const { db, executor, store, tmpDir, archiver } = setup();
+    const row = await seedStopped(db, executor, 'alice');
+    await archiver.archive(row);
+    const archived = findByUserKey(db, 'alice');
+    if (!archived) throw new Error('row vanished');
+
+    let entry: ReturnType<Archiver['beginRestore']> | undefined;
+    await new KeyedQueue().run('alice', async () => {
+      entry = archiver.beginRestore(archived);
+    });
+    // Non-blocking: the row is restoring the moment beginRestore returns.
+    expect(findByUserKey(db, 'alice')?.state).toBe('restoring');
+    expect(archiver.hasLiveRestore(row.sandboxId)).toBe(true);
+    expect(entry?.progress.phase).toBe('downloading');
+
+    await archiver.restoreJoin(row.sandboxId);
+
+    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(executor.stateOf(row.sandboxId)).toBe('running');
+    expect(
+      (await executor.readFile(row.sandboxId, 'kept.txt')).toString(),
+    ).toBe('data of alice');
+    expect(archiver.hasLiveRestore(row.sandboxId)).toBe(false);
+    // The object goes with the restore: from here "an object exists" means
+    // "the row is archived" — release never chases stale copies.
+    expect(store.has(objectKey(row.sandboxId))).toBe(false);
+    expect(readdirSync(tmpDir)).toEqual([]);
+  });
+
+  it('a missing archive object reverts the row to archived', async () => {
+    const { db, executor, store, tmpDir, archiver } = setup();
+    const row = await seedStopped(db, executor, 'alice');
+    await archiver.archive(row);
+    await store.delete(objectKey(row.sandboxId));
+    const archived = findByUserKey(db, 'alice');
+    if (!archived) throw new Error('row vanished');
+
+    archiver.beginRestore(archived);
+    await expect(archiver.restoreJoin(row.sandboxId)).rejects.toThrow(
+      `archive object ${objectKey(row.sandboxId)} is not in bucket`,
+    );
+
+    // The S3 object is the only copy; with it gone the honest state is
+    // archived-and-failing, retried on every acquire, loudly.
+    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+    expect(archiver.hasLiveRestore(row.sandboxId)).toBe(false);
+    expect(readdirSync(tmpDir)).toEqual([]);
+  });
+
+  it('calling beginRestore twice joins the same task', async () => {
+    const { db, executor, archiver } = setup();
+    const row = await seedStopped(db, executor, 'alice');
+    await archiver.archive(row);
+    const archived = findByUserKey(db, 'alice');
+    if (!archived) throw new Error('row vanished');
+
+    const first = archiver.beginRestore(archived);
+    const again = archiver.beginRestore(
+      findByUserKey(db, 'alice') as SandboxRow,
+    );
+    expect(again).toBe(first);
+    await archiver.restoreJoin(row.sandboxId);
+    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+  });
+});
+
+describe('Archiver.restoreJoin', () => {
+  it('is a no-op for a sandbox that is not archived', async () => {
+    const { db, executor, archiver } = setup();
+    const sandboxId = randomUUID();
+    await executor.create(sandboxId);
+    createSandbox(db, {
+      sandboxId,
+      userKey: 'alice',
+      nodeId: 'node-test',
+      policy: DEFAULT_LIFECYCLE_POLICY,
+    });
+    await archiver.restoreJoin(sandboxId);
+    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+  });
+
+  it('starts the restore itself when the row is archived', async () => {
+    const { db, executor, archiver } = setup();
+    const row = await seedStopped(db, executor, 'alice');
+    await archiver.archive(row);
+
+    await archiver.restoreJoin(row.sandboxId);
+
+    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(executor.stateOf(row.sandboxId)).toBe('running');
+  });
+});
diff --git a/packages/server/src/archive/archiver.ts b/packages/server/src/archive/archiver.ts
new file mode 100644
index 0000000..0d64b45
--- /dev/null
+++ b/packages/server/src/archive/archiver.ts
@@ -0,0 +1,249 @@
+import { mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import type { Db } from '../db/db';
+import {
+  findBySandboxId,
+  setPausedByUser,
+  touch,
+  transition,
+} from '../db/ledger';
+import type { SandboxRow } from '../db/schema';
+import { resolveImage } from '../db/templates';
+import type { Executor } from '../executor/executor';
+import type { KeyedQueue } from '../keyed-queue';
+import { type ArchiveStore, objectKey } from './store';
+
+/** What acquire reports while a sandbox is coming back from the archive. */
+export interface RestoreProgress {
+  phase: 'downloading' | 'extracting';
+  percent: number;
+}
+
+interface RestoreEntry {
+  /** Mutated in place by the running task; read through progressOf. */
+  progress: RestoreProgress;
+  /** Settles when the restore finishes — active on success, archived on failure. */
+  done: Promise<void>;
+}
+
+export interface ArchiverDeps {
+  db: Db;
+  executor: Executor;
+  locks: KeyedQueue;
+  store: ArchiveStore;
+  /**
+   * Where transfer temp files stage. No default on purpose: every
+   * construction site chooses, so a unit test can never land in
+   * /var/lib/dormice by omission. Production uses <DORMICE_DATA_DIR>/tmp —
+   * the same filesystem as the disks (temp archives are disk-sized, and
+   * /tmp may be RAM).
+   */
+  tmpDir: string;
+  log?: (msg: string) => void;
+}
+
+function clampPercent(fraction: number): number {
+  return Math.max(0, Math.min(100, Math.round(fraction * 100)));
+}
+
+/**
+ * The archive/restore state machine: stopped -> archived (the scanner's
+ * move) and archived -> restoring -> active (acquire's). The restore
+ * tracker is daemon memory, like the process table — a restart empties it,
+ * and the startup reconcile repairs any restoring zombies before listen,
+ * so at runtime a restoring row always has a live entry here.
+ */
+export class Archiver {
+  readonly store: ArchiveStore;
+  private readonly db: Db;
+  private readonly executor: Executor;
+  private readonly locks: KeyedQueue;
+  private readonly tmpDir: string;
+  private readonly log: (msg: string) => void;
+  private readonly restores = new Map<string, RestoreEntry>();
+
+  constructor(deps: ArchiverDeps) {
+    this.db = deps.db;
+    this.executor = deps.executor;
+    this.locks = deps.locks;
+    this.store = deps.store;
+    this.tmpDir = deps.tmpDir;
+    this.log = deps.log ?? (() => {});
+  }
+
+  /**
+   * Boot sweep: everything under tmpDir is a half of some interrupted
+   * transfer — the crash-recovery story never depends on temp files, so
+   * they are plain garbage here.
+   */
+  async init(): Promise<void> {
+    await rm(this.tmpDir, { recursive: true, force: true });
+    await mkdir(this.tmpDir, { recursive: true });
+  }
+
+  /**
+   * stopped -> archived. The caller holds the key slot and has re-read the
+   * row inside it; the state check here guards the destructive tail.
+   *
+   * The order IS the crash safety: local disk present <=> upload
+   * unconfirmed => every crash before the transition simply re-archives on
+   * a later sweep (put overwrites the same key). The transition is the
+   * confirmation; from there the local copy is cleanup — destroy, not
+   * removeDisk, because a stopped row still owns its exited container
+   * object, and "local copy freed" includes the shell (the next restore
+   * then rebuilds from the template's current image).
+   */
+  async archive(row: SandboxRow): Promise<void> {
+    if (row.state !== 'stopped') {
+      throw new Error(
+        `sandbox ${row.sandboxId} is ${row.state}, expected stopped — only a stopped sandbox can archive`,
+      );
+    }
+    const startedAt = Date.now();
+    const tmp = path.join(this.tmpDir, `${row.sandboxId}.archive.tar.zst`);
+    try {
+      await this.executor.exportDisk(row.sandboxId, tmp);
+      await this.store.put(objectKey(row.sandboxId), tmp);
+      transition(this.db, row.sandboxId, 'archived');
+      await this.executor.destroy(row.sandboxId);
+    } finally {
+      await rm(tmp, { force: true });
+    }
+    this.log(
+      `archived ${row.sandboxId} in ${((Date.now() - startedAt) / 1000).toFixed(1)}s`,
+    );
+  }
+
+  /**
+   * archived -> restoring, task fired, returns immediately — acquire's
+   * non-blocking half of the protocol's restoring promise. The caller holds
+   * the key slot. Calling again while a restore runs joins the same task.
+   */
+  beginRestore(row: SandboxRow): { progress: RestoreProgress } {
+    const existing = this.restores.get(row.sandboxId);
+    if (existing) return existing;
+    if (row.state !== 'archived') {
+      throw new Error(
+        `sandbox ${row.sandboxId} is ${row.state}, expected archived — beginRestore is the move on archived rows`,
+      );
+    }
+    transition(this.db, row.sandboxId, 'restoring');
+    const progress: RestoreProgress = { phase: 'downloading', percent: 0 };
+    const done = this.runRestore(row.sandboxId, row.userKey, progress).finally(
+      () => {
+        this.restores.delete(row.sandboxId);
+      },
+    );
+    // Native acquire never awaits this — a failure with no joiner must not
+    // crash the daemon as an unhandled rejection. Joiners still observe the
+    // rejection through the same promise.
+    done.catch(() => {});
+    const entry: RestoreEntry = { progress, done };
+    this.restores.set(row.sandboxId, entry);
+    return entry;
+  }
+
+  /** The live progress of a running restore; undefined when none runs. */
+  progressOf(sandboxId: string): RestoreProgress | undefined {
+    const entry = this.restores.get(sandboxId);
+    return entry ? { ...entry.progress } : undefined;
+  }
+
+  /** The reconciler's question: is this restoring row a live task or a zombie? */
+  hasLiveRestore(sandboxId: string): boolean {
+    return this.restores.has(sandboxId);
+  }
+
+  /**
+   * Blocks until the sandbox is out of the archive — the E2B surface's
+   * primitive (that protocol has no restoring concept, so its verbs wait).
+   * The key slot is held only to start or find the task; the wait itself
+   * happens outside any lock — KeyedQueue is not reentrant, and the task's
+   * own finish needs the slot.
+   */
+  async restoreJoin(sandboxId: string): Promise<void> {
+    const row = findBySandboxId(this.db, sandboxId);
+    if (!row || (row.state !== 'archived' && row.state !== 'restoring')) {
+      return;
+    }
+    const entry = await this.locks.run(row.userKey, async () => {
+      const fresh = findBySandboxId(this.db, sandboxId);
+      if (fresh?.state === 'archived') {
+        return this.beginRestore(fresh) as RestoreEntry;
+      }
+      if (fresh?.state === 'restoring') {
+        return this.restores.get(sandboxId);
+      }
+      // Released or already woken while we queued — nothing to join.
+      return undefined;
+    });
+    if (entry) await entry.done;
+  }
+
+  /**
+   * The restore task. Runs WITHOUT the key lock through the slow middle —
+   * the restoring state is the guard (acquire polls answer progress,
+   * release answers 409, the scanner and reconciler skip) — and takes the
+   * slot only for the finish. On failure the half-built disk is removed and
+   * the row reverts to archived: the S3 object is untouched, so the next
+   * acquire is a clean retry.
+   */
+  private async runRestore(
+    sandboxId: string,
+    userKey: string,
+    progress: RestoreProgress,
+  ): Promise<void> {
+    const tmp = path.join(this.tmpDir, `${sandboxId}.restore.tar.zst`);
+    try {
+      await this.store.get(objectKey(sandboxId), tmp, (fraction) => {
+        progress.percent = clampPercent(fraction);
+      });
+      progress.phase = 'extracting';
+      progress.percent = 0;
+      await this.executor.importDisk(sandboxId, tmp, (fraction) => {
+        progress.percent = clampPercent(fraction);
+      });
+      await this.locks.run(userKey, async () => {
+        const fresh = findBySandboxId(this.db, sandboxId);
+        if (fresh?.state !== 'restoring') {
+          // Nothing legal moves a restoring row but this task; hearing
+          // otherwise is a bug report. The disk just built is task-owned.
+          await this.executor.removeDisk(sandboxId);
+          throw new Error(
+            `sandbox ${sandboxId} became ${fresh?.state ?? 'released'} mid-restore — the restoring state belongs to the restore task alone`,
+          );
+        }
+        await this.executor.start(sandboxId, {
+          image: resolveImage(this.db, fresh.template),
+        });
+        // Awaken semantics, like every wake: an awake sandbox is by
+        // definition not paused — without this, an autoPause-archived row
+        // would restore into a logically-paused sandbox no one can reach.
+        if (fresh.pausedByUser) {
+          setPausedByUser(this.db, sandboxId, false);
+        }
+        transition(this.db, sandboxId, 'active');
+        touch(this.db, sandboxId);
+      });
+      // The object's job is done — the disk is local again, so from here
+      // "an object exists" means "the row is archived", and release never
+      // has to chase stale copies. Best effort: a leaked object costs
+      // pennies, failing a finished restore over cleanup costs a wake.
+      await this.store.delete(objectKey(sandboxId)).catch(() => {});
+    } catch (err) {
+      this.log(
+        `restore of ${sandboxId} failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      await this.executor.removeDisk(sandboxId).catch(() => {});
+      await this.locks.run(userKey, async () => {
+        const fresh = findBySandboxId(this.db, sandboxId);
+        if (fresh?.state === 'restoring') {
+          transition(this.db, sandboxId, 'archived');
+        }
+      });
+      throw err;
+    } finally {
+      await rm(tmp, { force: true });
+    }
+  }
+}
diff --git a/packages/server/src/archive/mem-store.ts b/packages/server/src/archive/mem-store.ts
new file mode 100644
index 0000000..9eb3e57
--- /dev/null
+++ b/packages/server/src/archive/mem-store.ts
@@ -0,0 +1,44 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { ArchiveObjectMissingError, type ArchiveStore } from './store';
+
+/**
+ * The permanent test double (FakeExecutor's discipline): objects in memory,
+ * but the file ends are real — the archiver hands this store the same real
+ * paths it hands S3Store, so what unit tests exercise is the same plumbing.
+ */
+export class MemStore implements ArchiveStore {
+  private readonly objects = new Map<string, Buffer>();
+
+  async put(key: string, filePath: string): Promise<void> {
+    this.objects.set(key, await readFile(filePath));
+  }
+
+  async get(
+    key: string,
+    destPath: string,
+    onProgress?: (fraction: number) => void,
+  ): Promise<void> {
+    const body = this.objects.get(key);
+    if (body === undefined) {
+      throw new ArchiveObjectMissingError(
+        `archive object ${key} is not in bucket mem`,
+      );
+    }
+    await writeFile(destPath, body);
+    onProgress?.(1);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.objects.delete(key);
+  }
+
+  /** Test hook: is the object there? */
+  has(key: string): boolean {
+    return this.objects.has(key);
+  }
+
+  /** Test hook: how many objects the store holds. */
+  get size(): number {
+    return this.objects.size;
+  }
+}
diff --git a/packages/server/src/archive/mini-s3.ts b/packages/server/src/archive/mini-s3.ts
new file mode 100644
index 0000000..cbddd7d
--- /dev/null
+++ b/packages/server/src/archive/mini-s3.ts
@@ -0,0 +1,123 @@
+import http from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+/**
+ * A miniature S3 for exams: exactly the three object verbs the archive
+ * store uses, over real HTTP, path-style (`/bucket/key...`). Auth is
+ * ignored — the exam is the wire shape, not the signature.
+ *
+ * One deliberate strictness, copied from Aliyun OSS's S3-compat layer: any
+ * upload that negotiates flexible checksums is refused. The AWS SDK's
+ * default streams bodies aws-chunked with a checksum trailer — and with
+ * buffered bodies it sends the checksum as a plain header instead — both
+ * of which OSS rejects; this server rejects both too, so the store's
+ * WHEN_REQUIRED configuration is pinned by CI forever, whichever body
+ * shape the SDK picks. (Measured in the predecessor system, pit #8: a
+ * string-body test stays green while real file streams fail.)
+ *
+ * A test double with a real socket — the fake executor's proxy-upstream
+ * precedent. Shipped in dist behind the "./mini-s3" subpath so the e2e
+ * suite can run the daemon against it; the package is private, so nothing
+ * is published.
+ */
+export interface MiniS3 {
+  /** http://127.0.0.1:<port> — hand it to DORMICE_S3_ENDPOINT (path style). */
+  url: string;
+  port: number;
+  /** The live object table, for assertions. Keys are `<bucket>/<key>`. */
+  objects: Map<string, Buffer>;
+  close(): Promise<void>;
+}
+
+const CHECKSUM_NEGOTIATION_HEADERS = [
+  'x-amz-trailer',
+  'x-amz-sdk-checksum-algorithm',
+];
+
+function negotiatesChecksums(req: http.IncomingMessage): boolean {
+  if (String(req.headers['content-encoding'] ?? '').includes('aws-chunked')) {
+    return true;
+  }
+  return Object.keys(req.headers).some(
+    (name) =>
+      CHECKSUM_NEGOTIATION_HEADERS.includes(name) ||
+      name.startsWith('x-amz-checksum-'),
+  );
+}
+
+function xmlError(code: string, message: string): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<Error><Code>${code}</Code><Message>${message}</Message></Error>`;
+}
+
+export async function startMiniS3(): Promise<MiniS3> {
+  const objects = new Map<string, Buffer>();
+
+  const server = http.createServer(async (req, res) => {
+    // Path style: /<bucket>/<key...>; the SDK appends query params (x-id).
+    const pathname = new URL(req.url ?? '/', 'http://mini-s3').pathname.replace(
+      /^\//,
+      '',
+    );
+
+    if (req.method === 'PUT') {
+      if (negotiatesChecksums(req)) {
+        res.writeHead(400, { 'content-type': 'application/xml' });
+        res.end(
+          xmlError(
+            'NotImplemented',
+            'checksum negotiation is not supported (aws-chunked / x-amz-checksum headers) — the OSS-compat behavior this server mimics',
+          ),
+        );
+        req.resume();
+        return;
+      }
+      const chunks: Buffer[] = [];
+      for await (const chunk of req) {
+        chunks.push(chunk as Buffer);
+      }
+      objects.set(pathname, Buffer.concat(chunks));
+      res.writeHead(200, { etag: '"mini-s3"' });
+      res.end();
+      return;
+    }
+
+    if (req.method === 'GET') {
+      const body = objects.get(pathname);
+      if (body === undefined) {
+        res.writeHead(404, { 'content-type': 'application/xml' });
+        res.end(xmlError('NoSuchKey', `no such key: ${pathname}`));
+        return;
+      }
+      // content-length is load-bearing: the store's download progress meter
+      // divides by it.
+      res.writeHead(200, {
+        'content-type': 'application/octet-stream',
+        'content-length': String(body.length),
+      });
+      res.end(body);
+      return;
+    }
+
+    if (req.method === 'DELETE') {
+      objects.delete(pathname);
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    res.writeHead(405, { 'content-type': 'application/xml' });
+    res.end(xmlError('MethodNotAllowed', `unsupported method ${req.method}`));
+  });
+
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const port = (server.address() as AddressInfo).port;
+  return {
+    url: `http://127.0.0.1:${port}`,
+    port,
+    objects,
+    close: () =>
+      new Promise<void>((resolve, reject) =>
+        server.close((err) => (err ? reject(err) : resolve())),
+      ),
+  };
+}
diff --git a/packages/server/src/archive/s3-store.ts b/packages/server/src/archive/s3-store.ts
new file mode 100644
index 0000000..037ca2b
--- /dev/null
+++ b/packages/server/src/archive/s3-store.ts
@@ -0,0 +1,106 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  type GetObjectCommandOutput,
+  S3Client,
+} from '@aws-sdk/client-s3';
+import { Upload } from '@aws-sdk/lib-storage';
+import { ArchiveObjectMissingError, type ArchiveStore } from './store';
+
+export interface S3Settings {
+  /** Full URL including scheme — MinIO speaks http, clouds speak https. */
+  endpoint: string;
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+  /** MinIO and friends route by path; the clouds route by bucket subdomain. */
+  forcePathStyle: boolean;
+}
+
+/**
+ * The production store: any S3-compatible endpoint (AWS, R2, MinIO, OSS in
+ * S3-compat mode). One deliberate setting pair, measured the hard way in
+ * the predecessor system: the SDK's default flexible checksums send
+ * streaming bodies aws-chunked with a trailer, which Aliyun OSS's compat
+ * layer rejects with InvalidArgument — and a string-body test never
+ * triggers it, only real file streams do. WHEN_REQUIRED on both directions
+ * turns that machinery off; the store contract pins it against a mini S3
+ * that refuses checksum negotiation exactly like OSS does.
+ */
+export class S3Store implements ArchiveStore {
+  private readonly client: S3Client;
+  private readonly bucket: string;
+
+  constructor(settings: S3Settings) {
+    this.bucket = settings.bucket;
+    this.client = new S3Client({
+      endpoint: settings.endpoint,
+      region: settings.region,
+      forcePathStyle: settings.forcePathStyle,
+      credentials: {
+        accessKeyId: settings.accessKeyId,
+        secretAccessKey: settings.secretAccessKey,
+      },
+      requestChecksumCalculation: 'WHEN_REQUIRED',
+      responseChecksumValidation: 'WHEN_REQUIRED',
+    });
+  }
+
+  async put(key: string, filePath: string): Promise<void> {
+    // Upload instead of a bare PutObject: it buffers parts and switches to
+    // multipart past the part size, so an archive over the single-request
+    // 5 GiB ceiling (a well-fed disk of incompressible data) still lands.
+    await new Upload({
+      client: this.client,
+      params: {
+        Bucket: this.bucket,
+        Key: key,
+        Body: createReadStream(filePath),
+      },
+    }).done();
+  }
+
+  async get(
+    key: string,
+    destPath: string,
+    onProgress?: (fraction: number) => void,
+  ): Promise<void> {
+    let response: GetObjectCommandOutput;
+    try {
+      response = await this.client.send(
+        new GetObjectCommand({ Bucket: this.bucket, Key: key }),
+      );
+    } catch (err) {
+      if ((err as { name?: string }).name === 'NoSuchKey') {
+        throw new ArchiveObjectMissingError(
+          `archive object ${key} is not in bucket ${this.bucket}`,
+        );
+      }
+      throw err;
+    }
+    const body = response.Body as NodeJS.ReadableStream | undefined;
+    if (!body) {
+      throw new Error(`downloading ${key} returned an empty body`);
+    }
+    // The meter and the pipeline attach in the same synchronous block, so
+    // no chunk can slip between them.
+    const total = response.ContentLength ?? 0;
+    let consumed = 0;
+    body.on('data', (chunk: Buffer) => {
+      consumed += chunk.length;
+      if (total > 0) onProgress?.(Math.min(consumed / total, 1));
+    });
+    await pipeline(body, createWriteStream(destPath));
+    onProgress?.(1);
+  }
+
+  async delete(key: string): Promise<void> {
+    // S3 DeleteObject is idempotent on its own: deleting nothing is 204.
+    await this.client.send(
+      new DeleteObjectCommand({ Bucket: this.bucket, Key: key }),
+    );
+  }
+}
diff --git a/packages/server/src/archive/store.contract.test.ts b/packages/server/src/archive/store.contract.test.ts
new file mode 100644
index 0000000..0711c75
--- /dev/null
+++ b/packages/server/src/archive/store.contract.test.ts
@@ -0,0 +1,169 @@
+import { createReadStream } from 'node:fs';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { S3Client } from '@aws-sdk/client-s3';
+import { Upload } from '@aws-sdk/lib-storage';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { MemStore } from './mem-store';
+import { startMiniS3 } from './mini-s3';
+import { S3Store } from './s3-store';
+import { ArchiveObjectMissingError, type ArchiveStore } from './store';
+
+/**
+ * One exam, both stores — the executor contract's discipline. The S3 flavor
+ * runs over the mini S3 on a real socket, so what CI pins is the real
+ * aws-sdk wire, not a mock's idea of it.
+ */
+
+interface StoreSubject {
+  store: ArchiveStore;
+  close(): Promise<void>;
+}
+
+const subjects: Record<string, () => Promise<StoreSubject>> = {
+  MemStore: async () => ({
+    store: new MemStore(),
+    close: async () => {},
+  }),
+  'S3Store over mini-S3': async () => {
+    const mini = await startMiniS3();
+    return {
+      store: new S3Store({
+        endpoint: mini.url,
+        bucket: 'exam',
+        accessKeyId: 'exam-key',
+        secretAccessKey: 'exam-secret',
+        region: 'us-east-1',
+        forcePathStyle: true,
+      }),
+      close: () => mini.close(),
+    };
+  },
+};
+
+// Multi-KB and patterned: a real file stream is what triggers the SDK's
+// checksum machinery (a string body never does — the predecessor system's
+// pit #8 hid behind exactly that).
+function payload(): Buffer {
+  const buffer = Buffer.alloc(64 * 1024);
+  for (let i = 0; i < buffer.length; i++) buffer[i] = (i * 7) % 251;
+  return buffer;
+}
+
+for (const [name, make] of Object.entries(subjects)) {
+  describe(`archive store contract: ${name}`, () => {
+    let subject: StoreSubject;
+    let dir: string;
+
+    beforeEach(async () => {
+      subject = await make();
+      dir = await mkdtemp(path.join(tmpdir(), 'dormice-store-'));
+    });
+
+    afterEach(async () => {
+      await subject.close();
+      await rm(dir, { recursive: true, force: true });
+    });
+
+    it('round-trips a real file', async () => {
+      const source = path.join(dir, 'source.bin');
+      const dest = path.join(dir, 'dest.bin');
+      await writeFile(source, payload());
+      await subject.store.put('disks/round.tar.zst', source);
+      await subject.store.get('disks/round.tar.zst', dest);
+      expect((await readFile(dest)).equals(payload())).toBe(true);
+    });
+
+    it('overwrites the same key', async () => {
+      const first = path.join(dir, 'first.bin');
+      const second = path.join(dir, 'second.bin');
+      const dest = path.join(dir, 'dest.bin');
+      await writeFile(first, Buffer.from('the stale archive'));
+      await writeFile(second, Buffer.from('the retried archive'));
+      await subject.store.put('disks/again.tar.zst', first);
+      // A crash between upload and the ledger transition retries the whole
+      // archive — the overwrite is what makes that retry safe.
+      await subject.store.put('disks/again.tar.zst', second);
+      await subject.store.get('disks/again.tar.zst', dest);
+      expect((await readFile(dest)).toString()).toBe('the retried archive');
+    });
+
+    it('get of a missing key throws the named error', async () => {
+      await expect(
+        subject.store.get('disks/never.tar.zst', path.join(dir, 'x')),
+      ).rejects.toThrow(ArchiveObjectMissingError);
+    });
+
+    it('delete removes the object', async () => {
+      const source = path.join(dir, 'source.bin');
+      await writeFile(source, payload());
+      await subject.store.put('disks/gone.tar.zst', source);
+      await subject.store.delete('disks/gone.tar.zst');
+      await expect(
+        subject.store.get('disks/gone.tar.zst', path.join(dir, 'x')),
+      ).rejects.toThrow(ArchiveObjectMissingError);
+    });
+
+    it('delete is idempotent', async () => {
+      await expect(
+        subject.store.delete('disks/never-was.tar.zst'),
+      ).resolves.toBeUndefined();
+    });
+
+    it('get reports progress reaching 1', async () => {
+      const source = path.join(dir, 'source.bin');
+      await writeFile(source, payload());
+      await subject.store.put('disks/meter.tar.zst', source);
+      const fractions: number[] = [];
+      await subject.store.get(
+        'disks/meter.tar.zst',
+        path.join(dir, 'dest.bin'),
+        (f) => fractions.push(f),
+      );
+      expect(fractions.length).toBeGreaterThan(0);
+      for (let i = 1; i < fractions.length; i++) {
+        expect(fractions[i]).toBeGreaterThanOrEqual(fractions[i - 1] ?? 0);
+      }
+      expect(fractions.at(-1)).toBe(1);
+    });
+  });
+}
+
+describe('mini-S3 strictness', () => {
+  it('rejects an SDK-default upload that negotiates checksums', async () => {
+    // The guard of the guard: an SDK left on its defaults (WHEN_SUPPORTED)
+    // negotiates flexible checksums — aws-chunked for streams, a checksum
+    // header for buffered parts. If the mini S3 let either through, removing
+    // WHEN_REQUIRED from S3Store would stay green and the pit-#8 pin would
+    // be a dud.
+    const mini = await startMiniS3();
+    const dir = await mkdtemp(path.join(tmpdir(), 'dormice-store-'));
+    try {
+      const client = new S3Client({
+        endpoint: mini.url,
+        region: 'us-east-1',
+        forcePathStyle: true,
+        credentials: {
+          accessKeyId: 'exam-key',
+          secretAccessKey: 'exam-secret',
+        },
+      });
+      const source = path.join(dir, 'source.bin');
+      await writeFile(source, payload());
+      await expect(
+        new Upload({
+          client,
+          params: {
+            Bucket: 'exam',
+            Key: 'disks/default-config.tar.zst',
+            Body: createReadStream(source),
+          },
+        }).done(),
+      ).rejects.toThrow(/checksum negotiation is not supported/);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+      await mini.close();
+    }
+  });
+});
diff --git a/packages/server/src/archive/store.ts b/packages/server/src/archive/store.ts
new file mode 100644
index 0000000..79dce39
--- /dev/null
+++ b/packages/server/src/archive/store.ts
@@ -0,0 +1,32 @@
+/**
+ * Where archived disks live. The store speaks object keys and local file
+ * paths — nothing about sandboxes, states or executors: storage policy and
+ * sandbox physicality stay on their own sides of the archiver.
+ */
+export interface ArchiveStore {
+  /** Uploads the file at filePath under key, overwriting — retries are safe. */
+  put(key: string, filePath: string): Promise<void>;
+  /**
+   * Downloads key into destPath (overwriting). onProgress reports a
+   * monotonic fraction 0..1, best-effort. A missing object throws
+   * ArchiveObjectMissingError — restore's honest "someone deleted it".
+   */
+  get(
+    key: string,
+    destPath: string,
+    onProgress?: (fraction: number) => void,
+  ): Promise<void>;
+  /** Removes key. Idempotent: an absent object already is the goal state. */
+  delete(key: string): Promise<void>;
+}
+
+/**
+ * The object key an archived sandbox lives under. Derived, never stored —
+ * the ledger needs no archive column because the id is the whole address.
+ */
+export function objectKey(sandboxId: string): string {
+  return `disks/${sandboxId}.tar.zst`;
+}
+
+/** get() on a key that is not there — named so restore can log the culprit. */
+export class ArchiveObjectMissingError extends Error {}
diff --git a/packages/server/src/config.test.ts b/packages/server/src/config.test.ts
index 61271d8..c35a15d 100644
--- a/packages/server/src/config.test.ts
+++ b/packages/server/src/config.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { loadConfig } from './config';
+import { loadConfig, s3Settings } from './config';
 
 const TOKEN = { DORMICE_API_TOKEN: 'x'.repeat(32) };
 
@@ -55,3 +55,62 @@ describe('loadConfig executor knobs', () => {
     expect(loadConfig(TOKEN).DORMICE_DB_PATH).toBe('data/dormice.db');
   });
 });
+
+describe('the S3 set', () => {
+  const S3 = {
+    DORMICE_S3_ENDPOINT: 'http://127.0.0.1:9000',
+    DORMICE_S3_BUCKET: 'dormice-archive',
+    DORMICE_S3_ACCESS_KEY_ID: 'minio-user',
+    DORMICE_S3_SECRET_ACCESS_KEY: 'minio-secret',
+  };
+
+  it('parses a full set and adjudicates the archiver as configured', () => {
+    const config = loadConfig({ ...TOKEN, ...S3 });
+    expect(s3Settings(config)).toEqual({
+      endpoint: 'http://127.0.0.1:9000',
+      bucket: 'dormice-archive',
+      accessKeyId: 'minio-user',
+      secretAccessKey: 'minio-secret',
+      region: 'us-east-1',
+      forcePathStyle: false,
+    });
+  });
+
+  it('adjudicates the archiver as absent when nothing is set', () => {
+    expect(s3Settings(loadConfig(TOKEN))).toBeNull();
+  });
+
+  it('refuses a partial set, naming exactly the missing variables', () => {
+    expect(() =>
+      loadConfig({
+        ...TOKEN,
+        DORMICE_S3_ENDPOINT: 'http://127.0.0.1:9000',
+        DORMICE_S3_BUCKET: 'dormice-archive',
+      }),
+    ).toThrow(
+      /DORMICE_S3_ACCESS_KEY_ID, DORMICE_S3_SECRET_ACCESS_KEY are missing/,
+    );
+  });
+
+  it('rejects an endpoint without a scheme', () => {
+    expect(() =>
+      loadConfig({ ...TOKEN, ...S3, DORMICE_S3_ENDPOINT: 's3.example.com' }),
+    ).toThrow(/DORMICE_S3_ENDPOINT must be a full http\(s\) URL/);
+  });
+
+  it('parses the path-style knob as a real boolean', () => {
+    // The z.coerce.boolean trap: the string "false" must not become true.
+    const on = loadConfig({
+      ...TOKEN,
+      ...S3,
+      DORMICE_S3_FORCE_PATH_STYLE: 'true',
+    });
+    expect(on.DORMICE_S3_FORCE_PATH_STYLE).toBe(true);
+    const off = loadConfig({
+      ...TOKEN,
+      ...S3,
+      DORMICE_S3_FORCE_PATH_STYLE: 'false',
+    });
+    expect(off.DORMICE_S3_FORCE_PATH_STYLE).toBe(false);
+  });
+});
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index 38dde8b..21b23df 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -1,5 +1,6 @@
 import { isAbsolute } from 'node:path';
 import { z } from 'zod';
+import type { S3Settings } from './archive/s3-store';
 
 /**
  * All configuration comes from environment variables, validated once at
@@ -73,6 +74,27 @@ const envSchema = z.object({
       },
     )
     .optional(),
+  /**
+   * The S3-compatible object store behind the archiver (AWS, R2, MinIO,
+   * OSS in S3-compat mode). The four core variables come as a set: with
+   * none of them, archiving is honestly absent — sandboxes park at stopped
+   * forever, and policies asking to archive are refused (the
+   * SANDBOX_DOMAIN precedent). Endpoint is a full URL including scheme
+   * (MinIO speaks http, the clouds https).
+   */
+  DORMICE_S3_ENDPOINT: z
+    .url({
+      protocol: /^https?$/,
+      error:
+        'DORMICE_S3_ENDPOINT must be a full http(s) URL, e.g. https://s3.example.com or http://127.0.0.1:9000',
+    })
+    .optional(),
+  DORMICE_S3_BUCKET: z.string().min(1).optional(),
+  DORMICE_S3_ACCESS_KEY_ID: z.string().min(1).optional(),
+  DORMICE_S3_SECRET_ACCESS_KEY: z.string().min(1).optional(),
+  DORMICE_S3_REGION: z.string().default('us-east-1'),
+  /** Path-style addressing: MinIO needs true; the clouds route by subdomain. */
+  DORMICE_S3_FORCE_PATH_STYLE: z.stringbool().default(false),
 });
 
 const checkedSchema = envSchema
@@ -106,10 +128,55 @@ const checkedSchema = envSchema
         'DORMICE_DATA_DIR must be an absolute path when DORMICE_EXECUTOR=docker — sandbox disks must not move when the start directory does',
       path: ['DORMICE_DATA_DIR'],
     },
-  );
+  )
+  // All-or-none: a half-configured store would make the archiver's
+  // existence ambiguous, and ambiguity here decides real policy defaults.
+  .superRefine((cfg, ctx) => {
+    const wanted = [
+      'DORMICE_S3_ENDPOINT',
+      'DORMICE_S3_BUCKET',
+      'DORMICE_S3_ACCESS_KEY_ID',
+      'DORMICE_S3_SECRET_ACCESS_KEY',
+    ] as const;
+    const missing = wanted.filter((name) => cfg[name] === undefined);
+    const first = missing[0];
+    if (first !== undefined && missing.length < wanted.length) {
+      ctx.addIssue({
+        code: 'custom',
+        message: `the DORMICE_S3_* variables come as a set: ${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} missing — set all four to enable the archiver, or none to disable it`,
+        path: [first],
+      });
+    }
+  });
 
 export type Config = z.infer<typeof envSchema>;
 
 export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
   return checkedSchema.parse(env);
 }
+
+/**
+ * The single adjudicator of "is the archiver configured": null unless the
+ * whole S3 set is present (a partial set never gets past the schema). What
+ * hangs off this one answer: whether an Archiver is built at boot, whether
+ * new sandboxes default to archiving, and whether archive-asking policy
+ * overrides are accepted at all.
+ */
+export function s3Settings(config: Config): S3Settings | null {
+  if (
+    config.DORMICE_S3_ENDPOINT === undefined ||
+    config.DORMICE_S3_BUCKET === undefined ||
+    config.DORMICE_S3_ACCESS_KEY_ID === undefined ||
+    config.DORMICE_S3_SECRET_ACCESS_KEY === undefined
+  ) {
+    return null;
+  }
+  return {
+    endpoint: config.DORMICE_S3_ENDPOINT,
+    bucket: config.DORMICE_S3_BUCKET,
+    accessKeyId: config.DORMICE_S3_ACCESS_KEY_ID,
+    secretAccessKey: config.DORMICE_S3_SECRET_ACCESS_KEY,
+    region: config.DORMICE_S3_REGION,
+    forcePathStyle: config.DORMICE_S3_FORCE_PATH_STYLE,
+  };
+}
diff --git a/packages/server/src/db/ledger.ts b/packages/server/src/db/ledger.ts
index 1cb95bf..3353e70 100644
--- a/packages/server/src/db/ledger.ts
+++ b/packages/server/src/db/ledger.ts
@@ -19,7 +19,9 @@ export const ALLOWED_TRANSITIONS: Record<
   frozen: ['active', 'stopped'],
   stopped: ['active', 'archived'],
   archived: ['restoring'],
-  restoring: ['active'],
+  // The archived edge is the failure edge: a restore that dies reverts —
+  // the S3 object is untouched, so the next acquire simply retries.
+  restoring: ['active', 'archived'],
 };
 
 export interface CreateSandboxInput {
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 1d1cec4..c5b3931 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -1,8 +1,14 @@
 import { createHash } from 'node:crypto';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gzipSync } from 'node:zlib';
 import { describe, expect, it } from 'vitest';
 import { buildApp } from '../app';
+import { Archiver } from '../archive/archiver';
+import { MemStore } from '../archive/mem-store';
+import { objectKey } from '../archive/store';
 import { loadConfig } from '../config';
 import { migrateDb, openDb } from '../db/db';
 import { findBySandboxId, setDeadline } from '../db/ledger';
@@ -1722,3 +1728,195 @@ describe('E2B templates', () => {
     expect(items).toMatchObject([{ templateID: 'py311', alias: 'py311' }]);
   });
 });
+
+describe('E2B surface vs the archiver', () => {
+  /** testApp plus a MemStore-backed archiver — the S3-configured daemon. */
+  function archiverTestApp(executor: FakeExecutor = new FakeExecutor()) {
+    const db = openDb(':memory:');
+    migrateDb(db, MIGRATIONS);
+    const config = loadConfig({
+      DORMICE_DB_PATH: ':memory:',
+      DORMICE_NODE_ID: 'node-test',
+      DORMICE_API_TOKEN: TOKEN,
+    });
+    const locks = new KeyedQueue();
+    const store = new MemStore();
+    const archiver = new Archiver({
+      db,
+      executor,
+      locks,
+      store,
+      tmpDir: mkdtempSync(path.join(tmpdir(), 'dormice-compat-')),
+    });
+    const app = buildApp({
+      config,
+      db,
+      executor,
+      locks,
+      logger: false,
+      archiver,
+    });
+    return { app, db, executor, locks, store, archiver };
+  }
+
+  /**
+   * Walks an autoPause sandbox down to archived. Only pause-type sandboxes
+   * can ever get there on this surface: a kill-type deadline destroys the
+   * sandbox long before any archive threshold — which is why every test
+   * here creates with autoPause.
+   */
+  async function walkToArchived(
+    t: ReturnType<typeof archiverTestApp>,
+    sandboxID: string,
+  ): Promise<void> {
+    const row = findBySandboxId(t.db, sandboxID);
+    if (!row) throw new Error('row missing');
+    const at = (s: number) => new Date(Date.parse(row.lastActiveAt) + s * 1000);
+    // The scanner sweeps travel in time, but e2bView reads the ledger's
+    // deadline against the real clock — so the deadline is planted in the
+    // real past, the shape a 7-days-idle autoPause sandbox actually has.
+    setDeadline(t.db, sandboxID, {
+      deadlineAt: new Date(Date.parse(row.lastActiveAt) - 1000).toISOString(),
+      onDeadline: 'pause',
+    });
+    // The expired pause deadline parks it frozen; the default idle policy
+    // then stops it at 3 days and archives it at 7.
+    await scanOnce(t.db, t.executor, t.locks, at(300), t.archiver);
+    await scanOnce(t.db, t.executor, t.locks, at(3 * 86400), t.archiver);
+    await scanOnce(t.db, t.executor, t.locks, at(7 * 86400), t.archiver);
+    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('archived');
+    expect(t.store.has(objectKey(sandboxID))).toBe(true);
+  }
+
+  it('reports an archived autoPause sandbox as paused — archived is not a wire state', async () => {
+    const t = archiverTestApp();
+    const { sandboxID } = await createSandbox(t, { autoPause: true });
+    await walkToArchived(t, sandboxID);
+    const res = await control(t, 'GET', '/v2/sandboxes?state=paused');
+    expect(
+      (res.json() as Array<{ sandboxID: string }>).map((s) => s.sandboxID),
+    ).toContain(sandboxID);
+  });
+
+  it('connect blocks through the restore and answers a live session', async () => {
+    const t = archiverTestApp();
+    const { sandboxID } = await createSandbox(t, { autoPause: true });
+    await walkToArchived(t, sandboxID);
+
+    const res = await control(t, 'POST', `/sandboxes/${sandboxID}/connect`, {});
+    // 201 = this connect resumed it — same answer as resuming a pause.
+    expect(res.statusCode).toBe(201);
+    expect(t.executor.stateOf(sandboxID)).toBe('running');
+    // The envd face serves immediately: the restore really finished.
+    const list = await envdRpc(t, sandboxID, '/process.Process/List', {});
+    expect(list.statusCode).toBe(200);
+  });
+
+  it('answers 502 for envd on a paused-archived sandbox WITHOUT restoring it', async () => {
+    // The logical gate outranks the restore: a paused sandbox refuses envd
+    // traffic whether frozen or archived, and refusing must not cost a
+    // whole restore first. connect (which extends the deadline) is the way
+    // back in — same as for a plain paused sandbox.
+    const t = archiverTestApp();
+    const { sandboxID } = await createSandbox(t, { autoPause: true });
+    await walkToArchived(t, sandboxID);
+
+    const stat = await envdRpc(t, sandboxID, '/filesystem.Filesystem/Stat', {
+      path: '/home/user',
+    });
+    expect(stat.statusCode).toBe(502);
+    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('archived');
+    expect(t.store.has(objectKey(sandboxID))).toBe(true);
+  });
+
+  it('the envd face restores a logically-running archived sandbox on first touch', async () => {
+    // A natively-acquired sandbox has no deadline — archived by idleness,
+    // it is still logically running, and envd traffic (a console terminal,
+    // a signed URL) restores it in place.
+    const t = archiverTestApp();
+    const acquired = await t.app.inject({
+      method: 'POST',
+      url: '/acquireSandbox',
+      headers: { authorization: `Bearer ${TOKEN}` },
+      payload: {
+        userKey: 'native',
+        policy: {
+          freezeAfterSeconds: 1,
+          stopAfterSeconds: 2,
+          archiveAfterSeconds: 3,
+        },
+      },
+    });
+    const sandboxID = acquired.json().sandbox.sandboxId as string;
+    const row = findBySandboxId(t.db, sandboxID);
+    if (!row) throw new Error('row missing');
+    const at = (s: number) => new Date(Date.parse(row.lastActiveAt) + s * 1000);
+    await scanOnce(t.db, t.executor, t.locks, at(1), t.archiver);
+    await scanOnce(t.db, t.executor, t.locks, at(2), t.archiver);
+    await scanOnce(t.db, t.executor, t.locks, at(3), t.archiver);
+    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('archived');
+
+    const stat = await envdRpc(t, sandboxID, '/filesystem.Filesystem/Stat', {
+      path: '/home/user',
+    });
+    expect(stat.statusCode).toBe(200);
+    expect(t.executor.stateOf(sandboxID)).toBe('running');
+    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('active');
+  });
+
+  it('create with metadata.userKey resumes its archived sandbox', async () => {
+    const t = archiverTestApp();
+    const first = await createSandbox(t, {
+      autoPause: true,
+      metadata: { userKey: 'alice' },
+    });
+    await walkToArchived(t, first.sandboxID);
+
+    const res = await control(t, 'POST', '/sandboxes', {
+      metadata: { userKey: 'alice' },
+    });
+    expect(res.statusCode).toBe(201);
+    expect(res.json().sandboxID).toBe(first.sandboxID);
+    expect(t.executor.stateOf(first.sandboxID)).toBe('running');
+  });
+
+  it('kill deletes an archived sandbox and its S3 object', async () => {
+    const t = archiverTestApp();
+    const { sandboxID } = await createSandbox(t, { autoPause: true });
+    await walkToArchived(t, sandboxID);
+
+    const res = await control(t, 'DELETE', `/sandboxes/${sandboxID}`);
+    expect(res.statusCode).toBe(204);
+    expect(t.store.has(objectKey(sandboxID))).toBe(false);
+    expect(findBySandboxId(t.db, sandboxID)).toBeUndefined();
+  });
+
+  it('kill mid-restore joins the task first, then deletes', async () => {
+    const t = archiverTestApp();
+    const { sandboxID } = await createSandbox(t, { autoPause: true });
+    await walkToArchived(t, sandboxID);
+    // Hold the download open so the row is mid-restoring when kill arrives.
+    let releaseDownload!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      releaseDownload = resolve;
+    });
+    const innerGet = t.store.get.bind(t.store);
+    t.store.get = async (key, dest, onProgress) => {
+      await gate;
+      return innerGet(key, dest, onProgress);
+    };
+    const row = findBySandboxId(t.db, sandboxID);
+    if (!row) throw new Error('row missing');
+    t.archiver.beginRestore(row);
+    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('restoring');
+
+    const del = control(t, 'DELETE', `/sandboxes/${sandboxID}`);
+    // Let the DELETE reach its join, then release the download.
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    releaseDownload();
+    const res = await del;
+    expect(res.statusCode).toBe(204);
+    expect(t.store.has(objectKey(sandboxID))).toBe(false);
+    expect(findBySandboxId(t.db, sandboxID)).toBeUndefined();
+  });
+});
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index f97f5c3..9e93631 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -86,8 +86,34 @@ const notFound = (sandboxId: string) =>
 
 export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   app,
-  { config, db, executor, locks },
+  { config, db, executor, locks, archiver, archiveDefaultSeconds },
 ) => {
+  /**
+   * The archive detour, taken before any slot work: E2B has no restoring
+   * concept, so this surface blocks until the sandbox is back — resuming
+   * an archived sandbox just takes longer. No-op for anything that is not
+   * archived/restoring; joined OUTSIDE the key slot (the restore task's
+   * own finish needs it).
+   */
+  async function joinRestore(row: SandboxRow | undefined): Promise<void> {
+    if (!row || (row.state !== 'archived' && row.state !== 'restoring')) {
+      return;
+    }
+    if (!archiver) {
+      throw apiError(
+        502,
+        `sandbox "${row.sandboxId}" is archived but the daemon has no S3 configured (DORMICE_S3_*)`,
+      );
+    }
+    try {
+      await archiver.restoreJoin(row.sandboxId);
+    } catch (error) {
+      throw apiError(
+        502,
+        `restoring sandbox "${row.sandboxId}" failed: ${error instanceof Error ? error.message : String(error)} — retry`,
+      );
+    }
+  }
   app.addHook('onRequest', async (request, reply) => {
     const presented = request.headers['x-api-key'];
     const key = Array.isArray(presented) ? presented[0] : presented;
@@ -226,6 +252,12 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       }
       const userKey = requestedKey ?? `e2b-${randomUUID()}`;
 
+      // The userKey reuse path may find an archived sandbox; the join
+      // brings it back before the slot work below wakes it as usual.
+      if (requestedKey !== undefined) {
+        await joinRestore(findByUserKey(db, requestedKey));
+      }
+
       // templateID resolution: a registered name wins; 'base', the base
       // image's own name (we have always echoed it as templateID, so it must
       // round-trip) and absence mean the base image; anything else is 404 —
@@ -257,7 +289,12 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         if (existing) {
           // Protocol-dead but not yet reaped: E2B semantics say it is gone,
           // so finish the job and build fresh under the same key.
-          await releaseSandbox(db, executor, existing.sandboxId);
+          await releaseSandbox(
+            db,
+            executor,
+            existing.sandboxId,
+            archiver?.store ?? null,
+          );
         }
 
         if (countSandboxes(db) >= config.DORMICE_MAX_SANDBOXES) {
@@ -274,7 +311,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
           sandboxId,
           userKey,
           nodeId: config.DORMICE_NODE_ID,
-          policy: resolvePolicy(undefined),
+          policy: resolvePolicy(undefined, archiveDefaultSeconds),
           template,
           e2b: {
             metadata: body.metadata ? JSON.stringify(body.metadata) : null,
@@ -301,6 +338,10 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     async (request, reply) => {
       const { id } = request.params as { id: string };
       const before = findLive(id);
+      // An archived sandbox resumes through the archiver first — connect
+      // then finds it active and the wake below is a no-op. Blocking is the
+      // faithful behavior: E2B's connect returns a live sandbox, period.
+      await joinRestore(before.row);
       const row = await locks.run(before.row.userKey, async () => {
         const fresh = findBySandboxId(db, id);
         if (!fresh || e2bView(fresh, new Date()) === 'dead') {
@@ -362,10 +403,22 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     // on the E2B surface is "don't kill" (autoPause / userKey), never a
     // kill that secretly keeps data.
     const { row } = findLive(id);
+    if (row.state === 'restoring') {
+      // A mid-restore teardown would race the task over the half-built
+      // disk; join it first. The outcome is irrelevant — we are deleting
+      // either way, and a failed restore parks the row back on archived,
+      // whose release below deletes the S3 object.
+      await archiver?.restoreJoin(id).catch(() => {});
+    }
     await locks.run(row.userKey, async () => {
       const fresh = findBySandboxId(db, id);
       if (!fresh) throw notFound(id);
-      await releaseSandbox(db, executor, fresh.sandboxId);
+      await releaseSandbox(
+        db,
+        executor,
+        fresh.sandboxId,
+        archiver?.store ?? null,
+      );
     });
     return reply.code(204).send();
   });
diff --git a/packages/server/src/e2b/deps.ts b/packages/server/src/e2b/deps.ts
index 8d66539..4337863 100644
--- a/packages/server/src/e2b/deps.ts
+++ b/packages/server/src/e2b/deps.ts
@@ -1,3 +1,4 @@
+import type { Archiver } from '../archive/archiver';
 import type { Config } from '../config';
 import type { Db } from '../db/db';
 import type { Executor } from '../executor/executor';
@@ -17,4 +18,12 @@ export interface E2bDeps {
   locks: KeyedQueue;
   processes: ProcessTable;
   watchers: WatcherTable;
+  /**
+   * Present exactly when S3 is configured. E2B has no restoring concept,
+   * so this surface's verbs block on restoreJoin — resuming an archived
+   * sandbox just takes longer, which is the faithful behavior.
+   */
+  archiver?: Archiver;
+  /** buildApp's one adjudication of the archive policy default (null = off). */
+  archiveDefaultSeconds: number | null;
 }
diff --git a/packages/server/src/e2b/envd/shared.ts b/packages/server/src/e2b/envd/shared.ts
index 496e152..6417899 100644
--- a/packages/server/src/e2b/envd/shared.ts
+++ b/packages/server/src/e2b/envd/shared.ts
@@ -130,7 +130,37 @@ export interface EnvdContext extends E2bDeps {
 }
 
 export function createEnvdContext(deps: E2bDeps): EnvdContext {
-  const { db, executor, locks } = deps;
+  const { db, executor, locks, archiver } = deps;
+
+  /**
+   * The archive detour, taken before any wake: E2B has no restoring
+   * concept, so this surface blocks until the sandbox is back — resuming
+   * an archived sandbox just takes longer. Joined OUTSIDE the key slot
+   * (the restore task's own finish needs it). No-op for anything that is
+   * not archived/restoring.
+   */
+  async function joinRestore(sandboxId: string): Promise<void> {
+    if (archiver) {
+      try {
+        await archiver.restoreJoin(sandboxId);
+      } catch (error) {
+        throw new E2bError(
+          502,
+          'unavailable',
+          `restoring the sandbox failed: ${error instanceof Error ? error.message : String(error)} — retry`,
+        );
+      }
+      return;
+    }
+    const row = findBySandboxId(db, sandboxId);
+    if (row && (row.state === 'archived' || row.state === 'restoring')) {
+      throw new E2bError(
+        502,
+        'unavailable',
+        'sandbox is archived and the daemon has no S3 configured (DORMICE_S3_*)',
+      );
+    }
+  }
 
   /**
    * Only a logically-running sandbox serves envd traffic: paused and dead
@@ -159,7 +189,11 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
    * take seconds and must not race the scanner or a release.
    */
   async function wakeForUse(sandboxId: string): Promise<SandboxRow> {
+    // The logical gate first: a paused-by-deadline sandbox answers 502
+    // whether it is frozen or archived — restoring it for a request that
+    // will be refused anyway would waste a whole restore.
     const before = requireRunningRow(sandboxId);
+    await joinRestore(sandboxId);
     return locks.run(before.userKey, async () => {
       const fresh = requireRunningRow(sandboxId);
       const awake = await wakeSandbox(db, executor, fresh);
@@ -172,6 +206,7 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
     work: (row: SandboxRow) => Promise<T>,
   ): Promise<T> {
     const before = requireRunningRow(sandboxId);
+    await joinRestore(sandboxId);
     return locks.run(before.userKey, async () => {
       const fresh = requireRunningRow(sandboxId);
       const awake = await wakeSandbox(db, executor, fresh);
diff --git a/packages/server/src/executor/contract/disk-transfer.ts b/packages/server/src/executor/contract/disk-transfer.ts
new file mode 100644
index 0000000..4a6c9be
--- /dev/null
+++ b/packages/server/src/executor/contract/disk-transfer.ts
@@ -0,0 +1,124 @@
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { ContractContext } from './index';
+
+/**
+ * exportDisk/importDisk — the archiver's physical halves. The rule under
+ * exam: export plus import equals the original disk, and both verbs guard
+ * the states they cannot serve. The archive's on-disk format is each
+ * executor's own (tar.zst vs JSON); the round-trip is the contract.
+ */
+export function diskTransferTests(ctx: ContractContext) {
+  const { timeoutMs } = ctx;
+
+  describe('disk transfer', () => {
+    let dir: string;
+    beforeEach(async () => {
+      dir = await mkdtemp(path.join(tmpdir(), 'dormice-contract-'));
+    });
+    afterEach(async () => {
+      await rm(dir, { recursive: true, force: true });
+    });
+
+    it(
+      'a round-trip restores the disk contents',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: 'kept.txt', content: Buffer.from('made it to S3 and back') },
+          { path: 'nested/deep.txt', content: Buffer.from('nested too') },
+        ]);
+        await ctx.executor.freeze(id);
+        await ctx.executor.stop(id);
+        const archive = path.join(dir, 'disk.archive');
+        await ctx.executor.exportDisk(id, archive);
+        // The archive is now the only copy — exactly the archiver's world.
+        await ctx.executor.destroy(id);
+        await ctx.executor.importDisk(id, archive);
+        await ctx.executor.start(id);
+        expect((await ctx.executor.readFile(id, 'kept.txt')).toString()).toBe(
+          'made it to S3 and back',
+        );
+        expect(
+          (await ctx.executor.readFile(id, 'nested/deep.txt')).toString(),
+        ).toBe('nested too');
+      },
+      timeoutMs,
+    );
+
+    it(
+      'exporting a running sandbox refuses',
+      async () => {
+        const id = await ctx.fresh();
+        await expect(
+          ctx.executor.exportDisk(id, path.join(dir, 'x.archive')),
+        ).rejects.toThrow(
+          `container ${id} is running, expected stopped or absent`,
+        );
+      },
+      timeoutMs,
+    );
+
+    it(
+      'exporting without a disk refuses',
+      async () => {
+        const id = randomUUID();
+        await expect(
+          ctx.executor.exportDisk(id, path.join(dir, 'x.archive')),
+        ).rejects.toThrow(`disk ${id} is absent, cannot export`);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'importing over an existing disk refuses',
+      async () => {
+        const id = await ctx.freshStopped();
+        const archive = path.join(dir, 'disk.archive');
+        await ctx.executor.exportDisk(id, archive);
+        await expect(ctx.executor.importDisk(id, archive)).rejects.toThrow(
+          `disk ${id} already exists, cannot import`,
+        );
+      },
+      timeoutMs,
+    );
+
+    it(
+      'import reports monotonic progress ending at 1',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.writeFiles(id, [
+          { path: 'blob.bin', content: Buffer.alloc(256 * 1024, 7) },
+        ]);
+        await ctx.executor.freeze(id);
+        await ctx.executor.stop(id);
+        const archive = path.join(dir, 'disk.archive');
+        await ctx.executor.exportDisk(id, archive);
+        await ctx.executor.destroy(id);
+        const fractions: number[] = [];
+        await ctx.executor.importDisk(id, archive, (f) => fractions.push(f));
+        expect(fractions.length).toBeGreaterThan(0);
+        for (let i = 1; i < fractions.length; i++) {
+          expect(fractions[i]).toBeGreaterThanOrEqual(fractions[i - 1] ?? 0);
+        }
+        expect(fractions.at(-1)).toBe(1);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'the exported archive is a real, nonempty file',
+      async () => {
+        // Guards a silent no-op export: the store uploads this very file.
+        const id = await ctx.freshStopped();
+        const archive = path.join(dir, 'disk.archive');
+        await ctx.executor.exportDisk(id, archive);
+        expect((await stat(archive)).size).toBeGreaterThan(0);
+      },
+      timeoutMs,
+    );
+  });
+}
diff --git a/packages/server/src/executor/contract/index.ts b/packages/server/src/executor/contract/index.ts
index 81a7a6b..f09b7c3 100644
--- a/packages/server/src/executor/contract/index.ts
+++ b/packages/server/src/executor/contract/index.ts
@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { afterEach, beforeEach, describe } from 'vitest';
 import type { ContainerState, Executor, ShellOptions } from '../executor';
+import { diskTransferTests } from './disk-transfer';
 import { entryTests } from './entries';
 import { execTests } from './exec';
 import { execStreamTests } from './exec-stream';
@@ -136,6 +137,7 @@ export function describeExecutorContract(
 
     lifecycleTests(ctx);
     imageTests(ctx);
+    diskTransferTests(ctx);
     execTests(ctx);
     execStreamTests(ctx);
     fileTests(ctx);
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 8bfdc09..32dd1d1 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
 import {
   access,
   chown,
@@ -11,7 +12,7 @@ import {
   statfs,
 } from 'node:fs/promises';
 import path from 'node:path';
-import type { Duplex, Writable } from 'node:stream';
+import { type Duplex, Transform, type Writable } from 'node:stream';
 import {
   EXEC_OUTPUT_LIMIT_BYTES,
   FILE_SIZE_LIMIT_BYTES,
@@ -300,6 +301,75 @@ export class DockerExecutor implements Executor {
     await this.teardownDisk(sandboxId);
   }
 
+  async exportDisk(sandboxId: string, destPath: string): Promise<void> {
+    const found = await this.inspect(sandboxId);
+    if (found !== null) {
+      const actual = containerStateFromDocker(found.status);
+      if (actual !== 'stopped') {
+        throw new Error(
+          `container ${sandboxId} is ${actual}, expected stopped or absent`,
+        );
+      }
+    }
+    if (!(await this.diskExists(sandboxId))) {
+      throw new Error(`disk ${sandboxId} is absent, cannot export`);
+    }
+    // A host reboot drops loop mounts while the image file survives; the
+    // tree has to be mounted to be read.
+    await this.ensureMounted(sandboxId);
+    // The mounted tree, not the raw image: the container is dead, so the
+    // tree is quiescent, and importDisk provisioning a fresh disk is what
+    // lets the restored sandbox follow the current size configuration.
+    // tar does not follow symlinks, so a link planted by the sandbox is
+    // archived as a link, never chased by the root-running daemon.
+    await execa('tar', [
+      '-I',
+      'zstd -T0',
+      '-cf',
+      destPath,
+      '-C',
+      this.mountDir(sandboxId),
+      '.',
+    ]);
+  }
+
+  async importDisk(
+    sandboxId: string,
+    srcPath: string,
+    onProgress?: (fraction: number) => void,
+  ): Promise<void> {
+    if (await this.diskExists(sandboxId)) {
+      throw new Error(`disk ${sandboxId} already exists, cannot import`);
+    }
+    await this.provisionDisk(sandboxId);
+    try {
+      const { size } = await stat(srcPath);
+      let consumed = 0;
+      // The archive is fed through a byte-counting stream into tar's stdin,
+      // so progress is what actually reached the extractor — not a guess.
+      const meter = new Transform({
+        transform(chunk: Buffer, _encoding, callback) {
+          consumed += chunk.length;
+          onProgress?.(size > 0 ? consumed / size : 1);
+          callback(null, chunk);
+        },
+      });
+      createReadStream(srcPath).pipe(meter);
+      // -p as root restores the recorded owners — uid-1000 files stay
+      // uid 1000 (measured in the predecessor system).
+      await execa(
+        'tar',
+        ['-I', 'zstd', '-xpf', '-', '-C', this.mountDir(sandboxId)],
+        { input: meter },
+      );
+      onProgress?.(1);
+    } catch (err) {
+      // Leave no half-disk behind the verb's own failure.
+      await this.teardownDisk(sandboxId);
+      throw err;
+    }
+  }
+
   async diskUsage(): Promise<DiskUsage> {
     const disksDir = path.join(this.opts.dataDir, 'disks');
     let entries: string[];
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index 5a9201d..8fe3508 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -298,6 +298,30 @@ export interface Executor {
    * Never called while the container exists — destroy tears its own disk.
    */
   removeDisk(sandboxId: string): Promise<void>;
+  /**
+   * Packs the sandbox's disk into one local archive file at destPath — the
+   * archiver's read half. The disk must exist ("disk ... is absent, cannot
+   * export") and the container must be stopped or absent ("container ... is
+   * <state>, expected stopped or absent"): a live filesystem cannot be
+   * captured consistently. The archive's format is each executor's own;
+   * only the importDisk round-trip is the contract. Speaks local paths only
+   * — object storage is the archiver's business, never the executor's.
+   */
+  exportDisk(sandboxId: string, destPath: string): Promise<void>;
+  /**
+   * Provisions a fresh disk — at the executor's *current* configured size,
+   * which is how a restored sandbox picks up a raised disk quota — and
+   * unpacks an exportDisk archive into it. The disk must not exist yet
+   * ("disk ... already exists, cannot import"); a failed unpack tears the
+   * fresh disk down again rather than leaving a half-disk behind the verb's
+   * own failure. onProgress reports a monotonic fraction 0..1, best-effort,
+   * ending at 1.
+   */
+  importDisk(
+    sandboxId: string,
+    srcPath: string,
+    onProgress?: (fraction: number) => void,
+  ): Promise<void>;
   /**
    * Where the host can reach a TCP port of this sandbox — what the sandbox
    * proxy dials to serve `<port>-<sandboxId>.<domain>` traffic. Requires
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index b942cd7..2c948f7 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -1,3 +1,4 @@
+import { readFile, writeFile } from 'node:fs/promises';
 import http from 'node:http';
 import type { AddressInfo } from 'node:net';
 import {
@@ -356,6 +357,66 @@ export class FakeExecutor implements Executor {
     this.closeUpstream(sandboxId);
   }
 
+  async exportDisk(sandboxId: string, destPath: string): Promise<void> {
+    const state = this.containers.get(sandboxId);
+    if (state === 'running' || state === 'paused') {
+      throw new Error(
+        `container ${sandboxId} is ${state}, expected stopped or absent`,
+      );
+    }
+    if (!this.disks.has(sandboxId)) {
+      throw new Error(`disk ${sandboxId} is absent, cannot export`);
+    }
+    // A real file on purpose (precedent: the proxy's real upstream socket):
+    // the archiver uploads whatever exportDisk wrote, so the fake writing
+    // real bytes is what lets the whole archive pipeline — store, daemon,
+    // e2e — run without Docker. The format is the fake's own; only the
+    // importDisk round-trip is the contract.
+    const files = [...this.disk(sandboxId)].map(([path, node]) => ({
+      path,
+      type: node.type,
+      modifiedTime: node.modifiedTime,
+      ...(node.type === 'file'
+        ? { contentBase64: node.content.toString('base64') }
+        : {}),
+    }));
+    await writeFile(destPath, JSON.stringify({ version: 1, files }));
+  }
+
+  async importDisk(
+    sandboxId: string,
+    srcPath: string,
+    onProgress?: (fraction: number) => void,
+  ): Promise<void> {
+    if (this.disks.has(sandboxId)) {
+      throw new Error(`disk ${sandboxId} already exists, cannot import`);
+    }
+    const parsed = JSON.parse(await readFile(srcPath, 'utf8')) as {
+      files: Array<{
+        path: string;
+        type: 'file' | 'dir';
+        modifiedTime: string;
+        contentBase64?: string;
+      }>;
+    };
+    const disk = new Map<string, FakeNode>();
+    for (const entry of parsed.files) {
+      disk.set(
+        entry.path,
+        entry.type === 'file'
+          ? {
+              type: 'file',
+              content: Buffer.from(entry.contentBase64 ?? '', 'base64'),
+              modifiedTime: entry.modifiedTime,
+            }
+          : { type: 'dir', modifiedTime: entry.modifiedTime },
+      );
+    }
+    this.disks.add(sandboxId);
+    this.fs.set(sandboxId, disk);
+    onProgress?.(1);
+  }
+
   async resolvePortTarget(
     sandboxId: string,
     port: number,
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index 41bfaf1..a5736bc 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -1,5 +1,11 @@
+import { type ArchiveStore, objectKey } from './archive/store';
 import type { Db } from './db/db';
-import { deleteSandbox, setPausedByUser, transition } from './db/ledger';
+import {
+  deleteSandbox,
+  findBySandboxId,
+  setPausedByUser,
+  transition,
+} from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import { resolveImage } from './db/templates';
 import type { Executor } from './executor/executor';
@@ -38,12 +44,31 @@ export async function stopSandbox(
  * Same order as everything else — reality first, ledger second; a crash in
  * between leaves a row pointing at nothing, which is the reconciler's kind
  * of drift, not this caller's.
+ *
+ * An archived sandbox's body is its S3 object — nothing physical exists
+ * locally, so release deletes the object instead of calling destroy (which
+ * would honestly throw at the double absence). Every caller passes the
+ * store explicitly (null = no archiver configured): releasing an archived
+ * row without a store fails loudly and keeps the row, retryable once the
+ * operator restores the DORMICE_S3_* configuration.
  */
 export async function releaseSandbox(
   db: Db,
   executor: Executor,
   sandboxId: string,
+  store: ArchiveStore | null,
 ): Promise<void> {
+  const row = findBySandboxId(db, sandboxId);
+  if (row?.state === 'archived') {
+    if (store === null) {
+      throw new Error(
+        `sandbox ${sandboxId} is archived but the daemon has no S3 configured (DORMICE_S3_*) — its archive object cannot be deleted`,
+      );
+    }
+    await store.delete(objectKey(sandboxId));
+    deleteSandbox(db, sandboxId);
+    return;
+  }
   await executor.destroy(sandboxId);
   deleteSandbox(db, sandboxId);
 }
@@ -91,10 +116,11 @@ export async function wakeSandbox(
       return awaken(db, row);
     case 'archived':
     case 'restoring':
-      // Unreachable today — nothing archives until the S3 archiver lands.
-      // If it fires anyway, fail loudly instead of pretending.
+      // Every legitimate path branches to the archiver before landing here
+      // (acquire begins a restore, the E2B surface joins one); reaching
+      // this arm is a caller bug worth hearing loudly.
       throw new Error(
-        `sandbox ${row.sandboxId} is ${row.state}; restore is not implemented yet`,
+        `sandbox ${row.sandboxId} is ${row.state}; restore goes through the archiver — this wake is a caller bug`,
       );
   }
 }
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 4cdcc3b..e86a033 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -1,8 +1,11 @@
 import { existsSync } from 'node:fs';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { pino } from 'pino';
 import { buildApp } from './app';
-import { type Config, loadConfig } from './config';
+import { Archiver } from './archive/archiver';
+import { S3Store } from './archive/s3-store';
+import { type Config, loadConfig, s3Settings } from './config';
 import { migrateDb, openDb } from './db/db';
 import { listSandboxes } from './db/ledger';
 import { acquireSingleWriterLock } from './db/lock';
@@ -12,7 +15,7 @@ import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
 import { reconcile } from './reconciler';
 import { scanOnce } from './scanner';
-import { startupGuard } from './startup-guard';
+import { locallyClaimedCount, startupGuard } from './startup-guard';
 
 // One logger, created before everything that needs it: the executor logs
 // through it directly and Fastify adopts it as its own.
@@ -67,6 +70,26 @@ const executor = buildExecutor(config, (msg) => log.info(msg));
 // must share the same per-sandbox slots or the serialization means nothing.
 const locks = new KeyedQueue();
 
+// The archiver exists exactly when S3 is configured; without it the daemon
+// is byte-for-byte the archive-less daemon. Temp transfers stage next to
+// the disks (same filesystem — they are disk-sized, and /tmp may be RAM).
+const s3 = s3Settings(config);
+let archiver: Archiver | undefined;
+if (s3 !== null) {
+  archiver = new Archiver({
+    db,
+    executor,
+    locks,
+    store: new S3Store(s3),
+    tmpDir: path.join(config.DORMICE_DATA_DIR, 'tmp'),
+    log: (msg) => log.info(msg),
+  });
+  await archiver.init();
+  log.info(`archiver enabled: bucket ${s3.bucket} at ${s3.endpoint}`);
+} else {
+  log.info('archiver disabled: DORMICE_S3_* not configured');
+}
+
 // The web console ships beside the server in the monorepo; this file sits
 // one level under packages/server both as src/main.ts and as dist/main.js,
 // so the relative hop to packages/console/dist is the same either way. A
@@ -85,6 +108,7 @@ const app = buildApp({
   locks,
   logger: log,
   consoleDistDir: existsSync(consoleDistDir) ? consoleDistDir : undefined,
+  archiver,
 });
 
 // Before trusting the pairing of this ledger and this reality, check it:
@@ -92,7 +116,7 @@ const app = buildApp({
 // against the wrong ledger, executor or data dir must refuse to start
 // instead of erasing sandboxes it merely cannot see.
 const refusal = startupGuard({
-  ledgerCount: listSandboxes(db).length,
+  ledgerCount: locallyClaimedCount(listSandboxes(db)),
   containers: await executor.listContainers(),
   disks: await executor.listDisks(),
   executor: config.DORMICE_EXECUTOR,
@@ -104,8 +128,10 @@ if (refusal !== null) {
 // Repair ledger/reality drift left by a crash — before serving traffic, so
 // every request runs against a ledger that reflects what actually exists.
 // A failure here is fatal on purpose: a daemon that cannot read reality
-// should not pretend to manage it.
-const repaired = await reconcile(db, executor, locks);
+// should not pretend to manage it. The archiver's restore tracker is empty
+// at boot, so this pass is also what repairs restoring zombies — before
+// listen, so no request ever observes one.
+const repaired = await reconcile(db, executor, locks, undefined, archiver);
 app.log.info(repaired, 'startup reconcile');
 
 // Red line: the daemon binds to loopback only, and the host is deliberately
@@ -130,18 +156,19 @@ await app.listen({ host: '127.0.0.1', port: config.DORMICE_PORT });
 let suspects: ReadonlySet<string> = new Set();
 async function tick() {
   try {
-    const drift = await reconcile(db, executor, locks, suspects);
+    const drift = await reconcile(db, executor, locks, suspects, archiver);
     suspects = new Set(drift.suspects);
     if (
       drift.repairedStates +
         drift.deletedRows +
         drift.destroyedOrphans +
-        drift.removedDisks >
+        drift.removedDisks +
+        drift.archivedSwept >
       0
     ) {
       app.log.warn(drift, 'runtime reconcile repaired drift');
     }
-    const scan = await scanOnce(db, executor, locks, new Date());
+    const scan = await scanOnce(db, executor, locks, new Date(), archiver);
     for (const failure of scan.failures) {
       app.log.error(failure, 'idle scan: sandbox transition failed');
     }
diff --git a/packages/server/src/policy.test.ts b/packages/server/src/policy.test.ts
index 79f158b..d2f39ad 100644
--- a/packages/server/src/policy.test.ts
+++ b/packages/server/src/policy.test.ts
@@ -1,15 +1,15 @@
 import { DEFAULT_LIFECYCLE_POLICY } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
-import { resolvePolicy } from './policy';
+import { ARCHIVE_DEFAULT_SECONDS, resolvePolicy } from './policy';
 
-describe('resolvePolicy', () => {
+describe('resolvePolicy without an archiver (archiveDefaultSeconds = null)', () => {
   it('returns the global defaults when no override is given', () => {
-    expect(resolvePolicy()).toEqual(DEFAULT_LIFECYCLE_POLICY);
-    expect(resolvePolicy({})).toEqual(DEFAULT_LIFECYCLE_POLICY);
+    expect(resolvePolicy(undefined, null)).toEqual(DEFAULT_LIFECYCLE_POLICY);
+    expect(resolvePolicy({}, null)).toEqual(DEFAULT_LIFECYCLE_POLICY);
   });
 
   it('merges a partial override over the defaults', () => {
-    expect(resolvePolicy({ freezeAfterSeconds: 60 })).toEqual({
+    expect(resolvePolicy({ freezeAfterSeconds: 60 }, null)).toEqual({
       ...DEFAULT_LIFECYCLE_POLICY,
       freezeAfterSeconds: 60,
     });
@@ -17,34 +17,85 @@ describe('resolvePolicy', () => {
 
   it('keeps an explicit null for archiveAfterSeconds (never archive)', () => {
     expect(
-      resolvePolicy({ archiveAfterSeconds: null }).archiveAfterSeconds,
+      resolvePolicy({ archiveAfterSeconds: null }, null).archiveAfterSeconds,
     ).toBeNull();
   });
 
+  it('refuses an explicit archive threshold — no archiver, no promise', () => {
+    expect(() => resolvePolicy({ archiveAfterSeconds: 60 }, null)).toThrow(
+      /archiving requires S3 \(DORMICE_S3_\*\) to be configured/,
+    );
+  });
+
   it('rejects a merged result that violates freeze <= stop', () => {
     expect(() =>
-      resolvePolicy({ freezeAfterSeconds: 61, stopAfterSeconds: 60 }),
+      resolvePolicy({ freezeAfterSeconds: 61, stopAfterSeconds: 60 }, null),
     ).toThrow(/freezeAfterSeconds/);
   });
 
-  it('rejects a merged result that violates stop <= archive', () => {
-    // Default stopAfterSeconds is 3 days; archiving after 1s must fail.
-    expect(() => resolvePolicy({ archiveAfterSeconds: 1 })).toThrow(
-      /stopAfterSeconds/,
-    );
-  });
-
   it('keeps an explicit null for stopAfterSeconds (never stop)', () => {
     // The resident-agent policy: park frozen forever, wake in ~50ms, never
     // decay to a cold boot.
     expect(
-      resolvePolicy({ stopAfterSeconds: null }).stopAfterSeconds,
+      resolvePolicy({ stopAfterSeconds: null }, null).stopAfterSeconds,
     ).toBeNull();
   });
+});
+
+describe('resolvePolicy with an archiver (archiveDefaultSeconds = 7 days)', () => {
+  it('defaults new sandboxes to archiving after a week', () => {
+    expect(resolvePolicy(undefined, ARCHIVE_DEFAULT_SECONDS)).toEqual({
+      ...DEFAULT_LIFECYCLE_POLICY,
+      archiveAfterSeconds: ARCHIVE_DEFAULT_SECONDS,
+    });
+  });
+
+  it('keeps an explicit null for archiveAfterSeconds (never archive)', () => {
+    expect(
+      resolvePolicy({ archiveAfterSeconds: null }, ARCHIVE_DEFAULT_SECONDS)
+        .archiveAfterSeconds,
+    ).toBeNull();
+  });
+
+  it('never archives a never-stop sandbox — the default yields to the override', () => {
+    // Only a stopped sandbox can archive; a stop:null override with the
+    // 7-day default left in place would be an invalid policy, so the
+    // default steps aside instead of turning the override into a 400.
+    expect(
+      resolvePolicy({ stopAfterSeconds: null }, ARCHIVE_DEFAULT_SECONDS),
+    ).toEqual({
+      ...DEFAULT_LIFECYCLE_POLICY,
+      stopAfterSeconds: null,
+      archiveAfterSeconds: null,
+    });
+  });
+
+  it('a stop pushed past the default drags the archive default along', () => {
+    // Same yielding rule: an explicit 30-day stop must not collide with the
+    // 7-day archive default — archiving then begins when stopping does.
+    const thirtyDays = 30 * 24 * 60 * 60;
+    expect(
+      resolvePolicy({ stopAfterSeconds: thirtyDays }, ARCHIVE_DEFAULT_SECONDS),
+    ).toEqual({
+      ...DEFAULT_LIFECYCLE_POLICY,
+      stopAfterSeconds: thirtyDays,
+      archiveAfterSeconds: thirtyDays,
+    });
+  });
+
+  it('rejects an explicit archive threshold below the stop threshold', () => {
+    // Default stopAfterSeconds is 3 days; archiving after 1s must fail.
+    expect(() =>
+      resolvePolicy({ archiveAfterSeconds: 1 }, ARCHIVE_DEFAULT_SECONDS),
+    ).toThrow(/stopAfterSeconds/);
+  });
 
   it('rejects archiving a sandbox that never stops', () => {
     expect(() =>
-      resolvePolicy({ stopAfterSeconds: null, archiveAfterSeconds: 60 }),
+      resolvePolicy(
+        { stopAfterSeconds: null, archiveAfterSeconds: 60 },
+        ARCHIVE_DEFAULT_SECONDS,
+      ),
     ).toThrow(/archiveAfterSeconds requires a stopAfterSeconds/);
   });
 });
diff --git a/packages/server/src/policy.ts b/packages/server/src/policy.ts
index 634a31c..d0c819f 100644
--- a/packages/server/src/policy.ts
+++ b/packages/server/src/policy.ts
@@ -6,27 +6,59 @@ import {
 } from '@dormice/shared';
 
 /**
- * Merges a per-sandbox override over the global defaults and validates the
- * merged result. This is the single arbiter for the freeze <= stop <= archive
- * rule — the override schema itself deliberately carries no ordering check.
+ * The default distance from stopped to archived, applied only when the
+ * daemon actually has an archiver (S3 configured) — the shared default
+ * stays null because a promise nobody can honor is a standing lie.
+ */
+export const ARCHIVE_DEFAULT_SECONDS = 7 * 24 * 60 * 60;
+
+/** An archive-asking policy on a daemon that has no archiver. */
+export class ArchiveDisabledError extends Error {
+  constructor() {
+    super('archiving requires S3 (DORMICE_S3_*) to be configured');
+  }
+}
+
+/**
+ * Merges a per-sandbox override over the defaults and validates the merged
+ * result. This is the single arbiter for the freeze <= stop <= archive rule
+ * — the override schema itself deliberately carries no ordering check.
  *
  * `null` is meaningful for stop and archive ("never take that step"), so
  * only `undefined` falls back to the default.
+ *
+ * archiveDefaultSeconds is the caller's adjudication of "is the archiver
+ * configured" (null = no): every call site answers explicitly. With no
+ * archiver, an override explicitly asking to archive is refused — and the
+ * archive default is null. With one, the default yields to an explicit
+ * stop rather than fighting it: a never-stop sandbox never archives (only
+ * a stopped sandbox can), and a stop pushed past the archive default drags
+ * the default along instead of turning a legal stop override into an
+ * ordering error.
  */
 export function resolvePolicy(
-  override?: LifecyclePolicyOverride,
+  override: LifecyclePolicyOverride | undefined,
+  archiveDefaultSeconds: number | null,
 ): LifecyclePolicy {
+  if (archiveDefaultSeconds === null && override?.archiveAfterSeconds != null) {
+    throw new ArchiveDisabledError();
+  }
+  const stopAfterSeconds =
+    override?.stopAfterSeconds !== undefined
+      ? override.stopAfterSeconds
+      : DEFAULT_LIFECYCLE_POLICY.stopAfterSeconds;
+  const archiveDefault =
+    archiveDefaultSeconds === null || stopAfterSeconds === null
+      ? null
+      : Math.max(archiveDefaultSeconds, stopAfterSeconds);
   return lifecyclePolicySchema.parse({
     freezeAfterSeconds:
       override?.freezeAfterSeconds ??
       DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
-    stopAfterSeconds:
-      override?.stopAfterSeconds !== undefined
-        ? override.stopAfterSeconds
-        : DEFAULT_LIFECYCLE_POLICY.stopAfterSeconds,
+    stopAfterSeconds,
     archiveAfterSeconds:
       override?.archiveAfterSeconds !== undefined
         ? override.archiveAfterSeconds
-        : DEFAULT_LIFECYCLE_POLICY.archiveAfterSeconds,
+        : archiveDefault,
   });
 }
diff --git a/packages/server/src/reconciler.test.ts b/packages/server/src/reconciler.test.ts
index 8323222..eeca470 100644
--- a/packages/server/src/reconciler.test.ts
+++ b/packages/server/src/reconciler.test.ts
@@ -16,6 +16,7 @@ const NONE = {
   deletedRows: 0,
   destroyedOrphans: 0,
   removedDisks: 0,
+  archivedSwept: 0,
   suspects: [],
 };
 
@@ -118,20 +119,123 @@ describe('startup reconcile', () => {
     expect(executor.stateOf('orphan')).toBeUndefined();
   });
 
-  it('leaves archived rows to the future archiver', async () => {
+  it('sweeps the stale local copy of an archived row', async () => {
     const { db, executor, locks } = setup();
     const row = await seed(db, executor, 'alice');
-    // Walk the legal path to archived; the container is still around, but
-    // judging that is the archiver's reconciliation, not this one's.
+    // A crash between the archive's ledger write and its local cleanup:
+    // the transition to archived IS the upload confirmation, so whatever is
+    // still here is a stale copy — the sweep resumes the interrupted job.
     await executor.freeze(row.sandboxId);
     await executor.stop(row.sandboxId);
     transition(db, row.sandboxId, 'frozen');
     transition(db, row.sandboxId, 'stopped');
     transition(db, row.sandboxId, 'archived');
 
+    expect(await reconcile(db, executor, locks)).toEqual({
+      ...NONE,
+      archivedSwept: 1,
+    });
+    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(executor.stateOf(row.sandboxId)).toBeUndefined();
+    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+  });
+
+  it('sweeps an archived row whose container is gone but disk remains', async () => {
+    const { db, executor, locks } = setup();
+    const row = await seed(db, executor, 'alice');
+    await executor.freeze(row.sandboxId);
+    await executor.stop(row.sandboxId);
+    transition(db, row.sandboxId, 'frozen');
+    transition(db, row.sandboxId, 'stopped');
+    transition(db, row.sandboxId, 'archived');
+    executor.vanishContainer(row.sandboxId);
+
+    expect(await reconcile(db, executor, locks)).toEqual({
+      ...NONE,
+      archivedSwept: 1,
+    });
+    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+  });
+
+  it('leaves a fully-archived row alone — its body is in S3', async () => {
+    const { db, executor, locks } = setup();
+    const row = await seed(db, executor, 'alice');
+    await executor.freeze(row.sandboxId);
+    await executor.stop(row.sandboxId);
+    transition(db, row.sandboxId, 'frozen');
+    transition(db, row.sandboxId, 'stopped');
+    transition(db, row.sandboxId, 'archived');
+    await executor.destroy(row.sandboxId);
+
+    // Nothing local, and crucially NOT deletedRows: an archived row with no
+    // local remains is the normal state, not drift.
     expect(await reconcile(db, executor, locks)).toEqual(NONE);
     expect(findByUserKey(db, 'alice')?.state).toBe('archived');
-    expect(executor.stateOf(row.sandboxId)).toBe('stopped');
+  });
+
+  it('reverts a restoring zombie with no live task to archived', async () => {
+    const { db, executor, locks } = setup();
+    const row = await seed(db, executor, 'alice');
+    // A crash mid-restore: the row says restoring, a half-extracted disk
+    // exists, no container yet — and the tracker (daemon memory) is empty.
+    await executor.freeze(row.sandboxId);
+    await executor.stop(row.sandboxId);
+    transition(db, row.sandboxId, 'frozen');
+    transition(db, row.sandboxId, 'stopped');
+    transition(db, row.sandboxId, 'archived');
+    await executor.destroy(row.sandboxId);
+    executor.plantDiskResidue(row.sandboxId);
+    transition(db, row.sandboxId, 'restoring');
+
+    const result = await reconcile(db, executor, locks);
+    // The disk is the task's garbage; the S3 object is intact, so archived
+    // makes the next acquire a clean retry.
+    expect(result).toEqual({ ...NONE, repairedStates: 1 });
+    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+  });
+
+  it('records a restoring zombie whose container runs as active', async () => {
+    const { db, executor, locks } = setup();
+    const row = await seed(db, executor, 'alice');
+    // A crash between the restore's start() and its ledger write: the
+    // restore physically finished. Reality wins — removing the disk under
+    // a live container would be the ledger trashing reality.
+    await executor.freeze(row.sandboxId);
+    await executor.stop(row.sandboxId);
+    transition(db, row.sandboxId, 'frozen');
+    transition(db, row.sandboxId, 'stopped');
+    transition(db, row.sandboxId, 'archived');
+    transition(db, row.sandboxId, 'restoring');
+    await executor.start(row.sandboxId);
+
+    const result = await reconcile(db, executor, locks);
+    expect(result).toEqual({ ...NONE, repairedStates: 1 });
+    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(executor.stateOf(row.sandboxId)).toBe('running');
+  });
+
+  it('leaves a restoring row with a live task untouched', async () => {
+    const { db, executor, locks } = setup();
+    const row = await seed(db, executor, 'alice');
+    await executor.freeze(row.sandboxId);
+    await executor.stop(row.sandboxId);
+    transition(db, row.sandboxId, 'frozen');
+    transition(db, row.sandboxId, 'stopped');
+    transition(db, row.sandboxId, 'archived');
+    await executor.destroy(row.sandboxId);
+    // Mid-restore: the task has built half a disk and is still running.
+    executor.plantDiskResidue(row.sandboxId);
+    transition(db, row.sandboxId, 'restoring');
+
+    const result = await reconcile(db, executor, locks, new Set(), {
+      hasLiveRestore: () => true,
+    });
+    expect(result).toEqual(NONE);
+    expect(findByUserKey(db, 'alice')?.state).toBe('restoring');
+    // The mid-flight disk also dodges the orphan pass: the row owns it.
+    expect(await executor.listDisks()).toContain(row.sandboxId);
   });
 
   it('repairs every sandbox in one pass', async () => {
@@ -152,6 +256,7 @@ describe('startup reconcile', () => {
       deletedRows: 1,
       destroyedOrphans: 1,
       removedDisks: 0,
+      archivedSwept: 0,
       suspects: [],
     });
     expect(findByUserKey(db, 'healthy')?.state).toBe('active');
diff --git a/packages/server/src/reconciler.ts b/packages/server/src/reconciler.ts
index 3b773f1..c0ca47c 100644
--- a/packages/server/src/reconciler.ts
+++ b/packages/server/src/reconciler.ts
@@ -19,6 +19,8 @@ export interface ReconcileResult {
   destroyedOrphans: number;
   /** Disks removed because neither a row nor a container owns them. */
   removedDisks: number;
+  /** Stale local remains of archived rows swept away (interrupted cleanups). */
+  archivedSwept: number;
   /**
    * Containers and disks with no row, seen for the first time — not
    * destroyed yet. The caller passes them back as `priorSuspects` on the
@@ -77,14 +79,24 @@ const LEDGER_STATE: Record<ContainerState, SandboxState> = {
  * `priorSuspects` carries the first strikes between runs; omitting it (at
  * startup, when nothing can be in flight) destroys orphans immediately.
  *
- * Archived and restoring rows are skipped: those sandboxes live in S3, not
- * in the executor, and their reconciliation lands with the archiver.
+ * Archived rows claim S3, not local reality — anything of theirs still
+ * here is an interrupted cleanup (the transition to archived IS the upload
+ * confirmation), swept by resuming it: a leftover container is destroyed,
+ * a leftover disk removed. Restoring rows with a live restore task are the
+ * task's own business and skipped; without one they are crash zombies (the
+ * tracker is daemon memory) repaired reality-first — a container means the
+ * restore physically finished before the crash, so the ledger records it;
+ * no container means a half-restore, whose disk is removed and whose row
+ * reverts to archived (the S3 object is intact — the next acquire retries
+ * cleanly). The startup run happens before listen, so no request ever
+ * observes an unrepaired zombie.
  */
 export async function reconcile(
   db: Db,
   executor: Executor,
   locks: KeyedQueue,
   priorSuspects?: ReadonlySet<string>,
+  archiver?: { hasLiveRestore(sandboxId: string): boolean },
 ): Promise<ReconcileResult> {
   const rows = listSandboxes(db);
   const containers = await executor.listContainers();
@@ -94,6 +106,7 @@ export async function reconcile(
     deletedRows: 0,
     destroyedOrphans: 0,
     removedDisks: 0,
+    archivedSwept: 0,
     suspects: [],
   };
   // Everything a disk may legitimately belong to: rows that survive this
@@ -102,21 +115,55 @@ export async function reconcile(
   const owners = new Set<string>();
 
   // Re-reads the row inside its queue slot and applies the repair only if
-  // the state this pass decided on still holds; ledger writes are
-  // synchronous, so nothing interleaves between the re-read and the write.
-  const repairUnderLock = (row: SandboxRow, apply: () => void) =>
+  // the state this pass decided on still holds. The slot is the guard:
+  // apply may await executor work (the archived sweep destroys), and
+  // nothing else touches this sandbox while the slot is held.
+  const repairUnderLock = (
+    row: SandboxRow,
+    apply: () => void | Promise<void>,
+  ) =>
     locks.tryRun(row.userKey, async () => {
       const fresh = findBySandboxId(db, row.sandboxId);
       if (fresh && fresh.state === row.state) {
-        apply();
+        await apply();
       }
     });
 
   for (const row of rows) {
     const observed = containers.get(row.sandboxId);
     containers.delete(row.sandboxId);
-    if (row.state === 'archived' || row.state === 'restoring') {
+    if (row.state === 'archived') {
       owners.add(row.sandboxId);
+      if (observed !== undefined) {
+        await repairUnderLock(row, async () => {
+          await executor.destroy(row.sandboxId);
+          result.archivedSwept += 1;
+        });
+      } else if (disks.has(row.sandboxId)) {
+        await repairUnderLock(row, async () => {
+          await executor.removeDisk(row.sandboxId);
+          result.archivedSwept += 1;
+        });
+      }
+      continue;
+    }
+    if (row.state === 'restoring') {
+      owners.add(row.sandboxId);
+      if (archiver?.hasLiveRestore(row.sandboxId)) {
+        continue; // The task owns this row; what we observe is its mid-work.
+      }
+      if (observed !== undefined) {
+        await repairUnderLock(row, () => {
+          overwriteState(db, row.sandboxId, LEDGER_STATE[observed]);
+          result.repairedStates += 1;
+        });
+      } else {
+        await repairUnderLock(row, async () => {
+          await executor.removeDisk(row.sandboxId);
+          overwriteState(db, row.sandboxId, 'archived');
+          result.repairedStates += 1;
+        });
+      }
       continue;
     }
     if (observed !== undefined) {
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index e39a8b8..bb9707b 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -20,6 +20,7 @@ import {
 } from '@dormice/shared';
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import { ZodError, z } from 'zod';
+import type { Archiver, RestoreProgress } from '../archive/archiver';
 import type { Config } from '../config';
 import type { Db } from '../db/db';
 import {
@@ -41,15 +42,24 @@ import {
 import { httpError } from '../http-error';
 import type { KeyedQueue } from '../keyed-queue';
 import { rebuildSandbox, releaseSandbox, wakeSandbox } from '../lifecycle';
-import { resolvePolicy } from '../policy';
+import { ArchiveDisabledError, resolvePolicy } from '../policy';
 
 export interface SandboxRoutesOptions {
   config: Config;
   db: Db;
   executor: Executor;
   locks: KeyedQueue;
+  /** Absent = no S3 configured: archiving and restores are honestly off. */
+  archiver?: Archiver;
+  /** buildApp's one adjudication of the archive policy default (null = off). */
+  archiveDefaultSeconds: number | null;
 }
 
+/** What acquire's slot work resolves to — the wire union's two arms. */
+type AcquireOutcome =
+  | { status: 'ready'; row: SandboxRow }
+  | { status: 'restoring'; row: SandboxRow; progress: RestoreProgress };
+
 /** Ledger row -> wire shape: nest the flat policy columns, attach the endpoint. */
 function toSandbox(row: SandboxRow, endpoint: string): Sandbox {
   return {
@@ -71,7 +81,10 @@ function toSandbox(row: SandboxRow, endpoint: string): Sandbox {
 
 export const sandboxRoutes: FastifyPluginAsyncZod<
   SandboxRoutesOptions
-> = async (app, { config, db, executor, locks }) => {
+> = async (
+  app,
+  { config, db, executor, locks, archiver, archiveDefaultSeconds },
+) => {
   // Every sandbox lives on this daemon today, so the endpoint is our own
   // address; with sharding it may point at another node.
   const endpoint = `http://127.0.0.1:${config.DORMICE_PORT}`;
@@ -87,15 +100,44 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     userKey: string,
     policy: LifecyclePolicy,
     template: string | null,
-  ): Promise<SandboxRow> {
+  ): Promise<AcquireOutcome> {
     const existing = findByUserKey(db, userKey);
+    if (existing?.state === 'archived' || existing?.state === 'restoring') {
+      // The protocol's promise: acquire never blocks on a slow wake-up. An
+      // archived sandbox starts its restore and answers `restoring` with
+      // progress at once; the caller polls acquire until it flips to ready.
+      if (!archiver) {
+        throw httpError(
+          503,
+          `sandbox for key "${userKey}" is ${existing.state} but the daemon has no S3 configured (DORMICE_S3_*) — restore is impossible until it is`,
+        );
+      }
+      if (existing.state === 'archived') {
+        archiver.beginRestore(existing);
+      }
+      const restoring = findByUserKey(db, userKey);
+      if (!restoring) {
+        throw httpError(500, `sandbox for key "${userKey}" vanished mid-slot`);
+      }
+      return {
+        status: 'restoring',
+        row: restoring,
+        // The fallback covers the crash-zombie instant before the next
+        // reconcile flips the row back to archived; at runtime a restoring
+        // row always has a live task.
+        progress: archiver.progressOf(existing.sandboxId) ?? {
+          phase: 'downloading',
+          percent: 0,
+        },
+      };
+    }
     if (existing) {
       // Wake whatever cold state it is in (a single jump back to active),
       // then refresh the idle clock — an acquire is what "activity" means.
       // A requested template is not applied: like policy, it takes effect
       // only when this acquire creates the sandbox.
       const awake = await wakeSandbox(db, executor, existing);
-      return touch(db, awake.sandboxId);
+      return { status: 'ready', row: touch(db, awake.sandboxId) };
     }
 
     // The capacity check lives at the only verb that creates — wakes of
@@ -118,13 +160,16 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     // names, DNS labels.
     const sandboxId = randomUUID();
     await executor.create(sandboxId, { image: resolveImage(db, template) });
-    return createSandbox(db, {
-      sandboxId,
-      userKey,
-      nodeId: config.DORMICE_NODE_ID,
-      policy,
-      template,
-    });
+    return {
+      status: 'ready',
+      row: createSandbox(db, {
+        sandboxId,
+        userKey,
+        nodeId: config.DORMICE_NODE_ID,
+        policy,
+        template,
+      }),
+    };
   }
 
   // Shared by every verb that uses an existing sandbox (exec, file ops):
@@ -140,6 +185,14 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         `no sandbox for key "${userKey}" — acquire it first`,
       );
     }
+    if (existing.state === 'archived' || existing.state === 'restoring') {
+      // The native restore path is acquire's poll loop; a use verb neither
+      // blocks for minutes nor starts restores on the side.
+      throw httpError(
+        409,
+        `sandbox for key "${userKey}" is ${existing.state} — call acquireSandbox and poll until it is ready`,
+      );
+    }
     const awake = await wakeSandbox(db, executor, existing);
     return touch(db, awake.sandboxId);
   }
@@ -169,7 +222,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       // deserves a 400, not a silent ignore.
       let policy: LifecyclePolicy;
       try {
-        policy = resolvePolicy(override);
+        policy = resolvePolicy(override, archiveDefaultSeconds);
       } catch (error) {
         if (error instanceof ZodError) {
           // The override passed shape validation but the merged policy broke
@@ -180,6 +233,11 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
               .join('; ')}`,
           });
         }
+        if (error instanceof ArchiveDisabledError) {
+          return reply.code(400).send({
+            message: `invalid lifecycle policy: ${error.message}`,
+          });
+        }
         throw error;
       }
 
@@ -192,10 +250,20 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         });
       }
 
-      const row = await locks.run(userKey, () =>
+      const outcome = await locks.run(userKey, () =>
         findOrCreate(userKey, policy, template ?? null),
       );
-      return { status: 'ready' as const, sandbox: toSandbox(row, endpoint) };
+      if (outcome.status === 'restoring') {
+        return {
+          status: 'restoring' as const,
+          sandbox: toSandbox(outcome.row, endpoint),
+          progress: outcome.progress,
+        };
+      }
+      return {
+        status: 'ready' as const,
+        sandbox: toSandbox(outcome.row, endpoint),
+      };
     },
   );
 
@@ -390,7 +458,18 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
           // under this key — already holds.
           return { released: false };
         }
-        await releaseSandbox(db, executor, existing.sandboxId);
+        if (existing.state === 'restoring') {
+          // The one documented dent in release's idempotence: tearing the
+          // half-built disk down would race the restore task over it. The
+          // task finishes in seconds to minutes; retry then.
+          throw httpError(409, 'sandbox is restoring; retry when it finishes');
+        }
+        await releaseSandbox(
+          db,
+          executor,
+          existing.sandboxId,
+          archiver?.store ?? null,
+        );
         return { released: true };
       });
     },
diff --git a/packages/server/src/scanner.test.ts b/packages/server/src/scanner.test.ts
index 1f41050..dbb412a 100644
--- a/packages/server/src/scanner.test.ts
+++ b/packages/server/src/scanner.test.ts
@@ -1,10 +1,16 @@
 import { randomUUID } from 'node:crypto';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   DEFAULT_LIFECYCLE_POLICY,
   type LifecyclePolicy,
 } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
+import { Archiver } from './archive/archiver';
+import { MemStore } from './archive/mem-store';
+import { objectKey } from './archive/store';
 import { type Db, migrateDb, openDb } from './db/db';
 import { createSandbox, findByUserKey, setDeadline, touch } from './db/ledger';
 import type { SandboxRow } from './db/schema';
@@ -21,6 +27,18 @@ function setup() {
   return { db, executor: new FakeExecutor(), locks: new KeyedQueue() };
 }
 
+/** The archive-enabled flavor: same setup plus a MemStore-backed archiver. */
+function setupWithArchiver() {
+  const base = setup();
+  const store = new MemStore();
+  const archiver = new Archiver({
+    ...base,
+    store,
+    tmpDir: mkdtempSync(path.join(tmpdir(), 'dormice-scan-')),
+  });
+  return { ...base, store, archiver };
+}
+
 async function seed(
   db: Db,
   executor: FakeExecutor,
@@ -45,6 +63,7 @@ describe('idle scanner', () => {
     expect(result).toEqual({
       frozen: 0,
       stopped: 0,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -64,6 +83,7 @@ describe('idle scanner', () => {
     expect(result).toEqual({
       frozen: 1,
       stopped: 0,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -84,6 +104,7 @@ describe('idle scanner', () => {
     expect(result).toEqual({
       frozen: 0,
       stopped: 1,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -98,6 +119,7 @@ describe('idle scanner', () => {
     expect(await scanOnce(db, executor, locks, yearLater)).toEqual({
       frozen: 1,
       stopped: 0,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -105,6 +127,7 @@ describe('idle scanner', () => {
     expect(await scanOnce(db, executor, locks, yearLater)).toEqual({
       frozen: 0,
       stopped: 1,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -122,6 +145,7 @@ describe('idle scanner', () => {
     expect(result).toEqual({
       frozen: 1,
       stopped: 0,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -150,6 +174,7 @@ describe('idle scanner', () => {
     expect(yearLater).toEqual({
       frozen: 0,
       stopped: 0,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -212,6 +237,7 @@ describe('idle scanner vs the per-key queue', () => {
     expect(result).toEqual({
       frozen: 0,
       stopped: 0,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -229,6 +255,7 @@ describe('idle scanner vs the per-key queue', () => {
     expect(next).toEqual({
       frozen: 1,
       stopped: 0,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -259,13 +286,14 @@ describe('idle scanner vs the per-key queue', () => {
       after(first, first.freezeAfterSeconds),
     );
     const released = locks.run('doomed', () =>
-      releaseSandbox(db, executor, doomed.sandboxId),
+      releaseSandbox(db, executor, doomed.sandboxId, null),
     );
     const [result] = await Promise.all([sweep, released]);
 
     expect(result).toEqual({
       frozen: 1,
       stopped: 0,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -273,6 +301,195 @@ describe('idle scanner vs the per-key queue', () => {
   });
 });
 
+describe('idle scanner: the archive rung', () => {
+  /** A short three-rung policy: freeze at 60, stop at 120, archive at 180. */
+  const ARCHIVING_POLICY: LifecyclePolicy = {
+    freezeAfterSeconds: 60,
+    stopAfterSeconds: 120,
+    archiveAfterSeconds: 180,
+  };
+
+  async function walkToStopped(
+    db: Db,
+    executor: FakeExecutor,
+    locks: KeyedQueue,
+    row: SandboxRow,
+  ): Promise<void> {
+    await scanOnce(db, executor, locks, after(row, 60));
+    await scanOnce(db, executor, locks, after(row, 120));
+    expect(findByUserKey(db, row.userKey)?.state).toBe('stopped');
+  }
+
+  it('archives a stopped sandbox idle past archiveAfterSeconds', async () => {
+    const { db, executor, locks, store, archiver } = setupWithArchiver();
+    const row = await seed(db, executor, 'alice', ARCHIVING_POLICY);
+    await executor.writeFiles(row.sandboxId, [
+      { path: 'kept.txt', content: Buffer.from('made it') },
+    ]);
+    await walkToStopped(db, executor, locks, row);
+
+    const result = await scanOnce(
+      db,
+      executor,
+      locks,
+      after(row, 180),
+      archiver,
+    );
+    expect(result).toEqual({
+      frozen: 0,
+      stopped: 0,
+      archived: 1,
+      expiredKilled: 0,
+      failures: [],
+    });
+    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(store.has(objectKey(row.sandboxId))).toBe(true);
+    // Local copy freed: container and disk both gone.
+    expect(executor.stateOf(row.sandboxId)).toBeUndefined();
+    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+  });
+
+  it('never moves the archive rung without an archiver', async () => {
+    const { db, executor, locks } = setup();
+    const row = await seed(db, executor, 'alice', ARCHIVING_POLICY);
+    await walkToStopped(db, executor, locks, row);
+
+    // No archiver passed: the row keeps its recorded intent, untouched.
+    const result = await scanOnce(db, executor, locks, after(row, 9999));
+    expect(result.archived).toBe(0);
+    expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
+    expect(await executor.listDisks()).toContain(row.sandboxId);
+  });
+
+  it('never archives a policy that says archive: null', async () => {
+    const { db, executor, locks, archiver } = setupWithArchiver();
+    const row = await seed(db, executor, 'alice', {
+      ...ARCHIVING_POLICY,
+      archiveAfterSeconds: null,
+    });
+    await walkToStopped(db, executor, locks, row);
+
+    const yearLater = await scanOnce(
+      db,
+      executor,
+      locks,
+      after(row, 365 * 24 * 60 * 60),
+      archiver,
+    );
+    expect(yearLater.archived).toBe(0);
+    expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
+  });
+
+  it('an archive failure lands in failures without blocking the sweep', async () => {
+    // The two-phase shape under test: the failing archive runs after —
+    // and therefore cannot stall — the same sweep's cheap freeze.
+    const { db, executor, locks, archiver } = setupWithArchiver();
+    const doomed = await seed(db, executor, 'doomed', ARCHIVING_POLICY);
+    await walkToStopped(db, executor, locks, doomed);
+    const cooling = await seed(db, executor, 'cooling', ARCHIVING_POLICY);
+    // Sabotage the upload: the store refuses everything.
+    archiver.store.put = async () => {
+      throw new Error('the bucket said no');
+    };
+
+    // One instant serves both rows (seeded milliseconds apart): cooling is
+    // 180s idle (past freeze), doomed is 180s idle (past archive).
+    const result = await scanOnce(
+      db,
+      executor,
+      locks,
+      after(cooling, 180),
+      archiver,
+    );
+    expect(result.frozen).toBe(1);
+    expect(result.archived).toBe(0);
+    expect(result.failures).toEqual([
+      {
+        sandboxId: doomed.sandboxId,
+        message: expect.stringContaining('the bucket said no'),
+      },
+    ]);
+    // Retryable: still stopped, disk still local.
+    expect(findByUserKey(db, 'doomed')?.state).toBe('stopped');
+    expect(await executor.listDisks()).toContain(doomed.sandboxId);
+  });
+
+  it('kill-deadline on an archived row deletes the S3 object too', async () => {
+    const { db, executor, locks, store, archiver } = setupWithArchiver();
+    const row = await seed(db, executor, 'alice', ARCHIVING_POLICY);
+    await walkToStopped(db, executor, locks, row);
+    await scanOnce(db, executor, locks, after(row, 180), archiver);
+    expect(store.has(objectKey(row.sandboxId))).toBe(true);
+    setDeadline(db, row.sandboxId, {
+      deadlineAt: after(row, 200).toISOString(),
+      onDeadline: 'kill',
+    });
+
+    const result = await scanOnce(
+      db,
+      executor,
+      locks,
+      after(row, 200),
+      archiver,
+    );
+    expect(result.expiredKilled).toBe(1);
+    expect(findByUserKey(db, 'alice')).toBeUndefined();
+    expect(store.has(objectKey(row.sandboxId))).toBe(false);
+  });
+
+  it('kill-deadline on a restoring row is deferred one sweep', async () => {
+    const { db, executor, locks, archiver } = setupWithArchiver();
+    const row = await seed(db, executor, 'alice', ARCHIVING_POLICY);
+    await walkToStopped(db, executor, locks, row);
+    await scanOnce(db, executor, locks, after(row, 180), archiver);
+    // Begin a restore whose download hangs on a test-held promise, so the
+    // row is mid-restoring when the killing sweep arrives.
+    let releaseDownload!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      releaseDownload = resolve;
+    });
+    const innerGet = archiver.store.get.bind(archiver.store);
+    archiver.store.get = async (key, dest, onProgress) => {
+      await gate;
+      return innerGet(key, dest, onProgress);
+    };
+    const archived = findByUserKey(db, 'alice');
+    if (!archived) throw new Error('row vanished');
+    archiver.beginRestore(archived);
+    expect(findByUserKey(db, 'alice')?.state).toBe('restoring');
+    setDeadline(db, row.sandboxId, {
+      deadlineAt: after(row, 200).toISOString(),
+      onDeadline: 'kill',
+    });
+
+    // Mid-restore: the kill is deferred, the row survives this sweep.
+    const during = await scanOnce(
+      db,
+      executor,
+      locks,
+      after(row, 300),
+      archiver,
+    );
+    expect(during.expiredKilled).toBe(0);
+    expect(findByUserKey(db, 'alice')?.state).toBe('restoring');
+
+    releaseDownload();
+    await archiver.restoreJoin(row.sandboxId);
+    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+
+    // Next sweep, with the restore settled, the kill lands clean.
+    const settled = await scanOnce(
+      db,
+      executor,
+      locks,
+      after(row, 300),
+      archiver,
+    );
+    expect(settled.expiredKilled).toBe(1);
+    expect(findByUserKey(db, 'alice')).toBeUndefined();
+  });
+});
+
 describe('E2B deadline rule', () => {
   async function seedWithDeadline(
     db: Db,
@@ -306,6 +523,7 @@ describe('E2B deadline rule', () => {
     expect(early).toEqual({
       frozen: 0,
       stopped: 0,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -314,6 +532,7 @@ describe('E2B deadline rule', () => {
     expect(late).toEqual({
       frozen: 0,
       stopped: 0,
+      archived: 0,
       expiredKilled: 1,
       failures: [],
     });
@@ -335,6 +554,7 @@ describe('E2B deadline rule', () => {
     expect(result).toEqual({
       frozen: 0,
       stopped: 0,
+      archived: 0,
       expiredKilled: 1,
       failures: [],
     });
@@ -367,6 +587,7 @@ describe('E2B deadline rule', () => {
     expect(late).toEqual({
       frozen: 1,
       stopped: 0,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
@@ -379,6 +600,7 @@ describe('E2B deadline rule', () => {
     expect(again).toEqual({
       frozen: 0,
       stopped: 0,
+      archived: 0,
       expiredKilled: 0,
       failures: [],
     });
diff --git a/packages/server/src/scanner.ts b/packages/server/src/scanner.ts
index 6c82fd5..8e0c8c5 100644
--- a/packages/server/src/scanner.ts
+++ b/packages/server/src/scanner.ts
@@ -1,3 +1,4 @@
+import type { Archiver } from './archive/archiver';
 import type { Db } from './db/db';
 import { findBySandboxId, listSandboxes } from './db/ledger';
 import type { SandboxRow } from './db/schema';
@@ -8,6 +9,8 @@ import { freezeSandbox, releaseSandbox, stopSandbox } from './lifecycle';
 export interface ScanResult {
   frozen: number;
   stopped: number;
+  /** Disks shipped to S3 and freed locally this sweep. */
+  archived: number;
   /** E2B deadlines whose action was kill, enforced this sweep: sandbox destroyed. */
   expiredKilled: number;
   /** Sandboxes whose transition failed this sweep; the caller logs them. */
@@ -23,6 +26,13 @@ export interface ScanResult {
  * logical view reads the expired deadline directly.
  */
 function dueDeadline(row: SandboxRow, now: Date): 'kill' | 'pause' | null {
+  if (row.state === 'restoring') {
+    // A kill mid-restore would race the restore task over the half-built
+    // disk. Deferred one sweep: the task's finish makes the row active (or
+    // archived on failure) and the kill then lands clean — meanwhile the
+    // logical view already reports the expired deadline as dead.
+    return null;
+  }
   if (row.deadlineAt === null || Date.parse(row.deadlineAt) > now.getTime()) {
     return null;
   }
@@ -35,7 +45,10 @@ function dueDeadline(row: SandboxRow, now: Date): 'kill' | 'pause' | null {
  * mirroring ALLOWED_TRANSITIONS — a long-dead sandbox freezes on this sweep
  * and stops on the next; nothing ever skips a state.
  */
-function dueTransition(row: SandboxRow, now: Date): 'freeze' | 'stop' | null {
+function dueTransition(
+  row: SandboxRow,
+  now: Date,
+): 'freeze' | 'stop' | 'archive' | null {
   const idleSeconds = (now.getTime() - Date.parse(row.lastActiveAt)) / 1000;
   if (row.state === 'active' && idleSeconds >= row.freezeAfterSeconds) {
     return 'freeze';
@@ -49,8 +62,14 @@ function dueTransition(row: SandboxRow, now: Date): 'freeze' | 'stop' | null {
     // and would stop every never-stop sandbox on its first frozen sweep.
     return 'stop';
   }
-  // stopped -> archived lands with the S3 archiver. The archiveAfterSeconds
-  // knob already exists so sandboxes created today carry their intent.
+  if (
+    row.state === 'stopped' &&
+    row.archiveAfterSeconds !== null &&
+    idleSeconds >= row.archiveAfterSeconds
+  ) {
+    // Same load-bearing null check as stop's.
+    return 'archive';
+  }
   return null;
 }
 
@@ -70,6 +89,14 @@ function dueTransition(row: SandboxRow, now: Date): 'freeze' | 'stop' | null {
  * catches rows that were released or woken between the snapshot and the
  * slot.
  *
+ * Two phases, fast then slow: an archive is minutes of tar and upload, and
+ * a batch of same-aged sandboxes crossing the archive line together would
+ * otherwise stall every freeze, stop and deadline-kill behind them for the
+ * whole heartbeat tick. Every cheap move lands first; archives then run
+ * serially (one disk's worth of I/O at a time — the host has one disk),
+ * each re-verified inside its own slot. With no archiver the archive rung
+ * simply never moves and rows keep their recorded intent.
+ *
  * One sandbox's failure must not punish the rest: a vanished container (a
  * gVisor box exits whole on OOM) would otherwise block every row behind it
  * on every sweep, and cooling — the product's core promise — would silently
@@ -82,15 +109,22 @@ export async function scanOnce(
   executor: Executor,
   locks: KeyedQueue,
   now: Date,
+  archiver?: Archiver,
 ): Promise<ScanResult> {
   const result: ScanResult = {
     frozen: 0,
     stopped: 0,
+    archived: 0,
     expiredKilled: 0,
     failures: [],
   };
+  const archiveDue: SandboxRow[] = [];
   for (const row of listSandboxes(db)) {
-    if (dueDeadline(row, now) === null && dueTransition(row, now) === null) {
+    const due = dueTransition(row, now);
+    if (due === 'archive' && archiver !== undefined) {
+      archiveDue.push(row);
+    }
+    if (dueDeadline(row, now) === null && (due === null || due === 'archive')) {
       continue;
     }
     try {
@@ -103,7 +137,12 @@ export async function scanOnce(
         // parks) by its deadline, not one rung colder.
         const deadline = dueDeadline(fresh, now);
         if (deadline === 'kill') {
-          await releaseSandbox(db, executor, fresh.sandboxId);
+          await releaseSandbox(
+            db,
+            executor,
+            fresh.sandboxId,
+            archiver?.store ?? null,
+          );
           result.expiredKilled += 1;
           return;
         }
@@ -112,11 +151,11 @@ export async function scanOnce(
           result.frozen += 1;
           return;
         }
-        const due = dueTransition(fresh, now);
-        if (due === 'freeze') {
+        const freshDue = dueTransition(fresh, now);
+        if (freshDue === 'freeze') {
           await freezeSandbox(db, executor, fresh.sandboxId);
           result.frozen += 1;
-        } else if (due === 'stop') {
+        } else if (freshDue === 'stop') {
           await stopSandbox(db, executor, fresh.sandboxId);
           result.stopped += 1;
         }
@@ -128,5 +167,31 @@ export async function scanOnce(
       });
     }
   }
+
+  if (archiver === undefined) return result;
+  for (const row of archiveDue) {
+    try {
+      await locks.tryRun(row.userKey, async () => {
+        const fresh = findBySandboxId(db, row.sandboxId);
+        // Re-verified in the slot: phase one may have killed it by
+        // deadline, an acquire may have woken it, a release removed it —
+        // the snapshot's opinion is void either way.
+        if (
+          !fresh ||
+          dueDeadline(fresh, now) !== null ||
+          dueTransition(fresh, now) !== 'archive'
+        ) {
+          return;
+        }
+        await archiver.archive(fresh);
+        result.archived += 1;
+      });
+    } catch (error) {
+      result.failures.push({
+        sandboxId: row.sandboxId,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
   return result;
 }
diff --git a/packages/server/src/startup-guard.test.ts b/packages/server/src/startup-guard.test.ts
index 37b3836..9d11279 100644
--- a/packages/server/src/startup-guard.test.ts
+++ b/packages/server/src/startup-guard.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import type { ContainerState } from './executor/executor';
-import { startupGuard } from './startup-guard';
+import { locallyClaimedCount, startupGuard } from './startup-guard';
 
 function containers(...ids: string[]): Map<string, ContainerState> {
   return new Map(ids.map((id) => [id, 'running' as const]));
@@ -87,4 +87,38 @@ describe('startupGuard', () => {
       }),
     ).toBeNull();
   });
+
+  it('starts a docker daemon whose whole ledger is archived sandboxes', () => {
+    // Every sandbox archived after a week of idleness, then a deploy
+    // restart: the ledger is populated, local reality legitimately empty —
+    // those rows claim S3. locallyClaimedCount is what main.ts feeds the
+    // guard, and it must exclude them or this daemon bricks forever.
+    const rows = [
+      { state: 'archived' as const },
+      { state: 'archived' as const },
+      { state: 'restoring' as const },
+    ];
+    expect(locallyClaimedCount(rows)).toBe(0);
+    expect(
+      startupGuard({
+        ledgerCount: locallyClaimedCount(rows),
+        containers: containers(),
+        disks: [],
+        executor: 'docker',
+      }),
+    ).toBeNull();
+  });
+
+  it('still refuses when active rows face an empty docker reality', () => {
+    const rows = [{ state: 'archived' as const }, { state: 'active' as const }];
+    expect(locallyClaimedCount(rows)).toBe(1);
+    expect(
+      startupGuard({
+        ledgerCount: locallyClaimedCount(rows),
+        containers: containers(),
+        disks: [],
+        executor: 'docker',
+      }),
+    ).toMatch(/cannot see the sandboxes it owns/);
+  });
 });
diff --git a/packages/server/src/startup-guard.ts b/packages/server/src/startup-guard.ts
index 8b2a00d..bee87b9 100644
--- a/packages/server/src/startup-guard.ts
+++ b/packages/server/src/startup-guard.ts
@@ -1,5 +1,20 @@
+import type { SandboxState } from '@dormice/shared';
 import type { ContainerState } from './executor/executor';
 
+/**
+ * How many ledger rows claim LOCAL reality. Archived and restoring rows
+ * claim S3 instead — a ledger of nothing but archived sandboxes
+ * legitimately faces an empty machine, and counting them into the guard
+ * below would brick every such daemon at its next restart.
+ */
+export function locallyClaimedCount(
+  rows: readonly { state: SandboxState }[],
+): number {
+  return rows.filter(
+    (row) => row.state !== 'archived' && row.state !== 'restoring',
+  ).length;
+}
+
 /**
  * The identity check between "this ledger" and "this reality", run once at
  * boot before the first reconcile. Reconciliation trusts that the ledger it
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8b8f2ba..2e2ea7e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -35,6 +35,10 @@ importers:
       e2b:
         specifier: ^2.31.0
         version: 2.31.0
+    devDependencies:
+      '@dormice/server':
+        specifier: workspace:*
+        version: link:../packages/server
 
   packages/cli:
     dependencies:
@@ -167,6 +171,12 @@ importers:
 
   packages/server:
     dependencies:
+      '@aws-sdk/client-s3':
+        specifier: ^3.1083.0
+        version: 3.1083.0
+      '@aws-sdk/lib-storage':
+        specifier: ^3.1083.0
+        version: 3.1083.0(@aws-sdk/client-s3@3.1083.0)
       '@dormice/shared':
         specifier: workspace:*
         version: link:../shared
@@ -323,6 +333,84 @@ packages:
     resolution: {integrity: sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw==}
     engines: {node: '>=10'}
 
+  '@aws-sdk/checksums@3.1000.16':
+    resolution: {integrity: sha512-EKnvkXSmz3IpA99tCNuI+dLFXyZyClSm8zns9sB/elvkU+MTuomAs6toJMPMBf98/fICG/urXDkzGz0/c3yyAQ==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/client-s3@3.1083.0':
+    resolution: {integrity: sha512-3YOicHy6qjexsy4rHk5jPvtLgg6Ho1u+ycOWtJcVTAIMlMq32MRtnhllAyFSezhAXeBnnLLtKtAGXim7vV8oog==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/core@3.975.1':
+    resolution: {integrity: sha512-8qh/6EYb7hl/ZwVfQufhbMEZs1gQIc7GbdrIf4eprQJ7cv042+74nE6l3YDfyWNzb9iPXb8fRyYSHkNIk5eE6Q==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-env@3.972.57':
+    resolution: {integrity: sha512-1RfJaF7SW1TOnvNGU7kaYjwUf5H3sfm+synGH1bHhRlqcnxCt3szebH3dmKEyY4tuGcbQ6ffzUT89cRitBV8OQ==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-http@3.972.59':
+    resolution: {integrity: sha512-sRCkpTiFnCdQvuaRVjQ6SVoHu6i7RUpurVo1c4F81HWhPvUJ7Wdp5MNtSdX1O29CNXc8em3O5m52hCjVtAD9SA==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-ini@3.973.1':
+    resolution: {integrity: sha512-6d8H6ZAh3ZPKZ6fe1nG2OWeZEZPtt9ravoD1dezPdPtsSkJRoxGAnFSHwKT3E/Te6fHE30zRzjV6TD12rvF6yQ==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-login@3.972.63':
+    resolution: {integrity: sha512-GREWRrMj0XnNKMaVa/Mauoaui26qBEHu71WWqXbwZOu/jFQOnPZjTf7u0KtGKC8VGa6VUs9kDWGgocrKNLS9vw==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-node@3.972.66':
+    resolution: {integrity: sha512-f+qjRXZpz7sgzbc4QB+6nLKfyKFgRRXzWdXbsKPv/VhVRyHsDyq4yBWC/B75BAJpFIcUeI2XR/3gdWJ677zB4A==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-process@3.972.57':
+    resolution: {integrity: sha512-TiVQhuU0pbhIZAUZacbPHMyzrIdiH+lnx+PMY/Pu/b93dJrq3wdZwzUJ0TPpvNxaqbHsxJvQZW3/h/beLiKq7Q==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-sso@3.973.1':
+    resolution: {integrity: sha512-3foTZUJ4821Ij60X7K3NJroygiZLnbBmarN+T//O2cjkISan90zElN3NBmgSlDrTQ7Gs6z/yO8V7h60QNcDZHQ==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-web-identity@3.972.63':
+    resolution: {integrity: sha512-8qZLFhM69eKcS37m459ctPR05Qimycm/74OPVioe6wNZabMT54GYhwBju0+J656RkMasNSawWQu+c8CmBe3TUQ==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/lib-storage@3.1083.0':
+    resolution: {integrity: sha512-r9PY+w81yeFIMKy/tAPRDD1AJnygXMdwUZOx5dGGHwx9Azk8CYYm9mA9Km5XxSdPihlrJ5sSleaHNFN0VHrIDA==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      '@aws-sdk/client-s3': ^3.1083.0
+
+  '@aws-sdk/middleware-sdk-s3@3.972.62':
+    resolution: {integrity: sha512-k8JJwYXVYlOOjWnPZDThQS1xDFJgi5Dokt73qFlDtrZAbdcint5aIdjB9XgJAAQVP5OoqcefQmh1FYXiPpvsvw==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/nested-clients@3.997.31':
+    resolution: {integrity: sha512-BDHTpwcsZHEBNEJzOg/B1BkFYJxAXY50dau/NyVWs3d51F0WgIUGSWZot/Os+N3KpDhXeaXnz37mWffAvduREw==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/signature-v4-multi-region@3.996.39':
+    resolution: {integrity: sha512-8+srXqYIF8KYMLC4FxMLEM5Ek7kUNibJu1R4m8/fUhhNYIZZz26oGtKkCr8I/HiG2fFQxBvaGgQZT4/mqRCSnA==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/token-providers@3.1083.0':
+    resolution: {integrity: sha512-s0woKnxuHrExLc5L2ArIH5BMkbonHPtt+5hSBM8oknp9M6QTuUmmAmJ2E0EdzCGONrO+8+ADPqvv6UX0nNcc7A==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/types@3.974.0':
+    resolution: {integrity: sha512-QIBrw90CDm4O0UaIIzkU6DrFdeJzEb2Va5EPEVpyldj6sHJxB6cshhStJuhZxk3wR3PmjJlYsjPmY1kNb+KGBg==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/xml-builder@3.972.34':
+    resolution: {integrity: sha512-wHhWL1y7sN3enBA8POrPpQM5jCcmu2ozyhbRei4c8OjVcEaEs6yLucLa/pla457ggS/ysuy7bosagz3HaJkZXA==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws/lambda-invoke-store@0.3.0':
+    resolution: {integrity: sha512-sl4Bm6yiMNYrZKkqqDFWN0UfnWhlS8ivKxrYl+6t0gCLrqr8y3B2IqZZbFRkfaVVp7C/baApyh71P+LeE1A2sQ==}
+    engines: {node: '>=18.0.0'}
+
   '@babel/code-frame@7.29.7':
     resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
     engines: {node: '>=6.9.0'}
@@ -2135,6 +2223,30 @@ packages:
     resolution: {integrity: sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==}
     engines: {node: '>=18'}
 
+  '@smithy/core@3.29.2':
+    resolution: {integrity: sha512-DXUk6yU0C1Q1tYvJh1VCtl8QOBcSoZpKwjTPkxT6A4MUQYHvgeKGByL8mrEdxnvhdf9nq5GyzmRb5n/vPgu3Lw==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/credential-provider-imds@4.4.7':
+    resolution: {integrity: sha512-UEMLOoA0Fl4uYBxh6l0uN0H6EJe/A89OGeDNTteQeXpJ20BcpfIr4wlCY9pel1jEAUHAxaYwuqrYlrKdXE1GKQ==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/fetch-http-handler@5.6.4':
+    resolution: {integrity: sha512-psnst7NZWdAEvJvyW8YZEE7xNVMyLrQFfHtyrVFrxNyy+dKWkQ+rqC6oI5ZhxThpUy9RSfEshgm34zqbOxzsRw==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/node-http-handler@4.9.4':
+    resolution: {integrity: sha512-BNTop/fSOptmoVk8g+efwHCofFh37g70OWGAFES1TeAAJja1K5aAI8rTE26ETSc5k8IQuWY2kAIoPla01NgYrA==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/signature-v4@5.6.3':
+    resolution: {integrity: sha512-8qVKKzqh7naF27ePmx0SkUfnGP/wBI9dyaeAmhHvopnbIlItUAmB/e6PkPCU3rRb2v9BY8D4EZXSoydSibatvw==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/types@4.16.0':
+    resolution: {integrity: sha512-aVUabzlBBmY0PfvVgLKQSOGFIL5/7R54JE3uD9a5Ay/jSED61SkuAcCYENNXJzYUvJ1NPrWO0P+rAXHCkbBUKw==}
+    engines: {node: '>=18.0.0'}
+
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
@@ -2601,6 +2713,9 @@ packages:
     resolution: {integrity: sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==}
     engines: {node: '>=18'}
 
+  bowser@2.14.1:
+    resolution: {integrity: sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==}
+
   brace-expansion@5.0.7:
     resolution: {integrity: sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA==}
     engines: {node: 18 || 20 || >=22}
@@ -2617,6 +2732,9 @@ packages:
   buffer-from@1.1.2:
     resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==}
 
+  buffer@5.6.0:
+    resolution: {integrity: sha512-/gDYp/UtU0eA1ys8bOs9J6a+E/KWIY+DZ+Q2WESNUA0jFRsJOc0SNUO6xJ5SGA1xueg3NL65W6s+NY5l9cunuw==}
+
   buffer@5.7.1:
     resolution: {integrity: sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==}
 
@@ -3220,6 +3338,10 @@ packages:
   eventemitter3@5.0.4:
     resolution: {integrity: sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==}
 
+  events@3.3.0:
+    resolution: {integrity: sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q==}
+    engines: {node: '>=0.8.x'}
+
   eventsource-parser@3.1.0:
     resolution: {integrity: sha512-kJezFj9YFAMLeORyi7aCLxLbD5/qWMQnoMVlVPyHIll7lgRJCc3JVln9Vgl9nwQi0YkMnhdGTMNn7CkRRAptMg==}
     engines: {node: '>=18.0.0'}
@@ -4856,6 +4978,9 @@ packages:
     resolution: {integrity: sha512-UhDfHmA92YAlNnCfhmq0VeNL5bDbiZGg7sZ2IvPsXubGkiNa9EC+tUTsjBRsYUAz87btI6/1wf4XoVvQ3uRnmQ==}
     engines: {node: '>=18'}
 
+  stream-browserify@3.0.0:
+    resolution: {integrity: sha512-H73RAHsVBapbim0tU2JwwOiXUj+fikfiaoYAKHF3VJfA0pe2BCzkhAHBlLG6REzE+2WNZcxOXjK7lkso+9euLA==}
+
   string-width@4.2.3:
     resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
     engines: {node: '>=8'}
@@ -5375,6 +5500,181 @@ snapshots:
 
   '@alloc/quick-lru@5.2.0': {}
 
+  '@aws-sdk/checksums@3.1000.16':
+    dependencies:
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/client-s3@3.1083.0':
+    dependencies:
+      '@aws-sdk/checksums': 3.1000.16
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/credential-provider-node': 3.972.66
+      '@aws-sdk/middleware-sdk-s3': 3.972.62
+      '@aws-sdk/signature-v4-multi-region': 3.996.39
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/fetch-http-handler': 5.6.4
+      '@smithy/node-http-handler': 4.9.4
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/core@3.975.1':
+    dependencies:
+      '@aws-sdk/types': 3.974.0
+      '@aws-sdk/xml-builder': 3.972.34
+      '@aws/lambda-invoke-store': 0.3.0
+      '@smithy/core': 3.29.2
+      '@smithy/signature-v4': 5.6.3
+      '@smithy/types': 4.16.0
+      bowser: 2.14.1
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-env@3.972.57':
+    dependencies:
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-http@3.972.59':
+    dependencies:
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/fetch-http-handler': 5.6.4
+      '@smithy/node-http-handler': 4.9.4
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-ini@3.973.1':
+    dependencies:
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/credential-provider-env': 3.972.57
+      '@aws-sdk/credential-provider-http': 3.972.59
+      '@aws-sdk/credential-provider-login': 3.972.63
+      '@aws-sdk/credential-provider-process': 3.972.57
+      '@aws-sdk/credential-provider-sso': 3.973.1
+      '@aws-sdk/credential-provider-web-identity': 3.972.63
+      '@aws-sdk/nested-clients': 3.997.31
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/credential-provider-imds': 4.4.7
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-login@3.972.63':
+    dependencies:
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/nested-clients': 3.997.31
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-node@3.972.66':
+    dependencies:
+      '@aws-sdk/credential-provider-env': 3.972.57
+      '@aws-sdk/credential-provider-http': 3.972.59
+      '@aws-sdk/credential-provider-ini': 3.973.1
+      '@aws-sdk/credential-provider-process': 3.972.57
+      '@aws-sdk/credential-provider-sso': 3.973.1
+      '@aws-sdk/credential-provider-web-identity': 3.972.63
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/credential-provider-imds': 4.4.7
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-process@3.972.57':
+    dependencies:
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-sso@3.973.1':
+    dependencies:
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/nested-clients': 3.997.31
+      '@aws-sdk/token-providers': 3.1083.0
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-web-identity@3.972.63':
+    dependencies:
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/nested-clients': 3.997.31
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/lib-storage@3.1083.0(@aws-sdk/client-s3@3.1083.0)':
+    dependencies:
+      '@aws-sdk/client-s3': 3.1083.0
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      buffer: 5.6.0
+      events: 3.3.0
+      stream-browserify: 3.0.0
+      tslib: 2.8.1
+
+  '@aws-sdk/middleware-sdk-s3@3.972.62':
+    dependencies:
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/signature-v4-multi-region': 3.996.39
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/nested-clients@3.997.31':
+    dependencies:
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/signature-v4-multi-region': 3.996.39
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/fetch-http-handler': 5.6.4
+      '@smithy/node-http-handler': 4.9.4
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/signature-v4-multi-region@3.996.39':
+    dependencies:
+      '@aws-sdk/types': 3.974.0
+      '@smithy/signature-v4': 5.6.3
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/token-providers@3.1083.0':
+    dependencies:
+      '@aws-sdk/core': 3.975.1
+      '@aws-sdk/nested-clients': 3.997.31
+      '@aws-sdk/types': 3.974.0
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/types@3.974.0':
+    dependencies:
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws-sdk/xml-builder@3.972.34':
+    dependencies:
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@aws/lambda-invoke-store@0.3.0': {}
+
   '@babel/code-frame@7.29.7':
     dependencies:
       '@babel/helper-validator-identifier': 7.29.7
@@ -6868,6 +7168,39 @@ snapshots:
 
   '@sindresorhus/merge-streams@4.0.0': {}
 
+  '@smithy/core@3.29.2':
+    dependencies:
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@smithy/credential-provider-imds@4.4.7':
+    dependencies:
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@smithy/fetch-http-handler@5.6.4':
+    dependencies:
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@smithy/node-http-handler@4.9.4':
+    dependencies:
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@smithy/signature-v4@5.6.3':
+    dependencies:
+      '@smithy/core': 3.29.2
+      '@smithy/types': 4.16.0
+      tslib: 2.8.1
+
+  '@smithy/types@4.16.0':
+    dependencies:
+      tslib: 2.8.1
+
   '@standard-schema/spec@1.1.0': {}
 
   '@standard-schema/utils@0.3.0': {}
@@ -7333,6 +7666,8 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  bowser@2.14.1: {}
+
   brace-expansion@5.0.7:
     dependencies:
       balanced-match: 4.0.4
@@ -7351,6 +7686,11 @@ snapshots:
 
   buffer-from@1.1.2: {}
 
+  buffer@5.6.0:
+    dependencies:
+      base64-js: 1.5.1
+      ieee754: 1.2.1
+
   buffer@5.7.1:
     dependencies:
       base64-js: 1.5.1
@@ -7916,6 +8256,8 @@ snapshots:
 
   eventemitter3@5.0.4: {}
 
+  events@3.3.0: {}
+
   eventsource-parser@3.1.0: {}
 
   eventsource@3.0.7:
@@ -9995,6 +10337,11 @@ snapshots:
 
   stdin-discarder@0.2.2: {}
 
+  stream-browserify@3.0.0:
+    dependencies:
+      inherits: 2.0.4
+      readable-stream: 3.6.2
+
   string-width@4.2.3:
     dependencies:
       emoji-regex: 8.0.0

From 3caac09f9013380e33e553cdc84a6a5a1fa9b9f0 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 11 Jul 2026 11:56:14 +0800
Subject: [PATCH 048/133] =?UTF-8?q?publishConfig=20pins=20the=20official?=
 =?UTF-8?q?=20registry=20=E2=80=94=20a=20local=20mirror=20default=20must?=
 =?UTF-8?q?=20never=20swallow=20a=20release?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/cli/package.json    | 3 ++-
 packages/sdk/package.json    | 3 ++-
 packages/shared/package.json | 3 ++-
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/cli/package.json b/packages/cli/package.json
index b322b50..99d7552 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -22,7 +22,8 @@
     "node": ">=22"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "type": "module",
   "bin": {
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index fc4261d..ed81d50 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -23,7 +23,8 @@
     "node": ">=22"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "sideEffects": false,
   "type": "module",
diff --git a/packages/shared/package.json b/packages/shared/package.json
index 0a5c745..e3eb503 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -21,7 +21,8 @@
     "node": ">=22"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "sideEffects": false,
   "type": "module",

From a84a5568f73b726ed3e74df9f2642022cd40da4e Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 11 Jul 2026 11:56:50 +0800
Subject: [PATCH 049/133] Community files: security policy, contributing guide,
 issue and PR templates, CI badges
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SECURITY.md routes reports to GitHub private vulnerability reporting —
a public issue about a sandbox escape would be a zero-day announcement.
The bug template requires dor doctor output, which exists precisely for
diagnosing a host remotely.
---
 .github/ISSUE_TEMPLATE/bug_report.yml      | 52 +++++++++++++++
 .github/ISSUE_TEMPLATE/config.yml          |  5 ++
 .github/ISSUE_TEMPLATE/feature_request.yml | 23 +++++++
 .github/pull_request_template.md           | 10 +++
 CONTRIBUTING.md                            | 75 ++++++++++++++++++++++
 README.md                                  |  3 +
 SECURITY.md                                | 38 +++++++++++
 7 files changed, 206 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml
 create mode 100644 .github/pull_request_template.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 SECURITY.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..4b8d190
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,52 @@
+name: Bug report
+description: Something behaves wrong
+labels: [bug]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: >
+        What did you do, what did you expect, and what happened instead?
+        Exact commands and exact error output beat descriptions.
+      placeholder: |
+        1. ...
+        2. ...
+        Expected: ...
+        Got: ...
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: dor doctor output
+      description: >
+        Run `dor doctor` on the host and paste the full output — most
+        host-related problems are diagnosed straight from it. If your
+        report does not involve a running daemon (an SDK-only problem,
+        say), write "not applicable" and why.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: How you run Dormice.
+      placeholder: |
+        Installed via: install.sh | from source
+        Dormice version/commit: ...
+        OS: Ubuntu 24.04 | macOS (fake executor) | ...
+        Executor: docker | fake
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Daemon logs (if relevant)
+      description: >
+        `journalctl -u dormice -n 200` on an install.sh host, or the
+        daemon's stdout. Redact your API token if it appears.
+      render: text
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..7875edb
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/BitMiracle-AI/Dormice/security/advisories/new
+    about: Private channel — never report a vulnerability in a public issue.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..be800ec
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,23 @@
+name: Feature request
+description: Propose an improvement or a new capability
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: >
+        What are you trying to do that Dormice makes hard or impossible
+        today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: >
+        If you have a shape in mind. Note that "When Dormice is the
+        wrong tool" in the README lists a few things that are out of
+        scope by design.
+    validations:
+      required: false
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..012c316
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,10 @@
+## What & why
+
+<!-- What changed, and the reasoning. Link the issue if one exists. -->
+
+## Checklist
+
+- [ ] `pnpm build && pnpm typecheck && pnpm lint && pnpm test` passes locally (build first — the e2e suite runs the built daemon)
+- [ ] Behavior changes come with tests that fail without the change
+- [ ] User-facing changes to `@dormice/shared` / `sdk` / `cli` have a changeset (`pnpm changeset`)
+- [ ] README updated if this changes documented behavior
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..835994a
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,75 @@
+# Contributing to Dormice
+
+Thanks for your interest! Dormice is in early development and moving
+fast — before building something large, please open an issue first so
+we can agree on the direction and nobody's work is wasted.
+
+## Development setup
+
+Requirements: Node.js >= 22 and pnpm. The exact pnpm version is pinned
+in `package.json`'s `packageManager` field, so `corepack enable` gives
+you the right one automatically.
+
+```sh
+pnpm install
+pnpm build      # build first: the e2e suite boots the *built* daemon
+pnpm typecheck
+pnpm lint
+pnpm test
+```
+
+That chain, in that order, is exactly what CI runs — if it is green
+locally, CI will agree. **`pnpm build` must come before `pnpm test`**:
+the black-box e2e suite spawns `dist/main.js`, and a stale or missing
+build fails honestly rather than testing yesterday's code.
+
+Everything above runs on any OS. By default the daemon uses an
+in-memory fake executor, so no Docker, no Linux, and no root are needed
+for development.
+
+### Real-sandbox tests (mostly a maintainer concern)
+
+The Docker + gVisor executor is verified by a contract suite — the same
+exam the fake executor takes, run against real containers. It needs a
+Linux host with root, gVisor (`runsc`) installed, and a base image
+built, and is skipped automatically everywhere else, including CI:
+
+```sh
+DORMICE_DOCKER_CONTRACT=1 DORMICE_BASE_IMAGE=<image> pnpm --filter @dormice/server test
+```
+
+You do not need this for most changes — a PR that passes the normal
+chain is reviewable, and real-hardware verification happens before
+release.
+
+## Code style
+
+- Formatting and linting are Biome's job (`pnpm format`, `pnpm lint`) —
+  single quotes, 2-space indent, no debates.
+- Comments explain constraints the code cannot express — the why, not
+  the what.
+- Prefer one place that decides a thing over defensive re-checks
+  scattered everywhere, and an honest, named error over a silent
+  fallback.
+
+## Tests
+
+Every behavior change comes with a test that fails without the change.
+The style here is black-box where possible: the e2e suite drives a real
+daemon process over HTTP, and both executors must pass one shared
+contract with identical error messages.
+
+## Commits and pull requests
+
+- Commit messages in English: a short first line saying what changed,
+  **no type prefixes** (`feat:`, `fix:`), reasoning in the body when a
+  decision is worth recording.
+- Keep PRs small and focused, and run the full verification chain
+  before opening one.
+- If your change affects users of the published packages
+  (`@dormice/shared`, `@dormice/sdk`, `@dormice/cli`), add a changeset:
+  `pnpm changeset`.
+
+## Security issues
+
+Never in a public issue or PR — see [SECURITY.md](SECURITY.md).
diff --git a/README.md b/README.md
index 31aa15b..8f7aab2 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,8 @@
 # Dormice
 
+[![CI](https://github.com/BitMiracle-AI/Dormice/actions/workflows/ci.yml/badge.svg)](https://github.com/BitMiracle-AI/Dormice/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
 **The SQLite of agent sandboxes** — a self-hosted sandbox platform for AI agents. One machine, sandboxes that live forever, idle costs nothing.
 
 > **Status: early development.** The daemon, its lifecycle engine, the SDK, the CLI, the web console, the real Docker + gVisor executor, the S3 archiver, and the E2B-compatible API work end to end — the full create → freeze → stop → archive → restore cycle, command execution, file I/O, and the official `e2b` SDK against real infrastructure. Nothing here is ready for production yet.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..e3ed262
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,38 @@
+# Security Policy
+
+Dormice runs untrusted code on your own machine — security reports are
+the most valuable kind of feedback this project can get.
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for a security problem.** A public
+issue is a zero-day announcement for everyone running Dormice.
+
+Instead, use GitHub's private vulnerability reporting:
+[**Report a vulnerability**](https://github.com/BitMiracle-AI/Dormice/security/advisories/new)
+— it opens a private thread between you and the maintainers.
+
+You can expect an acknowledgement within 7 days. Dormice is in early
+development and not yet recommended for production, so there is no
+formal SLA and no bug bounty — but security reports are prioritized
+over feature work, and you will be credited in the advisory unless you
+prefer otherwise.
+
+## What counts
+
+Anything that breaks the model documented in the README, for example:
+
+- **Sandbox escape**: code inside a sandbox affecting the host or
+  another sandbox (the isolation boundary is Docker + gVisor).
+- **Authentication bypass** on the daemon API, the E2B-compatible
+  surface, the signed file URLs, or the web console's session cookies.
+- **Unexpected exposure**: the daemon being reachable in ways the
+  documentation says it is not (it binds to 127.0.0.1 only, by design).
+
+Vulnerabilities in upstream components (gVisor, Docker, Node.js) belong
+with those projects — but if Dormice *configures* them insecurely, that
+is ours and we want to know.
+
+## Supported versions
+
+Pre-1.0, only the latest release and `main` receive fixes.

From 06a6f50ba03b583d01dc6bd1d598f03063729eb0 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 11 Jul 2026 12:39:36 +0800
Subject: [PATCH 050/133] The docs sidebar learns groups; concepts,
 configuration, and a split E2B chapter fill them

---
 website/content/docs/architecture.mdx         |  81 ++++++++++++++
 website/content/docs/configuration.mdx        |  84 +++++++++++++++
 ...-compatibility.mdx => e2b-differences.mdx} |  56 +++++-----
 website/content/docs/e2b-sdks.mdx             |  80 ++++++++++++++
 website/content/docs/index.mdx                |   5 +-
 website/content/docs/lifecycle.mdx            | 102 ++++++++++++++++++
 website/content/docs/meta.json                |  19 +++-
 website/content/docs/persistence.mdx          |  70 ++++++++++++
 website/src/app/docs/layout.tsx               |  14 ++-
 website/src/app/layout.tsx                    |  15 +--
 website/src/components/SiteHeader.tsx         |   6 +-
 website/src/components/docs/DocsMobileNav.tsx |  10 +-
 website/src/components/docs/DocsSearch.tsx    |  47 ++++----
 website/src/components/docs/DocsSidebar.tsx   |  47 ++++----
 website/src/lib/docs.ts                       |  62 +++++++----
 15 files changed, 590 insertions(+), 108 deletions(-)
 create mode 100644 website/content/docs/architecture.mdx
 create mode 100644 website/content/docs/configuration.mdx
 rename website/content/docs/{e2b-compatibility.mdx => e2b-differences.mdx} (56%)
 create mode 100644 website/content/docs/e2b-sdks.mdx
 create mode 100644 website/content/docs/lifecycle.mdx
 create mode 100644 website/content/docs/persistence.mdx

diff --git a/website/content/docs/architecture.mdx b/website/content/docs/architecture.mdx
new file mode 100644
index 0000000..fd482b1
--- /dev/null
+++ b/website/content/docs/architecture.mdx
@@ -0,0 +1,81 @@
+---
+title: Architecture & security
+description: One daemon keeping a SQLite ledger and Docker reality in agreement — and what the sandbox boundary actually is.
+---
+
+## The ledger and reality
+
+The mental model behind the whole daemon: **SQLite is the ledger, Docker
+is reality, and the daemon's core job is keeping the two in agreement.**
+
+- Reality moves first, then the ledger records it — a crash between the
+  two leaves a container without a row, never a row without a container,
+  and the reconciler cleans up the former.
+- A **reconciler** runs before the daemon starts listening (a failure
+  refuses startup) and again on every heartbeat: a container that died
+  behind the daemon's back is recorded stopped — its disk, and therefore
+  its data, kept; ownerless leftovers are swept.
+- The design is **crash-only**: there is no graceful-shutdown path to get
+  wrong. Kill the daemon at any moment; it reconciles on the way up.
+- **One machine, one daemon**, enforced rather than assumed: an exclusive
+  lock next to the ledger makes a second daemon refuse to start, and a
+  startup guard refuses to boot when the ledger and the machine's reality
+  cannot belong together (an empty ledger facing live sandboxes means a
+  wrong database path — starting anyway would destroy them all).
+
+There is deliberately no cluster mode, no external database, no queue.
+The ledger schema carries the fields sharding would need (node IDs,
+endpoints), but today the simplicity *is* the feature.
+
+## One sandbox = a gVisor container + a loop disk
+
+Each sandbox is a Docker container running under **gVisor** (`runsc`),
+with its `/home/user` on a dedicated loop-mounted disk image (see
+[The disk is the sandbox](/docs/persistence)). Every sandbox runs with
+the same non-negotiable parameters: non-root (uid 1000), `--init`,
+`no-new-privileges`, a pids limit, CPU and memory caps.
+
+Why gVisor and not VMs: freezing requires sandboxes to be **processes**
+(suspend them, squeeze their memory to swap), and "installs anywhere"
+rules out requiring KVM. Firecracker-class hardware virtualization is a
+different trade — see the last section.
+
+## The security boundary, honestly
+
+- **gVisor's userspace kernel is the boundary.** Sandbox code — even
+  running as `root` inside — talks to gVisor's reimplemented kernel, not
+  the host's. `uname -r` inside a sandbox reports a `-gvisor` kernel; the
+  host kernel is never exposed.
+- **Four red lines** hold everywhere:
+  1. The daemon binds to 127.0.0.1 only — by design without a knob.
+     Exposing anything is a reverse proxy's explicit job.
+  2. The Docker socket never enters a container.
+  3. Containers cannot reach the cloud metadata service (iptables) or
+     each other (`icc: false`).
+  4. Containers may vanish at any time; only the disk is the sandbox.
+- **Credentials never downgrade.** The API token must be 32+ characters
+  and is compared in constant time; the E2B surface derives per-sandbox
+  access tokens from it (HMAC, stateless); the web console trades it once
+  for an httpOnly session cookie and never stores it anywhere page
+  JavaScript can read.
+- **Sandbox preview URLs are deliberately unauthenticated** (the
+  `getHost()` port proxy, when `DORMICE_SANDBOX_DOMAIN` is set) — same as
+  E2B: they exist to be opened by humans and shared. Don't run a service
+  on a sandbox port unless you mean for the URL to work.
+
+## When Dormice is the wrong tool
+
+Pick something else if:
+
+- **You need a fleet.** One machine, one daemon, by design — that is
+  where the simplicity comes from. Multi-machine sharding is a future
+  direction (the schema already carries the fields), not a current
+  feature.
+- **You want a managed service.** No hosted anything, no SLA. That is
+  E2B's product, and it is good at it.
+- **Your threat model demands hardware virtualization.** Sandboxes are
+  Docker + gVisor — a userspace kernel, chosen deliberately: freezing
+  requires sandboxes to be processes, and "installs anywhere" rules out
+  requiring KVM. If only Firecracker-class VM isolation will do, this
+  trade is not for you.
+- **Your workloads aren't Linux.** Sandboxes are Linux containers.
diff --git a/website/content/docs/configuration.mdx b/website/content/docs/configuration.mdx
new file mode 100644
index 0000000..43c7e93
--- /dev/null
+++ b/website/content/docs/configuration.mdx
@@ -0,0 +1,84 @@
+---
+title: Configuration
+description: Every environment variable the daemon reads, with defaults — validated once at startup, failing loudly.
+---
+
+All daemon configuration comes from `DORMICE_*` environment variables,
+validated once at startup: a bad value refuses to boot with a named error
+instead of surfacing later as confusing runtime behavior. Everything has
+a default except the API token and, in docker mode, the base image.
+
+On a host set up by `install.sh`, the variables live in
+`/etc/dormice/env` (loaded by the systemd unit); edit the file and
+`systemctl restart dormice`.
+
+## Core
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `DORMICE_API_TOKEN` | — **(required)** | Bearer token for the native API, and (with an `e2b_` prefix) the E2B API key. At least 32 characters; generate with `openssl rand -hex 32`. Keep it hex: the official Python e2b SDK validates `e2b_[0-9a-f]+` client-side before any request leaves the machine. |
+| `DORMICE_PORT` | `3676` | The one port everything is served on: native API, E2B surface, web console. Always bound to 127.0.0.1 — there is deliberately no host knob. |
+| `DORMICE_DB_PATH` | `data/dormice.db` | Where the SQLite ledger lives. Must be an **absolute path** in docker mode — a relative path depends on the start directory, and a wrong start directory means an empty ledger facing real sandboxes. |
+| `DORMICE_NODE_ID` | `node-1` | Identifies this machine in the ledger. Single-machine today; the field keeps the ledger shardable later. |
+
+## Executor
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `DORMICE_EXECUTOR` | `fake` | What drives reality: `fake` is an in-memory executor so a bare `pnpm dev` works on any machine (development, tests); `docker` runs real gVisor sandboxes and needs a prepared Linux host — see [Installation](/docs/installation). |
+| `DORMICE_BASE_IMAGE` | — | The image sandboxes boot from. **Required in docker mode**; `install.sh` builds one and records it here. |
+| `DORMICE_DATA_DIR` | `/var/lib/dormice` | Sandbox disk images and their mount points (docker mode). Must be an absolute path in docker mode. |
+
+## Per-sandbox resources
+
+Applied when the container (or disk) is created, so existing sandboxes
+keep what they were born with. A rebuild replaces the container and picks
+up current CPU/memory/pids values — but keeps the disk, so a changed disk
+size only applies to new sandboxes and restores from archive.
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `DORMICE_SANDBOX_DISK_GB` | `10` | Size of each sandbox's disk image. The quota is physical — the file is simply that big — and sparse, so unwritten space costs nothing. |
+| `DORMICE_SANDBOX_CPUS` | `1` | CPU limit per sandbox. |
+| `DORMICE_SANDBOX_MEMORY_GB` | `2` | Memory cap per sandbox. A sandbox that hits it is killed as a whole by gVisor (exit 137) and parks at stopped — files intact, next acquire revives it. |
+| `DORMICE_SANDBOX_PIDS_LIMIT` | `512` | Fork-bomb ceiling per sandbox. |
+
+## Lifecycle engine
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `DORMICE_SCAN_INTERVAL_SECONDS` | `60` | How often the idle scanner sweeps the ledger. Each sweep demotes an idle sandbox at most one rung — see [Sandbox lifecycle](/docs/lifecycle). |
+| `DORMICE_MAX_SANDBOXES` | `100` | How many sandboxes may exist at once. Past the cap, *creation* answers an honest 429; wakes of existing sandboxes are never blocked. The binding resource is disk — a full host cannot even write its ledger. |
+| `DORMICE_RECLAIM_TIMEOUT_SECONDS` | `45` | Upper bound on the memory-reclaim step of a freeze. Hitting it is expected on stubborn tails, not a failure. |
+
+## Sandbox network
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `DORMICE_SANDBOX_DOMAIN` | — | The wildcard domain behind the E2B SDK's `getHost(port)`: set it (a bare hostname like `sbx.example.com`) and responses carry it, the SDK builds `<port>-<sandboxId>.<domain>` URLs, and requests arriving with such a `Host` header are proxied into the sandbox — frozen sandboxes wake on traffic. You point `*.<domain>` DNS plus a TLS-terminating reverse proxy at the daemon. Unset, the feature is honestly absent. |
+
+## Archiver (S3)
+
+The four core variables come as a set: with none of them, archiving is
+honestly absent — sandboxes park at stopped forever, and a policy asking
+to archive is refused. Set all four and stopped sandboxes take the last
+step down after 7 idle days (tunable per sandbox). A partial set refuses
+to boot, naming the missing variables.
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `DORMICE_S3_ENDPOINT` | — | Full URL including scheme (MinIO speaks http, the clouds https). Any S3-compatible store: AWS, Cloudflare R2, MinIO, Alibaba OSS in S3-compat mode. |
+| `DORMICE_S3_BUCKET` | — | The bucket. Must already exist. |
+| `DORMICE_S3_ACCESS_KEY_ID` | — | Credentials. |
+| `DORMICE_S3_SECRET_ACCESS_KEY` | — | Credentials. |
+| `DORMICE_S3_REGION` | `us-east-1` | Region, if your store cares. |
+| `DORMICE_S3_FORCE_PATH_STYLE` | `false` | Path-style addressing: MinIO needs `true`; the clouds route by subdomain. |
+
+## Client-side variables
+
+The `dor` CLI (and nothing else) reads two variables to find the daemon:
+
+| Variable | What it does |
+| --- | --- |
+| `DORMICE_ENDPOINT` | The daemon's base URL, e.g. `http://127.0.0.1:3676`. |
+| `DORMICE_API_TOKEN` | The same token the daemon was configured with. |
diff --git a/website/content/docs/e2b-compatibility.mdx b/website/content/docs/e2b-differences.mdx
similarity index 56%
rename from website/content/docs/e2b-compatibility.mdx
rename to website/content/docs/e2b-differences.mdx
index 0995820..3b499a4 100644
--- a/website/content/docs/e2b-compatibility.mdx
+++ b/website/content/docs/e2b-differences.mdx
@@ -1,25 +1,11 @@
 ---
-title: E2B compatibility
-description: The official e2b SDK runs against Dormice by changing two URLs.
+title: Capabilities & differences
+description: What of the E2B surface is implemented — verified through the official SDK — and where Dormice deliberately diverges.
 ---
 
-The daemon speaks the E2B protocol on two prefixes (`/e2b/api`,
-`/e2b/envd`). The **official `e2b` package** — unmodified, straight from
-npm — runs against Dormice with two URLs and an API-key prefix; migrating
-an application is configuration, not code:
-
-```ts
-import { Sandbox } from 'e2b';
-
-const sbx = await Sandbox.create({
-  apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`,
-  apiUrl: 'http://127.0.0.1:3676/e2b/api',
-  sandboxUrl: 'http://127.0.0.1:3676/e2b/envd',
-});
-```
-
 Everything below is exercised by the black-box e2e suite *through the
-official package*, and has passed against a real Docker + gVisor daemon:
+official `e2b` package*, and has passed against a real Docker + gVisor
+daemon:
 
 | Surface | Notes |
 | --- | --- |
@@ -34,20 +20,34 @@ official package*, and has passed against a real Docker + gVisor daemon:
 | `files.watchDir` | streamed events, and the polling watcher API the Python sync SDK uses |
 | `getHost(port)` | port proxy with wake-on-traffic (set `DORMICE_SANDBOX_DOMAIN`) |
 | `getMetrics()` | one live sample; observing never wakes a frozen sandbox |
+| Templates by name | `Sandbox.create('name')` resolves a registered template; an unregistered name is an honest 404 |
 
 ## Deliberate deltas from the hosted product
 
-- **No template builds.** Every sandbox runs the daemon's single base
-  image (`DORMICE_BASE_IMAGE`); the `template` argument is accepted and
-  ignored.
+- **No template builds.** Templates are named images: build one with
+  docker, register it with `dor template add`, and `Sandbox.create('name')`
+  resolves it. The hosted product's build pipeline (`e2b template build`)
+  is not implemented.
 - **Freezing keeps processes.** A frozen sandbox's processes suspend and
   resume mid-flight — any touch wakes the sandbox in ~50 ms.
 - **Permanence stays the default.** Sandboxes created through the E2B
-  surface get real deadlines, as E2B semantics demand; deadlines are never
-  imposed on natively created sandboxes.
+  surface get real deadlines, as E2B semantics demand; deadlines are
+  never imposed on natively created sandboxes.
 - **`metadata.userKey`** turns `Sandbox.create` into Dormice's idempotent
-  acquire: the same key returns the same sandbox instead of a new one.
-- **Not implemented**, answered with an honest `unimplemented` on the
-  wire: `Process/StreamInput` (the JS SDK never calls it) and xattr-based
-  file metadata. The daemon reports envd `0.6.1`, so the SDK itself gates
-  those features client-side.
+  acquire — see [Using the official E2B SDKs](/docs/e2b-sdks).
+- **One domain, not one subdomain per sandbox.** The SDK addresses
+  sandboxes through a header on a single endpoint, so no wildcard DNS is
+  needed for the API itself — only `getHost()` preview URLs want a
+  wildcard domain (`DORMICE_SANDBOX_DOMAIN`).
+
+## Not implemented
+
+Answered with an honest `unimplemented` on the wire, never silently
+swallowed:
+
+- `Process/StreamInput` (the JS SDK never calls it — `sendStdin` covers
+  the real path)
+- xattr-based file metadata
+
+The daemon reports envd `0.6.1`, so the SDK gates these client-side
+before they ever reach the wire.
diff --git a/website/content/docs/e2b-sdks.mdx b/website/content/docs/e2b-sdks.mdx
new file mode 100644
index 0000000..6e86238
--- /dev/null
+++ b/website/content/docs/e2b-sdks.mdx
@@ -0,0 +1,80 @@
+---
+title: Using the official E2B SDKs
+description: The official e2b packages — JavaScript and Python, unmodified — run against Dormice by changing two URLs.
+---
+
+The daemon speaks the E2B protocol on two prefixes (`/e2b/api` for the
+control plane, `/e2b/envd` for the in-sandbox surface). Point the official
+SDK at them and prefix your token with `e2b_` — migrating an application
+is configuration, not code. Everything documented here is exercised by
+black-box test suites *through the official packages* (e2b 2.31.0,
+JavaScript and Python) against a real Docker + gVisor daemon.
+
+## JavaScript
+
+```ts
+import { Sandbox } from 'e2b';
+
+const sbx = await Sandbox.create({
+  apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`,
+  apiUrl: 'http://127.0.0.1:3676/e2b/api',
+  sandboxUrl: 'http://127.0.0.1:3676/e2b/envd',
+});
+
+await sbx.commands.run('echo hello');
+```
+
+## Python
+
+Both the sync and the async client pass the suite:
+
+```python
+import os
+from e2b import Sandbox
+
+sandbox = Sandbox.create(
+    api_key=f"e2b_{os.environ['DORMICE_API_TOKEN']}",
+    api_url="http://127.0.0.1:3676/e2b/api",
+    sandbox_url="http://127.0.0.1:3676/e2b/envd",
+)
+
+sandbox.commands.run("echo hello")
+```
+
+One constraint worth knowing: **keep the API token hexadecimal**
+(`openssl rand -hex 32`, which is also what `install.sh` generates). The
+Python SDK validates its key against `e2b_[0-9a-f]+` client-side, before
+any request leaves the machine — a token with other characters fails in
+the SDK, not on the wire.
+
+## `metadata.userKey`: idempotent create
+
+A Dormice extension: pass `metadata: { userKey: '...' }` and
+`Sandbox.create` behaves like the native `acquireSandbox` — the same key
+always returns the same sandbox instead of a new one, whatever state it
+was in, with its files intact:
+
+```ts
+const sbx = await Sandbox.create({
+  metadata: { userKey: 'my-project' },
+  // ...the two URLs and apiKey as above
+});
+```
+
+Without it, `create` makes a fresh sandbox every time — faithful E2B
+semantics.
+
+## Timeouts are real
+
+`timeoutMs` and `setTimeout()` set an absolute deadline, exactly as E2B
+defines them: at the deadline the sandbox is killed, or — with
+`lifecycle: { onTimeout: 'pause' }` — parked, to be revived by `connect`.
+See [Sandbox lifecycle](/docs/lifecycle) for how deadlines interact with
+Dormice's own idle policy.
+
+## Version gating
+
+The daemon reports envd `0.6.1`, chosen so the SDK itself gates features
+client-side: everything at or below that version is implemented, and the
+few gaps above it are answered with an honest `unimplemented` on the wire
+— the full list is in [Capabilities & differences](/docs/e2b-differences).
diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdx
index c7c4906..f8566d9 100644
--- a/website/content/docs/index.mdx
+++ b/website/content/docs/index.mdx
@@ -18,8 +18,9 @@ keep the longer they sit idle.
   it takes ~50 ms.
 - **Deploys like a single binary.** One daemon, one SQLite ledger, one
   port. No Kubernetes, no external database.
-- **E2B compatible.** The official `e2b` SDK works against Dormice by
-  changing two URLs — see [E2B compatibility](/docs/e2b-compatibility).
+- **E2B compatible.** The official `e2b` SDKs — JavaScript and Python —
+  work against Dormice by changing two URLs — see
+  [Using the official E2B SDKs](/docs/e2b-sdks).
 
 ## How it works
 
diff --git a/website/content/docs/lifecycle.mdx b/website/content/docs/lifecycle.mdx
new file mode 100644
index 0000000..b6a47f4
--- /dev/null
+++ b/website/content/docs/lifecycle.mdx
@@ -0,0 +1,102 @@
+---
+title: Sandbox lifecycle
+description: Four states, three knobs — sandboxes cool down on their own, and any acquire brings them back.
+---
+
+A sandbox is always in one of four states. Idle time moves it down the
+ladder one rung at a time; `acquireSandbox` brings it back from any rung.
+The colder the state, the cheaper it is to keep — and the longer the wake.
+
+```text
+active ── idle ──▶ frozen ── idle ──▶ stopped ── idle ──▶ archived
+  ~full RAM         ~5 MiB RAM         disk only            S3 only
+                    wakes in ~50 ms    cold start (seconds)  restore (download)
+```
+
+- **active** — the container is running, normally.
+- **frozen** — every process is suspended mid-flight and its memory
+  squeezed out to swap. Measured on real hardware: an idle sandbox holding
+  1 GiB drops to about 5 MiB resident, and wakes in about 50 ms with all
+  its processes still running, exactly where they were.
+- **stopped** — the container is shut down; only the disk remains. Waking
+  is a cold start: a fresh boot from the surviving disk, seconds rather
+  than milliseconds. Processes do not survive this step — files do.
+- **archived** — the disk itself is packed with `tar` + `zstd` and shipped
+  to an S3-compatible bucket; nothing remains on the host. Only exists
+  when the archiver is configured (`DORMICE_S3_*`). Waking downloads and
+  unpacks; `acquireSandbox` reports `{ status: 'restoring', progress }`
+  immediately and flips to `ready` when the disk is back — a slow wake is
+  honest, never a silent hang.
+
+A background scanner sweeps the ledger every `DORMICE_SCAN_INTERVAL_SECONDS`
+(default 60) and demotes each idle sandbox at most one rung per sweep.
+
+## The three knobs
+
+Each sandbox carries a lifecycle policy — three thresholds, all counting
+seconds since the sandbox's last activity, all points on the same clock
+(hence the ordering rule freeze ≤ stop ≤ archive):
+
+| Knob | Default | `null` means |
+| --- | --- | --- |
+| `freezeAfterSeconds` | 10 minutes | — (freezing is always on) |
+| `stopAfterSeconds` | 3 days | never stop |
+| `archiveAfterSeconds` | 7 days when S3 is configured, otherwise never | never archive |
+
+Overrides are passed at acquire time and validated as a merged whole:
+
+```ts
+await client.acquireSandbox('my-agent', {
+  freezeAfterSeconds: 60,        // freeze aggressively
+  stopAfterSeconds: 7 * 86400,   // a week to cold storage
+});
+```
+
+Three rules worth knowing:
+
+- **Policy is fixed at creation.** An override sent while acquiring an
+  *existing* sandbox is not applied — the sandbox keeps the policy it was
+  born with. (An invalid override is still rejected with a 400.)
+- **Archiving requires stopping.** Only a stopped sandbox can archive, so
+  `archiveAfterSeconds` needs a non-null `stopAfterSeconds` — and on a
+  daemon with no S3 configured, a policy asking to archive is refused
+  outright rather than silently stored.
+- **Defaults yield to your explicit values.** Push `stopAfterSeconds`
+  past the 7-day archive default and the archive threshold follows it
+  instead of turning your legal override into an ordering error.
+
+## Resident agents: `stopAfterSeconds: null`
+
+The setting for a long-lived agent's sandbox:
+
+```ts
+await client.acquireSandbox('my-agent', { stopAfterSeconds: null });
+```
+
+It parks at **frozen** forever — memory in swap, a few MiB of RAM, ~50 ms
+from any touch — and never decays to a cold boot. Its processes are never
+killed by idleness; they suspend and resume mid-flight, indefinitely.
+
+## What counts as activity
+
+Running commands, file operations, and `acquireSandbox` reset the idle
+clock. A long-running command keeps its sandbox alive for as long as it
+runs.
+
+Observation deliberately does not count: `listSandboxes`, sandbox metrics,
+and the console's list and detail views never wake a frozen sandbox and
+never reset its clock. Watching is free — using is what keeps a sandbox
+warm.
+
+## E2B deadlines are a separate clock
+
+Sandboxes created through the [E2B surface](/docs/e2b-sdks) additionally
+carry an absolute deadline (`timeoutMs`), because E2B semantics demand
+one: at the deadline the sandbox is killed — or parked, with
+`lifecycle: { onTimeout: 'pause' }`. Activity does not extend a deadline;
+only `create`, `connect`, and `setTimeout()` do. The deadline rule runs
+before the idle rules above.
+
+Natively created sandboxes never get a deadline — permanence is the
+native default, and the E2B compatibility layer never imposes deadlines
+on sandboxes it does not own.
diff --git a/website/content/docs/meta.json b/website/content/docs/meta.json
index 6da52f8..7dcf126 100644
--- a/website/content/docs/meta.json
+++ b/website/content/docs/meta.json
@@ -1,3 +1,20 @@
 {
-  "pages": ["index", "installation", "quickstart", "e2b-compatibility"]
+  "groups": [
+    {
+      "title": "Getting started",
+      "pages": ["index", "installation", "quickstart"]
+    },
+    {
+      "title": "Concepts",
+      "pages": ["lifecycle", "persistence", "architecture"]
+    },
+    {
+      "title": "E2B compatibility",
+      "pages": ["e2b-sdks", "e2b-differences"]
+    },
+    {
+      "title": "Reference",
+      "pages": ["configuration"]
+    }
+  ]
 }
diff --git a/website/content/docs/persistence.mdx b/website/content/docs/persistence.mdx
new file mode 100644
index 0000000..a718fd5
--- /dev/null
+++ b/website/content/docs/persistence.mdx
@@ -0,0 +1,70 @@
+---
+title: The disk is the sandbox
+description: /home/user lives on its own disk, and that disk — not the container — is what Dormice keeps alive.
+---
+
+Every sandbox owns a disk: a sparse image file on the host
+(`DORMICE_SANDBOX_DISK_GB`, default 10 GB), formatted ext4 and mounted at
+`/home/user`. The container around it is a shell — replaceable machinery.
+That gives Dormice one contract worth memorizing:
+
+> **What lives in `/home/user` survives everything short of an explicit
+> release. Everything outside it is container state, and containers may
+> vanish at any time.**
+
+## What survives
+
+All of these are exercised by the test suite against a real Docker +
+gVisor host:
+
+- **Freeze / stop / wake cycles** — files ride through every lifecycle
+  transition.
+- **The daemon restarting, the host rebooting** — the daemon reconciles
+  its ledger against reality at boot, and the next wake re-attaches the
+  disk (a reboot drops loop mounts; starting a sandbox repairs its own).
+- **`docker container prune`** eating the container object — a stopped
+  sandbox is an exited container plus a disk, and prune eats exited
+  containers. The next acquire rebuilds a container *from the surviving
+  disk*: same sandbox ID, `/home/user` intact.
+- **Out-of-memory** — a sandbox that hits its memory cap
+  (`DORMICE_SANDBOX_MEMORY_GB`, default 2 GB) is killed as a whole by
+  gVisor, exit code 137. The reconciler records it stopped; the same key
+  acquires it right back, files intact.
+- **Archive → restore** — the disk round-trips through S3 as a
+  `tar.zst` and comes back byte-for-byte.
+
+## What does not
+
+- **`releaseSandbox`** — the only verb that loses data, by design.
+- **Everything outside `/home/user`** whenever the container is replaced
+  (rebuild, prune, OOM): `/tmp`, packages installed at runtime outside the
+  home directory, running processes. If it matters, keep it in
+  `/home/user`.
+
+## The quota is physical
+
+The disk file is simply that big. A sandbox that fills its disk gets
+`ENOSPC` from its own filesystem — there is no accounting layer to game,
+and the host's disk stays healthy. The image is sparse: a 10 GB promise
+occupies only what has actually been written, so disk is overcommitted by
+default and `getHostMetrics` reports both the promised and the real total.
+
+## Rebuild: new shell, same body
+
+`rebuildSandbox` (SDK), `dor sandbox rebuild` (CLI), or the Rebuild button
+in the console tears the container down — in any state — and keeps the
+disk. The next wake builds a fresh container from the daemon's *current*
+base image (or the sandbox's template's current image), with `/home/user`
+carried over untouched.
+
+That makes rebuild the upgrade path: update the image, re-register the
+template, rebuild the sandbox — its files never move. Rebuild deliberately
+does not wake the sandbox afterwards; the cold start bills to whoever
+actually comes back for it.
+
+## Restore is also an upgrade
+
+An archived sandbox's restore builds a **new** disk at the current
+`DORMICE_SANDBOX_DISK_GB` and unpacks into it, then boots from the current
+image. Grow the disk setting while a sandbox sits in the bucket and it
+comes back bigger — for free.
diff --git a/website/src/app/docs/layout.tsx b/website/src/app/docs/layout.tsx
index db939fe..1bec24c 100644
--- a/website/src/app/docs/layout.tsx
+++ b/website/src/app/docs/layout.tsx
@@ -6,10 +6,16 @@ import {
   SidebarContent,
   SidebarProvider,
 } from '@/components/ui/sidebar';
-import { docs } from '@/lib/docs';
+import { docGroups } from '@/lib/docs';
 
 export default function Layout({ children }: { children: ReactNode }) {
-  const items = docs.map(({ href, title }) => ({ href, title }));
+  const groups = docGroups.map((group) => ({
+    title: group.title,
+    items: group.entries.map((entry) => ({
+      href: entry.href,
+      title: entry.title,
+    })),
+  }));
 
   return (
     // The provider defaults to a full-viewport app shell (min-h-svh); this
@@ -20,12 +26,12 @@ export default function Layout({ children }: { children: ReactNode }) {
         className="sticky top-14 hidden h-[calc(100svh-3.5rem)] w-52 shrink-0 self-start border-r bg-transparent md:flex"
       >
         <SidebarContent className="py-4">
-          <DocsSidebar items={items} />
+          <DocsSidebar groups={groups} />
         </SidebarContent>
       </Sidebar>
       <div className="min-w-0 flex-1 md:pl-8">
         <div className="border-b py-3 md:hidden">
-          <DocsMobileNav items={items} />
+          <DocsMobileNav groups={groups} />
         </div>
         {children}
       </div>
diff --git a/website/src/app/layout.tsx b/website/src/app/layout.tsx
index 8ddf795..94f01fa 100644
--- a/website/src/app/layout.tsx
+++ b/website/src/app/layout.tsx
@@ -3,7 +3,7 @@ import type { ReactNode } from 'react';
 import { SiteFooter } from '@/components/SiteFooter';
 import { SiteHeader } from '@/components/SiteHeader';
 import { ThemeProvider } from '@/components/ThemeProvider';
-import { docs } from '@/lib/docs';
+import { docGroups } from '@/lib/docs';
 import { SITE_DESCRIPTION, SITE_TITLE } from '@/lib/site';
 import './global.css';
 
@@ -16,17 +16,20 @@ export const metadata: Metadata = {
 };
 
 export default function Layout({ children }: { children: ReactNode }) {
-  const searchItems = docs.map(({ href, title, description }) => ({
-    href,
-    title,
-    description,
+  const searchGroups = docGroups.map((group) => ({
+    title: group.title,
+    items: group.entries.map(({ href, title, description }) => ({
+      href,
+      title,
+      description,
+    })),
   }));
 
   return (
     <html lang="en" suppressHydrationWarning>
       <body className="flex min-h-screen flex-col antialiased">
         <ThemeProvider>
-          <SiteHeader searchItems={searchItems} />
+          <SiteHeader searchGroups={searchGroups} />
           {children}
           <SiteFooter />
         </ThemeProvider>
diff --git a/website/src/components/SiteHeader.tsx b/website/src/components/SiteHeader.tsx
index 4fd7a9a..49f23dd 100644
--- a/website/src/components/SiteHeader.tsx
+++ b/website/src/components/SiteHeader.tsx
@@ -1,12 +1,12 @@
 import { GithubIcon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
 import Link from 'next/link';
-import { DocsSearch, type SearchItem } from '@/components/docs/DocsSearch';
+import { DocsSearch, type SearchGroup } from '@/components/docs/DocsSearch';
 import { ThemeToggle } from '@/components/ThemeToggle';
 import { Button } from '@/components/ui/button';
 import { GITHUB_URL } from '@/lib/site';
 
-export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
+export function SiteHeader({ searchGroups }: { searchGroups: SearchGroup[] }) {
   return (
     <header className="sticky top-0 z-40 border-b bg-background/80 backdrop-blur">
       <div className="mx-auto flex h-14 w-full max-w-6xl items-center px-4">
@@ -25,7 +25,7 @@ export function SiteHeader({ searchItems }: { searchItems: SearchItem[] }) {
           </Button>
         </nav>
         <div className="ml-auto flex items-center gap-1">
-          <DocsSearch items={searchItems} />
+          <DocsSearch groups={searchGroups} />
           <Button
             variant="ghost"
             size="icon"
diff --git a/website/src/components/docs/DocsMobileNav.tsx b/website/src/components/docs/DocsMobileNav.tsx
index 1921cf6..44e3f39 100644
--- a/website/src/components/docs/DocsMobileNav.tsx
+++ b/website/src/components/docs/DocsMobileNav.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { useState } from 'react';
-import { type DocsNavItem, DocsSidebar } from '@/components/docs/DocsSidebar';
+import { type DocsNavGroup, DocsSidebar } from '@/components/docs/DocsSidebar';
 import { Button } from '@/components/ui/button';
 import {
   Sheet,
@@ -11,7 +11,7 @@ import {
   SheetTrigger,
 } from '@/components/ui/sheet';
 
-export function DocsMobileNav({ items }: { items: DocsNavItem[] }) {
+export function DocsMobileNav({ groups }: { groups: DocsNavGroup[] }) {
   const [open, setOpen] = useState(false);
 
   return (
@@ -20,12 +20,12 @@ export function DocsMobileNav({ items }: { items: DocsNavItem[] }) {
         Menu
       </SheetTrigger>
       <SheetContent side="left">
-        {/* The visible label comes from the menu's own group label. */}
+        {/* The visible labels come from the menu's own group labels. */}
         <SheetHeader className="sr-only">
           <SheetTitle>Documentation</SheetTitle>
         </SheetHeader>
-        <div className="px-2">
-          <DocsSidebar items={items} onNavigate={() => setOpen(false)} />
+        <div className="overflow-y-auto px-2">
+          <DocsSidebar groups={groups} onNavigate={() => setOpen(false)} />
         </div>
       </SheetContent>
     </Sheet>
diff --git a/website/src/components/docs/DocsSearch.tsx b/website/src/components/docs/DocsSearch.tsx
index e432df0..0f91d7c 100644
--- a/website/src/components/docs/DocsSearch.tsx
+++ b/website/src/components/docs/DocsSearch.tsx
@@ -19,10 +19,15 @@ export interface SearchItem {
   description: string;
 }
 
+export interface SearchGroup {
+  title: string;
+  items: SearchItem[];
+}
+
 // Search over doc titles and descriptions, fully client-side — the honest
 // size for a docs set this small. Grow it into a real text index when the
 // page count earns it.
-export function DocsSearch({ items }: { items: SearchItem[] }) {
+export function DocsSearch({ groups }: { groups: SearchGroup[] }) {
   const [open, setOpen] = useState(false);
   const router = useRouter();
 
@@ -57,25 +62,27 @@ export function DocsSearch({ items }: { items: SearchItem[] }) {
         <CommandInput placeholder="Search documentation…" />
         <CommandList>
           <CommandEmpty>No results found.</CommandEmpty>
-          <CommandGroup heading="Documentation">
-            {items.map((item) => (
-              <CommandItem
-                key={item.href}
-                value={`${item.title} ${item.description}`}
-                onSelect={() => {
-                  setOpen(false);
-                  router.push(item.href);
-                }}
-              >
-                <div className="flex flex-col gap-0.5">
-                  <span>{item.title}</span>
-                  <span className="text-xs text-muted-foreground">
-                    {item.description}
-                  </span>
-                </div>
-              </CommandItem>
-            ))}
-          </CommandGroup>
+          {groups.map((group) => (
+            <CommandGroup key={group.title} heading={group.title}>
+              {group.items.map((item) => (
+                <CommandItem
+                  key={item.href}
+                  value={`${item.title} ${item.description}`}
+                  onSelect={() => {
+                    setOpen(false);
+                    router.push(item.href);
+                  }}
+                >
+                  <div className="flex flex-col gap-0.5">
+                    <span>{item.title}</span>
+                    <span className="text-xs text-muted-foreground">
+                      {item.description}
+                    </span>
+                  </div>
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          ))}
         </CommandList>
       </CommandDialog>
     </>
diff --git a/website/src/components/docs/DocsSidebar.tsx b/website/src/components/docs/DocsSidebar.tsx
index 8edd3dd..7d833fd 100644
--- a/website/src/components/docs/DocsSidebar.tsx
+++ b/website/src/components/docs/DocsSidebar.tsx
@@ -16,34 +16,43 @@ export interface DocsNavItem {
   title: string;
 }
 
+export interface DocsNavGroup {
+  title: string;
+  items: DocsNavItem[];
+}
+
 // Menu content only — it must live inside a <SidebarProvider> (the docs
 // layout provides one; the mobile Sheet sits inside the same provider).
 export function DocsSidebar({
-  items,
+  groups,
   onNavigate,
 }: {
-  items: DocsNavItem[];
+  groups: DocsNavGroup[];
   onNavigate?: () => void;
 }) {
   const pathname = usePathname();
 
   return (
-    <SidebarGroup>
-      <SidebarGroupLabel>Documentation</SidebarGroupLabel>
-      <SidebarGroupContent>
-        <SidebarMenu>
-          {items.map((item) => (
-            <SidebarMenuItem key={item.href}>
-              <SidebarMenuButton
-                isActive={pathname === item.href}
-                render={<Link href={item.href} onClick={onNavigate} />}
-              >
-                {item.title}
-              </SidebarMenuButton>
-            </SidebarMenuItem>
-          ))}
-        </SidebarMenu>
-      </SidebarGroupContent>
-    </SidebarGroup>
+    <>
+      {groups.map((group) => (
+        <SidebarGroup key={group.title}>
+          <SidebarGroupLabel>{group.title}</SidebarGroupLabel>
+          <SidebarGroupContent>
+            <SidebarMenu>
+              {group.items.map((item) => (
+                <SidebarMenuItem key={item.href}>
+                  <SidebarMenuButton
+                    isActive={pathname === item.href}
+                    render={<Link href={item.href} onClick={onNavigate} />}
+                  >
+                    {item.title}
+                  </SidebarMenuButton>
+                </SidebarMenuItem>
+              ))}
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+      ))}
+    </>
   );
 }
diff --git a/website/src/lib/docs.ts b/website/src/lib/docs.ts
index 9d98373..caeff1e 100644
--- a/website/src/lib/docs.ts
+++ b/website/src/lib/docs.ts
@@ -2,16 +2,21 @@ import type { MDXProps } from 'mdx/types';
 import type { JSX } from 'react';
 // Relative imports: content/ lives beside src/ on purpose — it is authored
 // content, not source, and stays portable across doc-shell rewrites.
-import * as e2bCompatibility from '../../content/docs/e2b-compatibility.mdx';
+import * as architecture from '../../content/docs/architecture.mdx';
+import * as configuration from '../../content/docs/configuration.mdx';
+import * as e2bDifferences from '../../content/docs/e2b-differences.mdx';
+import * as e2bSdks from '../../content/docs/e2b-sdks.mdx';
 import * as indexDoc from '../../content/docs/index.mdx';
 import * as installation from '../../content/docs/installation.mdx';
+import * as lifecycle from '../../content/docs/lifecycle.mdx';
 import meta from '../../content/docs/meta.json';
+import * as persistence from '../../content/docs/persistence.mdx';
 import * as quickstart from '../../content/docs/quickstart.mdx';
 
 // Server-only registry of every doc. MDX renders as server components, so
 // importing them all here costs the client nothing — pages ship as HTML.
-// meta.json stays the single decision point for order; the assertions below
-// fail the build when the two drift.
+// meta.json stays the single decision point for grouping and order; the
+// assertions below fail the build when the two drift.
 
 interface DocModule {
   frontmatter: { title: string; description: string };
@@ -23,7 +28,12 @@ const modules: Record<string, DocModule> = {
   index: indexDoc,
   installation,
   quickstart,
-  'e2b-compatibility': e2bCompatibility,
+  lifecycle,
+  persistence,
+  architecture,
+  'e2b-sdks': e2bSdks,
+  'e2b-differences': e2bDifferences,
+  configuration,
 };
 
 export interface DocEntry {
@@ -34,24 +44,36 @@ export interface DocEntry {
   description: string;
 }
 
-export const docs: DocEntry[] = meta.pages.map((name) => {
-  const mod = modules[name];
-  if (!mod) {
-    throw new Error(
-      `content/docs/meta.json lists "${name}" but src/lib/docs.ts does not import it`,
-    );
-  }
-  const slug = name === 'index' ? '' : name;
-  return {
-    slug,
-    href: slug === '' ? '/docs' : `/docs/${slug}`,
-    title: mod.frontmatter.title,
-    description: mod.frontmatter.description,
-  };
-});
+export interface DocGroup {
+  title: string;
+  entries: DocEntry[];
+}
+
+export const docGroups: DocGroup[] = meta.groups.map((group) => ({
+  title: group.title,
+  entries: group.pages.map((name) => {
+    const mod = modules[name];
+    if (!mod) {
+      throw new Error(
+        `content/docs/meta.json lists "${name}" but src/lib/docs.ts does not import it`,
+      );
+    }
+    const slug = name === 'index' ? '' : name;
+    return {
+      slug,
+      href: slug === '' ? '/docs' : `/docs/${slug}`,
+      title: mod.frontmatter.title,
+      description: mod.frontmatter.description,
+    };
+  }),
+}));
+
+// Flat, in sidebar order. Groups exist only in the sidebar — URLs stay flat
+// and prev/next pagination walks straight across group boundaries.
+export const docs: DocEntry[] = docGroups.flatMap((group) => group.entries);
 
 for (const name of Object.keys(modules)) {
-  if (!meta.pages.includes(name)) {
+  if (!meta.groups.some((group) => group.pages.includes(name))) {
     throw new Error(
       `src/lib/docs.ts imports "${name}" but content/docs/meta.json does not list it`,
     );

From 381dcbb23d42d1dbf10dcd374e21c3f6359bc357 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 11 Jul 2026 12:48:21 +0800
Subject: [PATCH 051/133] Runnable examples: native lifecycle, official e2b
 package, resident agent

Examples are the part of the facade a stranger actually executes. They are
plain .mjs so node runs them with zero build step, and they join the
workspace with checkJs typechecking, so an example that drifts from the SDK
fails CI instead of rotting silently. Also fixes the acquire snippets that
still showed the pre-template acquireSandbox signature, and brings the SDK
README's method table up to the real surface.
---
 README.md                     |  6 ++--
 examples/README.md            | 48 ++++++++++++++++++++++++++++++++
 examples/e2b-compat.mjs       | 47 +++++++++++++++++++++++++++++++
 examples/native-lifecycle.mjs | 52 +++++++++++++++++++++++++++++++++++
 examples/package.json         | 15 ++++++++++
 examples/resident-agent.mjs   | 44 +++++++++++++++++++++++++++++
 examples/tsconfig.json        | 11 ++++++++
 packages/sdk/README.md        |  8 ++++--
 pnpm-lock.yaml                |  9 ++++++
 pnpm-workspace.yaml           |  4 ++-
 10 files changed, 239 insertions(+), 5 deletions(-)
 create mode 100644 examples/README.md
 create mode 100644 examples/e2b-compat.mjs
 create mode 100644 examples/native-lifecycle.mjs
 create mode 100644 examples/package.json
 create mode 100644 examples/resident-agent.mjs
 create mode 100644 examples/tsconfig.json

diff --git a/README.md b/README.md
index 8f7aab2..8fd4937 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,7 @@ const client = new Dormice({
 // One key, one sandbox — created, woken or restarted as needed.
 // stopAfterSeconds: null makes it a resident agent: it may freeze when
 // idle (~50 ms to wake) but never cold-starts.
-await client.acquireSandbox('my-agent', { stopAfterSeconds: null });
+await client.acquireSandbox('my-agent', { policy: { stopAfterSeconds: null } });
 
 const result = await client.execCommand('my-agent', 'python3 -c "print(6 * 7)"');
 console.log(result.exitCode, result.stdout); // 0 42
@@ -63,7 +63,8 @@ The wire is plain HTTP RPC (`POST /acquireSandbox`, `POST /execCommand`, …),
 so `curl` works where the SDK doesn't reach, and the `dor` CLI covers the
 operator side: `dor sandbox ls / exec / push / pull / rebuild / release`,
 plus `dor doctor`. The full native surface is documented in
-[`packages/sdk`](packages/sdk/README.md).
+[`packages/sdk`](packages/sdk/README.md), and runnable versions of these
+flows live in [`examples/`](examples/).
 
 ## E2B compatibility
 
@@ -228,6 +229,7 @@ pnpm monorepo:
 | `packages/cli` | `dormice` command-line tool (`dor` for short) |
 | `packages/console` | Web console: React SPA, served by the daemon at `/console` |
 | `e2e` | Black-box suite: boots the built daemon, drives it over the wire |
+| `examples` | Runnable demos: the native SDK, the official `e2b` package, a resident agent |
 
 ## Development
 
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..69f3d57
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,48 @@
+# Examples
+
+Small, runnable programs against a live Dormice daemon. Each file is
+self-contained — read it top to bottom, then run it.
+
+| File | What it shows |
+| --- | --- |
+| [`native-lifecycle.mjs`](native-lifecycle.mjs) | The native SDK end to end: idempotent `acquireSandbox`, command execution, file I/O, `releaseSandbox` |
+| [`e2b-compat.mjs`](e2b-compat.mjs) | The **official `e2b` package**, unmodified, pointed at Dormice by two URLs — with live output streaming |
+| [`resident-agent.mjs`](resident-agent.mjs) | A permanent per-agent sandbox (`stopAfterSeconds: null`): run it repeatedly, its state survives |
+
+## Prerequisites
+
+A running daemon with the docker executor — a host prepared by
+[`install.sh`](../deploy/install.sh) is exactly right. The examples speak to
+it through the same two environment variables the `dor` CLI uses:
+
+```sh
+export DORMICE_ENDPOINT=http://127.0.0.1:3676   # the default; omit when local
+export DORMICE_API_TOKEN=...                    # /etc/dormice/env on the host
+```
+
+The daemon binds to 127.0.0.1 only. To run the examples from your laptop
+against a remote host, open a tunnel first and keep the default endpoint:
+
+```sh
+ssh -L 3676:127.0.0.1:3676 root@your-host
+```
+
+## Running
+
+From the repository root (`@dormice/sdk` is not on npm yet, so the examples
+link against the local build):
+
+```sh
+pnpm install
+pnpm build
+node examples/native-lifecycle.mjs
+node examples/e2b-compat.mjs
+node examples/resident-agent.mjs   # leaves its sandbox behind — that is the point
+```
+
+In your own project, once the packages are published, the same code runs
+after `npm install @dormice/sdk e2b`.
+
+`resident-agent.mjs` deliberately leaves its sandbox running; when you are
+done playing, remove it with `dor sandbox release example-resident-agent`
+(or `releaseSandbox` from the SDK).
diff --git a/examples/e2b-compat.mjs b/examples/e2b-compat.mjs
new file mode 100644
index 0000000..ba6f6b6
--- /dev/null
+++ b/examples/e2b-compat.mjs
@@ -0,0 +1,47 @@
+// The official `e2b` package from npm, unmodified, pointed at Dormice by two
+// URLs and an API-key prefix — migrating an E2B application is configuration,
+// not code.
+//
+//   DORMICE_API_TOKEN=... node examples/e2b-compat.mjs
+import { Sandbox } from 'e2b';
+
+const endpoint = process.env.DORMICE_ENDPOINT ?? 'http://127.0.0.1:3676';
+const token = process.env.DORMICE_API_TOKEN;
+if (!token) {
+  console.error(
+    'Set DORMICE_API_TOKEN (it is in /etc/dormice/env on an install.sh host).',
+  );
+  process.exit(1);
+}
+
+const sbx = await Sandbox.create({
+  apiKey: `e2b_${token}`,
+  apiUrl: `${endpoint}/e2b/api`,
+  sandboxUrl: `${endpoint}/e2b/envd`,
+  // E2B semantics hold: this is a real deadline, and this sandbox really is
+  // killed when it expires. (Sandboxes made through the native API never get
+  // a deadline — there, permanence is the default.)
+  timeoutMs: 120_000,
+});
+console.log(`created ${sbx.sandboxId}`);
+
+try {
+  // Output streams live, frame by frame — not one lump when the command ends.
+  await sbx.commands.run('for i in 1 2 3; do echo tick $i; sleep 1; done', {
+    onStdout: (data) => {
+      process.stdout.write(data);
+    },
+  });
+
+  await sbx.files.write('/home/user/hello.txt', 'through the official SDK\n');
+  const text = await sbx.files.read('/home/user/hello.txt');
+  console.log(`read back: ${text.trimEnd()}`);
+} finally {
+  await sbx.kill();
+  console.log('killed');
+}
+
+// Dormice extension worth knowing: Sandbox.create({ metadata: { userKey } })
+// makes create idempotent — the same key returns the same sandbox instead of
+// a new one, which is how an E2B application picks up permanent sandboxes
+// without leaving the e2b package.
diff --git a/examples/native-lifecycle.mjs b/examples/native-lifecycle.mjs
new file mode 100644
index 0000000..f8bdc2b
--- /dev/null
+++ b/examples/native-lifecycle.mjs
@@ -0,0 +1,52 @@
+// The whole native surface in one pass: acquire → exec → files → release.
+//
+// From the repository root, against a daemon installed with install.sh:
+//   pnpm install && pnpm build
+//   DORMICE_API_TOKEN=... node examples/native-lifecycle.mjs
+import { Dormice } from '@dormice/sdk';
+
+const endpoint = process.env.DORMICE_ENDPOINT ?? 'http://127.0.0.1:3676';
+const token = process.env.DORMICE_API_TOKEN;
+if (!token) {
+  console.error(
+    'Set DORMICE_API_TOKEN (it is in /etc/dormice/env on an install.sh host).',
+  );
+  process.exit(1);
+}
+
+const client = new Dormice({ endpoint, token });
+const key = 'example-lifecycle';
+
+// acquire() is the single entry point, idempotent on a key you choose:
+// no sandbox → create, frozen → wake, stopped → restart, archived → restore.
+const { sandbox } = await client.acquireSandbox(key);
+console.log(`acquired ${sandbox.sandboxId} (${sandbox.state})`);
+
+// Real code execution. `uname -r` names gVisor's userspace kernel — proof
+// the command did not run on your host.
+const result = await client.execCommand(
+  key,
+  'python3 -c "print(6 * 7)" && uname -r',
+);
+console.log(result.stdout.trimEnd());
+
+// A nonzero exit is a result, not an exception.
+const failed = await client.execCommand(key, 'exit 3');
+console.log(`'exit 3' exited with ${failed.exitCode}`);
+
+// Files go in and out; relative paths resolve against /home/user.
+await client.writeFiles(key, [
+  { path: 'hello.txt', content: 'written through the SDK\n' },
+]);
+const file = await client.readFile(key, 'hello.txt');
+console.log(`read back: ${new TextDecoder().decode(file.content).trimEnd()}`);
+
+// The same key always answers with the same sandbox.
+const again = await client.acquireSandbox(key);
+console.log(
+  `same sandbox on re-acquire: ${again.sandbox.sandboxId === sandbox.sandboxId}`,
+);
+
+// release() destroys container and disk — the only verb that loses data.
+await client.releaseSandbox(key);
+console.log('released');
diff --git a/examples/package.json b/examples/package.json
new file mode 100644
index 0000000..02247b1
--- /dev/null
+++ b/examples/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "@dormice/examples",
+  "version": "0.0.0",
+  "description": "Runnable examples: the native SDK, the official e2b package, a resident agent",
+  "license": "Apache-2.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@dormice/sdk": "workspace:*",
+    "e2b": "^2.31.0"
+  }
+}
diff --git a/examples/resident-agent.mjs b/examples/resident-agent.mjs
new file mode 100644
index 0000000..92b2c95
--- /dev/null
+++ b/examples/resident-agent.mjs
@@ -0,0 +1,44 @@
+// A resident agent: one sandbox per agent, kept forever. Run this file
+// several times — the journal grows; nothing is ever re-created.
+//
+// `stopAfterSeconds: null` pins the sandbox to the top two rungs of the
+// lifecycle: idle, it freezes (measured: ~1 GiB of resident memory squeezed
+// to ~5 MiB) and any touch wakes it in ~50 ms — it never decays to a
+// seconds-long cold start. Idle cost is a few MiB of swap and a sparse disk.
+//
+//   DORMICE_API_TOKEN=... node examples/resident-agent.mjs
+import { Dormice } from '@dormice/sdk';
+
+const endpoint = process.env.DORMICE_ENDPOINT ?? 'http://127.0.0.1:3676';
+const token = process.env.DORMICE_API_TOKEN;
+if (!token) {
+  console.error(
+    'Set DORMICE_API_TOKEN (it is in /etc/dormice/env on an install.sh host).',
+  );
+  process.exit(1);
+}
+
+const client = new Dormice({ endpoint, token });
+const key = 'example-resident-agent';
+
+// The policy applies when this acquire creates the sandbox; every later run
+// just comes back to it.
+const { sandbox } = await client.acquireSandbox(key, {
+  policy: { stopAfterSeconds: null },
+});
+console.log(
+  `${sandbox.sandboxId} — ${sandbox.state}, created ${sandbox.createdAt}`,
+);
+
+// State lives on the sandbox's disk, not in this script: every visit appends
+// to the same journal.
+const visit = await client.execCommand(
+  key,
+  'echo "$(date -u +%FT%TZ) visited" >> journal.txt && cat journal.txt',
+);
+console.log(visit.stdout.trimEnd());
+
+// Deliberately NOT released — a resident agent's sandbox outlives every run
+// of this script. When you are done playing:
+//   dor sandbox release example-resident-agent
+console.log('\nleft running; the journal will still be here tomorrow.');
diff --git a/examples/tsconfig.json b/examples/tsconfig.json
new file mode 100644
index 0000000..34b4f08
--- /dev/null
+++ b/examples/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    // The examples are plain .mjs so `node <file>` runs them with zero build
+    // step; checkJs keeps them honest in CI — an example that drifts from the
+    // SDK fails typecheck instead of rotting silently.
+    "allowJs": true,
+    "checkJs": true
+  },
+  "include": ["*.mjs"]
+}
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index 94fe0e0..492a92e 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -45,13 +45,17 @@ lifecycle policy is set at creation: `freezeAfterSeconds`, `stopAfterSeconds`
 
 | Method | What it does |
 | --- | --- |
-| `acquireSandbox(userKey, policy?)` | Create or wake the sandbox behind a key (idempotent) |
+| `acquireSandbox(userKey, { policy?, template? })` | Create or wake the sandbox behind a key (idempotent); both options apply only when this call creates it |
 | `listSandboxes()` | Every sandbox with its current lifecycle state |
 | `execCommand(userKey, command, opts?)` | Run a shell command; buffered stdout/stderr and the real exit code |
 | `writeFiles(userKey, files)` | Write files onto the sandbox disk (relative paths land under `/home/user`) |
 | `readFile(userKey, path)` | Read a file back as bytes |
-| `rebuildSandbox(userKey)` | Swap the container, keep `/home/user` — next use starts on the daemon's current base image |
+| `rebuildSandbox(userKey)` | Swap the container, keep `/home/user` — next use starts on the current image of its template (or the base image) |
 | `releaseSandbox(userKey)` | Destroy the sandbox (idempotent) |
+| `registerTemplate(name, image)` | Name a Docker image on the host as a template (an upsert — re-register to upgrade) |
+| `listTemplates()` | Every registered template |
+| `removeTemplate(name)` | Remove a template's registration; refused (409) while sandboxes use it |
+| `getHostMetrics()` | One snapshot of the host: CPU, memory, swap, data disk, sandbox disks, ledger totals |
 
 A non-zero exit code is a result, not an error. API failures throw
 `DormiceApiError` carrying the HTTP status and the daemon's message.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2e2ea7e..6e88801 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -40,6 +40,15 @@ importers:
         specifier: workspace:*
         version: link:../packages/server
 
+  examples:
+    dependencies:
+      '@dormice/sdk':
+        specifier: workspace:*
+        version: link:../packages/sdk
+      e2b:
+        specifier: ^2.31.0
+        version: 2.31.0
+
   packages/cli:
     dependencies:
       '@dormice/sdk':
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 557d18a..17259cc 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,10 +1,12 @@
 # Workspace members: every directory under packages/ is a package; e2e is its
 # own package — the black-box suite that boots the built daemon and drives it
 # over the wire (the E2B compatibility suite will join it when that layer lands);
-# website is the public site (Next.js static export), never published to npm
+# examples holds runnable demos linked against the local build; website is the
+# public site (Next.js static export). Neither is ever published to npm
 packages:
   - packages/*
   - e2e
+  - examples
   - website
 
 # Supply-chain defense: a newly published npm version must be at least 24 hours

From d82a0c76fcaf408aa840b2dc4d0b967ca381110a Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 11 Jul 2026 13:11:55 +0800
Subject: [PATCH 052/133] A Guides chapter joins the docs: commands, files,
 templates, resident agents, ports, archiving, metrics

Every claim traced to source before writing: schema field names, SDK
signatures, CLI flags, the stock image's Dockerfile. Also fixes three
acquireSandbox snippets in lifecycle/quickstart that still showed the
pre-template flat-knobs signature (README's copy was fixed in 381dcbb;
the website copies were missed).
---
 website/content/docs/archiving.mdx       | 82 +++++++++++++++++++++++
 website/content/docs/commands.mdx        | 83 ++++++++++++++++++++++++
 website/content/docs/files.mdx           | 66 +++++++++++++++++++
 website/content/docs/lifecycle.mdx       |  8 ++-
 website/content/docs/meta.json           | 12 ++++
 website/content/docs/metrics.mdx         | 72 ++++++++++++++++++++
 website/content/docs/ports.mdx           | 69 ++++++++++++++++++++
 website/content/docs/quickstart.mdx      |  2 +-
 website/content/docs/resident-agents.mdx | 61 +++++++++++++++++
 website/content/docs/templates.mdx       | 73 +++++++++++++++++++++
 website/src/lib/docs.ts                  | 14 ++++
 11 files changed, 538 insertions(+), 4 deletions(-)
 create mode 100644 website/content/docs/archiving.mdx
 create mode 100644 website/content/docs/commands.mdx
 create mode 100644 website/content/docs/files.mdx
 create mode 100644 website/content/docs/metrics.mdx
 create mode 100644 website/content/docs/ports.mdx
 create mode 100644 website/content/docs/resident-agents.mdx
 create mode 100644 website/content/docs/templates.mdx

diff --git a/website/content/docs/archiving.mdx b/website/content/docs/archiving.mdx
new file mode 100644
index 0000000..345adfa
--- /dev/null
+++ b/website/content/docs/archiving.mdx
@@ -0,0 +1,82 @@
+---
+title: Archiving to S3
+description: The last rung of the lifecycle — idle disks pack to tar.zst in any S3-compatible bucket, and acquire restores them with honest progress.
+---
+
+Frozen costs a few MiB of RAM; stopped costs only disk. Archiving takes
+the last step: the sandbox's disk is packed with `tar` + `zstd` and
+shipped to an S3-compatible bucket, and the host keeps **nothing**. A
+machine with a modest disk can hold a long tail of dormant sandboxes for
+the price of object storage.
+
+Set the four `DORMICE_S3_*` variables
+([reference](/docs/configuration#archiver-s3)) — AWS, Cloudflare R2,
+MinIO, anything S3-compatible — and stopped sandboxes archive after 7
+more idle days by default, tunable per sandbox:
+
+```ts
+await client.acquireSandbox('user-42', {
+  policy: {
+    stopAfterSeconds: 3600,         // an hour idle → cold storage
+    archiveAfterSeconds: 7 * 86400, // a week idle → the bucket
+  },
+});
+```
+
+Without the S3 variables, archiving is honestly absent: sandboxes park at
+stopped forever, and a policy asking to archive is refused at acquire
+time — never stored as a promise the daemon cannot keep.
+
+## Restore: non-blocking, with real progress
+
+`acquireSandbox` on an archived key starts the restore and answers
+immediately — a slow wake is honest, never a silent multi-minute hang:
+
+```ts
+let res = await client.acquireSandbox('user-42');
+while (res.status === 'restoring') {
+  console.log(res.progress.phase, `${res.progress.percent}%`); // downloading | extracting
+  await new Promise((r) => setTimeout(r, 1000));
+  res = await client.acquireSandbox('user-42');
+}
+```
+
+Progress is measured, not invented: download percent against the
+object's actual size, extraction percent against bytes fed to `tar`.
+While a restore runs, command and file verbs answer 409 pointing back at
+acquire, and release is refused too (the one exception to its
+idempotence — destroying a disk mid-rebuild would race the restore).
+
+The E2B surface has no `restoring` concept, so there `connect` / `create`
+simply block until the sandbox is ready — faithful E2B semantics.
+
+The whole loop is verified end to end against MinIO: sandbox idles down
+to archived, the bucket object appears and the local disk is freed;
+re-acquire reports `restoring { downloading }`, flips to `ready`, and the
+files come back byte-identical.
+
+## Crash-safe by ordering, not by ceremony
+
+The archiver holds one invariant: **the local disk is deleted only after
+the upload is confirmed and recorded.** A crash anywhere between the
+steps leaves either a stopped sandbox (the retry re-archives to the same
+object key, an idempotent overwrite) or an archived one — never a sandbox
+whose only copy is a half-written object. A failed restore deletes its
+half-built disk and returns the row to archived; the object was never
+touched, so the retry is clean.
+
+One object per sandbox (`disks/<sandboxId>.tar.zst`). A successful
+restore deletes the object; releasing an archived sandbox deletes it too
+— nothing leaks in the bucket. And if you unset the S3 variables while
+sandboxes sit archived, touching one answers a 503 naming the missing
+variables.
+
+## The trade, in plain terms
+
+Archiving converts disk money into wake-up time: a stopped sandbox
+cold-starts in seconds, an archived one needs a download and an unpack
+first — proportional to how much the sandbox actually wrote. Two knobs
+frame it: raise `archiveAfterSeconds` to keep sandboxes on disk longer,
+or set it `null` for sandboxes that must never wait. As a bonus, a
+restore builds its disk at the *current* size setting and boots the
+*current* image — [restore is also an upgrade](/docs/persistence#restore-is-also-an-upgrade).
diff --git a/website/content/docs/commands.mdx b/website/content/docs/commands.mdx
new file mode 100644
index 0000000..c68c383
--- /dev/null
+++ b/website/content/docs/commands.mdx
@@ -0,0 +1,83 @@
+---
+title: Running commands
+description: execCommand is a buffered shell round-trip — honest exit codes, timeouts enforced inside the container, output capped at 1 MiB per stream.
+---
+
+The native surface has one command verb: `execCommand(userKey, command)`.
+It wakes the sandbox if it is cold, runs the command as `bash -c` inside
+the container (as the sandbox's non-root user, uid 1000), waits, and
+returns the whole result at once:
+
+```ts
+const result = await client.execCommand('my-agent', 'python3 --version');
+result.exitCode;        // 0
+result.stdout;          // 'Python 3.12.…\n'
+result.stderr;          // ''
+result.stdoutTruncated; // false — see "Output is capped" below
+```
+
+The same verb from the CLI, where stdout and stderr pass through to your
+own streams and the exit code becomes `dor`'s own:
+
+```sh
+dor sandbox exec my-agent 'uname -r'
+dor sandbox exec my-agent 'npm ci && npm test' -t 3600
+```
+
+## A non-zero exit is a result, not an error
+
+`execCommand` resolves with `exitCode: 1` — it does not throw. Errors are
+reserved for the protocol failing (no sandbox behind the key: 404, never
+silently created; sandbox mid-restore: 409), not for your command doing
+what commands do.
+
+## Timeouts are enforced inside the container
+
+`timeoutSeconds` (default 300, ceiling 86400) arms a
+`timeout --signal=KILL` around your command *inside* the sandbox; on
+expiry the command dies with exit 137 like any SIGKILLed process. Inside
+on purpose: dropping the HTTP request cannot reach a process on the other
+side of the container boundary, so a host-side deadline would report a
+kill without performing one.
+
+There is deliberately no `timedOut` flag in the response: 137 is also what
+an in-sandbox OOM kill looks like, and the daemon cannot tell the two
+apart — so it does not pretend to.
+
+The SDK derives its HTTP deadline from the same `timeoutSeconds` (plus
+slack for the wake and the round-trip), so a long-running command is never
+cut short by the client-wide `timeoutMs`.
+
+## A running command is activity
+
+While a command runs, the sandbox's idle clock keeps resetting — the idle
+scanner never freezes a sandbox mid-command, even one that legitimately
+runs for hours.
+
+## Output is capped at 1 MiB per stream
+
+The buffered protocol holds the whole result in daemon memory, so stdout
+and stderr are each capped at 1 MiB. Truncation is reported
+(`stdoutTruncated` / `stderrTruncated`), never silent. A capped log still
+informs; for bulk output, write to a file and [read it out](/docs/files)
+instead of routing bytes through stdout.
+
+## Working directory and environment
+
+```ts
+await client.execCommand('my-agent', 'env | sort', {
+  cwd: '/home/user/project',
+  env: { NODE_ENV: 'test' },
+});
+```
+
+`cwd` defaults to `/home/user` — the same base relative file paths
+resolve against.
+
+## When buffered is the wrong shape
+
+`execCommand` is deliberately simple: one request, one finished result.
+For live streaming output, processes that outlive the request, stdin, or
+an interactive terminal, use the E2B surface — `commands.run` streams,
+backgrounds, and reconnects, and `pty.*` is a real interactive bash. See
+[Using the official E2B SDKs](/docs/e2b-sdks).
diff --git a/website/content/docs/files.mdx b/website/content/docs/files.mdx
new file mode 100644
index 0000000..4ac0bfd
--- /dev/null
+++ b/website/content/docs/files.mdx
@@ -0,0 +1,66 @@
+---
+title: Moving files
+description: writeFiles and readFile move files through JSON — 16 MiB per file, honest refusals past that, and streaming alternatives when you need more.
+---
+
+Native file transfer is two verbs. Both wake a cold sandbox first; paths
+are absolute, or relative to `/home/user`:
+
+```ts
+await client.writeFiles('my-agent', [
+  { path: 'config.json', content: JSON.stringify(config) }, // string → UTF-8
+  { path: 'data/input.bin', content: bytes },               // Uint8Array, as-is
+]);
+
+const file = await client.readFile('my-agent', 'results/out.csv');
+const text = new TextDecoder().decode(file.content);
+```
+
+Parent directories are created as needed; existing files are overwritten.
+The CLI moves single files:
+
+```sh
+dor sandbox push my-agent ./data.csv            # → /home/user/data.csv
+dor sandbox push my-agent ./data.csv inputs/d.csv
+dor sandbox pull my-agent results/out.csv out.csv
+dor sandbox pull my-agent results/out.csv       # no local path: raw bytes to stdout
+```
+
+## A batch saves round-trips — it is not a transaction
+
+`writeFiles` writes in array order and fails fast: on an error, the files
+earlier in the array are already written. Splitting a big upload into
+several calls loses nothing — writes are per-file independent.
+
+## The 16 MiB cap, and what to do past it
+
+Content crosses the wire as base64 inside JSON and is buffered in daemon
+memory, so each file is capped at 16 MiB, write and read alike (a
+`writeFiles` batch tops out at 48 MiB of request body). The refusals are
+honest:
+
+- Reading a file over the cap is a **413 naming the file's actual size** —
+  never a truncated file. Unlike exec output, where a capped log still
+  informs, a truncated file is simply a corrupt file.
+- Missing file: 404. A directory or other non-regular file: 400.
+
+Bigger files are not this protocol's job:
+
+- **Fetch from inside the sandbox.** `execCommand` with `curl` or `wget`
+  (both in the stock image) downloads at full speed without routing bytes
+  through the daemon's JSON layer.
+- **Use the E2B files surface.** `files.read` / `files.write` stream with
+  no artificial cap — the disk quota is the cap — and
+  `uploadUrl()` / `downloadUrl()` mint signed URLs a bare browser or curl
+  can use, no headers required. See
+  [Using the official E2B SDKs](/docs/e2b-sdks).
+
+## Every byte moves through the container
+
+File verbs execute *inside* the sandbox, streamed through an in-container
+process — never as host-side writes into the disk image. The disk's
+contents belong to the sandbox, so a hostile symlink planted there must
+have nothing to escape to; resolved inside the container, it can only
+point at the container's own root. Ownership lands on the sandbox user
+(uid 1000) naturally. See [Architecture](/docs/architecture) for the
+boundary this preserves.
diff --git a/website/content/docs/lifecycle.mdx b/website/content/docs/lifecycle.mdx
index b6a47f4..d4796a6 100644
--- a/website/content/docs/lifecycle.mdx
+++ b/website/content/docs/lifecycle.mdx
@@ -47,8 +47,10 @@ Overrides are passed at acquire time and validated as a merged whole:
 
 ```ts
 await client.acquireSandbox('my-agent', {
-  freezeAfterSeconds: 60,        // freeze aggressively
-  stopAfterSeconds: 7 * 86400,   // a week to cold storage
+  policy: {
+    freezeAfterSeconds: 60,      // freeze aggressively
+    stopAfterSeconds: 7 * 86400, // a week to cold storage
+  },
 });
 ```
 
@@ -70,7 +72,7 @@ Three rules worth knowing:
 The setting for a long-lived agent's sandbox:
 
 ```ts
-await client.acquireSandbox('my-agent', { stopAfterSeconds: null });
+await client.acquireSandbox('my-agent', { policy: { stopAfterSeconds: null } });
 ```
 
 It parks at **frozen** forever — memory in swap, a few MiB of RAM, ~50 ms
diff --git a/website/content/docs/meta.json b/website/content/docs/meta.json
index 7dcf126..92c9222 100644
--- a/website/content/docs/meta.json
+++ b/website/content/docs/meta.json
@@ -8,6 +8,18 @@
       "title": "Concepts",
       "pages": ["lifecycle", "persistence", "architecture"]
     },
+    {
+      "title": "Guides",
+      "pages": [
+        "commands",
+        "files",
+        "templates",
+        "resident-agents",
+        "ports",
+        "archiving",
+        "metrics"
+      ]
+    },
     {
       "title": "E2B compatibility",
       "pages": ["e2b-sdks", "e2b-differences"]
diff --git a/website/content/docs/metrics.mdx b/website/content/docs/metrics.mdx
new file mode 100644
index 0000000..ac71e2c
--- /dev/null
+++ b/website/content/docs/metrics.mdx
@@ -0,0 +1,72 @@
+---
+title: Metrics
+description: Two observation windows — one per sandbox, one for the host — and neither ever wakes anything.
+---
+
+Dormice ships observation windows, deliberately not a monitoring system:
+each call answers "how are things *right now*" with a single snapshot.
+For history, trends, and alerting, point a real monitoring stack at the
+box.
+
+One rule governs both windows: **observation never wakes a sandbox and
+never resets its idle clock** — the same principle as listing
+([what counts as activity](/docs/lifecycle#what-counts-as-activity)).
+Watching a fleet of frozen sandboxes from a dashboard keeps them exactly
+as cheap as ignoring them.
+
+## Per sandbox: `getMetrics()` (E2B surface)
+
+The official SDK's `getMetrics()` returns an array with one live sample —
+CPU count and usage, memory, and disk:
+
+```ts
+const [m] = await sbx.getMetrics();
+m.memUsed;  // bytes
+m.memTotal;
+m.diskUsed; // real occupancy of the sandbox's disk
+m.diskTotal;
+```
+
+- A **frozen** sandbox is readable without waking it — its resource
+  accounting is still there, and reading is not activity.
+- A **stopped** sandbox answers an empty array: no container, honestly no
+  sample — never zeros pretending to be measurements.
+- The SDK's `start` / `end` range parameters are accepted and ignored —
+  there is no metrics history to query, only now.
+
+## The host: `getHostMetrics()` (native surface)
+
+The operator's question — *is this machine okay, and what do the
+sandboxes collectively cost it?* — in one call:
+
+```ts
+const m = await client.getHostMetrics();
+```
+
+Four sections:
+
+- **`host`** — CPU (computed as the delta between your calls, so the
+  first call after a daemon start honestly answers `null` rather than a
+  made-up zero), memory as `MemAvailable` (what could still be allocated
+  without swapping — the naive "free" number cries wolf on any healthy
+  Linux box), and **swap**, which is the freeze mechanism's fuel: frozen
+  sandboxes live there, and a full swap means "idle is free" stops being
+  true. `swap.totalBytes: 0` is a real reading of a machine with no swap
+  configured; `null` means the platform offers no reading at all.
+- **`dataDisk`** — the filesystem holding `DORMICE_DATA_DIR`, where
+  sandbox disks live. This is the real capacity ceiling: past it, even
+  the ledger cannot write.
+- **`sandboxes`** — ledger aggregates: total, the `DORMICE_MAX_SANDBOXES`
+  cap, and a count per lifecycle state.
+- **`sandboxDisks`** — what the sparse disk images *promise* (nominal)
+  versus what they *occupy* (actual). The gap is your disk overcommit,
+  and this number is its only cap — nothing else stops a hundred 10 GB
+  promises on a 200 GB disk, which is fine exactly as long as you watch
+  it. Measured on the test host: a sandbox promising 10 GiB actually
+  occupied 68 MiB.
+
+The web console's Overview page renders exactly this snapshot — CPU,
+memory, swap, and the data disk side by side, sandbox states, and the
+overcommit meter — refreshed every few seconds. Readings a platform
+cannot produce come back `null`, never invented; the console shows an
+amber hint (pointing at `dor doctor`) instead of a fake number.
diff --git a/website/content/docs/ports.mdx b/website/content/docs/ports.mdx
new file mode 100644
index 0000000..db72c98
--- /dev/null
+++ b/website/content/docs/ports.mdx
@@ -0,0 +1,69 @@
+---
+title: Exposing ports
+description: getHost(port) preview URLs — a transparent proxy with wake-on-traffic, behind one wildcard domain you control.
+---
+
+Anything listening on a port inside a sandbox — a dev server, a notebook,
+an agent's UI — can be reached from outside through the daemon's sandbox
+proxy. Switch it on with one variable:
+
+```sh
+DORMICE_SANDBOX_DOMAIN=sbx.example.com
+```
+
+and the E2B SDK's `getHost()` does the rest:
+
+```ts
+const sbx = await Sandbox.create({ /* the two URLs + apiKey */ });
+await sbx.commands.run('python3 -m http.server 8000', { background: true });
+
+const host = sbx.getHost(8000); // '8000-<sandboxId>.sbx.example.com'
+await fetch(`https://${host}/`);
+```
+
+Requests arriving with such a `Host` header are proxied straight into the
+sandbox — headers untouched, WebSocket upgrades passed through both ways.
+Verified on real hardware: a `python3 -m http.server` inside a gVisor
+sandbox answers 200 through the proxy. If nothing listens on the port,
+the proxy answers an honest **502 naming the port**, not a hang.
+
+Unset, the feature is honestly absent: responses carry no domain and the
+SDK has nothing to build URLs from.
+
+## Wake-on-traffic
+
+A frozen sandbox is woken by the first proxied request — ~50 ms,
+invisible to the caller — so a preview URL keeps working against a
+sandbox nobody has touched in days. While a proxied connection stays
+open, the sandbox counts as active; when the last one closes, the idle
+clock resumes.
+
+## The ops recipe
+
+The daemon itself only ever binds `127.0.0.1`. The internet-facing half
+is one wildcard DNS record plus a reverse proxy that terminates TLS:
+
+```text
+*.sbx.example.com → your host
+
+# Caddyfile
+*.sbx.example.com {
+  reverse_proxy 127.0.0.1:3676 {
+    flush_interval -1
+  }
+}
+```
+
+`flush_interval -1` keeps streaming responses unbuffered — verified with
+a real terminal session through Caddy: output arrived while the stream
+was still open. (A wildcard certificate needs Caddy's DNS challenge; a
+plain HTTP setup works for a LAN.)
+
+## No authentication, on purpose
+
+Preview URLs are unauthenticated — the same call E2B made, because these
+URLs exist to be opened in browsers. The sandbox ID in the hostname is
+unguessable (a UUID), but that is obscurity, not access control: treat a
+preview URL as public while the port is open. Everything else on the
+daemon — native API, E2B API, console — stays authenticated; only sandbox
+port traffic passes free.
diff --git a/website/content/docs/quickstart.mdx b/website/content/docs/quickstart.mdx
index 439d68c..078c47d 100644
--- a/website/content/docs/quickstart.mdx
+++ b/website/content/docs/quickstart.mdx
@@ -17,7 +17,7 @@ const client = new Dormice({
 // One key, one sandbox — created, woken or restarted as needed.
 // stopAfterSeconds: null makes it a resident agent: it may freeze when
 // idle (~50 ms to wake) but never cold-starts.
-await client.acquireSandbox('my-agent', { stopAfterSeconds: null });
+await client.acquireSandbox('my-agent', { policy: { stopAfterSeconds: null } });
 
 const result = await client.execCommand('my-agent', 'python3 -c "print(6 * 7)"');
 console.log(result.exitCode, result.stdout); // 0 42
diff --git a/website/content/docs/resident-agents.mdx b/website/content/docs/resident-agents.mdx
new file mode 100644
index 0000000..cfaeba4
--- /dev/null
+++ b/website/content/docs/resident-agents.mdx
@@ -0,0 +1,61 @@
+---
+title: Resident agents
+description: One permanent sandbox per agent — frozen to a few MiB when idle, awake in ~50 ms, never a cold start.
+---
+
+The pattern Dormice was built for: give every agent (or user, or project)
+a permanent sandbox keyed by its own ID, and let the lifecycle engine
+make the idle time free.
+
+```ts
+const res = await client.acquireSandbox(`agent-${userId}`, {
+  policy: { stopAfterSeconds: null },
+});
+```
+
+`stopAfterSeconds: null` pins the sandbox to the top two rungs of the
+[lifecycle](/docs/lifecycle): idle, it freezes — measured on real
+hardware, ~1 GiB of resident memory squeezed to ~5 MiB — and any touch
+wakes it in about 50 ms. It never decays to a seconds-long cold start.
+
+Every later `acquireSandbox` with the same key — tomorrow, next month —
+comes back to the same sandbox: same files, same installed packages, same
+processes. A runnable version of this pattern lives at
+[`examples/resident-agent.mjs`](https://github.com/BitMiracle-AI/Dormice/blob/main/examples/resident-agent.mjs).
+
+## Freezing suspends processes — it does not kill them
+
+A frozen sandbox's processes stop mid-flight and resume exactly where
+they were: a REPL keeps its state, a dev server its sockets, an agent
+process its memory. Nothing running in a resident sandbox is ever killed
+by idleness.
+
+The flip side, stated honestly: a background process does not *keep* its
+sandbox warm. Once the streams watching it disconnect, the idle clock
+runs, the scanner freezes the sandbox, and the process suspends with it —
+to continue, mid-instruction, on the next touch. A resident sandbox is
+not a way to run an unattended 24×7 workload; it is a way to make "ready
+whenever the agent returns" cost a few MiB.
+
+## What a sandbox costs while frozen
+
+A few MiB of resident memory (the rest sits in swap), plus a sparse disk
+that occupies only what was actually written. That is the entire idle
+bill — which is why one modest machine can hold a long tail of dormant
+agents. If even frozen is too warm, leave `stopAfterSeconds` set and let
+sandboxes fall to stopped (disk only, cold start in seconds) or
+[archived](/docs/archiving) (S3 only, nothing on the host).
+
+## What the stock image ships
+
+Sandboxes boot from the image `install.sh` builds
+([`images/Dockerfile`](https://github.com/BitMiracle-AI/Dormice/blob/main/images/Dockerfile)):
+Ubuntu 24.04 with Python 3.12 (`pip install` works — the PEP 668 guard is
+removed), Node.js 24 (sha256-pinned), git, ripgrep, jq, curl/wget, and a
+version-pinned [Claude Code](https://claude.com/claude-code) — so a coding
+agent can start working in its sandbox with zero setup. Everything runs
+as a non-root user (uid 1000) inside gVisor.
+
+Need more? Bake it into a [template](/docs/templates) instead of
+reinstalling per sandbox — and remember that whatever an agent installs
+into `/home/user` at runtime [persists anyway](/docs/persistence).
diff --git a/website/content/docs/templates.mdx b/website/content/docs/templates.mdx
new file mode 100644
index 0000000..ba72d71
--- /dev/null
+++ b/website/content/docs/templates.mdx
@@ -0,0 +1,73 @@
+---
+title: Templates
+description: A template is a named Docker image — build it with docker, register the name, and both APIs create sandboxes from it.
+---
+
+Dormice deliberately has no template build pipeline. The host's Docker
+daemon is already an image store and `docker build` is already the build
+tool — a template is just a **name pointing at an image**, recorded in
+the ledger:
+
+```sh
+docker build -t my-agent-env:v1 .        # any image, built anywhere
+dor template add my-agent-env my-agent-env:v1
+dor template ls
+```
+
+Create sandboxes from it on either surface:
+
+```ts
+// Native: a creation-time option, like policy
+await client.acquireSandbox('user-42', { template: 'my-agent-env' });
+
+// E2B: the templateID argument
+const sbx = await Sandbox.create('my-agent-env', { /* the two URLs + apiKey */ });
+```
+
+An unknown template name is refused — 400 natively, 404 through the E2B
+surface — never silently substituted with the base image.
+
+## Names resolve late — that is the upgrade mechanism
+
+A sandbox's ledger row records the template *name*, not the image behind
+it. Every time a container is built — waking from stopped, a rebuild, a
+restore from archive — the name resolves to the template's **current**
+image. So upgrading is three commands:
+
+```sh
+docker build -t my-agent-env:v2 .
+dor template add my-agent-env my-agent-env:v2  # re-registering re-points the name
+dor sandbox rebuild user-42                    # per sandbox: new shell, same /home/user
+```
+
+Until rebuilt (or cold-started), existing sandboxes keep running the
+image they were born on. Through a rebuild, `/home/user` carries over
+untouched and everything outside it resets onto the new image — see
+[Rebuild: new shell, same body](/docs/persistence#rebuild-new-shell-same-body).
+
+## Rules and edge cases
+
+- **Registration is configuration.** The image is not checked for
+  existence — register first, build later, if you like. If it is still
+  missing when a sandbox needs it, creation fails with a named error
+  (`image X is not on this host — docker pull or build it, then retry`).
+- **`base` is reserved.** Through the E2B surface, `Sandbox.create()`
+  with no template argument sends the string `base`, which means the
+  daemon's base image; the name cannot be registered.
+- **A referenced template cannot be removed.** `dor template rm` answers
+  a 409 naming a sandbox that still uses the template. Removing an
+  unknown name is a no-op, and removing a registration never removes the
+  image itself.
+- **Templates apply at creation only.** An acquire with a `template` on
+  a key that already has a sandbox keeps the sandbox it finds, template
+  unchanged — but an unknown name is still refused, never silently
+  ignored.
+
+## Keep the image rules in mind
+
+Sandboxes mount their own disk over `/home/user`, so a template must
+install into image paths (`/opt`, `/usr/local`) — anything baked under
+`/home/user` is shadowed at runtime. The stock image's
+[`Dockerfile`](https://github.com/BitMiracle-AI/Dormice/blob/main/images/Dockerfile)
+is the reference: layers ordered by change frequency, tools outside the
+home directory, non-root user at uid 1000.
diff --git a/website/src/lib/docs.ts b/website/src/lib/docs.ts
index caeff1e..4e6df29 100644
--- a/website/src/lib/docs.ts
+++ b/website/src/lib/docs.ts
@@ -3,15 +3,22 @@ import type { JSX } from 'react';
 // Relative imports: content/ lives beside src/ on purpose — it is authored
 // content, not source, and stays portable across doc-shell rewrites.
 import * as architecture from '../../content/docs/architecture.mdx';
+import * as archiving from '../../content/docs/archiving.mdx';
+import * as commands from '../../content/docs/commands.mdx';
 import * as configuration from '../../content/docs/configuration.mdx';
 import * as e2bDifferences from '../../content/docs/e2b-differences.mdx';
 import * as e2bSdks from '../../content/docs/e2b-sdks.mdx';
+import * as files from '../../content/docs/files.mdx';
 import * as indexDoc from '../../content/docs/index.mdx';
 import * as installation from '../../content/docs/installation.mdx';
 import * as lifecycle from '../../content/docs/lifecycle.mdx';
 import meta from '../../content/docs/meta.json';
+import * as metrics from '../../content/docs/metrics.mdx';
 import * as persistence from '../../content/docs/persistence.mdx';
+import * as ports from '../../content/docs/ports.mdx';
 import * as quickstart from '../../content/docs/quickstart.mdx';
+import * as residentAgents from '../../content/docs/resident-agents.mdx';
+import * as templates from '../../content/docs/templates.mdx';
 
 // Server-only registry of every doc. MDX renders as server components, so
 // importing them all here costs the client nothing — pages ship as HTML.
@@ -31,6 +38,13 @@ const modules: Record<string, DocModule> = {
   lifecycle,
   persistence,
   architecture,
+  commands,
+  files,
+  templates,
+  'resident-agents': residentAgents,
+  ports,
+  archiving,
+  metrics,
   'e2b-sdks': e2bSdks,
   'e2b-differences': e2bDifferences,
   configuration,

From b67e5b02b7a665c7e0c0ce5ed925d79452fd7a5c Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 11 Jul 2026 14:22:57 +0800
Subject: [PATCH 053/133] Reference and Operations chapters finish the docs
 arc: CLI, HTTP API, console, doctor, upgrading, troubleshooting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six pages, every claim pinned against source before writing: CLI
signatures from the commander declarations, the route table from
routes/*.ts and the shared schemas, doctor's checks one by one from
doctor.ts, upgrade semantics from install.sh itself, and only the real
pit list in troubleshooting. Along the way two counts had already
drifted ("19 checks", "three probes" — doctor grew to 22 and 4), so
install.sh's header and the new pages say it rustproof: no totals,
doctor reports its own numbers.
---
 deploy/install.sh                        |   2 +-
 website/content/docs/cli.mdx             |  92 ++++++++++++++++++++
 website/content/docs/console.mdx         |  77 +++++++++++++++++
 website/content/docs/doctor.mdx          |  92 ++++++++++++++++++++
 website/content/docs/http-api.mdx        |  92 ++++++++++++++++++++
 website/content/docs/meta.json           |   6 +-
 website/content/docs/troubleshooting.mdx | 102 +++++++++++++++++++++++
 website/content/docs/upgrading.mdx       |  68 +++++++++++++++
 website/src/lib/docs.ts                  |  12 +++
 9 files changed, 541 insertions(+), 2 deletions(-)
 create mode 100644 website/content/docs/cli.mdx
 create mode 100644 website/content/docs/console.mdx
 create mode 100644 website/content/docs/doctor.mdx
 create mode 100644 website/content/docs/http-api.mdx
 create mode 100644 website/content/docs/troubleshooting.mdx
 create mode 100644 website/content/docs/upgrading.mdx

diff --git a/deploy/install.sh b/deploy/install.sh
index a76ee48..5802caf 100644
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -15,7 +15,7 @@
 #     the code and repairs drift, and never rotates your API token.
 #   - Loud. Every step prints what it found and what it did.
 #   - Verified. The install has not succeeded until `dor doctor` says so —
-#     the same 19 checks, including the three real-container probes.
+#     the same battery of checks, including the real-container probes.
 set -euo pipefail
 export DEBIAN_FRONTEND=noninteractive
 
diff --git a/website/content/docs/cli.mdx b/website/content/docs/cli.mdx
new file mode 100644
index 0000000..e83794e
--- /dev/null
+++ b/website/content/docs/cli.mdx
@@ -0,0 +1,92 @@
+---
+title: CLI reference
+description: Every dor command — sandboxes, templates, and the host doctor — with the exact flags and exit-code behavior.
+---
+
+The CLI installs as two names for the same binary: `dormice` (the name you
+can guess) and `dor` (the name you actually type). It talks to a daemon
+over the [HTTP API](/docs/http-api) and connects with exactly two
+environment variables — missing one produces an error naming it:
+
+```sh
+export DORMICE_ENDPOINT=http://127.0.0.1:3676
+export DORMICE_API_TOKEN=<token>   # on the daemon host: grep ^DORMICE_API_TOKEN /etc/dormice/env
+```
+
+Errors print as one line on stderr (no stack traces at a shell prompt) and
+exit 1.
+
+## dor doctor
+
+```sh
+dor doctor           # every check, including probes that start a real container
+dor doctor --quick   # skip the container probes
+```
+
+Read-only host checks: can this machine run the daemon? Exit 0 unless a
+check fails. Every check is documented one by one in
+[dor doctor](/docs/doctor).
+
+## dor sandbox
+
+```sh
+dor sandbox ls
+```
+
+Every sandbox with its lifecycle state, as a table. Listing is
+observation — it never wakes anything. (Table output strips control
+characters: user keys are not restricted on the wire, and an ANSI escape
+inside one must not reach your terminal.)
+
+```sh
+dor sandbox exec <userKey> '<command>' [-t <seconds>]
+```
+
+Runs a shell command in the sandbox behind the key, waking it first. The
+command is one quoted argument, executed as `bash -c`. Its stdout and
+stderr pass through to yours, raw — this is your own command's output —
+and **its exit code becomes `dor`'s exit code**, so `dor sandbox exec` in
+a script behaves like the command itself. `-t, --timeout <seconds>` kills
+it after that long ([enforced inside the container](/docs/commands)). An
+unknown key is a 404, never a sandbox created by accident.
+
+```sh
+dor sandbox push <userKey> <localPath> [remotePath]
+dor sandbox pull <userKey> <remotePath> [localPath]
+```
+
+One file in, one file out. Relative remote paths land under `/home/user`;
+`push` without a remote path uses the local file's name. `pull` without a
+local path writes the raw bytes to stdout — pipe it wherever. Both obey
+the [16 MiB single-file contract](/docs/files).
+
+```sh
+dor sandbox rebuild <userKey>
+```
+
+Swaps the container, keeps `/home/user` — the sandbox's next use starts
+on its template's *current* image (or the base image). This is how a
+[template upgrade](/docs/templates) reaches an existing sandbox. Details:
+[rebuild: new shell, same body](/docs/persistence#rebuild-new-shell-same-body).
+
+```sh
+dor sandbox release <userKey>
+```
+
+Destroys the sandbox — container, disk, and (if archived) the S3 object.
+The only verb that loses data. Idempotent: releasing a key that has no
+sandbox reports so and exits 0.
+
+## dor template
+
+```sh
+dor template add <name> <image>   # register, or re-point — that is the upgrade
+dor template ls
+dor template rm <name>
+```
+
+A template is a name for a Docker image already on the daemon's host —
+`add` on an existing name re-points it at the new image, which is the
+[upgrade front door](/docs/templates). `rm` is refused (with the sandboxes
+named) while any sandbox still uses the template, and never removes the
+image itself.
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
new file mode 100644
index 0000000..5e57e0e
--- /dev/null
+++ b/website/content/docs/console.mdx
@@ -0,0 +1,77 @@
+---
+title: Web console
+description: The daemon serves its own UI at /console — sign in once, watch everything, wake nothing by accident.
+---
+
+The daemon hosts a web console at `http://127.0.0.1:3676/console` — same
+process, same port, nothing extra to run. It is an observation window
+with hands: everything it shows comes from the same API documented in
+this section, and it follows the same rule the API does — **watching
+never wakes a sandbox; using does, and only behind an explicit click**.
+
+(The console UI is currently Chinese-language.)
+
+## Signing in
+
+Paste the API token once. The browser trades it for an `httpOnly` session
+cookie (valid 7 days) and never stores the token anywhere page
+JavaScript can read — a script injected into the console cannot steal
+your long-term credential. Sessions are derived from the API token, so
+rotating the token signs every browser out at once.
+
+## Overview
+
+The "is this machine healthy" page: CPU, memory, **swap** and the **data
+disk** as first-class cards — swap filling up means "idle is free" is
+ending, and a full data disk is the real capacity ceiling. Below them,
+sandbox counts by lifecycle state and the sandbox-disk overcommit figure
+(promised vs actually occupied — the same numbers as
+[`getHostMetrics`](/docs/metrics)). Usage bars turn amber at 75% and red
+at 90%; a host without swap gets an amber warning pointing at
+`dor doctor`.
+
+## Sandboxes
+
+The live list — every sandbox with its state, polled every 2 seconds,
+with search, a state filter, and multi-select batch release. Creating a
+sandbox from here is exactly `acquireSandbox`: user key, the lifecycle
+knobs (including the never-stop [resident-agent
+switch](/docs/resident-agents)), and a template dropdown when templates
+are registered.
+
+A sandbox's detail page is a workspace with four tabs:
+
+- **Overview** — identity, policy thresholds, last activity; release and
+  [rebuild](/docs/persistence#rebuild-new-shell-same-body) buttons, each
+  behind a confirmation dialog.
+- **Terminal** — a real interactive shell, kept behind an explicit
+  "open" button because opening one *wakes* the sandbox. The browser
+  speaks the same wire the official E2B SDK does — the console did not
+  grow a second terminal protocol. Closing the terminal kills its shell
+  rather than leaving an orphan behind.
+- **Files** — browse, upload, download, rename, delete under
+  `/home/user`. File operations wake the sandbox too, so a cold sandbox
+  shows an explicit "open" gate first.
+- **Processes** — the E2B process table, polled without waking (a
+  stopped sandbox honestly shows none).
+
+## Templates
+
+Register a name for an image, re-register to re-point it — the console's
+form is the same [upgrade front door](/docs/templates) as
+`dor template add`. Deleting a template a sandbox still uses is refused
+with the daemon's own message naming the sandboxes.
+
+## Connect
+
+Copy-paste snippets for the SDK, the official E2B packages, and curl,
+pre-filled with the endpoint the browser itself is using. The API token
+is never displayed — the console traded it for a cookie at sign-in and
+cannot read it back; fetch it from the daemon host
+(`grep ^DORMICE_API_TOKEN /etc/dormice/env`).
+
+## What you will not find
+
+Development builds show extra preview pages backed by sample data,
+clearly badged; a production build hides them entirely. The rule: a real
+deployment must never render a fake all-green health report.
diff --git a/website/content/docs/doctor.mdx b/website/content/docs/doctor.mdx
new file mode 100644
index 0000000..ce01d7d
--- /dev/null
+++ b/website/content/docs/doctor.mdx
@@ -0,0 +1,92 @@
+---
+title: dor doctor
+description: Read-only host checks, one by one — what each verifies, why it exists, and what fix it names.
+---
+
+`dor doctor` answers one question: **can this host run the Dormice
+daemon?** Every check encodes a fact measured on real hardware — a pit
+someone actually fell into — not a hypothesis. Three disciplines shape
+it:
+
+- **Read-only.** Doctor names the fix but never applies it. Fixing is
+  [the installer's](/docs/installation) job.
+- **Effective values, not config files.** Some clouds ship
+  `vm.swappiness=0` in their own sysctl.d file, so "our config file
+  exists" proves nothing — doctor reads `/proc/sys/vm/swappiness` live.
+- **No silent downloads.** A missing image is reported with build
+  instructions; doctor never runs `docker pull` behind your back.
+
+Checks are gated: when a prerequisite fails, dependents report *skip*
+with the blocker's name instead of piling on noise. Any failure exits 1;
+warnings don't affect the exit code. `--quick` skips the probes that
+start a real container.
+
+## Platform
+
+- **operating system** — Linux, full stop: loop mounts, cgroups and
+  gVisor exist nowhere else.
+- **Node.js version** — 22 or newer.
+- **running as root** — loop mounts, `mkfs` and cgroup writes need uid 0.
+- **cgroup v2 memory controller** — freezing works by writing
+  `memory.reclaim`, a cgroup v2 file (default on Ubuntu 22.04+).
+
+## Docker
+
+- **Docker daemon** — dockerd answers.
+- **gVisor runtime (runsc)** — registered as a Docker runtime; without
+  it sandboxes would share the host kernel.
+- **inter-container traffic off** — `"icc": false` in
+  `/etc/docker/daemon.json`, or one sandbox can port-scan another.
+- **container log rotation** — unbounded stdout logs fill the disk over
+  months of a long-lived sandbox's life.
+
+## Memory (the freeze fuel)
+
+- **swap present** — freezing pushes sandbox memory to swap; measured
+  without it: 0 bytes reclaimed.
+- **vm.swappiness = 100** — below 100 the kernel refuses to swap the
+  shmem-backed memory gVisor holds sandboxes in; measured at the default
+  60: 0 bytes reclaimed. This is the check that reads the live value.
+
+## Network containment
+
+- **cloud metadata firewall** — `DROP` rules in the `DOCKER-USER` chain
+  for `169.254.0.0/16` and `100.100.100.200`; without them a sandbox can
+  steal cloud credentials from the metadata service.
+- **firewall rules persisted** — *warn*: rules living only in memory
+  silently vanish on reboot.
+
+## Configuration
+
+- **DORMICE_API_TOKEN** — set and at least 32 characters (the daemon
+  refuses to start without it).
+- **S3 archive configuration** — three honest states: none set (skipped —
+  archiver off, sandboxes park at stopped), all four set (pass), or a
+  partial set (fail, naming the missing variables — the daemon refuses a
+  half-configured archiver anyway).
+- **zstd available** — the archiver shells out to `tar -I zstd` on the
+  host at every archive and restore.
+- **base image available** — present locally; the fix names
+  `images/Dockerfile`, and doctor never pulls.
+- **docker-mode paths absolute** — a relative `DORMICE_DB_PATH` depends
+  on the start directory, and a wrong start directory opens an *empty
+  ledger next to real sandboxes* — the exact mismatch the daemon's
+  startup guard exists to refuse.
+- **free disk space** — *warn* under 10 GiB for the data directory: past
+  full, even the ledger cannot write.
+
+## Probes (start a real sandbox container)
+
+- **gVisor fake kernel** — `uname -r` inside must report a gVisor
+  kernel; a real kernel version means isolation is not happening.
+- **metadata blocked inside** — the probe tries to reach the metadata
+  service *from inside a sandbox* and must find it blocked. The
+  firewall check above reads rules; this one tests reality.
+- **image runs as uid 1000** — sandboxes must not run as root, even
+  behind gVisor.
+- **image has inotify-tools** — *warn*: without `inotifywait`, E2B
+  directory watching honestly refuses to start; everything else works.
+
+When all of this passes, the machine can run the daemon — that is the
+installer's definition of success too: it ends by running doctor and
+believing the answer.
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
new file mode 100644
index 0000000..c174391
--- /dev/null
+++ b/website/content/docs/http-api.mdx
@@ -0,0 +1,92 @@
+---
+title: HTTP API
+description: One RPC route per verb, plain JSON, Bearer auth — everything the SDK does, curl can do.
+---
+
+The native API is deliberately boring: every operation is a `POST` to a
+camelCase verb route, input and output entirely in the JSON body, and the
+route name is identical to the SDK method name. There is nothing the SDK
+can do that `curl` cannot.
+
+```sh
+curl -X POST http://127.0.0.1:3676/acquireSandbox \
+  -H "Authorization: Bearer $DORMICE_API_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"userKey": "my-agent"}'
+```
+
+Two rules cover the whole surface:
+
+- **Auth** is `Authorization: Bearer <token>` on every route except
+  `GET /healthz`, the open liveness probe (probes have no secrets — it
+  answers `{"status":"ok"}`).
+- **Every non-2xx body is `{ "message": "..." }`** — one error shape,
+  whoever produced the error. 4xx name your mistake; 5xx are the daemon's.
+
+The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
+`/e2b/*` with its own authentication — nothing below applies to it.
+
+## The verbs
+
+| Route | Does | Refusals worth knowing |
+| --- | --- | --- |
+| `POST /acquireSandbox` | create, wake, or restore — idempotent per key | 400 invalid policy/unknown template, 429 at the sandbox limit |
+| `POST /listSandboxes` | every sandbox and its state; never wakes anything | — |
+| `POST /execCommand` | run a command, buffered | 404 unknown key, 409 archived/restoring |
+| `POST /writeFiles` | batch write, base64 in JSON | 404/409 as above; body over 48 MiB refused |
+| `POST /readFile` | read one file, base64 out | 404 no such file, 400 not a file, 413 over 16 MiB (names the real size) |
+| `POST /rebuildSandbox` | swap container, keep `/home/user` | 404 unknown key, 409 archived/restoring |
+| `POST /releaseSandbox` | destroy; idempotent | 409 mid-restore (the one dent — retry when it finishes) |
+| `POST /registerTemplate` | upsert name → image | 400 `'base'` is reserved |
+| `POST /listTemplates` | every registered template | — |
+| `POST /removeTemplate` | unregister; idempotent | 409 while sandboxes still use it (names them) |
+| `POST /getHostMetrics` | host snapshot; never wakes anything | — |
+
+Use verbs (`execCommand`, files, `rebuildSandbox`) answer 404 for an
+unknown key rather than creating a sandbox as a side effect — an unknown
+key is more likely a typo than an intent. Only `acquireSandbox` creates.
+
+## The sandbox object
+
+Everything that returns a sandbox returns this shape:
+
+```json
+{
+  "sandboxId": "8b1e…-uuid", "userKey": "my-agent",
+  "state": "active", "nodeId": "…", "endpoint": "http://127.0.0.1:3676",
+  "policy": { "freezeAfterSeconds": 600, "stopAfterSeconds": 259200, "archiveAfterSeconds": null },
+  "template": null, "createdAt": "…", "lastActiveAt": "…"
+}
+```
+
+`state` is one of `active | frozen | stopped | archived | restoring` (the
+[lifecycle ladder](/docs/lifecycle)). `acquireSandbox` wraps it in a
+union: `{ "status": "ready", "sandbox": … }`, or — when the sandbox is
+coming back from S3 —
+`{ "status": "restoring", "sandbox": …, "progress": { "phase": "downloading" | "extracting", "percent": … } }`;
+poll acquire until it flips to `ready`
+([archiving](/docs/archiving)).
+
+## Commands and files on the wire
+
+`execCommand` takes `{ userKey, command, timeoutSeconds?, cwd?, env? }`
+and returns
+`{ exitCode, stdout, stderr, stdoutTruncated, stderrTruncated }` — a
+non-zero exit code is a result, not an HTTP error
+([details](/docs/commands)).
+
+File content crosses the wire as base64 inside JSON: `writeFiles` takes
+`{ userKey, files: [{ path, contentBase64 }] }`, `readFile` takes
+`{ userKey, path }` and returns `{ path, contentBase64 }` with the path
+resolved absolute. Limits and refusal semantics:
+[moving files](/docs/files).
+
+## Bring a patient HTTP client
+
+`execCommand`'s response headers arrive only when the command finishes —
+legally hours later. Many HTTP clients ship a hidden ~5-minute
+first-byte/header timeout (Node's undici does); the SDK disables it and
+enforces one deadline derived from `timeoutSeconds`. Rolling your own
+client, do the same, or a `sleep 310` dies at exactly 300 s with a
+connection error that looks like the daemon's fault. It isn't —
+measured, twice.
diff --git a/website/content/docs/meta.json b/website/content/docs/meta.json
index 92c9222..ac651b3 100644
--- a/website/content/docs/meta.json
+++ b/website/content/docs/meta.json
@@ -26,7 +26,11 @@
     },
     {
       "title": "Reference",
-      "pages": ["configuration"]
+      "pages": ["configuration", "cli", "http-api", "console"]
+    },
+    {
+      "title": "Operations",
+      "pages": ["doctor", "upgrading", "troubleshooting"]
     }
   ]
 }
diff --git a/website/content/docs/troubleshooting.mdx b/website/content/docs/troubleshooting.mdx
new file mode 100644
index 0000000..876ecbb
--- /dev/null
+++ b/website/content/docs/troubleshooting.mdx
@@ -0,0 +1,102 @@
+---
+title: Troubleshooting
+description: Symptoms, causes, and fixes — every entry was hit on real hardware before it was written down.
+---
+
+Three places answer most questions before this page does: the daemon's
+log (`journalctl -u dormice -f` — refusals are written to be read),
+`dor doctor` (the environment, [check by check](/docs/doctor)), and the
+console's Overview or `getHostMetrics` (the machine's
+[capacity](/docs/metrics)).
+
+## Freezing frees almost no memory
+
+Idle sandboxes stay at full residency instead of dropping to a few MiB.
+Freezing works by pushing sandbox memory to swap, and two host settings
+gate it: **swap must exist**, and **`vm.swappiness` must be 100** — at
+the default 60 the kernel refuses to swap the shmem-backed memory gVisor
+holds sandboxes in. Measured: 0 bytes reclaimed at 60; the same sandbox
+went from ~1 GiB to ~5 MiB at 100. `dor doctor` checks both; note some
+clouds ship `swappiness=0` in their own sysctl.d file, which is why
+doctor reads the live value.
+
+## The daemon refuses to start
+
+It refuses loudly and on purpose — each message names its situation:
+
+- **"another daemon holds the ledger"** — the ledger carries an
+  exclusive lock; one daemon per machine is enforced, not suggested.
+  The lock dies with the process, so no stale-pidfile cleanup exists.
+- **Empty ledger, but sandbox containers exist** — almost always a
+  wrong `DORMICE_DB_PATH` or a docker-mode daemon started from the
+  wrong directory. Starting anyway would make the reconciler destroy
+  every "orphan" — so it won't. Fix the path, or clean the leftovers
+  up by hand if they really are debris.
+- **Ledger has sandboxes, but Docker shows none** — the mirror image:
+  wrong machine or wrong data directory; starting would empty the
+  ledger.
+- **Relative paths in docker mode** — refused outright, because a
+  relative DB path is how the first situation happens.
+
+## `docker container prune` deleted my sandbox containers
+
+Not data loss. The **disk is the sandbox's body**; the container is a
+disposable shell. The reconciler records the pruned sandboxes as
+stopped, and the next `acquireSandbox` rebuilds a container from the
+surviving disk — same sandbox ID, `/home/user` intact. Verified
+end-to-end on real hardware. ([Persistence](/docs/persistence) is the
+full contract.)
+
+## Long commands die at exactly 5 minutes
+
+A command past ~300 s fails with a client-side connection error while
+the daemon shows nothing wrong. `execCommand` sends its response headers
+only when the command *finishes*, and many HTTP clients ship a hidden
+~5-minute wait-for-headers timeout — Node's undici does. The SDK
+disables those clocks and derives one honest deadline from
+`timeoutSeconds`; a hand-rolled client must do the same
+([details](/docs/http-api)).
+
+## Terminals or streams stall behind a reverse proxy
+
+Proxies buffer by default, which turns live output into
+nothing-then-everything. Tell yours not to — for Caddy,
+`flush_interval -1` ([reverse-proxy recipe](/docs/ports)); verified with
+a live terminal session through Caddy.
+
+## A sandbox turned up stopped with exit code 137
+
+Out-of-memory *inside* the sandbox takes down the whole gVisor container
+— that is the isolation working: the guest hit its
+`DORMICE_SANDBOX_MEMORY_GB` ceiling (default 2). The disk survives; the
+next acquire revives the sandbox. Raise the limit if the workload
+honestly needs more.
+
+## E2B `watchDir` refuses to start
+
+The sandbox image predates `inotify-tools`. Rebuild it from
+`images/Dockerfile`, point `DORMICE_BASE_IMAGE` at the new tag, and
+[rebuild](/docs/upgrading) the sandboxes that need watching. Doctor's
+image probe warns about exactly this.
+
+## `acquireSandbox` answers 429
+
+The sandbox limit (`DORMICE_MAX_SANDBOXES`, default 100) gates
+*creation* only — waking an existing sandbox is never blocked. Before
+raising it, look at the disk-overcommit figure in
+[`getHostMetrics`](/docs/metrics): disk is the real ceiling, and past
+full even the ledger cannot write.
+
+## Creating from a template fails: "image … is not on this host"
+
+By design: [registration is configuration](/docs/templates) — the image
+is not checked when a name is registered, so the error surfaces at
+create time, named. `docker pull` or build the image on the daemon
+host, then retry.
+
+## A paused container won't `docker rm` by hand
+
+Only relevant when poking Docker directly: signals cannot be delivered
+to a paused gVisor container, so a force-remove waits and fails.
+`docker unpause` it first, then remove. The daemon's own destroy path
+already does this dance for you.
diff --git a/website/content/docs/upgrading.mdx b/website/content/docs/upgrading.mdx
new file mode 100644
index 0000000..4b6ac78
--- /dev/null
+++ b/website/content/docs/upgrading.mdx
@@ -0,0 +1,68 @@
+---
+title: Upgrading
+description: Re-running the installer is the upgrade — what survives, what restarts, and how sandbox images move.
+---
+
+The installer is idempotent: every step checks before it acts, and a
+step whose outcome is already in place says `[skip]` and touches
+nothing. **Re-running it is the upgrade** — it pulls the latest code,
+rebuilds the daemon, CLI and console, restarts the service, and proves
+the result by running `dor doctor` again:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash
+```
+
+Use the `curl | bash` form for upgrades. If you instead run a local copy
+(`bash /opt/dormice/deploy/install.sh`), know that its `git pull`
+updates the script file mid-run while bash keeps executing the *old*
+bytes — measured on a real upgrade. Run a local copy twice, or just
+pipe from the repo.
+
+## What survives an upgrade
+
+- **Your configuration.** `/etc/dormice/env` is never touched once it
+  exists — the API token is never rotated, and the recorded
+  `DORMICE_BASE_IMAGE` is kept (delete the file to regenerate).
+- **The ledger and every disk.** Everything under `/var/lib/dormice`
+  stays; schema migrations run forward automatically when the new
+  daemon boots — there is no manual migration step.
+- **The sandboxes.** A daemon restart does not touch containers: active
+  ones keep running, frozen ones stay frozen. The daemon is crash-only
+  by design — before it starts listening it reconciles the ledger
+  against what Docker actually shows, so restarting it is always safe.
+
+Two honest footnotes. The E2B process and watcher tables live in daemon
+memory: processes started over that surface keep running inside their
+containers across a restart, but the fresh daemon no longer lists them
+([details](/docs/e2b-differences)). And the pinned toolchain (Node,
+gVisor) is only *installed* when missing — an already-present gVisor is
+kept as-is, not upgraded.
+
+## Upgrading sandbox images
+
+The daemon upgrade above changes no sandbox's image — images move on a
+separate, per-sandbox path, because a container swap is visible to
+whoever is using the sandbox and should happen on your schedule:
+
+```sh
+docker build -t dormice-base:NEW -f images/Dockerfile images/
+# point DORMICE_BASE_IMAGE at the new tag in /etc/dormice/env, then:
+systemctl restart dormice
+dor sandbox rebuild <userKey>   # per sandbox, when it suits you
+```
+
+[Rebuild](/docs/persistence#rebuild-new-shell-same-body) swaps the
+container and keeps `/home/user` — nothing under it is lost. Sandboxes
+created from a [template](/docs/templates) follow the same rhythm with
+`dor template add` re-pointing the name first. Sandboxes you never
+rebuild simply keep running on the image they were born with.
+
+## When something looks wrong afterwards
+
+The installer refuses to call itself done until the daemon answers
+`/healthz` and `dor doctor` passes. If it stops early, the step that
+failed prints what it found; fix that and re-run — it continues from
+where it left off. The daemon's own story is in
+`journalctl -u dormice -f`, and [troubleshooting](/docs/troubleshooting)
+collects the failures that have actually happened.
diff --git a/website/src/lib/docs.ts b/website/src/lib/docs.ts
index 4e6df29..820616d 100644
--- a/website/src/lib/docs.ts
+++ b/website/src/lib/docs.ts
@@ -4,11 +4,15 @@ import type { JSX } from 'react';
 // content, not source, and stays portable across doc-shell rewrites.
 import * as architecture from '../../content/docs/architecture.mdx';
 import * as archiving from '../../content/docs/archiving.mdx';
+import * as cli from '../../content/docs/cli.mdx';
 import * as commands from '../../content/docs/commands.mdx';
 import * as configuration from '../../content/docs/configuration.mdx';
+import * as consoleDoc from '../../content/docs/console.mdx';
+import * as doctor from '../../content/docs/doctor.mdx';
 import * as e2bDifferences from '../../content/docs/e2b-differences.mdx';
 import * as e2bSdks from '../../content/docs/e2b-sdks.mdx';
 import * as files from '../../content/docs/files.mdx';
+import * as httpApi from '../../content/docs/http-api.mdx';
 import * as indexDoc from '../../content/docs/index.mdx';
 import * as installation from '../../content/docs/installation.mdx';
 import * as lifecycle from '../../content/docs/lifecycle.mdx';
@@ -19,6 +23,8 @@ import * as ports from '../../content/docs/ports.mdx';
 import * as quickstart from '../../content/docs/quickstart.mdx';
 import * as residentAgents from '../../content/docs/resident-agents.mdx';
 import * as templates from '../../content/docs/templates.mdx';
+import * as troubleshooting from '../../content/docs/troubleshooting.mdx';
+import * as upgrading from '../../content/docs/upgrading.mdx';
 
 // Server-only registry of every doc. MDX renders as server components, so
 // importing them all here costs the client nothing — pages ship as HTML.
@@ -48,6 +54,12 @@ const modules: Record<string, DocModule> = {
   'e2b-sdks': e2bSdks,
   'e2b-differences': e2bDifferences,
   configuration,
+  cli,
+  'http-api': httpApi,
+  console: consoleDoc,
+  doctor,
+  upgrading,
+  troubleshooting,
 };
 
 export interface DocEntry {

From f72ee264737393624fe1ad263120ffa9950f5f48 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 11 Jul 2026 17:35:20 +0800
Subject: [PATCH 054/133] Three observation verbs feed the console: an activity
 ring, effective config, per-sandbox metrics

---
 e2e/src/native.test.ts                        |  38 +++
 .../console/src/components/AppSidebar.tsx     |   4 +-
 .../console/src/features/activity/fixtures.ts | 111 -------
 .../features/activity/hooks/useActivity.ts    |  15 +
 .../features/activity/pages/ActivityPage.tsx  | 185 +++++++-----
 .../components/CreateSandboxDialog.tsx        |  52 +++-
 .../sandboxes/components/MetricsPanel.tsx     |  96 +++---
 .../sandboxes/components/RestoreCard.tsx      |  87 ++++++
 .../features/sandboxes/hooks/useSandboxes.ts  |  14 +
 .../sandboxes/pages/SandboxDetailPage.tsx     |  10 +-
 .../console/src/features/settings/fixtures.ts |  79 -----
 .../src/features/settings/hooks/useConfig.ts  |  16 +
 .../features/settings/pages/SettingsPage.tsx  |  88 ++++--
 packages/console/src/lib/api.ts               |  16 +
 packages/console/vite.config.ts               |   3 +
 packages/sdk/src/client.test.ts               |  35 +++
 packages/sdk/src/client.ts                    |  42 +++
 .../server/drizzle/0004_activity-ring.sql     |   8 +
 .../server/drizzle/meta/0004_snapshot.json    | 225 ++++++++++++++
 packages/server/drizzle/meta/_journal.json    |   7 +
 packages/server/src/app.ts                    |  17 +-
 packages/server/src/archive/archiver.ts       |  32 +-
 packages/server/src/config.ts                 |  48 +++
 packages/server/src/db/activity.ts            |  51 ++++
 packages/server/src/db/ledger.ts              |  10 +
 packages/server/src/db/schema.ts              |  24 +-
 packages/server/src/e2b/control.ts            |  19 +-
 packages/server/src/lifecycle.ts              |  67 ++++-
 packages/server/src/main.ts                   |   8 +
 packages/server/src/reconciler.ts             |  40 +++
 packages/server/src/routes/activity.ts        |  34 +++
 packages/server/src/routes/config.ts          |  47 +++
 .../server/src/routes/observability.test.ts   | 274 ++++++++++++++++++
 packages/server/src/routes/sandboxes.ts       |  32 ++
 packages/server/src/scanner.ts                |  22 +-
 packages/shared/src/activity.ts               |  60 ++++
 packages/shared/src/config.ts                 |  41 +++
 packages/shared/src/index.ts                  |   3 +
 packages/shared/src/metrics.ts                |  44 +++
 39 files changed, 1638 insertions(+), 366 deletions(-)
 delete mode 100644 packages/console/src/features/activity/fixtures.ts
 create mode 100644 packages/console/src/features/activity/hooks/useActivity.ts
 create mode 100644 packages/console/src/features/sandboxes/components/RestoreCard.tsx
 delete mode 100644 packages/console/src/features/settings/fixtures.ts
 create mode 100644 packages/console/src/features/settings/hooks/useConfig.ts
 create mode 100644 packages/server/drizzle/0004_activity-ring.sql
 create mode 100644 packages/server/drizzle/meta/0004_snapshot.json
 create mode 100644 packages/server/src/db/activity.ts
 create mode 100644 packages/server/src/routes/activity.ts
 create mode 100644 packages/server/src/routes/config.ts
 create mode 100644 packages/server/src/routes/observability.test.ts
 create mode 100644 packages/shared/src/activity.ts
 create mode 100644 packages/shared/src/config.ts
 create mode 100644 packages/shared/src/metrics.ts

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index 1f820bd..07a941b 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -405,3 +405,41 @@ describe('native API over a real daemon', () => {
     await client().releaseSandbox('host-metrics-key');
   });
 });
+
+describe('the observability verbs over a real daemon', () => {
+  it('getConfig reports effective knobs and never leaks the token', async () => {
+    const config = await client().getConfig();
+    const token = config.entries.find((e) => e.key === 'DORMICE_API_TOKEN');
+    expect(token).toMatchObject({ value: null, redacted: true });
+    // Black-box secrecy: the real token appears nowhere in the response.
+    expect(JSON.stringify(config)).not.toContain(inject('dormiceToken'));
+    // The exam daemon runs with miniS3 configured, so the daemon's own
+    // adjudication says archiving is live, with the one-week default.
+    expect(config.archive).toEqual({
+      enabled: true,
+      defaultSeconds: 7 * 24 * 60 * 60,
+    });
+  });
+
+  it('getSandboxMetrics samples a live sandbox and 404s after release', async () => {
+    await client().acquireSandbox('obs-metrics-key');
+    const sample = await client().getSandboxMetrics('obs-metrics-key');
+    expect(sample).not.toBeNull();
+    expect(sample?.memTotalBytes).toBeGreaterThan(0);
+    expect(sample?.diskTotalBytes).toBeGreaterThan(0);
+
+    await client().releaseSandbox('obs-metrics-key');
+    await expect(
+      client().getSandboxMetrics('obs-metrics-key'),
+    ).rejects.toMatchObject({ name: 'DormiceApiError', status: 404 });
+  });
+
+  it("listActivity tells one sandbox's story, newest first", async () => {
+    await client().acquireSandbox('obs-story-key');
+    await client().releaseSandbox('obs-story-key');
+    const events = await client().listActivity({ limit: 500 });
+    const mine = events.filter((e) => e.userKey === 'obs-story-key');
+    expect(mine.map((e) => e.kind)).toEqual(['released', 'created']);
+    expect(mine[1]?.detail).toContain('acquireSandbox');
+  });
+});
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index 0e4f536..c6bb2d6 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -51,9 +51,9 @@ const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
   {
     label: '运维',
     items: [
-      { to: '/activity', label: '活动', icon: Activity01Icon, mock: true },
+      { to: '/activity', label: '活动', icon: Activity01Icon },
       { to: '/doctor', label: '体检', icon: StethoscopeIcon, mock: true },
-      { to: '/settings', label: '设置', icon: Settings01Icon, mock: true },
+      { to: '/settings', label: '设置', icon: Settings01Icon },
     ],
   },
   {
diff --git a/packages/console/src/features/activity/fixtures.ts b/packages/console/src/features/activity/fixtures.ts
deleted file mode 100644
index 3d63b7d..0000000
--- a/packages/console/src/features/activity/fixtures.ts
+++ /dev/null
@@ -1,111 +0,0 @@
-/**
- * 提案中的 wire 形状:POST /listActivity 的响应行。事件将来自账本状态
- * 迁移处的单点埋点(transition/对账/扫描器),存 SQLite 有界环形表
- * (最近 N 条,溢出丢最老)— 是账本的历史,不是监控系统。落地时这些
- * 类型进 @dormice/shared,本文件只剩删除。
- */
-export type ActivityKind =
-  | 'created'
-  | 'woken'
-  | 'frozen'
-  | 'stopped'
-  | 'rebuilt'
-  | 'released'
-  | 'reconciled'
-  | 'expired-killed';
-
-export interface ActivityEvent {
-  id: string;
-  at: string;
-  kind: ActivityKind;
-  userKey: string | null;
-  /** 一句话补充:谁干的、为什么、修了什么。 */
-  detail: string;
-}
-
-export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
-  created: '创建',
-  woken: '唤醒',
-  frozen: '冻结',
-  stopped: '停止',
-  rebuilt: '重建',
-  released: '释放',
-  reconciled: '对账修复',
-  'expired-killed': '到期销毁',
-};
-
-const minutesAgo = (n: number) =>
-  new Date(Date.now() - n * 60_000).toISOString();
-
-export const SAMPLE_ACTIVITY: ActivityEvent[] = [
-  {
-    id: 'evt-01',
-    at: minutesAgo(1),
-    kind: 'frozen',
-    userKey: 'web-scraper',
-    detail: '空闲 5 分钟到阈值,内存挤入 swap(扫描器)',
-  },
-  {
-    id: 'evt-02',
-    at: minutesAgo(3),
-    kind: 'woken',
-    userKey: 'demo-agent',
-    detail: 'execCommand 触达,~50ms 从 frozen 恢复',
-  },
-  {
-    id: 'evt-03',
-    at: minutesAgo(12),
-    kind: 'created',
-    userKey: 'demo-agent',
-    detail: 'acquire 新建,模板 python-ml,策略 冻结 10分钟 · 停止 永不',
-  },
-  {
-    id: 'evt-04',
-    at: minutesAgo(25),
-    kind: 'rebuilt',
-    userKey: 'build-runner',
-    detail: '换壳保盘:下次唤醒用 daemon 当前基础镜像',
-  },
-  {
-    id: 'evt-05',
-    at: minutesAgo(41),
-    kind: 'stopped',
-    userKey: 'docs-writer',
-    detail: '空闲 30 分钟到阈值,容器拆除、磁盘保留(扫描器)',
-  },
-  {
-    id: 'evt-06',
-    at: minutesAgo(58),
-    kind: 'reconciled',
-    userKey: 'email-triage',
-    detail: '容器消失但磁盘还在(疑似 docker prune),账本改记 stopped',
-  },
-  {
-    id: 'evt-07',
-    at: minutesAgo(95),
-    kind: 'expired-killed',
-    userKey: 'ci-check-4821',
-    detail: 'E2B deadline(kill 型)到点,连盘一起销毁',
-  },
-  {
-    id: 'evt-08',
-    at: minutesAgo(130),
-    kind: 'released',
-    userKey: 'scratch-1',
-    detail: 'releaseSandbox:先拆容器再删账本行',
-  },
-  {
-    id: 'evt-09',
-    at: minutesAgo(178),
-    kind: 'created',
-    userKey: 'web-scraper',
-    detail: 'acquire 新建,基础镜像,默认策略',
-  },
-  {
-    id: 'evt-10',
-    at: minutesAgo(240),
-    kind: 'woken',
-    userKey: 'build-runner',
-    detail: '同 key acquire 从 stopped 冷启动重建(盘是本体)',
-  },
-];
diff --git a/packages/console/src/features/activity/hooks/useActivity.ts b/packages/console/src/features/activity/hooks/useActivity.ts
new file mode 100644
index 0000000..0eac9ef
--- /dev/null
+++ b/packages/console/src/features/activity/hooks/useActivity.ts
@@ -0,0 +1,15 @@
+import { useQuery } from '@tanstack/react-query';
+import { listActivity } from '@/lib/api';
+
+/**
+ * 活动流是观察窗:5 秒轮询即可 — 事件写在动作发生处,读只是翻账本,
+ * 比沙箱列表的 2 秒松一档(历史不像状态那样急着看)。
+ */
+export function useActivity() {
+  return useQuery({
+    queryKey: ['activity'],
+    queryFn: listActivity,
+    refetchInterval: 5000,
+    retry: false,
+  });
+}
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index aef335b..e516ce3 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -1,5 +1,5 @@
+import type { ActivityKind } from '@dormice/shared';
 import { Link } from '@tanstack/react-router';
-import { SampleDataBadge } from '@/components/SampleDataBadge';
 import { Badge } from '@/components/ui/badge';
 import {
   Empty,
@@ -7,6 +7,7 @@ import {
   EmptyHeader,
   EmptyTitle,
 } from '@/components/ui/empty';
+import { Spinner } from '@/components/ui/spinner';
 import {
   Table,
   TableBody,
@@ -16,13 +17,25 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { since } from '@/features/sandboxes/format';
-import { MOCK_PAGES_ENABLED } from '@/lib/mock';
 import { cn } from '@/lib/utils';
-import {
-  ACTIVITY_KIND_LABELS,
-  type ActivityKind,
-  SAMPLE_ACTIVITY,
-} from '../fixtures';
+import { useActivity } from '../hooks/useActivity';
+
+/** 事件的中文名 — 与 wire 上的 kind 一比一,这里是唯一的翻译点。 */
+export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
+  created: '创建',
+  woken: '唤醒',
+  frozen: '冻结',
+  stopped: '停止',
+  rebuilt: '重建',
+  released: '释放',
+  'expired-killed': '到期销毁',
+  archived: '归档',
+  'restore-started': '开始恢复',
+  restored: '恢复完成',
+  'restore-failed': '恢复失败',
+  reconciled: '对账修复',
+  'daemon-started': 'daemon 启动',
+};
 
 // 事件色与沙箱状态徽章同一色系:落到哪个状态就穿哪个颜色。
 const KIND_STYLES: Record<ActivityKind, string> = {
@@ -35,90 +48,106 @@ const KIND_STYLES: Record<ActivityKind, string> = {
   rebuilt:
     'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
   released: 'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
-  reconciled:
-    'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
   'expired-killed':
     'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
+  archived:
+    'border-indigo-500/40 bg-indigo-500/10 text-indigo-600 dark:text-indigo-400',
+  'restore-started':
+    'border-indigo-500/40 bg-indigo-500/10 text-indigo-600 dark:text-indigo-400',
+  restored:
+    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+  'restore-failed':
+    'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
+  reconciled:
+    'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
+  'daemon-started': 'border-border bg-muted text-muted-foreground',
 };
 
 /**
- * 「我不在的时候发生了什么」。生产里等 /listActivity 落地(账本迁移处
- * 单点埋点 + 有界环形表);眼下用示例数据把版式定下来,生产构建整页隐藏。
+ * 「我不在的时候发生了什么」:daemon 每一次生命周期动作(创建、降温、
+ * 唤醒、销毁)和对账修复的有界环形记录 — 事件写在动作发生处,这里只读。
  */
 export function ActivityPage() {
-  if (!MOCK_PAGES_ENABLED) {
-    return (
-      <Empty className="border border-dashed">
-        <EmptyHeader>
-          <EmptyTitle>尚未接入</EmptyTitle>
-          <EmptyDescription>
-            活动流等 listActivity 端点落地后可用。
-          </EmptyDescription>
-        </EmptyHeader>
-      </Empty>
-    );
-  }
+  const { data, isPending, isError, error } = useActivity();
 
   return (
     <>
-      <div className="flex flex-wrap items-center gap-3">
-        <div>
-          <h1 className="flex items-center gap-2 text-lg font-semibold">
-            活动 <SampleDataBadge />
-          </h1>
-          <p className="text-sm text-muted-foreground">
-            账本的历史:谁被创建、冻结、停止、销毁,对账修了什么。 将来自
-            transition() 单点埋点的有界环形记录。
-          </p>
-        </div>
+      <div>
+        <h1 className="text-lg font-semibold">活动</h1>
+        <p className="text-sm text-muted-foreground">
+          账本的历史:谁被创建、冻结、停止、销毁,对账修了什么。保留最近 1000
+          条,更老的自然滚出。
+        </p>
       </div>
 
-      <div className="overflow-x-auto rounded-lg border">
-        <Table>
-          <TableHeader>
-            <TableRow>
-              <TableHead className="w-28">时间</TableHead>
-              <TableHead className="w-28">事件</TableHead>
-              <TableHead className="w-40">userKey</TableHead>
-              <TableHead>详情</TableHead>
-            </TableRow>
-          </TableHeader>
-          <TableBody>
-            {SAMPLE_ACTIVITY.map((event) => (
-              <TableRow key={event.id}>
-                <TableCell className="tabular-nums text-muted-foreground">
-                  {since(event.at)}前
-                </TableCell>
-                <TableCell>
-                  <Badge
-                    variant="outline"
-                    className={cn('font-medium', KIND_STYLES[event.kind])}
-                  >
-                    {ACTIVITY_KIND_LABELS[event.kind]}
-                  </Badge>
-                </TableCell>
-                <TableCell>
-                  {event.userKey ? (
-                    <Link
-                      to="/sandboxes/$userKey"
-                      params={{ userKey: event.userKey }}
-                      search={{ tab: 'overview' as const }}
-                      className="font-mono hover:underline"
-                    >
-                      {event.userKey}
-                    </Link>
-                  ) : (
-                    <span className="text-muted-foreground">—</span>
-                  )}
-                </TableCell>
-                <TableCell className="text-muted-foreground">
-                  {event.detail}
-                </TableCell>
+      {isPending ? (
+        <div className="flex items-center gap-2 text-sm text-muted-foreground">
+          <Spinner /> 读取活动…
+        </div>
+      ) : isError ? (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyTitle>读取失败</EmptyTitle>
+            <EmptyDescription>{error.message}</EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      ) : data.events.length === 0 ? (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyTitle>还没有活动</EmptyTitle>
+            <EmptyDescription>
+              创建一个沙箱,它的整个生命周期就会出现在这里。
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      ) : (
+        <div className="overflow-x-auto rounded-lg border">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead className="w-28">时间</TableHead>
+                <TableHead className="w-28">事件</TableHead>
+                <TableHead className="w-40">userKey</TableHead>
+                <TableHead>详情</TableHead>
               </TableRow>
-            ))}
-          </TableBody>
-        </Table>
-      </div>
+            </TableHeader>
+            <TableBody>
+              {data.events.map((event) => (
+                <TableRow key={event.id}>
+                  <TableCell className="tabular-nums text-muted-foreground">
+                    {since(event.at)}前
+                  </TableCell>
+                  <TableCell>
+                    <Badge
+                      variant="outline"
+                      className={cn('font-medium', KIND_STYLES[event.kind])}
+                    >
+                      {ACTIVITY_KIND_LABELS[event.kind]}
+                    </Badge>
+                  </TableCell>
+                  <TableCell>
+                    {event.userKey ? (
+                      <Link
+                        to="/sandboxes/$userKey"
+                        params={{ userKey: event.userKey }}
+                        search={{ tab: 'overview' as const }}
+                        className="font-mono hover:underline"
+                      >
+                        {event.userKey}
+                      </Link>
+                    ) : (
+                      <span className="text-muted-foreground">—</span>
+                    )}
+                  </TableCell>
+                  <TableCell className="text-muted-foreground">
+                    {event.detail}
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </div>
+      )}
     </>
   );
 }
diff --git a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
index 5d4deaf..9dc4be1 100644
--- a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
+++ b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
@@ -27,6 +27,7 @@ import {
 } from '@/components/ui/native-select';
 import { Spinner } from '@/components/ui/spinner';
 import { Switch } from '@/components/ui/switch';
+import { useConfig } from '@/features/settings/hooks/useConfig';
 import { useTemplates } from '@/features/templates/hooks/useTemplates';
 import { useAcquireSandbox } from '../hooks/useSandboxes';
 
@@ -35,9 +36,11 @@ import { useAcquireSandbox } from '../hooks/useSandboxes';
  * same sandbox — "creating" an existing key just returns it (the policy
  * override only applies when the acquire actually creates).
  *
- * The two policy knobs are optional; empty means the daemon's default.
- * Archive has no knob here on purpose: there is no archiver yet, so the
- * only honest value is the default (never).
+ * The policy knobs are optional; empty means the daemon's default. The
+ * archive knob only exists when the daemon says archiving is available
+ * (getConfig's adjudication) — an unconfigured feature stays honestly
+ * absent. A never-stop sandbox never reaches stopped, so its archive knob
+ * disappears too.
  */
 export function CreateSandboxDialog() {
   const [open, setOpen] = useState(false);
@@ -46,8 +49,11 @@ export function CreateSandboxDialog() {
   const [freezeAfter, setFreezeAfter] = useState('');
   const [neverStop, setNeverStop] = useState(false);
   const [stopAfter, setStopAfter] = useState('');
+  const [neverArchive, setNeverArchive] = useState(false);
+  const [archiveAfter, setArchiveAfter] = useState('');
   const mutation = useAcquireSandbox();
   const templates = useTemplates().data?.templates ?? [];
+  const archive = useConfig().data?.archive;
 
   const reset = () => {
     setUserKey('');
@@ -55,6 +61,8 @@ export function CreateSandboxDialog() {
     setFreezeAfter('');
     setNeverStop(false);
     setStopAfter('');
+    setNeverArchive(false);
+    setArchiveAfter('');
     mutation.reset();
   };
 
@@ -63,6 +71,11 @@ export function CreateSandboxDialog() {
     if (freezeAfter !== '') policy.freezeAfterSeconds = Number(freezeAfter);
     if (neverStop) policy.stopAfterSeconds = null;
     else if (stopAfter !== '') policy.stopAfterSeconds = Number(stopAfter);
+    if (archive?.enabled && !neverStop) {
+      if (neverArchive) policy.archiveAfterSeconds = null;
+      else if (archiveAfter !== '')
+        policy.archiveAfterSeconds = Number(archiveAfter);
+    }
 
     mutation.mutate(
       {
@@ -191,6 +204,39 @@ export function CreateSandboxDialog() {
                 </FieldDescription>
               </Field>
             )}
+            {archive?.enabled && !neverStop && (
+              <>
+                <Field orientation="horizontal">
+                  <Switch
+                    id="create-never-archive"
+                    checked={neverArchive}
+                    onCheckedChange={setNeverArchive}
+                  />
+                  <FieldLabel htmlFor="create-never-archive">
+                    永不归档
+                  </FieldLabel>
+                </Field>
+                {!neverArchive && (
+                  <Field>
+                    <FieldLabel htmlFor="create-archive-after">
+                      空闲多久后归档(秒)
+                    </FieldLabel>
+                    <Input
+                      id="create-archive-after"
+                      type="number"
+                      min={1}
+                      value={archiveAfter}
+                      onChange={(event) => setArchiveAfter(event.target.value)}
+                      placeholder={`${archive.defaultSeconds ?? ''}(daemon 默认)`}
+                    />
+                    <FieldDescription>
+                      已停止 → 已归档:磁盘压缩上传 S3,本地零占用;
+                      唤醒要下载解压,慢但有真进度。
+                    </FieldDescription>
+                  </Field>
+                )}
+              </>
+            )}
             {mutation.isError && (
               <FieldError>{mutation.error.message}</FieldError>
             )}
diff --git a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
index 1ef608e..dc10dfd 100644
--- a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
@@ -5,7 +5,6 @@ import {
   RamMemoryIcon,
 } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
-import { SampleDataBadge } from '@/components/SampleDataBadge';
 import { Card, CardContent } from '@/components/ui/card';
 import {
   Empty,
@@ -13,34 +12,11 @@ import {
   EmptyHeader,
   EmptyTitle,
 } from '@/components/ui/empty';
+import { Spinner } from '@/components/ui/spinner';
 import { formatBytes, pctOf } from '@/lib/format';
-import { MOCK_PAGES_ENABLED } from '@/lib/mock';
 import { cn } from '@/lib/utils';
-
-/**
- * 提案中的 wire 形状:原生 POST /getSandboxMetrics { userKey } 的响应。
- * 单次快照,与 getHostMetrics/E2B getMetrics 同一原则 — 观察窗不是监控
- * 系统;执行器的 metrics() 动词已经存在,服务端落地时这个类型进 shared。
- */
-interface SandboxMetricsSample {
-  timestamp: string;
-  cpuCount: number;
-  cpuUsedPct: number;
-  memUsedBytes: number;
-  memTotalBytes: number;
-  diskUsedBytes: number;
-  diskTotalBytes: number;
-}
-
-const SAMPLE: SandboxMetricsSample = {
-  timestamp: new Date().toISOString(),
-  cpuCount: 2,
-  cpuUsedPct: 23.4,
-  memUsedBytes: 412 * 1024 * 1024,
-  memTotalBytes: 2 * 1024 * 1024 * 1024,
-  diskUsedBytes: 68.2 * 1024 * 1024,
-  diskTotalBytes: 10 * 1024 * 1024 * 1024,
-};
+import { since } from '../format';
+import { useSandboxMetrics } from '../hooks/useSandboxes';
 
 function Meter({ pct }: { pct: number }) {
   const clamped = Math.min(100, Math.max(0, pct));
@@ -89,19 +65,41 @@ function MetricCard({
 }
 
 /**
- * 单沙箱指标。控制台走 cookie,而 E2B 的 metrics 端点只认 API key,
- * 浏览器刻意拿不到 — 所以这一面要等原生 /getSandboxMetrics 动词落地,
- * 眼下先用示例数据把版式定下来(执行器侧 metrics() 已经存在,缺的只是
- * 一个原生路由)。
+ * 单沙箱指标:5 秒一拍的单次快照(观察窗不是监控系统)。观察不唤醒 —
+ * 冻结的沙箱睡着也能读(cgroup 记账还在),停了的沙箱没有容器可测,
+ * daemon 答 null,这里出空态而不是把它吵醒。
  */
-export function MetricsPanel(_props: { sandbox: Sandbox }) {
-  if (!MOCK_PAGES_ENABLED) {
+export function MetricsPanel({ sandbox }: { sandbox: Sandbox }) {
+  const { data, isPending, isError, error } = useSandboxMetrics(
+    sandbox.userKey,
+  );
+
+  if (isPending) {
+    return (
+      <div className="flex items-center gap-2 text-sm text-muted-foreground">
+        <Spinner /> 读取指标…
+      </div>
+    );
+  }
+  if (isError) {
     return (
       <Empty className="border border-dashed">
         <EmptyHeader>
-          <EmptyTitle>尚未接入</EmptyTitle>
+          <EmptyTitle>读取失败</EmptyTitle>
+          <EmptyDescription>{error.message}</EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    );
+  }
+  const sample = data.sample;
+  if (sample === null) {
+    return (
+      <Empty className="border border-dashed">
+        <EmptyHeader>
+          <EmptyTitle>没有运行中的容器可测</EmptyTitle>
           <EmptyDescription>
-            单沙箱指标等原生 getSandboxMetrics 动词落地后可用。
+            沙箱现在没有活着的容器(已停止/已归档)。观察不唤醒 —
+            打开终端或执行命令才会把它叫醒。
           </EmptyDescription>
         </EmptyHeader>
       </Empty>
@@ -110,36 +108,32 @@ export function MetricsPanel(_props: { sandbox: Sandbox }) {
 
   return (
     <div className="flex flex-col gap-3">
-      <div className="flex items-center gap-2">
-        <SampleDataBadge />
-        <span className="text-sm text-muted-foreground">
-          版式预览 — 接入原生 getSandboxMetrics 后换真数据(单次快照,
-          观察不唤醒)。
-        </span>
-      </div>
       <div className="grid gap-4 sm:grid-cols-2 xl:grid-cols-3">
         <MetricCard
           icon={CpuIcon}
           label="CPU"
-          value={`${Math.round(SAMPLE.cpuUsedPct)}%`}
-          hint={`${SAMPLE.cpuCount} 核`}
-          pct={SAMPLE.cpuUsedPct}
+          value={`${Math.round(sample.cpuUsedPct)}%`}
+          hint={`${sample.cpuCount} 核 · 百分比按单核计`}
+          pct={sample.cpuUsedPct / sample.cpuCount}
         />
         <MetricCard
           icon={RamMemoryIcon}
           label="内存"
-          value={formatBytes(SAMPLE.memUsedBytes)}
-          hint={`共 ${formatBytes(SAMPLE.memTotalBytes)}`}
-          pct={pctOf(SAMPLE.memUsedBytes, SAMPLE.memTotalBytes)}
+          value={formatBytes(sample.memUsedBytes)}
+          hint={`共 ${formatBytes(sample.memTotalBytes)} · 缓存 ${formatBytes(sample.memCacheBytes)}`}
+          pct={pctOf(sample.memUsedBytes, sample.memTotalBytes)}
         />
         <MetricCard
           icon={HardDriveIcon}
           label="磁盘"
-          value={formatBytes(SAMPLE.diskUsedBytes)}
-          hint={`名义 ${formatBytes(SAMPLE.diskTotalBytes)} — 稀疏镜像只为真实内容付费`}
-          pct={pctOf(SAMPLE.diskUsedBytes, SAMPLE.diskTotalBytes)}
+          value={formatBytes(sample.diskUsedBytes)}
+          hint={`名义 ${formatBytes(sample.diskTotalBytes)} — 稀疏镜像只为真实内容付费`}
+          pct={pctOf(sample.diskUsedBytes, sample.diskTotalBytes)}
         />
       </div>
+      <p className="text-xs text-muted-foreground">
+        单次快照,5 秒刷新;本次读数取自 {since(sample.timestamp)}前。
+      </p>
     </div>
   );
 }
diff --git a/packages/console/src/features/sandboxes/components/RestoreCard.tsx b/packages/console/src/features/sandboxes/components/RestoreCard.tsx
new file mode 100644
index 0000000..2fd10fa
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/RestoreCard.tsx
@@ -0,0 +1,87 @@
+import type { Sandbox } from '@dormice/shared';
+import { DatabaseRestoreIcon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent } from '@/components/ui/card';
+import { Progress } from '@/components/ui/progress';
+import { Spinner } from '@/components/ui/spinner';
+import { acquireSandbox } from '@/lib/api';
+
+/**
+ * 归档态的工作台横幅。已归档:磁盘在 S3、本地零占用,给一个显式的
+ * 「恢复」动作(就是 acquire — 平台从头到尾只有这一个入口动词)。
+ * 恢复中:轮询 acquire 拿真进度 — 协议的承诺就是"acquire 撞 restoring
+ * 立即返回进度",对 restoring 行它没有副作用,所以放心每 1.5 秒问一次;
+ * 恢复完成后 2 秒轮询的列表会把状态翻回 active,这张卡自然消失。
+ */
+export function RestoreCard({ sandbox }: { sandbox: Sandbox }) {
+  const queryClient = useQueryClient();
+  const restoring = sandbox.state === 'restoring';
+
+  const progressQuery = useQuery({
+    queryKey: ['restore-progress', sandbox.userKey],
+    queryFn: () => acquireSandbox({ userKey: sandbox.userKey }),
+    enabled: restoring,
+    refetchInterval: 1500,
+    retry: false,
+  });
+  const begin = useMutation({
+    mutationFn: () => acquireSandbox({ userKey: sandbox.userKey }),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
+    onError: (error) => toast.error(`恢复没能开始:${error.message}`),
+  });
+
+  if (restoring) {
+    const progress =
+      progressQuery.data?.status === 'restoring'
+        ? progressQuery.data.progress
+        : undefined;
+    return (
+      <Card size="sm">
+        <CardContent className="flex flex-col gap-3">
+          <div className="flex items-center gap-2 text-sm font-medium">
+            <Spinner />
+            正在从 S3 恢复 —{' '}
+            {progress?.phase === 'extracting' ? '解压到新盘' : '下载归档'}
+            {progress ? ` ${progress.percent}%` : ''}
+          </div>
+          <Progress value={progress?.percent ?? 0} />
+          <p className="text-xs text-muted-foreground">
+            恢复完成后自动回到「运行中」;期间释放会被拒绝(409),等它跑完。
+          </p>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <Card size="sm">
+      <CardContent className="flex flex-wrap items-center justify-between gap-3">
+        <div className="flex flex-col gap-1">
+          <div className="flex items-center gap-2 text-sm font-medium">
+            <HugeiconsIcon
+              icon={DatabaseRestoreIcon}
+              className="size-4"
+              strokeWidth={1.8}
+            />
+            已归档:磁盘压缩存放在 S3,本地零占用
+          </div>
+          <p className="text-xs text-muted-foreground">
+            恢复 = 下载归档并解压到一块新盘,再按模板当前镜像重建容器 —
+            也就是恢复即升级。终端/文件要等恢复完成后才可用。
+          </p>
+        </div>
+        <Button
+          size="sm"
+          onClick={() => begin.mutate()}
+          disabled={begin.isPending}
+        >
+          {begin.isPending && <Spinner />}
+          恢复
+        </Button>
+      </CardContent>
+    </Card>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
index e10c19f..30f2655 100644
--- a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
+++ b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
@@ -2,6 +2,7 @@ import type { AcquireRequest } from '@dormice/shared';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import {
   acquireSandbox,
+  getSandboxMetrics,
   listSandboxes,
   rebuildSandbox,
   releaseSandbox,
@@ -32,6 +33,19 @@ export function useSandbox(userKey: string) {
   };
 }
 
+/**
+ * 单沙箱指标,5 秒一拍。观察不唤醒:停着的沙箱答 sample: null,面板
+ * 据此出空态而不是把沙箱吵醒。只在指标 tab 挂载时才跑(面板卸载即停)。
+ */
+export function useSandboxMetrics(userKey: string) {
+  return useQuery({
+    queryKey: ['sandbox-metrics', userKey],
+    queryFn: () => getSandboxMetrics(userKey),
+    refetchInterval: 5000,
+    retry: false,
+  });
+}
+
 export function useAcquireSandbox() {
   const queryClient = useQueryClient();
   return useMutation({
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index c940d38..93fd04c 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -15,12 +15,12 @@ import {
   EmptyTitle,
 } from '@/components/ui/empty';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
-import { MOCK_PAGES_ENABLED } from '@/lib/mock';
 import { FilesPanel } from '../components/FilesPanel';
 import { MetricsPanel } from '../components/MetricsPanel';
 import { ProcessesPanel } from '../components/ProcessesPanel';
 import { RebuildSandboxButton } from '../components/RebuildSandboxButton';
 import { ReleaseSandboxButton } from '../components/ReleaseSandboxButton';
+import { RestoreCard } from '../components/RestoreCard';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
 import { SandboxTerminalCard } from '../components/SandboxTerminal';
 import { formatDuration, since } from '../format';
@@ -95,6 +95,10 @@ export function SandboxDetailPage() {
         </div>
       </div>
 
+      {(sandbox.state === 'archived' || sandbox.state === 'restoring') && (
+        <RestoreCard sandbox={sandbox} />
+      )}
+
       <Tabs
         value={tab}
         onValueChange={(next) =>
@@ -109,9 +113,7 @@ export function SandboxDetailPage() {
           <TabsTrigger value="terminal">终端</TabsTrigger>
           <TabsTrigger value="files">文件</TabsTrigger>
           <TabsTrigger value="processes">进程</TabsTrigger>
-          {MOCK_PAGES_ENABLED && (
-            <TabsTrigger value="metrics">指标</TabsTrigger>
-          )}
+          <TabsTrigger value="metrics">指标</TabsTrigger>
         </TabsList>
 
         <TabsContent value="overview">
diff --git a/packages/console/src/features/settings/fixtures.ts b/packages/console/src/features/settings/fixtures.ts
deleted file mode 100644
index 3687c05..0000000
--- a/packages/console/src/features/settings/fixtures.ts
+++ /dev/null
@@ -1,79 +0,0 @@
-/**
- * 提案中的 wire 形状:POST /getConfig 的响应行 — daemon 生效配置的只读
- * 快照(查生效值,与 doctor 同一条纪律)。敏感值只报"已设置",绝不回传
- * 内容。落地时类型进 shared,本文件只剩删除。
- */
-export interface ConfigEntry {
-  key: string;
-  /** 生效值;敏感项为 null,配 redacted: true。 */
-  value: string | null;
-  /** 值从哪来:环境变量显式给的,还是代码里的默认值。 */
-  source: 'env' | 'default';
-  redacted?: boolean;
-  /** 这个旋钮管什么,一句话。 */
-  hint: string;
-}
-
-export const SAMPLE_CONFIG: ConfigEntry[] = [
-  {
-    key: 'DORMICE_API_TOKEN',
-    value: null,
-    source: 'env',
-    redacted: true,
-    hint: '唯一的 API 凭证;控制台登录时换成 httpOnly cookie,页面永远读不到它',
-  },
-  {
-    key: 'DORMICE_EXECUTOR',
-    value: 'docker',
-    source: 'env',
-    hint: '执行器:docker 是真沙箱,fake 是内存假执行器(开发/测试用)',
-  },
-  {
-    key: 'DORMICE_BASE_IMAGE',
-    value: 'dormice-base:20260710b',
-    source: 'env',
-    hint: '沙箱的默认镜像;docker 模式必填,启动即校验存在',
-  },
-  {
-    key: 'DORMICE_DB_PATH',
-    value: '/var/lib/dormice/dormice.db',
-    source: 'env',
-    hint: 'SQLite 账本;docker 模式强制绝对路径',
-  },
-  {
-    key: 'DORMICE_DATA_DIR',
-    value: '/var/lib/dormice',
-    source: 'env',
-    hint: '沙箱磁盘镜像的家(disks/*.img)',
-  },
-  {
-    key: 'DORMICE_PORT',
-    value: '3676',
-    source: 'default',
-    hint: 'daemon 端口;只绑 127.0.0.1,对外暴露是反向代理的活',
-  },
-  {
-    key: 'DORMICE_MAX_SANDBOXES',
-    value: '100',
-    source: 'default',
-    hint: '创建上限(撞上回 429);唤醒永不受限 — 磁盘才是真瓶颈',
-  },
-  {
-    key: 'DORMICE_SCAN_INTERVAL_SECONDS',
-    value: '60',
-    source: 'default',
-    hint: '空闲扫描周期:每一轮把到阈值的沙箱降一格温度',
-  },
-  {
-    key: 'DORMICE_SANDBOX_MEMORY_GB',
-    value: '2',
-    source: 'default',
-    hint: '每个沙箱的内存上限;沙箱内 OOM 会让 gVisor 整箱退出(对账救回)',
-  },
-  {
-    key: 'DORMICE_SANDBOX_DOMAIN',
-    value: null,
-    source: 'default',
-    hint: '端口预览域名(getHost);不配则响应里诚实缺席,代理层不启用',
-  },
-];
diff --git a/packages/console/src/features/settings/hooks/useConfig.ts b/packages/console/src/features/settings/hooks/useConfig.ts
new file mode 100644
index 0000000..7883254
--- /dev/null
+++ b/packages/console/src/features/settings/hooks/useConfig.ts
@@ -0,0 +1,16 @@
+import { useQuery } from '@tanstack/react-query';
+import { getConfig } from '@/lib/api';
+
+/**
+ * 生效配置基本不变(改它要动 env + 重启 daemon),不轮询;窗口重新聚焦
+ * 时的默认 refetch 已经足够新鲜。创建沙箱表单也吃它 — archive.enabled
+ * 决定归档旋钮是否存在。
+ */
+export function useConfig() {
+  return useQuery({
+    queryKey: ['config'],
+    queryFn: getConfig,
+    staleTime: 30_000,
+    retry: false,
+  });
+}
diff --git a/packages/console/src/features/settings/pages/SettingsPage.tsx b/packages/console/src/features/settings/pages/SettingsPage.tsx
index 934136f..9595f9b 100644
--- a/packages/console/src/features/settings/pages/SettingsPage.tsx
+++ b/packages/console/src/features/settings/pages/SettingsPage.tsx
@@ -1,4 +1,4 @@
-import { SampleDataBadge } from '@/components/SampleDataBadge';
+import type { ConfigEntry } from '@dormice/shared';
 import { Badge } from '@/components/ui/badge';
 import {
   Empty,
@@ -6,6 +6,7 @@ import {
   EmptyHeader,
   EmptyTitle,
 } from '@/components/ui/empty';
+import { Spinner } from '@/components/ui/spinner';
 import {
   Table,
   TableBody,
@@ -14,8 +15,49 @@ import {
   TableHeader,
   TableRow,
 } from '@/components/ui/table';
-import { MOCK_PAGES_ENABLED } from '@/lib/mock';
-import { SAMPLE_CONFIG } from '../fixtures';
+import { formatDuration } from '@/features/sandboxes/format';
+import { useConfig } from '../hooks/useConfig';
+
+/**
+ * 每个旋钮管什么,一句话 — UI 文案,所以住在前端;wire 上只有键、值、
+ * 来源(daemon 不说中文)。没列到的键显示为空,不编造。
+ */
+const KEY_HINTS: Record<string, string> = {
+  DORMICE_PORT: 'daemon 端口;只绑 127.0.0.1,对外暴露是反向代理的活',
+  DORMICE_DB_PATH: 'SQLite 账本;docker 模式强制绝对路径',
+  DORMICE_NODE_ID: '这台机器在账本里的名字(为将来分片预留)',
+  DORMICE_API_TOKEN:
+    '唯一的 API 凭证;控制台登录时换成 httpOnly cookie,页面永远读不到它',
+  DORMICE_EXECUTOR: '执行器:docker 是真沙箱,fake 是内存假执行器(开发/测试用)',
+  DORMICE_BASE_IMAGE: '沙箱的默认镜像;docker 模式必填',
+  DORMICE_DATA_DIR: '沙箱磁盘镜像的家(disks/*.img);归档临时文件也在这里',
+  DORMICE_MAX_SANDBOXES: '创建上限(撞上回 429);唤醒永不受限 — 磁盘才是真瓶颈',
+  DORMICE_SCAN_INTERVAL_SECONDS: '空闲扫描周期:每一轮把到阈值的沙箱降一格温度',
+  DORMICE_SANDBOX_DISK_GB: '每个沙箱磁盘的名义大小;稀疏镜像只为真实内容付费',
+  DORMICE_SANDBOX_CPUS: '每个沙箱的 CPU 配额',
+  DORMICE_SANDBOX_MEMORY_GB:
+    '每个沙箱的内存上限;沙箱内 OOM 会让 gVisor 整箱退出(对账救回)',
+  DORMICE_SANDBOX_PIDS_LIMIT: '每个沙箱的进程数上限(fork 炸弹的物理闸)',
+  DORMICE_RECLAIM_TIMEOUT_SECONDS: '冻结时挤内存进 swap 的最长等待',
+  DORMICE_SANDBOX_DOMAIN:
+    '端口预览泛域名(getHost);不配则响应里诚实缺席,代理层不启用',
+  DORMICE_S3_ENDPOINT: '归档对象存储的地址;四件套齐了归档才启用',
+  DORMICE_S3_BUCKET: '归档桶名',
+  DORMICE_S3_ACCESS_KEY_ID: '归档存储的 Access Key(只报已设置)',
+  DORMICE_S3_SECRET_ACCESS_KEY: '归档存储的 Secret Key(只报已设置)',
+  DORMICE_S3_REGION: 'S3 区域;多数兼容实现随意',
+  DORMICE_S3_FORCE_PATH_STYLE: '路径风格寻址:MinIO 要 true,云厂商走子域名',
+};
+
+function ValueCell({ entry }: { entry: ConfigEntry }) {
+  if (entry.redacted) {
+    return <Badge variant="secondary">已设置,不显示</Badge>;
+  }
+  if (entry.value === null) {
+    return <span className="text-muted-foreground">未配置</span>;
+  }
+  return <>{entry.value}</>;
+}
 
 /**
  * daemon 生效配置的只读观察窗:回答"这台 daemon 开了哪些旋钮"。刻意
@@ -23,15 +65,21 @@ import { SAMPLE_CONFIG } from '../fixtures';
  * 改配置意味着 daemon 要能写自己的配置文件,那是另一个安全等级的决定。
  */
 export function SettingsPage() {
-  if (!MOCK_PAGES_ENABLED) {
+  const { data, isPending, isError, error } = useConfig();
+
+  if (isPending) {
+    return (
+      <div className="flex items-center gap-2 text-sm text-muted-foreground">
+        <Spinner /> 读取生效配置…
+      </div>
+    );
+  }
+  if (isError) {
     return (
       <Empty className="border border-dashed">
         <EmptyHeader>
-          <EmptyTitle>尚未接入</EmptyTitle>
-          <EmptyDescription>
-            生效配置视图等 getConfig 端点落地后可用;现在请看主机上的{' '}
-            <code className="font-mono">/etc/dormice/env</code>。
-          </EmptyDescription>
+          <EmptyTitle>读取失败</EmptyTitle>
+          <EmptyDescription>{error.message}</EmptyDescription>
         </EmptyHeader>
       </Empty>
     );
@@ -40,13 +88,15 @@ export function SettingsPage() {
   return (
     <>
       <div>
-        <h1 className="flex items-center gap-2 text-lg font-semibold">
-          设置 <SampleDataBadge />
-        </h1>
+        <h1 className="text-lg font-semibold">设置</h1>
         <p className="text-sm text-muted-foreground">
           daemon 的生效配置,只读。改配置在主机的{' '}
           <code className="font-mono">/etc/dormice/env</code>,改完{' '}
-          <code className="font-mono">systemctl restart dormice</code>。
+          <code className="font-mono">systemctl restart dormice</code>。归档:
+          {data.archive.enabled
+            ? `已启用(默认停止后 ${formatDuration(data.archive.defaultSeconds ?? 0)} 归档)`
+            : '未启用 — 配齐 DORMICE_S3_* 四件套后可用'}
+          。
         </p>
       </div>
 
@@ -61,19 +111,13 @@ export function SettingsPage() {
             </TableRow>
           </TableHeader>
           <TableBody>
-            {SAMPLE_CONFIG.map((entry) => (
+            {data.entries.map((entry) => (
               <TableRow key={entry.key}>
                 <TableCell className="font-mono text-xs font-medium">
                   {entry.key}
                 </TableCell>
                 <TableCell className="font-mono text-xs">
-                  {entry.redacted ? (
-                    <Badge variant="secondary">已设置,不显示</Badge>
-                  ) : entry.value === null ? (
-                    <span className="text-muted-foreground">未配置</span>
-                  ) : (
-                    entry.value
-                  )}
+                  <ValueCell entry={entry} />
                 </TableCell>
                 <TableCell>
                   <Badge
@@ -83,7 +127,7 @@ export function SettingsPage() {
                   </Badge>
                 </TableCell>
                 <TableCell className="text-sm text-muted-foreground">
-                  {entry.hint}
+                  {KEY_HINTS[entry.key] ?? ''}
                 </TableCell>
               </TableRow>
             ))}
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 75d0fa3..a405f35 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -1,7 +1,10 @@
 import type {
   AcquireRequest,
   AcquireResponse,
+  GetConfigResponse,
+  GetSandboxMetricsResponse,
   HostMetricsResponse,
+  ListActivityResponse,
   RegisterTemplateResponse,
   Sandbox,
   Template,
@@ -87,6 +90,19 @@ export const listSandboxes = () =>
 // Pure observation — the daemon wakes nothing to answer it.
 export const getHostMetrics = () => rpc<HostMetricsResponse>('/getHostMetrics');
 
+// One sandbox's point-in-time reading. Same principle: a frozen sandbox is
+// measured as it sleeps, a stopped one answers sample: null — never woken.
+export const getSandboxMetrics = (userKey: string) =>
+  rpc<GetSandboxMetricsResponse>('/getSandboxMetrics', { userKey });
+
+// The ledger's recent history, newest first — a bounded ring, not an audit
+// log. The daemon records at the moves themselves; this only reads.
+export const listActivity = () => rpc<ListActivityResponse>('/listActivity');
+
+// Effective configuration, read-only. Secrets come back as "set", never as
+// their value; archive.enabled is the daemon's own adjudication.
+export const getConfig = () => rpc<GetConfigResponse>('/getConfig');
+
 export const listTemplates = () =>
   rpc<{ templates: Template[] }>('/listTemplates');
 
diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index d56323f..a8309c0 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -32,6 +32,9 @@ export default defineConfig({
       '/registerTemplate': 'http://127.0.0.1:3676',
       '/removeTemplate': 'http://127.0.0.1:3676',
       '/getHostMetrics': 'http://127.0.0.1:3676',
+      '/getSandboxMetrics': 'http://127.0.0.1:3676',
+      '/listActivity': 'http://127.0.0.1:3676',
+      '/getConfig': 'http://127.0.0.1:3676',
       // The terminal speaks the envd surface directly, like the e2b SDK.
       '/e2b': 'http://127.0.0.1:3676',
     },
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 1191fab..54bf3f8 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -337,3 +337,38 @@ describe('templates over real HTTP', () => {
     });
   });
 });
+
+describe('the observability verbs over real HTTP', () => {
+  it('getConfig reports the knobs and withholds the token', async () => {
+    // Source attribution is asserted server-side with injected sources;
+    // this test app reads the real process.env, which proves nothing here.
+    const config = await client.getConfig();
+    const token = config.entries.find((e) => e.key === 'DORMICE_API_TOKEN');
+    expect(token).toMatchObject({ value: null, redacted: true });
+    const port = config.entries.find((e) => e.key === 'DORMICE_PORT');
+    expect(port).toMatchObject({ value: '3676' });
+    expect(config.archive.enabled).toBe(false);
+  });
+
+  it('getSandboxMetrics answers a sample for a live sandbox and 404s an unknown key', async () => {
+    await client.acquireSandbox('metrics-sdk');
+    const sample = await client.getSandboxMetrics('metrics-sdk');
+    expect(sample?.memTotalBytes).toBeGreaterThan(0);
+    await client.releaseSandbox('metrics-sdk');
+
+    await expect(
+      client.getSandboxMetrics('metrics-nobody'),
+    ).rejects.toMatchObject({
+      name: 'DormiceApiError',
+      status: 404,
+    });
+  });
+
+  it('listActivity tells the story just written, newest first', async () => {
+    await client.acquireSandbox('story-sdk');
+    await client.releaseSandbox('story-sdk');
+    const log = await client.listActivity({ limit: 10 });
+    const mine = log.filter((e) => e.userKey === 'story-sdk');
+    expect(mine.map((e) => e.kind)).toEqual(['released', 'created']);
+  });
+});
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 1a5fb74..5a03922 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -1,12 +1,17 @@
 import {
   type AcquireResponse,
+  type ActivityEvent,
   acquireResponseSchema,
   DEFAULT_EXEC_TIMEOUT_SECONDS,
   type ExecCommandResponse,
   execCommandResponseSchema,
+  type GetConfigResponse,
+  getConfigResponseSchema,
+  getSandboxMetricsResponseSchema,
   type HostMetricsResponse,
   hostMetricsResponseSchema,
   type LifecyclePolicyOverride,
+  listActivityResponseSchema,
   listSandboxesResponseSchema,
   listTemplatesResponseSchema,
   type RebuildSandboxResponse,
@@ -19,6 +24,7 @@ import {
   releaseSandboxResponseSchema,
   removeTemplateResponseSchema,
   type Sandbox,
+  type SandboxMetricsSample,
   type Template,
   type WriteFilesResponse,
   writeFilesResponseSchema,
@@ -142,6 +148,42 @@ export class Dormice {
     return hostMetricsResponseSchema.parse(data);
   }
 
+  /**
+   * One sandbox's point-in-time resource reading (CPU, memory, disk) — a
+   * single sample, the daemon keeps no history. Observation never wakes:
+   * a frozen sandbox is measured as it sleeps, and with no running
+   * container (stopped, archived, restoring) the sample is null.
+   */
+  async getSandboxMetrics(
+    userKey: string,
+  ): Promise<SandboxMetricsSample | null> {
+    const data = await this.rpc('getSandboxMetrics', { userKey });
+    return getSandboxMetricsResponseSchema.parse(data).sample;
+  }
+
+  /**
+   * The daemon's recent history, newest first: who was created, cooled,
+   * woken, destroyed, and what reconciliation repaired. A bounded ring —
+   * an explanation window, not an audit log.
+   */
+  async listActivity(options?: { limit?: number }): Promise<ActivityEvent[]> {
+    const data = await this.rpc('listActivity', {
+      limit: options?.limit,
+    });
+    return listActivityResponseSchema.parse(data).events;
+  }
+
+  /**
+   * The daemon's effective configuration, read-only: every knob, the value
+   * in force, and whether it came from the environment or a default.
+   * Secrets are reported as present-or-absent only. `archive.enabled` is
+   * the daemon's own adjudication of whether archiving is available.
+   */
+  async getConfig(): Promise<GetConfigResponse> {
+    const data = await this.rpc('getConfig', {});
+    return getConfigResponseSchema.parse(data);
+  }
+
   /**
    * Swaps the sandbox's container while keeping its disk: /home/user is
    * untouched, and the next use builds a fresh container from the current
diff --git a/packages/server/drizzle/0004_activity-ring.sql b/packages/server/drizzle/0004_activity-ring.sql
new file mode 100644
index 0000000..e8ab241
--- /dev/null
+++ b/packages/server/drizzle/0004_activity-ring.sql
@@ -0,0 +1,8 @@
+CREATE TABLE `activity` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`at` text NOT NULL,
+	`kind` text NOT NULL,
+	`user_key` text,
+	`sandbox_id` text,
+	`detail` text NOT NULL
+);
diff --git a/packages/server/drizzle/meta/0004_snapshot.json b/packages/server/drizzle/meta/0004_snapshot.json
new file mode 100644
index 0000000..c90ce40
--- /dev/null
+++ b/packages/server/drizzle/meta/0004_snapshot.json
@@ -0,0 +1,225 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "f54d106b-2995-448f-828a-898e1fd9f948",
+  "prevId": "1f1a3eaf-d3bf-47d5-b6e4-364b73fd1b3a",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "user_key": {
+          "name": "user_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "user_key": {
+          "name": "user_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_user_key_unique": {
+          "name": "sandboxes_user_key_unique",
+          "columns": [
+            "user_key"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index aab5880..c88d2ed 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -29,6 +29,13 @@
       "when": 1783681552934,
       "tag": "0003_templates",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "6",
+      "when": 1783744976921,
+      "tag": "0004_activity-ring",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index c6e0aa1..e79eb58 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -10,7 +10,7 @@ import { type Logger, pino } from 'pino';
 import { z } from 'zod';
 import type { Archiver } from './archive/archiver';
 import { requireApiAuth } from './auth';
-import type { Config } from './config';
+import { type Config, type ConfigSources, configSources } from './config';
 import type { Db } from './db/db';
 import { registerE2bCompat } from './e2b';
 import { ProcessTable } from './e2b/process-table';
@@ -18,6 +18,8 @@ import { WatcherTable } from './e2b/watcher-table';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
 import { ARCHIVE_DEFAULT_SECONDS } from './policy';
+import { activityRoutes } from './routes/activity';
+import { configRoutes } from './routes/config';
 import { consoleRoutes } from './routes/console';
 import { hostRoutes } from './routes/host';
 import { sandboxRoutes } from './routes/sandboxes';
@@ -54,6 +56,12 @@ export interface AppDeps {
    * honestly absent, never half-present).
    */
   archiver?: Archiver;
+  /**
+   * Which knobs came from the environment versus defaults, for getConfig.
+   * Defaults to reading process.env — right for the daemon; tests that
+   * assert on sources inject a fixed map instead of trusting the shell.
+   */
+  sources?: ConfigSources;
 }
 
 /**
@@ -73,6 +81,7 @@ export function buildApp({
   logger = true,
   consoleDistDir,
   archiver,
+  sources = configSources(),
 }: AppDeps) {
   // The archive default is adjudicated once, here, by the archiver's
   // presence: with one, new sandboxes archive after a week of idleness;
@@ -159,6 +168,12 @@ export function buildApp({
     });
     await api.register(templateRoutes, { db });
     await api.register(hostRoutes, { config, db, executor });
+    await api.register(activityRoutes, { db });
+    await api.register(configRoutes, {
+      config,
+      sources,
+      archiveDefaultSeconds,
+    });
   });
 
   // The web console: session endpoints (open — login carries the token
diff --git a/packages/server/src/archive/archiver.ts b/packages/server/src/archive/archiver.ts
index 0d64b45..221945c 100644
--- a/packages/server/src/archive/archiver.ts
+++ b/packages/server/src/archive/archiver.ts
@@ -1,5 +1,6 @@
 import { mkdir, rm } from 'node:fs/promises';
 import path from 'node:path';
+import { recordActivity } from '../db/activity';
 import type { Db } from '../db/db';
 import {
   findBySandboxId,
@@ -109,9 +110,14 @@ export class Archiver {
     } finally {
       await rm(tmp, { force: true });
     }
-    this.log(
-      `archived ${row.sandboxId} in ${((Date.now() - startedAt) / 1000).toFixed(1)}s`,
-    );
+    const seconds = ((Date.now() - startedAt) / 1000).toFixed(1);
+    recordActivity(this.db, {
+      kind: 'archived',
+      userKey: row.userKey,
+      sandboxId: row.sandboxId,
+      detail: `disk shipped to S3 in ${seconds}s; local copy freed`,
+    });
+    this.log(`archived ${row.sandboxId} in ${seconds}s`);
   }
 
   /**
@@ -128,6 +134,12 @@ export class Archiver {
       );
     }
     transition(this.db, row.sandboxId, 'restoring');
+    recordActivity(this.db, {
+      kind: 'restore-started',
+      userKey: row.userKey,
+      sandboxId: row.sandboxId,
+      detail: 'restore from S3 began',
+    });
     const progress: RestoreProgress = { phase: 'downloading', percent: 0 };
     const done = this.runRestore(row.sandboxId, row.userKey, progress).finally(
       () => {
@@ -224,6 +236,12 @@ export class Archiver {
         }
         transition(this.db, sandboxId, 'active');
         touch(this.db, sandboxId);
+        recordActivity(this.db, {
+          kind: 'restored',
+          userKey,
+          sandboxId,
+          detail: 'disk back from S3, sandbox active; archive object deleted',
+        });
       });
       // The object's job is done — the disk is local again, so from here
       // "an object exists" means "the row is archived", and release never
@@ -239,6 +257,14 @@ export class Archiver {
         const fresh = findBySandboxId(this.db, sandboxId);
         if (fresh?.state === 'restoring') {
           transition(this.db, sandboxId, 'archived');
+          recordActivity(this.db, {
+            kind: 'restore-failed',
+            userKey,
+            sandboxId,
+            detail: `back to archived, S3 object intact — ${
+              err instanceof Error ? err.message : String(err)
+            }`.slice(0, 300),
+          });
         }
       });
       throw err;
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index 21b23df..f83d83f 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -155,6 +155,54 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
   return checkedSchema.parse(env);
 }
 
+/**
+ * Every knob the daemon has, in display order, with its secrecy flag — the
+ * single adjudication of "what getConfig reports". A Record over keyof
+ * Config so the compiler refuses a new env variable until it is listed
+ * here too: a knob that exists but is invisible would be a silent lie.
+ */
+export const CONFIG_KEYS: Record<keyof Config, { sensitive: boolean }> = {
+  DORMICE_PORT: { sensitive: false },
+  DORMICE_DB_PATH: { sensitive: false },
+  DORMICE_NODE_ID: { sensitive: false },
+  DORMICE_API_TOKEN: { sensitive: true },
+  DORMICE_EXECUTOR: { sensitive: false },
+  DORMICE_BASE_IMAGE: { sensitive: false },
+  DORMICE_DATA_DIR: { sensitive: false },
+  DORMICE_MAX_SANDBOXES: { sensitive: false },
+  DORMICE_SCAN_INTERVAL_SECONDS: { sensitive: false },
+  DORMICE_SANDBOX_DISK_GB: { sensitive: false },
+  DORMICE_SANDBOX_CPUS: { sensitive: false },
+  DORMICE_SANDBOX_MEMORY_GB: { sensitive: false },
+  DORMICE_SANDBOX_PIDS_LIMIT: { sensitive: false },
+  DORMICE_RECLAIM_TIMEOUT_SECONDS: { sensitive: false },
+  DORMICE_SANDBOX_DOMAIN: { sensitive: false },
+  DORMICE_S3_ENDPOINT: { sensitive: false },
+  DORMICE_S3_BUCKET: { sensitive: false },
+  DORMICE_S3_ACCESS_KEY_ID: { sensitive: true },
+  DORMICE_S3_SECRET_ACCESS_KEY: { sensitive: true },
+  DORMICE_S3_REGION: { sensitive: false },
+  DORMICE_S3_FORCE_PATH_STYLE: { sensitive: false },
+};
+
+export type ConfigSources = Record<keyof Config, 'env' | 'default'>;
+
+/**
+ * Which knobs the operator set explicitly versus which fell back to
+ * defaults. Read off the raw environment at load time — the parsed config
+ * cannot tell the two apart once defaults are applied.
+ */
+export function configSources(
+  env: NodeJS.ProcessEnv = process.env,
+): ConfigSources {
+  return Object.fromEntries(
+    (Object.keys(CONFIG_KEYS) as Array<keyof Config>).map((key) => [
+      key,
+      env[key] !== undefined ? 'env' : 'default',
+    ]),
+  ) as ConfigSources;
+}
+
 /**
  * The single adjudicator of "is the archiver configured": null unless the
  * whole S3 set is present (a partial set never gets past the schema). What
diff --git a/packages/server/src/db/activity.ts b/packages/server/src/db/activity.ts
new file mode 100644
index 0000000..d5985cd
--- /dev/null
+++ b/packages/server/src/db/activity.ts
@@ -0,0 +1,51 @@
+import type { ActivityKind } from '@dormice/shared';
+import { desc, lte } from 'drizzle-orm';
+import type { Db } from './db';
+import { type ActivityRow, activity } from './schema';
+
+/**
+ * How much history the ring keeps. Not a knob: nobody sizes an explanation
+ * window, and a bound this generous covers days of a busy single machine —
+ * anyone needing more than "what just happened" needs a real audit trail,
+ * which this deliberately is not.
+ */
+export const ACTIVITY_KEEP = 1000;
+
+export interface ActivityInput {
+  kind: ActivityKind;
+  userKey?: string | null;
+  sandboxId?: string | null;
+  detail: string;
+}
+
+/**
+ * Appends one event and prunes the ring in the same breath. Synchronous
+ * like every ledger write, and deliberately unguarded: if the ledger can
+ * record state, it can record history — a failure here is the same disk
+ * catastrophe that would fail the transition itself.
+ */
+export function recordActivity(db: Db, input: ActivityInput): void {
+  const inserted = db
+    .insert(activity)
+    .values({
+      at: new Date().toISOString(),
+      kind: input.kind,
+      userKey: input.userKey ?? null,
+      sandboxId: input.sandboxId ?? null,
+      detail: input.detail,
+    })
+    .run();
+  db.delete(activity)
+    .where(lte(activity.id, Number(inserted.lastInsertRowid) - ACTIVITY_KEEP))
+    .run();
+}
+
+/** Newest first — the question is always "what just happened". */
+export function listActivityEvents(db: Db, limit: number): ActivityRow[] {
+  return db
+    .select()
+    .from(activity)
+    .orderBy(desc(activity.id))
+    .limit(limit)
+    .all();
+}
diff --git a/packages/server/src/db/ledger.ts b/packages/server/src/db/ledger.ts
index 3353e70..0845c12 100644
--- a/packages/server/src/db/ledger.ts
+++ b/packages/server/src/db/ledger.ts
@@ -1,5 +1,6 @@
 import type { LifecyclePolicy, SandboxState } from '@dormice/shared';
 import { count, eq } from 'drizzle-orm';
+import { recordActivity } from './activity';
 import type { Db } from './db';
 import { type SandboxRow, sandboxes } from './schema';
 
@@ -66,6 +67,15 @@ export function createSandbox(db: Db, input: CreateSandboxInput): SandboxRow {
     pausedByUser: false,
   };
   db.insert(sandboxes).values(row).run();
+  // The one place every creation passes through, whichever face asked.
+  recordActivity(db, {
+    kind: 'created',
+    userKey: row.userKey,
+    sandboxId: row.sandboxId,
+    detail: `${input.e2b ? 'via E2B create' : 'via acquireSandbox'}${
+      input.template ? `, template ${input.template}` : ''
+    }`,
+  });
   return row;
 }
 
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index 5fc70b1..63bd95f 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -1,4 +1,4 @@
-import { SANDBOX_STATES } from '@dormice/shared';
+import { ACTIVITY_KINDS, SANDBOX_STATES } from '@dormice/shared';
 import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
 
 /**
@@ -66,3 +66,25 @@ export const templates = sqliteTable('templates', {
 });
 
 export type TemplateRow = typeof templates.$inferSelect;
+
+/**
+ * The activity ring: the ledger's recent history, one row per lifecycle
+ * event (created, cooled, woken, destroyed, repaired). Bounded by count —
+ * recordActivity prunes past the newest N — so it answers "what just
+ * happened" without ever becoming a second database to babysit. The
+ * autoincrement id is the ring position AND the newest-first sort key;
+ * unlike sandbox ids it never leaves this machine, so the UUID rule does
+ * not apply.
+ */
+export const activity = sqliteTable('activity', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  /** ISO 8601 UTC. */
+  at: text('at').notNull(),
+  kind: text('kind', { enum: ACTIVITY_KINDS }).notNull(),
+  /** Null for events with no owning sandbox (orphan sweeps, daemon start). */
+  userKey: text('user_key'),
+  sandboxId: text('sandbox_id'),
+  detail: text('detail').notNull(),
+});
+
+export type ActivityRow = typeof activity.$inferSelect;
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index 9e93631..6e6b42b 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -294,6 +294,10 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
             executor,
             existing.sandboxId,
             archiver?.store ?? null,
+            {
+              kind: 'released',
+              cause: 'protocol-dead row reaped by E2B create',
+            },
           );
         }
 
@@ -418,6 +422,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         executor,
         fresh.sandboxId,
         archiver?.store ?? null,
+        { kind: 'released', cause: 'via E2B kill' },
       );
     });
     return reply.code(204).send();
@@ -458,12 +463,22 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         if (!fresh) throw notFound(id);
         let current = fresh;
         if (current.state === 'active') {
-          current = await freezeSandbox(db, executor, current.sandboxId);
+          current = await freezeSandbox(
+            db,
+            executor,
+            current.sandboxId,
+            'paused via E2B',
+          );
         }
         // keepMemory:false maps to stopped: filesystem only, cold boot on
         // resume — physically exactly what E2B promises for it.
         if (request.body?.memory === false && current.state === 'frozen') {
-          await stopSandbox(db, executor, current.sandboxId);
+          await stopSandbox(
+            db,
+            executor,
+            current.sandboxId,
+            'paused via E2B (memory discarded)',
+          );
         }
         setPausedByUser(db, fresh.sandboxId, true);
       });
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index a5736bc..7508030 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -1,4 +1,5 @@
 import { type ArchiveStore, objectKey } from './archive/store';
+import { recordActivity } from './db/activity';
 import type { Db } from './db/db';
 import {
   deleteSandbox,
@@ -21,22 +22,44 @@ import type { Executor } from './executor/executor';
  * reconciler's job, not something every caller hedges against.
  */
 
+/**
+ * The lifecycle verbs also feed the activity ring here, after the ledger
+ * write — history is recorded where reality and ledger already move
+ * together, so no caller can forget it. `cause` is the caller's one line of
+ * context ("who did this and why"); the default names the bare move.
+ */
 export async function freezeSandbox(
   db: Db,
   executor: Executor,
   sandboxId: string,
+  cause?: string,
 ): Promise<SandboxRow> {
   await executor.freeze(sandboxId);
-  return transition(db, sandboxId, 'frozen');
+  const row = transition(db, sandboxId, 'frozen');
+  recordActivity(db, {
+    kind: 'frozen',
+    userKey: row.userKey,
+    sandboxId,
+    detail: cause ?? 'memory squeezed into swap',
+  });
+  return row;
 }
 
 export async function stopSandbox(
   db: Db,
   executor: Executor,
   sandboxId: string,
+  cause?: string,
 ): Promise<SandboxRow> {
   await executor.stop(sandboxId);
-  return transition(db, sandboxId, 'stopped');
+  const row = transition(db, sandboxId, 'stopped');
+  recordActivity(db, {
+    kind: 'stopped',
+    userKey: row.userKey,
+    sandboxId,
+    detail: cause ?? 'container torn down, disk kept',
+  });
+  return row;
 }
 
 /**
@@ -57,6 +80,10 @@ export async function releaseSandbox(
   executor: Executor,
   sandboxId: string,
   store: ArchiveStore | null,
+  activity: { kind: 'released' | 'expired-killed'; cause: string } = {
+    kind: 'released',
+    cause: 'via releaseSandbox',
+  },
 ): Promise<void> {
   const row = findBySandboxId(db, sandboxId);
   if (row?.state === 'archived') {
@@ -67,10 +94,24 @@ export async function releaseSandbox(
     }
     await store.delete(objectKey(sandboxId));
     deleteSandbox(db, sandboxId);
+    recordActivity(db, {
+      kind: activity.kind,
+      userKey: row.userKey,
+      sandboxId,
+      detail: `${activity.cause}; archive object deleted`,
+    });
     return;
   }
   await executor.destroy(sandboxId);
   deleteSandbox(db, sandboxId);
+  if (row) {
+    recordActivity(db, {
+      kind: activity.kind,
+      userKey: row.userKey,
+      sandboxId,
+      detail: activity.cause,
+    });
+  }
 }
 
 /**
@@ -89,6 +130,13 @@ export async function rebuildSandbox(
   row: SandboxRow,
 ): Promise<SandboxRow> {
   await executor.removeContainer(row.sandboxId);
+  recordActivity(db, {
+    kind: 'rebuilt',
+    userKey: row.userKey,
+    sandboxId: row.sandboxId,
+    detail:
+      'shell removed, disk kept — next wake builds from the current image',
+  });
   if (row.state === 'stopped') {
     return row;
   }
@@ -106,14 +154,14 @@ export async function wakeSandbox(
       return row;
     case 'frozen':
       await executor.unfreeze(row.sandboxId);
-      return awaken(db, row);
+      return awaken(db, row, 'from frozen (memory back out of swap)');
     case 'stopped':
       // If the container object was pruned away, start rebuilds the shell —
       // from the template's current image, resolved here at wake time.
       await executor.start(row.sandboxId, {
         image: resolveImage(db, row.template),
       });
-      return awaken(db, row);
+      return awaken(db, row, 'cold start from the surviving disk');
     case 'archived':
     case 'restoring':
       // Every legitimate path branches to the archiver before landing here
@@ -130,9 +178,16 @@ export async function wakeSandbox(
  * so any explicit E2B pause mark is cleared along with the transition —
  * ledger honesty, not an E2B-surface concern leaking in.
  */
-function awaken(db: Db, row: SandboxRow): SandboxRow {
+function awaken(db: Db, row: SandboxRow, how: string): SandboxRow {
   if (row.pausedByUser) {
     setPausedByUser(db, row.sandboxId, false);
   }
-  return { ...transition(db, row.sandboxId, 'active'), pausedByUser: false };
+  const awake = transition(db, row.sandboxId, 'active');
+  recordActivity(db, {
+    kind: 'woken',
+    userKey: row.userKey,
+    sandboxId: row.sandboxId,
+    detail: how,
+  });
+  return { ...awake, pausedByUser: false };
 }
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index e86a033..d0ba213 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -6,6 +6,7 @@ import { buildApp } from './app';
 import { Archiver } from './archive/archiver';
 import { S3Store } from './archive/s3-store';
 import { type Config, loadConfig, s3Settings } from './config';
+import { recordActivity } from './db/activity';
 import { migrateDb, openDb } from './db/db';
 import { listSandboxes } from './db/ledger';
 import { acquireSingleWriterLock } from './db/lock';
@@ -133,6 +134,13 @@ if (refusal !== null) {
 // listen, so no request ever observes one.
 const repaired = await reconcile(db, executor, locks, undefined, archiver);
 app.log.info(repaired, 'startup reconcile');
+recordActivity(db, {
+  kind: 'daemon-started',
+  detail:
+    `executor ${config.DORMICE_EXECUTOR}; startup reconcile: ` +
+    `${repaired.repairedStates} states repaired, ${repaired.deletedRows} rows deleted, ` +
+    `${repaired.destroyedOrphans} orphan containers destroyed, ${repaired.removedDisks} disks removed`,
+});
 
 // Red line: the daemon binds to loopback only, and the host is deliberately
 // not configurable — a knob would be one typo away from 0.0.0.0. Exposing
diff --git a/packages/server/src/reconciler.ts b/packages/server/src/reconciler.ts
index c0ca47c..2361b39 100644
--- a/packages/server/src/reconciler.ts
+++ b/packages/server/src/reconciler.ts
@@ -1,4 +1,5 @@
 import type { SandboxState } from '@dormice/shared';
+import { recordActivity } from './db/activity';
 import type { Db } from './db/db';
 import {
   deleteSandbox,
@@ -129,6 +130,16 @@ export async function reconcile(
       }
     });
 
+  // Every applied repair is history worth explaining: reconciliation is
+  // the actor an operator least expects, so its moves go on the record.
+  const note = (row: SandboxRow, detail: string) =>
+    recordActivity(db, {
+      kind: 'reconciled',
+      userKey: row.userKey,
+      sandboxId: row.sandboxId,
+      detail,
+    });
+
   for (const row of rows) {
     const observed = containers.get(row.sandboxId);
     containers.delete(row.sandboxId);
@@ -138,11 +149,13 @@ export async function reconcile(
         await repairUnderLock(row, async () => {
           await executor.destroy(row.sandboxId);
           result.archivedSwept += 1;
+          note(row, 'leftover container of an archived sandbox destroyed');
         });
       } else if (disks.has(row.sandboxId)) {
         await repairUnderLock(row, async () => {
           await executor.removeDisk(row.sandboxId);
           result.archivedSwept += 1;
+          note(row, 'leftover disk of an archived sandbox removed');
         });
       }
       continue;
@@ -156,12 +169,20 @@ export async function reconcile(
         await repairUnderLock(row, () => {
           overwriteState(db, row.sandboxId, LEDGER_STATE[observed]);
           result.repairedStates += 1;
+          note(
+            row,
+            `crashed restore had finished — recorded ${LEDGER_STATE[observed]}`,
+          );
         });
       } else {
         await repairUnderLock(row, async () => {
           await executor.removeDisk(row.sandboxId);
           overwriteState(db, row.sandboxId, 'archived');
           result.repairedStates += 1;
+          note(
+            row,
+            'crashed restore: half-built disk removed, back to archived',
+          );
         });
       }
       continue;
@@ -172,6 +193,10 @@ export async function reconcile(
         await repairUnderLock(row, () => {
           overwriteState(db, row.sandboxId, LEDGER_STATE[observed]);
           result.repairedStates += 1;
+          note(
+            row,
+            `container is ${observed} — state ${row.state} corrected to ${LEDGER_STATE[observed]}`,
+          );
         });
       }
     } else if (disks.has(row.sandboxId)) {
@@ -180,12 +205,17 @@ export async function reconcile(
         await repairUnderLock(row, () => {
           overwriteState(db, row.sandboxId, 'stopped');
           result.repairedStates += 1;
+          note(
+            row,
+            `container gone but disk survives (docker prune?) — recorded stopped, was ${row.state}`,
+          );
         });
       }
     } else {
       await repairUnderLock(row, () => {
         deleteSandbox(db, row.sandboxId);
         result.deletedRows += 1;
+        note(row, 'container and disk both gone — row deleted, key freed');
       });
     }
   }
@@ -197,6 +227,11 @@ export async function reconcile(
     if (priorSuspects === undefined || priorSuspects.has(sandboxId)) {
       await executor.destroy(sandboxId);
       result.destroyedOrphans += 1;
+      recordActivity(db, {
+        kind: 'reconciled',
+        sandboxId,
+        detail: 'unowned container destroyed — no ledger row points at it',
+      });
     } else {
       result.suspects.push(sandboxId);
     }
@@ -208,6 +243,11 @@ export async function reconcile(
     if (priorSuspects === undefined || priorSuspects.has(sandboxId)) {
       await executor.removeDisk(sandboxId);
       result.removedDisks += 1;
+      recordActivity(db, {
+        kind: 'reconciled',
+        sandboxId,
+        detail: 'unowned disk removed — neither a row nor a container owns it',
+      });
     } else {
       result.suspects.push(sandboxId);
     }
diff --git a/packages/server/src/routes/activity.ts b/packages/server/src/routes/activity.ts
new file mode 100644
index 0000000..cba6ee3
--- /dev/null
+++ b/packages/server/src/routes/activity.ts
@@ -0,0 +1,34 @@
+import {
+  listActivityRequestSchema,
+  listActivityResponseSchema,
+} from '@dormice/shared';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import { listActivityEvents } from '../db/activity';
+import type { Db } from '../db/db';
+
+export interface ActivityRoutesOptions {
+  db: Db;
+}
+
+/**
+ * The ledger's recent history — the explanation window beside the
+ * observation windows (listSandboxes for now, getHostMetrics for the
+ * machine). Read-only over the activity ring; recording happens where the
+ * moves themselves happen.
+ */
+export const activityRoutes: FastifyPluginAsyncZod<
+  ActivityRoutesOptions
+> = async (app, { db }) => {
+  app.post(
+    '/listActivity',
+    {
+      schema: {
+        body: listActivityRequestSchema,
+        response: { 200: listActivityResponseSchema },
+      },
+    },
+    async (request) => ({
+      events: listActivityEvents(db, request.body.limit),
+    }),
+  );
+};
diff --git a/packages/server/src/routes/config.ts b/packages/server/src/routes/config.ts
new file mode 100644
index 0000000..74a2a47
--- /dev/null
+++ b/packages/server/src/routes/config.ts
@@ -0,0 +1,47 @@
+import { getConfigResponseSchema } from '@dormice/shared';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import { CONFIG_KEYS, type Config, type ConfigSources } from '../config';
+
+export interface ConfigRoutesOptions {
+  config: Config;
+  sources: ConfigSources;
+  /** buildApp's one adjudication of the archive default (null = no archiver). */
+  archiveDefaultSeconds: number | null;
+}
+
+/**
+ * The daemon's effective configuration, read-only: what is actually in
+ * force, not what a config file says (doctor's discipline). Editing stays
+ * on the host — /etc/dormice/env plus a restart — because a daemon that
+ * rewrites its own environment is a different security decision entirely.
+ * Secrets never cross the wire: set-or-unset is all anyone learns.
+ */
+export const configRoutes: FastifyPluginAsyncZod<ConfigRoutesOptions> = async (
+  app,
+  { config, sources, archiveDefaultSeconds },
+) => {
+  app.post(
+    '/getConfig',
+    {
+      schema: {
+        response: { 200: getConfigResponseSchema },
+      },
+    },
+    async () => ({
+      entries: (Object.keys(CONFIG_KEYS) as Array<keyof Config>).map((key) => {
+        const { sensitive } = CONFIG_KEYS[key];
+        const value = config[key];
+        return {
+          key,
+          value: sensitive || value === undefined ? null : String(value),
+          source: sources[key],
+          ...(sensitive && value !== undefined ? { redacted: true } : {}),
+        };
+      }),
+      archive: {
+        enabled: archiveDefaultSeconds !== null,
+        defaultSeconds: archiveDefaultSeconds,
+      },
+    }),
+  );
+};
diff --git a/packages/server/src/routes/observability.test.ts b/packages/server/src/routes/observability.test.ts
new file mode 100644
index 0000000..31c105c
--- /dev/null
+++ b/packages/server/src/routes/observability.test.ts
@@ -0,0 +1,274 @@
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  type ActivityEvent,
+  type ConfigEntry,
+  getConfigResponseSchema,
+  getSandboxMetricsResponseSchema,
+  listActivityResponseSchema,
+} from '@dormice/shared';
+import { count } from 'drizzle-orm';
+import { describe, expect, it } from 'vitest';
+import { buildApp } from '../app';
+import { Archiver } from '../archive/archiver';
+import { MemStore } from '../archive/mem-store';
+import { CONFIG_KEYS, type ConfigSources, loadConfig } from '../config';
+import { ACTIVITY_KEEP, recordActivity } from '../db/activity';
+import { migrateDb, openDb } from '../db/db';
+import { activity } from '../db/schema';
+import { FakeExecutor } from '../executor/fake';
+import { KeyedQueue } from '../keyed-queue';
+import { freezeSandbox, stopSandbox } from '../lifecycle';
+import { ARCHIVE_DEFAULT_SECONDS } from '../policy';
+import { reconcile } from '../reconciler';
+import { scanOnce } from '../scanner';
+
+// The three observability verbs, app-level: getConfig, listActivity,
+// getSandboxMetrics — the console's food, so the tests eat exactly what a
+// browser would.
+
+const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
+const TOKEN = 'test-token-test-token-test-token';
+const authed = { authorization: `Bearer ${TOKEN}` };
+
+/** All-defaults source map; tests override the keys they assert on. */
+function fixedSources(overrides: Partial<ConfigSources> = {}): ConfigSources {
+  const all = Object.fromEntries(
+    Object.keys(CONFIG_KEYS).map((key) => [key, 'default']),
+  ) as ConfigSources;
+  return { ...all, ...overrides, DORMICE_API_TOKEN: 'env' };
+}
+
+function testApp(env: Record<string, string> = {}) {
+  const db = openDb(':memory:');
+  migrateDb(db, MIGRATIONS);
+  const config = loadConfig({
+    DORMICE_DB_PATH: ':memory:',
+    DORMICE_NODE_ID: 'node-test',
+    DORMICE_API_TOKEN: TOKEN,
+    ...env,
+  });
+  const executor = new FakeExecutor();
+  const locks = new KeyedQueue();
+  const sources = fixedSources(
+    Object.fromEntries(
+      Object.keys(env).map((key) => [key, 'env']),
+    ) as Partial<ConfigSources>,
+  );
+  const app = buildApp({ config, db, executor, locks, logger: false, sources });
+  return { app, db, executor, locks };
+}
+
+type App = ReturnType<typeof testApp>['app'];
+
+function rpc(app: App, url: string, payload: Record<string, unknown> = {}) {
+  return app.inject({ method: 'POST', url, headers: authed, payload });
+}
+
+async function events(app: App): Promise<ActivityEvent[]> {
+  const res = await rpc(app, '/listActivity');
+  expect(res.statusCode).toBe(200);
+  return listActivityResponseSchema.parse(res.json()).events;
+}
+
+describe('getConfig', () => {
+  it('reports every knob with value and source, and validates', async () => {
+    const { app } = testApp({ DORMICE_MAX_SANDBOXES: '7' });
+    const res = await rpc(app, '/getConfig');
+    expect(res.statusCode).toBe(200);
+    const body = getConfigResponseSchema.parse(res.json());
+
+    const byKey = new Map(body.entries.map((e: ConfigEntry) => [e.key, e]));
+    // Complete: one entry per knob the config schema knows.
+    expect(body.entries).toHaveLength(Object.keys(CONFIG_KEYS).length);
+    expect(byKey.get('DORMICE_MAX_SANDBOXES')).toMatchObject({
+      value: '7',
+      source: 'env',
+    });
+    expect(byKey.get('DORMICE_PORT')).toMatchObject({
+      value: '3676',
+      source: 'default',
+    });
+    // Optional and unset: honestly null, not invented.
+    expect(byKey.get('DORMICE_SANDBOX_DOMAIN')).toMatchObject({ value: null });
+  });
+
+  it('withholds secrets, reporting only their presence', async () => {
+    const { app } = testApp();
+    const body = getConfigResponseSchema.parse(
+      (await rpc(app, '/getConfig')).json(),
+    );
+    const token = body.entries.find(
+      (e: ConfigEntry) => e.key === 'DORMICE_API_TOKEN',
+    );
+    expect(token).toMatchObject({ value: null, redacted: true });
+    // The raw token must appear nowhere in the whole response.
+    expect(JSON.stringify(body)).not.toContain(TOKEN);
+  });
+
+  it('adjudicates archive availability: off without an archiver', async () => {
+    const { app } = testApp();
+    const body = getConfigResponseSchema.parse(
+      (await rpc(app, '/getConfig')).json(),
+    );
+    expect(body.archive).toEqual({ enabled: false, defaultSeconds: null });
+  });
+
+  it('reports the archive default when an archiver is wired', async () => {
+    // buildApp derives the default purely from the archiver's presence.
+    const db = openDb(':memory:');
+    migrateDb(db, MIGRATIONS);
+    const executor = new FakeExecutor();
+    const locks = new KeyedQueue();
+    const config = loadConfig({
+      DORMICE_DB_PATH: ':memory:',
+      DORMICE_API_TOKEN: TOKEN,
+    });
+    const archiver = new Archiver({
+      db,
+      executor,
+      locks,
+      store: new MemStore(),
+      tmpDir: mkdtempSync(path.join(tmpdir(), 'dormice-obs-')),
+    });
+    const app = buildApp({
+      config,
+      db,
+      executor,
+      locks,
+      logger: false,
+      sources: fixedSources(),
+      archiver,
+    });
+    const body = getConfigResponseSchema.parse(
+      (await rpc(app, '/getConfig')).json(),
+    );
+    expect(body.archive).toEqual({
+      enabled: true,
+      defaultSeconds: ARCHIVE_DEFAULT_SECONDS,
+    });
+  });
+});
+
+describe('listActivity', () => {
+  it('records create, wake, cooling and release, newest first', async () => {
+    const { app, db, executor, locks } = testApp();
+    const res = await rpc(app, '/acquireSandbox', {
+      userKey: 'story',
+      policy: { freezeAfterSeconds: 5, stopAfterSeconds: 10 },
+    });
+    expect(res.statusCode).toBe(200);
+    const created = res.json().sandbox;
+
+    // Cool it two rungs by time travel, then wake it back through acquire.
+    await scanOnce(
+      db,
+      executor,
+      locks,
+      new Date(Date.parse(created.lastActiveAt) + 6_000),
+    );
+    await scanOnce(
+      db,
+      executor,
+      locks,
+      new Date(Date.parse(created.lastActiveAt) + 11_000),
+    );
+    await rpc(app, '/acquireSandbox', { userKey: 'story' });
+    await rpc(app, '/releaseSandbox', { userKey: 'story' });
+
+    const log = await events(app);
+    expect(log.map((e) => e.kind)).toEqual([
+      'released',
+      'woken',
+      'stopped',
+      'frozen',
+      'created',
+    ]);
+    // Every event names its sandbox, and the scanner names its threshold.
+    expect(new Set(log.map((e) => e.userKey))).toEqual(new Set(['story']));
+    expect(log.find((e) => e.kind === 'frozen')?.detail).toContain('scanner');
+    expect(log.find((e) => e.kind === 'created')?.detail).toContain(
+      'acquireSandbox',
+    );
+  });
+
+  it('records what reconciliation repaired', async () => {
+    const { app, db, executor, locks } = testApp();
+    await rpc(app, '/acquireSandbox', { userKey: 'doomed' });
+    const { sandboxes } = (await rpc(app, '/listSandboxes')).json();
+    // Reality loses both container and disk behind the ledger's back.
+    await executor.destroy(sandboxes[0].sandboxId);
+    await reconcile(db, executor, locks);
+
+    const log = await events(app);
+    expect(log[0]).toMatchObject({ kind: 'reconciled', userKey: 'doomed' });
+    expect(log[0]?.detail).toContain('row deleted');
+  });
+
+  it('honors the limit and keeps the ring bounded', async () => {
+    const { app, db } = testApp();
+    for (let i = 0; i < ACTIVITY_KEEP + 50; i += 1) {
+      recordActivity(db, { kind: 'daemon-started', detail: `tick ${i}` });
+    }
+    const page = listActivityResponseSchema.parse(
+      (await rpc(app, '/listActivity', { limit: 3 })).json(),
+    ).events;
+    expect(page).toHaveLength(3);
+    expect(page[0]?.detail).toBe(`tick ${ACTIVITY_KEEP + 49}`);
+
+    // The bound must live in the TABLE, not in the page clamp: a missing
+    // prune with limit=1000 would return the same page — count the rows.
+    const total = db.select({ n: count() }).from(activity).get() as {
+      n: number;
+    };
+    expect(total.n).toBe(ACTIVITY_KEEP);
+    const all = listActivityResponseSchema.parse(
+      (await rpc(app, '/listActivity', { limit: 1000 })).json(),
+    ).events;
+    // The oldest 50 fell off the ring.
+    expect(all.at(-1)?.detail).toBe('tick 50');
+  });
+
+  it('rejects an out-of-range limit', async () => {
+    const { app } = testApp();
+    const res = await rpc(app, '/listActivity', { limit: 0 });
+    expect(res.statusCode).toBe(400);
+  });
+});
+
+describe('getSandboxMetrics', () => {
+  it('answers a single sample for a running sandbox', async () => {
+    const { app } = testApp();
+    await rpc(app, '/acquireSandbox', { userKey: 'measured' });
+    const res = await rpc(app, '/getSandboxMetrics', { userKey: 'measured' });
+    expect(res.statusCode).toBe(200);
+    const { sample } = getSandboxMetricsResponseSchema.parse(res.json());
+    expect(sample).not.toBeNull();
+    expect(sample?.memTotalBytes).toBeGreaterThan(0);
+    expect(sample?.diskTotalBytes).toBeGreaterThan(0);
+  });
+
+  it('answers null for a stopped sandbox instead of waking it', async () => {
+    const { app, db, executor } = testApp();
+    const res = await rpc(app, '/acquireSandbox', { userKey: 'cold' });
+    const { sandboxId } = res.json().sandbox;
+    await freezeSandbox(db, executor, sandboxId);
+    await stopSandbox(db, executor, sandboxId);
+
+    const metrics = await rpc(app, '/getSandboxMetrics', { userKey: 'cold' });
+    expect(getSandboxMetricsResponseSchema.parse(metrics.json()).sample).toBe(
+      null,
+    );
+    // Observation is not activity: still stopped afterwards.
+    const { sandboxes } = (await rpc(app, '/listSandboxes')).json();
+    expect(sandboxes[0].state).toBe('stopped');
+  });
+
+  it('404s an unknown key instead of inventing a sandbox', async () => {
+    const { app } = testApp();
+    const res = await rpc(app, '/getSandboxMetrics', { userKey: 'nobody' });
+    expect(res.statusCode).toBe(404);
+  });
+});
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index bb9707b..da1197e 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -4,6 +4,8 @@ import {
   acquireResponseSchema,
   execCommandRequestSchema,
   execCommandResponseSchema,
+  getSandboxMetricsRequestSchema,
+  getSandboxMetricsResponseSchema,
   type LifecyclePolicy,
   listSandboxesResponseSchema,
   readFileRequestSchema,
@@ -281,6 +283,36 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     }),
   );
 
+  // One sandbox's point-in-time resource reading — the native twin of the
+  // E2B metrics endpoint, same rules: a single sample (no history kept),
+  // and observation never wakes anything. A frozen sandbox is measured as
+  // it sleeps (its cgroup accounting stays readable); with no running
+  // container there is nothing to measure and the answer is an honest null.
+  app.post(
+    '/getSandboxMetrics',
+    {
+      schema: {
+        body: getSandboxMetricsRequestSchema,
+        response: { 200: getSandboxMetricsResponseSchema },
+      },
+    },
+    async (request) => {
+      const { userKey } = request.body;
+      const row = findByUserKey(db, userKey);
+      if (!row) {
+        throw httpError(
+          404,
+          `no sandbox for key "${userKey}" — acquire it first`,
+        );
+      }
+      if (row.state !== 'active' && row.state !== 'frozen') {
+        return { sample: null };
+      }
+      const m = await executor.metrics(row.sandboxId);
+      return { sample: { timestamp: new Date().toISOString(), ...m } };
+    },
+  );
+
   app.post(
     '/execCommand',
     {
diff --git a/packages/server/src/scanner.ts b/packages/server/src/scanner.ts
index 8e0c8c5..b68fac6 100644
--- a/packages/server/src/scanner.ts
+++ b/packages/server/src/scanner.ts
@@ -142,21 +142,37 @@ export async function scanOnce(
             executor,
             fresh.sandboxId,
             archiver?.store ?? null,
+            { kind: 'expired-killed', cause: 'E2B deadline (kill) reached' },
           );
           result.expiredKilled += 1;
           return;
         }
         if (deadline === 'pause') {
-          await freezeSandbox(db, executor, fresh.sandboxId);
+          await freezeSandbox(
+            db,
+            executor,
+            fresh.sandboxId,
+            'E2B deadline reached (pause)',
+          );
           result.frozen += 1;
           return;
         }
         const freshDue = dueTransition(fresh, now);
         if (freshDue === 'freeze') {
-          await freezeSandbox(db, executor, fresh.sandboxId);
+          await freezeSandbox(
+            db,
+            executor,
+            fresh.sandboxId,
+            `idle ${fresh.freezeAfterSeconds}s reached — memory squeezed into swap (scanner)`,
+          );
           result.frozen += 1;
         } else if (freshDue === 'stop') {
-          await stopSandbox(db, executor, fresh.sandboxId);
+          await stopSandbox(
+            db,
+            executor,
+            fresh.sandboxId,
+            `idle ${fresh.stopAfterSeconds}s reached — container torn down, disk kept (scanner)`,
+          );
           result.stopped += 1;
         }
       });
diff --git a/packages/shared/src/activity.ts b/packages/shared/src/activity.ts
new file mode 100644
index 0000000..dfdf449
--- /dev/null
+++ b/packages/shared/src/activity.ts
@@ -0,0 +1,60 @@
+import { z } from 'zod';
+
+/**
+ * listActivity() — the ledger's recent history: who was created, cooled,
+ * woken, destroyed, and what reconciliation repaired. Events come from the
+ * daemon's own actors (lifecycle moves, the idle scanner, the reconciler,
+ * the archiver) and live in a bounded ring in SQLite — the newest N are
+ * kept, older ones fall off. This is an explanation window, not an audit
+ * log and not a monitoring system: it answers "why is my sandbox stopped",
+ * not "prove nobody touched it".
+ */
+export const ACTIVITY_KINDS = [
+  'created',
+  'woken',
+  'frozen',
+  'stopped',
+  'rebuilt',
+  'released',
+  /** An E2B deadline with the kill action passed: destroyed, disk and all. */
+  'expired-killed',
+  'archived',
+  'restore-started',
+  'restored',
+  'restore-failed',
+  /** The reconciler corrected the ledger (or reality) to match the other. */
+  'reconciled',
+  'daemon-started',
+] as const;
+
+export const activityKindSchema = z.enum(ACTIVITY_KINDS);
+export type ActivityKind = z.infer<typeof activityKindSchema>;
+
+export const activityEventSchema = z.object({
+  /** Ring position; monotonically increasing, newest is largest. */
+  id: z.number().int(),
+  /** ISO 8601 UTC. */
+  at: z.string(),
+  kind: activityKindSchema,
+  /** Null for events with no owning sandbox (orphan sweeps, daemon start). */
+  userKey: z.string().nullable(),
+  sandboxId: z.string().nullable(),
+  /** One short line of context: which actor, which threshold, what was repaired. */
+  detail: z.string(),
+});
+
+export type ActivityEvent = z.infer<typeof activityEventSchema>;
+
+export const listActivityRequestSchema = z.object({
+  /** Newest-first page size; the ring never holds more than its bound anyway. */
+  limit: z.number().int().min(1).max(1000).default(200),
+});
+
+export type ListActivityRequest = z.input<typeof listActivityRequestSchema>;
+
+export const listActivityResponseSchema = z.object({
+  /** Newest first. */
+  events: z.array(activityEventSchema),
+});
+
+export type ListActivityResponse = z.infer<typeof listActivityResponseSchema>;
diff --git a/packages/shared/src/config.ts b/packages/shared/src/config.ts
new file mode 100644
index 0000000..451a22f
--- /dev/null
+++ b/packages/shared/src/config.ts
@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+/**
+ * getConfig() — the daemon's effective configuration, read-only: every knob
+ * with the value actually in force and where it came from. The same
+ * discipline as doctor: report effective values, never parrot a config
+ * file. Secrets are reported as present-or-absent only — their value never
+ * crosses the wire, whoever asks.
+ */
+export const configEntrySchema = z.object({
+  /** The environment variable name, e.g. DORMICE_PORT. */
+  key: z.string(),
+  /**
+   * Effective value, stringified. Null when the knob is unset (optional
+   * knobs without a default) or when the entry is redacted.
+   */
+  value: z.string().nullable(),
+  /** Explicitly set in the environment, or the built-in default. */
+  source: z.enum(['env', 'default']),
+  /** True on secrets that are set: presence reported, value withheld. */
+  redacted: z.boolean().optional(),
+});
+
+export type ConfigEntry = z.infer<typeof configEntrySchema>;
+
+export const getConfigResponseSchema = z.object({
+  entries: z.array(configEntrySchema),
+  /**
+   * The daemon's one adjudication of "is archiving available" (the whole
+   * DORMICE_S3_* set configured), plus the default distance from stopped
+   * to archived that new sandboxes get. Clients gate archive knobs on
+   * this instead of re-deriving it from the S3 entries.
+   */
+  archive: z.object({
+    enabled: z.boolean(),
+    /** Null exactly when disabled: a promise nobody can honor is never made. */
+    defaultSeconds: z.number().int().nullable(),
+  }),
+});
+
+export type GetConfigResponse = z.infer<typeof getConfigResponseSchema>;
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index ab8e23e..daa2d9e 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -1,8 +1,11 @@
 export * from './acquire';
+export * from './activity';
+export * from './config';
 export * from './exec';
 export * from './files';
 export * from './host';
 export * from './list';
+export * from './metrics';
 export * from './policy';
 export * from './rebuild';
 export * from './release';
diff --git a/packages/shared/src/metrics.ts b/packages/shared/src/metrics.ts
new file mode 100644
index 0000000..c12c5e0
--- /dev/null
+++ b/packages/shared/src/metrics.ts
@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { userKeySchema } from './sandbox';
+
+/**
+ * getSandboxMetrics(userKey) — one sandbox's point-in-time resource
+ * reading: the per-sandbox sibling of getHostMetrics, and the native twin
+ * of the E2B surface's metrics endpoint (same executor reading, same
+ * single-sample answer — the daemon keeps no metrics history). Observation
+ * never wakes a sandbox: a frozen sandbox is measured as it sleeps, and a
+ * sandbox with no running container answers null instead of being started
+ * just to be looked at.
+ */
+export const sandboxMetricsSampleSchema = z.object({
+  /** ISO 8601 UTC — when the reading was taken. */
+  timestamp: z.string(),
+  /** Configured CPU allowance. */
+  cpuCount: z.number(),
+  /** Percent of one CPU; can exceed 100 on a multi-CPU sandbox. */
+  cpuUsedPct: z.number(),
+  memUsedBytes: z.number(),
+  memTotalBytes: z.number(),
+  memCacheBytes: z.number(),
+  diskUsedBytes: z.number(),
+  diskTotalBytes: z.number(),
+});
+
+export type SandboxMetricsSample = z.infer<typeof sandboxMetricsSampleSchema>;
+
+export const getSandboxMetricsRequestSchema = z.object({
+  userKey: userKeySchema,
+});
+
+export type GetSandboxMetricsRequest = z.infer<
+  typeof getSandboxMetricsRequestSchema
+>;
+
+export const getSandboxMetricsResponseSchema = z.object({
+  /** Null when nothing is running to measure (stopped, archived, restoring). */
+  sample: sandboxMetricsSampleSchema.nullable(),
+});
+
+export type GetSandboxMetricsResponse = z.infer<
+  typeof getSandboxMetricsResponseSchema
+>;

From c2d225ea40c3ef446864e5ee77e89e5de6a35fd5 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 12 Jul 2026 19:02:58 +0800
Subject: [PATCH 055/133] Bind a domain from the console: managed Caddy ingress
 with honest probes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The daemon still binds 127.0.0.1 — what it gains is custody of one Caddy
config file (DORMICE_INGRESS_FILE). setIngress rewrites it (domain site
plus a :80 catch-all, the no-lockout guarantee) and hot-reloads Caddy;
certificates are entirely Caddy's job (ACME). The file is the single
source of truth: no ledger column, no boot reconcile — getIngress parses
it back and probes reality live (DNS record, TLS handshake against
127.0.0.1:443 with the domain as SNI), so the settings page shows real
progress while a bind converges. An ownership marker guards the file:
configs Dormice did not write are refused, never overwritten, and a
failed reload restores the previous file with Caddy's own words.

install.sh grows an ingress step (pinned Caddy binary with checksum,
honest skip when port 80 is taken), doctor an ingress check, the SDK the
two verbs, the activity ring an ingress-updated kind, and the login page
a plaintext-HTTP notice for the bootstrap phase.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 deploy/install.sh                             |  91 ++++++
 e2e/src/ingress.test.ts                       |  94 +++++++
 e2e/src/setup/daemon.ts                       |   8 +
 packages/cli/src/doctor.test.ts               |  67 +++++
 packages/cli/src/doctor.ts                    |  46 +++
 .../features/activity/pages/ActivityPage.tsx  |   3 +
 .../src/features/auth/pages/LoginPage.tsx     |   8 +
 .../console/src/features/doctor/fixtures.ts   |  22 +-
 .../settings/components/IngressCard.tsx       | 259 +++++++++++++++++
 .../src/features/settings/hooks/useIngress.ts |  27 ++
 .../features/settings/pages/SettingsPage.tsx  |   7 +
 packages/console/src/lib/api.ts               |  12 +
 packages/console/src/lib/mock.ts              |  13 +-
 packages/console/vite.config.ts               |   2 +
 packages/sdk/src/client.ts                    |  27 ++
 packages/server/src/app.ts                    |  10 +
 packages/server/src/config.ts                 |  25 ++
 packages/server/src/ingress.test.ts           | 261 ++++++++++++++++++
 packages/server/src/ingress.ts                | 233 ++++++++++++++++
 packages/server/src/main.ts                   |  19 ++
 packages/server/src/routes/ingress.ts         |  76 +++++
 packages/shared/src/activity.ts               |   2 +
 packages/shared/src/index.ts                  |   1 +
 packages/shared/src/ingress.ts                |  76 +++++
 24 files changed, 1381 insertions(+), 8 deletions(-)
 create mode 100644 e2e/src/ingress.test.ts
 create mode 100644 packages/console/src/features/settings/components/IngressCard.tsx
 create mode 100644 packages/console/src/features/settings/hooks/useIngress.ts
 create mode 100644 packages/server/src/ingress.test.ts
 create mode 100644 packages/server/src/ingress.ts
 create mode 100644 packages/server/src/routes/ingress.ts
 create mode 100644 packages/shared/src/ingress.ts

diff --git a/deploy/install.sh b/deploy/install.sh
index 5802caf..d0134b3 100644
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -309,6 +309,83 @@ else
   note "built $base_image from images/Dockerfile"
 fi
 
+# ---- ingress (Caddy reverse proxy) -------------------------------------------
+# The daemon binds 127.0.0.1 by design; Caddy on :80 is what makes
+# http://<host-ip>/console reachable from a browser. The Caddyfile below is
+# also what the daemon rewrites when the operator binds a domain in the
+# console (setIngress) — Caddy then obtains and renews the TLS certificate
+# on its own. Pinned binary with checksum, same posture as gVisor.
+log 'ingress (Caddy reverse proxy)'
+CADDY_VERSION=2.10.0
+CADDY_SHA512=626682d623ca04356ab3c9a93a82386cfde6d8243b11f2d0eea9e97ba630c7ada62373401e96b72c6690c98ae8dd004d61fafe477f5249690d5cb251ebbfd2d9
+CADDYFILE=/etc/caddy/Caddyfile
+if command -v caddy >/dev/null; then
+  note "[skip] caddy is installed ($(caddy version | cut -d' ' -f1))"
+elif ss -ltnH 'sport = :80' 2>/dev/null | grep -q .; then
+  # Another server owns port 80: never fight it. The operator keeps their
+  # proxy (point it at 127.0.0.1:$PORT); web domain binding stays off.
+  note "port 80 is already in use and caddy is not installed — skipping the ingress layer"
+  note "point your own reverse proxy at 127.0.0.1:$PORT; the console's domain binding stays disabled"
+else
+  caddy_url="https://github.com/caddyserver/caddy/releases/download/v$CADDY_VERSION/caddy_${CADDY_VERSION}_linux_amd64.tar.gz"
+  [ "$MIRROR" = cn ] && caddy_url="https://ghfast.top/$caddy_url"
+  curl -fsSL -o /tmp/caddy.tar.gz "$caddy_url"
+  echo "$CADDY_SHA512  /tmp/caddy.tar.gz" | sha512sum -c - >/dev/null
+  tar -C /tmp -xzf /tmp/caddy.tar.gz caddy
+  install -m 755 /tmp/caddy /usr/local/bin/caddy
+  rm -f /tmp/caddy.tar.gz /tmp/caddy
+  note "installed caddy v$CADDY_VERSION to /usr/local/bin"
+fi
+INGRESS_FILE_READY=''
+if command -v caddy >/dev/null; then
+  mkdir -p /etc/caddy
+  if [ ! -f "$CADDYFILE" ]; then
+    # The marker below is the ownership contract: the daemon refuses to
+    # rewrite a Caddyfile that lacks it. Kept in sync by hand with
+    # packages/server/src/ingress.ts.
+    cat >"$CADDYFILE" <<EOF
+# Managed by Dormice — setIngress rewrites this file.
+
+:80 {
+	reverse_proxy 127.0.0.1:$PORT {
+		flush_interval -1
+	}
+}
+EOF
+    note "wrote $CADDYFILE (plain HTTP on :80 — bind a domain in the console's settings page for HTTPS)"
+    INGRESS_FILE_READY=1
+  elif grep -q 'Managed by Dormice' "$CADDYFILE"; then
+    note "[skip] $CADDYFILE is managed by Dormice — left to the daemon"
+    INGRESS_FILE_READY=1
+  else
+    note "$CADDYFILE exists but was not written by Dormice — left untouched; domain binding will refuse to overwrite it"
+    INGRESS_FILE_READY=1
+  fi
+  if [ ! -f /etc/systemd/system/caddy.service ]; then
+    cat >/etc/systemd/system/caddy.service <<EOF
+[Unit]
+Description=Caddy reverse proxy for Dormice
+After=network.target
+
+[Service]
+ExecStart=/usr/local/bin/caddy run --config $CADDYFILE
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+EOF
+    systemctl daemon-reload
+    note 'wrote /etc/systemd/system/caddy.service'
+  fi
+  systemctl enable caddy >/dev/null 2>&1
+  if [ "$(systemctl is-active caddy)" != active ]; then
+    systemctl start caddy
+    note 'started caddy'
+  else
+    note '[skip] caddy is running'
+  fi
+fi
+
 # ---- daemon configuration ----------------------------------------------------
 log "daemon configuration ($ENV_FILE)"
 install -d -m 700 "$DATA_DIR"
@@ -340,6 +417,16 @@ EOF
   chmod 600 "$ENV_FILE"
   note "wrote $ENV_FILE (mode 600) with a fresh API token"
 fi
+# Appended outside the create-once block so an upgrade re-run picks the
+# knob up too. The knob is what turns on web domain binding in the console.
+if [ -n "$INGRESS_FILE_READY" ] && ! grep -q '^DORMICE_INGRESS_FILE=' "$ENV_FILE"; then
+  {
+    echo '# The Caddy config file the daemon owns: enables binding a domain (and'
+    echo '# getting HTTPS) from the console settings page.'
+    echo "DORMICE_INGRESS_FILE=$CADDYFILE"
+  } >>"$ENV_FILE"
+  note "added DORMICE_INGRESS_FILE=$CADDYFILE to $ENV_FILE"
+fi
 
 # ---- systemd service ---------------------------------------------------------
 log 'systemd service'
@@ -371,3 +458,7 @@ printf '  API token:   grep ^DORMICE_API_TOKEN %s\n' "$ENV_FILE"
 printf '  daemon logs: journalctl -u dormice -f\n'
 printf '  CLI:         export DORMICE_ENDPOINT=http://127.0.0.1:%s DORMICE_API_TOKEN=<token>; dor sandbox ls\n' "$PORT"
 printf '  The daemon listens on 127.0.0.1 only, by design — exposing it is a reverse proxy'"'"'s job.\n'
+if [ "$(systemctl is-active caddy 2>/dev/null)" = active ]; then
+  printf '  console:     http://<this-host-ip>/console (Caddy on :80 — open your cloud firewall for 80/443,\n'
+  printf '               then bind a domain in the settings page for automatic HTTPS)\n'
+fi
diff --git a/e2e/src/ingress.test.ts b/e2e/src/ingress.test.ts
new file mode 100644
index 0000000..1334597
--- /dev/null
+++ b/e2e/src/ingress.test.ts
@@ -0,0 +1,94 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { Dormice } from '@dormice/sdk';
+import { describe, expect, inject, it } from 'vitest';
+
+// Web domain binding, black-box: the daemon owns a Caddy config file (the
+// exam points DORMICE_INGRESS_FILE into its temp dir, reload is a no-op —
+// Caddy's half is real-machine acceptance). The file is an operator-visible
+// artifact, so reading and tampering with it from the test is fair play:
+// that is exactly what an operator can do.
+//
+// Tests in this file share the daemon's single ingress state, so they run
+// as one ordered story instead of independent keys.
+
+function client() {
+  return new Dormice({
+    endpoint: inject('dormiceEndpoint'),
+    token: inject('dormiceToken'),
+  });
+}
+
+describe('ingress domain binding over a real daemon', () => {
+  it('walks bind → status → rebind → clear, with the file telling the same story', async () => {
+    const file = inject('dormiceIngressFile');
+
+    // Managed but unbound: the daemon has a file knob, nothing written yet.
+    const before = await client().getIngress();
+    expect(before).toMatchObject({ managed: true, domain: null, probe: null });
+
+    // Bind. The exam domain has no DNS record — binding must still be
+    // accepted (write the intent, let the probes report reality honestly).
+    const bound = await client().setIngress('console.dormice-e2e.test');
+    expect(bound).toEqual({ domain: 'console.dormice-e2e.test' });
+    const content = readFileSync(file, 'utf8');
+    expect(content).toContain('# Managed by Dormice');
+    expect(content).toContain('console.dormice-e2e.test {');
+    expect(content).toContain(':80 {'); // the no-lockout catch-all
+
+    // Status carries live probes; on a record-less domain they are honest
+    // reds/empties, never invented greens.
+    const status = await client().getIngress();
+    expect(status.managed).toBe(true);
+    expect(status.domain).toBe('console.dormice-e2e.test');
+    expect(status.probe).not.toBeNull();
+    expect(status.probe?.tlsOk).toBe(false);
+
+    // Rebind replaces the site; clear falls back to IP-only.
+    await client().setIngress('other.dormice-e2e.test');
+    expect(readFileSync(file, 'utf8')).not.toContain(
+      'console.dormice-e2e.test',
+    );
+    const cleared = await client().setIngress(null);
+    expect(cleared).toEqual({ domain: null });
+    expect((await client().getIngress()).domain).toBeNull();
+    expect(readFileSync(file, 'utf8')).not.toContain('dormice-e2e.test');
+  });
+
+  it('rejects a domain with a scheme, names the shape it wants', async () => {
+    await expect(
+      client().setIngress('https://console.example.com'),
+    ).rejects.toMatchObject({
+      status: 400,
+      message: expect.stringContaining('bare hostname'),
+    });
+  });
+
+  it('refuses to overwrite a config file it does not own, and recovers', async () => {
+    const file = inject('dormiceIngressFile');
+    const ours = readFileSync(file, 'utf8');
+    writeFileSync(file, ':80 {\n\trespond "hand-edited"\n}\n');
+    await expect(
+      client().setIngress('console.dormice-e2e.test'),
+    ).rejects.toMatchObject({
+      status: 409,
+      message: expect.stringContaining('not written by Dormice'),
+    });
+    // The operator's hand-edited file is untouched by the refusal.
+    expect(readFileSync(file, 'utf8')).toContain('hand-edited');
+    writeFileSync(file, ours);
+    expect((await client().getIngress()).domain).toBeNull();
+  });
+
+  it('records binds in the activity window', async () => {
+    await client().setIngress('activity.dormice-e2e.test');
+    await client().setIngress(null);
+    const events = await client().listActivity();
+    const details = events
+      .filter((event) => event.kind === 'ingress-updated')
+      .map((event) => event.detail);
+    expect(details.length).toBeGreaterThanOrEqual(2);
+    expect(details.some((d) => d.includes('activity.dormice-e2e.test'))).toBe(
+      true,
+    );
+  });
+});
diff --git a/e2e/src/setup/daemon.ts b/e2e/src/setup/daemon.ts
index af9c095..7a70d3f 100644
--- a/e2e/src/setup/daemon.ts
+++ b/e2e/src/setup/daemon.ts
@@ -12,6 +12,8 @@ declare module 'vitest' {
   export interface ProvidedContext {
     dormiceEndpoint: string;
     dormiceToken: string;
+    /** The Caddy config file the exam daemon owns — an operator-visible artifact. */
+    dormiceIngressFile: string;
   }
 }
 
@@ -87,6 +89,11 @@ export default async function setup(project: TestProject) {
       DORMICE_S3_ACCESS_KEY_ID: 'e2e-key',
       DORMICE_S3_SECRET_ACCESS_KEY: 'e2e-secret',
       DORMICE_S3_FORCE_PATH_STYLE: 'true',
+      // A managed ingress so the domain-binding verbs run black-box. The
+      // reload command is a no-op: the exam grades what the daemon writes
+      // and answers, not Caddy — Caddy's side is real-machine acceptance.
+      DORMICE_INGRESS_FILE: join(dataDir, 'Caddyfile'),
+      DORMICE_INGRESS_RELOAD_CMD: 'true',
     },
     stdio: ['ignore', 'pipe', 'pipe'],
   });
@@ -120,6 +127,7 @@ export default async function setup(project: TestProject) {
 
   project.provide('dormiceEndpoint', endpoint);
   project.provide('dormiceToken', token);
+  project.provide('dormiceIngressFile', join(dataDir, 'Caddyfile'));
 
   return async () => {
     child.kill();
diff --git a/packages/cli/src/doctor.test.ts b/packages/cli/src/doctor.test.ts
index a548074..48192ac 100644
--- a/packages/cli/src/doctor.test.ts
+++ b/packages/cli/src/doctor.test.ts
@@ -51,6 +51,8 @@ function fakeHost(
     '/proc/meminfo': 'MemTotal: 30000000 kB\nSwapTotal: 16777212 kB',
     '/proc/sys/vm/swappiness': '100\n',
     '/etc/iptables/rules.v4': IPTABLES_GOOD,
+    '/etc/caddy/Caddyfile':
+      '# Managed by Dormice — setIngress rewrites this file.\n\n:80 {\n\treverse_proxy 127.0.0.1:3676\n}\n',
     ...overrides.files,
   };
   const commands: Record<string, RunResult> = {
@@ -69,6 +71,8 @@ function fakeHost(
     [`docker run --rm --runtime=runsc ${IMAGE} bash -c command -v inotifywait || echo MISSING`]:
       ok('/usr/bin/inotifywait\n'),
     'zstd --version': ok('zstd command line interface v1.5.5\n'),
+    'caddy version': ok('v2.10.0 h1:fakehash\n'),
+    'systemctl is-active caddy': ok('active\n'),
     ...overrides.commands,
   };
   const calls: string[] = [];
@@ -86,6 +90,7 @@ function fakeHost(
       DORMICE_S3_BUCKET: 'dormice-archive',
       DORMICE_S3_ACCESS_KEY_ID: 'minio-user',
       DORMICE_S3_SECRET_ACCESS_KEY: 'minio-secret',
+      DORMICE_INGRESS_FILE: '/etc/caddy/Caddyfile',
     },
     calls,
     run: async (cmd, args) => {
@@ -353,6 +358,68 @@ describe('container probes', () => {
   });
 });
 
+describe('the ingress check', () => {
+  it('skips when the daemon manages no proxy', async () => {
+    const ctx = fakeHost({ env: { DORMICE_API_TOKEN: TOKEN } });
+    const { results } = await runDoctor(ctx, { quick: true });
+    expect(results.ingress).toMatchObject({
+      status: 'skip',
+      detail: expect.stringContaining('DORMICE_INGRESS_FILE'),
+    });
+  });
+
+  it('fails when the knob is set but caddy is missing or stopped', async () => {
+    const noBinary = await runDoctor(
+      fakeHost({ commands: { 'caddy version': boom('not found') } }),
+      { quick: true },
+    );
+    expect(noBinary.results.ingress).toMatchObject({
+      status: 'fail',
+      detail: expect.stringContaining('caddy binary is missing'),
+    });
+
+    const stopped = await runDoctor(
+      fakeHost({ commands: { 'systemctl is-active caddy': boom('inactive') } }),
+      { quick: true },
+    );
+    expect(stopped.results.ingress).toMatchObject({
+      status: 'fail',
+      fix: expect.stringContaining('systemctl start caddy'),
+    });
+  });
+
+  it('warns on a config file Dormice does not own', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        files: {
+          '/etc/caddy/Caddyfile': 'example.org {\n\trespond "mine"\n}\n',
+        },
+      }),
+      { quick: true },
+    );
+    expect(results.ingress).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('not written by Dormice'),
+    });
+  });
+
+  it('reports the bound domain from the managed file', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        files: {
+          '/etc/caddy/Caddyfile':
+            '# Managed by Dormice — setIngress rewrites this file.\n\nconsole.example.com {\n\treverse_proxy 127.0.0.1:3676\n}\n\n:80 {\n\treverse_proxy 127.0.0.1:3676\n}\n',
+        },
+      }),
+      { quick: true },
+    );
+    expect(results.ingress).toMatchObject({
+      status: 'pass',
+      detail: expect.stringContaining('domain console.example.com'),
+    });
+  });
+});
+
 describe('the S3 archive checks', () => {
   // fakeHost's env override replaces wholesale; this is the healthy host's
   // env WITHOUT the S3 set — the archiver-less operator.
diff --git a/packages/cli/src/doctor.ts b/packages/cli/src/doctor.ts
index 6c291ac..c74e564 100644
--- a/packages/cli/src/doctor.ts
+++ b/packages/cli/src/doctor.ts
@@ -399,6 +399,52 @@ const CHECKS: DoctorCheck[] = [
           );
     },
   },
+  {
+    id: 'ingress',
+    title: 'ingress (Caddy)',
+    run: async (ctx) => {
+      const file = ctx.env.DORMICE_INGRESS_FILE;
+      if (!file) {
+        return skip(
+          'DORMICE_INGRESS_FILE not set — the daemon manages no reverse proxy; bind domains by editing your proxy config directly',
+        );
+      }
+      const caddy = await ctx.run('caddy', ['version']);
+      if (!caddy.ok) {
+        return fail(
+          'DORMICE_INGRESS_FILE is set but the caddy binary is missing — setIngress cannot reload anything',
+          're-run install.sh (it installs Caddy), or unset DORMICE_INGRESS_FILE',
+        );
+      }
+      const active = await ctx.run('systemctl', ['is-active', 'caddy']);
+      if (!active.ok) {
+        return fail(
+          'the caddy service is not active — nothing proxies the outside world to the daemon',
+          'systemctl start caddy (and `journalctl -u caddy` for why it stopped)',
+        );
+      }
+      const content = await ctx.readTextFile(file);
+      if (content === undefined) {
+        // Not a failure: setIngress creates the file on the first bind.
+        return warn(`${file} does not exist yet — created on the first bind`);
+      }
+      if (!content.includes('Managed by Dormice')) {
+        return warn(
+          `${file} was not written by Dormice — setIngress refuses to overwrite it, so web domain binding is effectively off`,
+          'move your config elsewhere and re-run install.sh, or point DORMICE_INGRESS_FILE at a file the daemon may own',
+        );
+      }
+      // The generated shape puts site addresses at column 0; the first
+      // non-:80 one is the bound domain.
+      const domain = content
+        .split('\n')
+        .map((line) => /^([^\s#:{][^\s{]*)\s*\{/.exec(line)?.[1])
+        .find((match) => match !== undefined);
+      return pass(
+        `caddy ${caddy.stdout.trim().split(' ')[0]} active; ${domain ? `domain ${domain}` : 'no domain bound (IP access only)'}`,
+      );
+    },
+  },
   {
     id: 'base-image',
     title: 'base image available',
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index e516ce3..4f36ef6 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -35,6 +35,7 @@ export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
   'restore-failed': '恢复失败',
   reconciled: '对账修复',
   'daemon-started': 'daemon 启动',
+  'ingress-updated': '域名配置',
 };
 
 // 事件色与沙箱状态徽章同一色系:落到哪个状态就穿哪个颜色。
@@ -61,6 +62,8 @@ const KIND_STYLES: Record<ActivityKind, string> = {
   reconciled:
     'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
   'daemon-started': 'border-border bg-muted text-muted-foreground',
+  'ingress-updated':
+    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
 };
 
 /**
diff --git a/packages/console/src/features/auth/pages/LoginPage.tsx b/packages/console/src/features/auth/pages/LoginPage.tsx
index 573913d..22d605a 100644
--- a/packages/console/src/features/auth/pages/LoginPage.tsx
+++ b/packages/console/src/features/auth/pages/LoginPage.tsx
@@ -73,6 +73,14 @@ export function LoginPage() {
               {mutation.isPending && <Spinner />}
               登录
             </Button>
+            {!window.isSecureContext && (
+              // 明文 HTTP 下 token 在链路上裸奔 — 引导期(IP 访问)的已知
+              // 取舍,提醒但不拦:绑定域名后这行自然消失。
+              <p className="text-xs text-muted-foreground">
+                当前连接是明文 HTTP,token 在网络上不加密。建议登录后在
+                设置页绑定域名启用 HTTPS。
+              </p>
+            )}
           </form>
         </CardContent>
       </Card>
diff --git a/packages/console/src/features/doctor/fixtures.ts b/packages/console/src/features/doctor/fixtures.ts
index 0edb703..33d9517 100644
--- a/packages/console/src/features/doctor/fixtures.ts
+++ b/packages/console/src/features/doctor/fixtures.ts
@@ -1,8 +1,8 @@
 /**
  * 提案中的 wire 形状:POST /runDoctor 的响应(daemon 内跑 CLI 同一套
  * 只读检查,规则单一来源在 packages/cli/src/doctor.ts)。检查 ID 与真
- * doctor 一比一 — 版式对着真实的 20 项设计,不发明假检查。落地时类型
- * 进 shared,本文件只剩删除。
+ * doctor 一比一,不发明假检查(总数以 doctor.ts 跑出来的为准,会随检查
+ * 增长)。落地时类型进 shared,本文件只剩删除。
  */
 export type DoctorStatus = 'pass' | 'warn' | 'fail' | 'skip';
 
@@ -105,6 +105,24 @@ export const SAMPLE_DOCTOR: DoctorReport = {
       status: 'pass',
       detail: '存在且非空(不显示内容)',
     },
+    {
+      id: 's3-config',
+      title: 'S3 归档配置',
+      status: 'skip',
+      detail: 'DORMICE_S3_* 未配置 — 归档器关闭,沙箱永远停在 stopped',
+    },
+    {
+      id: 'zstd',
+      title: 'zstd 可用',
+      status: 'skip',
+      detail: '归档器关闭时不需要 host 侧 tar + zstd',
+    },
+    {
+      id: 'ingress',
+      title: '接入层(Caddy)',
+      status: 'pass',
+      detail: 'caddy v2.10.0 active;未绑定域名(IP 访问)',
+    },
     {
       id: 'base-image',
       title: '基础镜像存在',
diff --git a/packages/console/src/features/settings/components/IngressCard.tsx b/packages/console/src/features/settings/components/IngressCard.tsx
new file mode 100644
index 0000000..0bd8e7a
--- /dev/null
+++ b/packages/console/src/features/settings/components/IngressCard.tsx
@@ -0,0 +1,259 @@
+import type { GetIngressResponse } from '@dormice/shared';
+import {
+  Alert02Icon,
+  ArrowUpRight01Icon,
+  CheckmarkCircle01Icon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import { Field, FieldDescription, FieldLabel } from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import { useIngress, useSetIngress } from '../hooks/useIngress';
+
+/**
+ * 一行探测结果:绿 = 事实成立,黄 = 还没成立(等待中,不是故障),
+ * 红 = 探测本身失败。probe 是 daemon 请求时现测的,不是缓存。
+ */
+function ProbeRow({
+  label,
+  ok,
+  pendingText,
+  okText,
+  errorText,
+}: {
+  label: string;
+  ok: boolean;
+  pendingText: string;
+  okText: string;
+  errorText: string | null;
+}) {
+  return (
+    <div className="flex items-start gap-2 text-sm">
+      {ok ? (
+        <HugeiconsIcon
+          icon={CheckmarkCircle01Icon}
+          className="mt-0.5 size-4 shrink-0 text-emerald-600 dark:text-emerald-400"
+        />
+      ) : (
+        <HugeiconsIcon
+          icon={Alert02Icon}
+          className="mt-0.5 size-4 shrink-0 text-amber-600 dark:text-amber-400"
+        />
+      )}
+      <div>
+        <span className="font-medium">{label}</span>{' '}
+        <span className="text-muted-foreground">
+          {ok ? okText : pendingText}
+        </span>
+        {!ok && errorText && (
+          <div className="font-mono text-xs text-muted-foreground">
+            {errorText}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function DomainForm({
+  initial,
+  pending,
+  onSubmit,
+  onCancel,
+}: {
+  initial: string;
+  pending: boolean;
+  onSubmit: (domain: string) => void;
+  onCancel?: () => void;
+}) {
+  const [domain, setDomain] = useState(initial);
+  return (
+    <form
+      className="flex flex-col gap-3"
+      onSubmit={(event) => {
+        event.preventDefault();
+        onSubmit(domain.trim());
+      }}
+    >
+      <Field>
+        <FieldLabel htmlFor="ingress-domain">域名</FieldLabel>
+        <Input
+          id="ingress-domain"
+          value={domain}
+          onChange={(event) => setDomain(event.target.value)}
+          placeholder="console.example.com"
+          className="font-mono"
+        />
+        <FieldDescription>
+          先去域名商处添加一条 A 记录,指向本机的公网 IP;绑定后 Caddy 会自动向
+          Let's Encrypt 申请并续期证书,无需手动配置。
+        </FieldDescription>
+      </Field>
+      <div className="flex gap-2">
+        <Button type="submit" disabled={domain.trim().length === 0 || pending}>
+          {pending && <Spinner />}
+          绑定
+        </Button>
+        {onCancel && (
+          <Button type="button" variant="ghost" onClick={onCancel}>
+            取消
+          </Button>
+        )}
+      </div>
+    </form>
+  );
+}
+
+function BoundStatus({
+  status,
+  pending,
+  onRebind,
+  onClear,
+}: {
+  status: GetIngressResponse & { domain: string };
+  pending: boolean;
+  onRebind: (domain: string) => void;
+  onClear: () => void;
+}) {
+  const [editing, setEditing] = useState(false);
+  const probe = status.probe;
+  const dnsOk = (probe?.dnsAddresses.length ?? 0) > 0 && !probe?.dnsError;
+  const tlsOk = probe?.tlsOk ?? false;
+  // 探测跑在 daemon 主机上,证明不了公网可达 — 安全组是它看不见的一层。
+  const hereOverHttp = window.location.protocol === 'http:';
+
+  if (editing) {
+    return (
+      <DomainForm
+        initial={status.domain}
+        pending={pending}
+        onSubmit={onRebind}
+        onCancel={() => setEditing(false)}
+      />
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="font-mono text-sm">{status.domain}</div>
+      <div className="flex flex-col gap-2">
+        <ProbeRow
+          label="DNS 解析"
+          ok={dnsOk}
+          okText={`已解析到 ${probe?.dnsAddresses.join(', ')}`}
+          pendingText={
+            probe?.dnsError
+              ? 'DNS 查询失败'
+              : '还没有解析记录 — 去域名商处加 A 记录指向本机公网 IP,生效通常要几分钟'
+          }
+          errorText={probe?.dnsError ?? null}
+        />
+        <ProbeRow
+          label="HTTPS 证书"
+          ok={tlsOk}
+          okText="证书已签发,HTTPS 正常服务"
+          pendingText={
+            dnsOk
+              ? '签发中 — Caddy 会自动重试,通常一分钟内完成'
+              : '等 DNS 生效后 Caddy 自动申请,无需操作'
+          }
+          errorText={tlsOk ? null : (probe?.tlsError ?? null)}
+        />
+        {tlsOk && hereOverHttp && (
+          <p className="text-sm text-muted-foreground">
+            当前页面还在用明文 HTTP — 若浏览器打不开下面的 HTTPS
+            地址,通常是云安全组还没放行 443 端口。
+          </p>
+        )}
+      </div>
+      <div className="flex flex-wrap gap-2">
+        {tlsOk && hereOverHttp && (
+          <Button
+            nativeButton={false}
+            // 整页跳转:换源意味着 cookie 换域,重新登录是预期行为。
+            render={<a href={`https://${status.domain}/console/settings`} />}
+          >
+            改用 HTTPS 访问
+            <HugeiconsIcon icon={ArrowUpRight01Icon} />
+          </Button>
+        )}
+        <Button variant="outline" onClick={() => setEditing(true)}>
+          更换域名
+        </Button>
+        <Button variant="ghost" disabled={pending} onClick={onClear}>
+          {pending && <Spinner />}
+          解除绑定
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * 域名与 HTTPS:setIngress 改写 daemon 托管的 Caddy 配置并热重载,
+ * 证书全权归 Caddy(ACME)。绑定失败不锁门 — :80 的 IP 访问始终保留。
+ */
+export function IngressCard() {
+  const { data, isPending, isError, error } = useIngress();
+  const mutation = useSetIngress();
+
+  const submit = (domain: string | null) => {
+    mutation.mutate(domain, {
+      onSuccess: () =>
+        toast.success(
+          domain ? `已绑定 ${domain},等待证书签发` : '已解除绑定,回到 IP 访问',
+        ),
+      onError: (mutationError) => toast.error(mutationError.message),
+    });
+  };
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>域名与 HTTPS</CardTitle>
+        <CardDescription>
+          给控制台(和 API)绑一个域名。证书自动申请与续期;绑定期间 IP
+          访问始终可用,不会被锁在门外。
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        {isPending ? (
+          <div className="flex items-center gap-2 text-sm text-muted-foreground">
+            <Spinner /> 读取接入层状态…
+          </div>
+        ) : isError ? (
+          <p className="text-sm text-muted-foreground">{error.message}</p>
+        ) : !data.managed ? (
+          <p className="text-sm text-muted-foreground">
+            本 daemon 未接管反向代理(DORMICE_INGRESS_FILE
+            未配置),网页绑定不可用。重跑 install.sh 会自动装配 Caddy
+            并打开这里;或继续自行维护你的代理配置。
+          </p>
+        ) : data.domain === null ? (
+          <DomainForm
+            initial=""
+            pending={mutation.isPending}
+            onSubmit={submit}
+          />
+        ) : (
+          <BoundStatus
+            status={data as GetIngressResponse & { domain: string }}
+            pending={mutation.isPending}
+            onRebind={submit}
+            onClear={() => submit(null)}
+          />
+        )}
+      </CardContent>
+    </Card>
+  );
+}
diff --git a/packages/console/src/features/settings/hooks/useIngress.ts b/packages/console/src/features/settings/hooks/useIngress.ts
new file mode 100644
index 0000000..72a06bd
--- /dev/null
+++ b/packages/console/src/features/settings/hooks/useIngress.ts
@@ -0,0 +1,27 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { getIngress, setIngress } from '@/lib/api';
+
+/**
+ * daemon 前门(反向代理)的观察与绑定。绑定后证书由 Caddy 后台申请,
+ * 收敛前(域名已绑但 TLS 探测还没绿)每 5s 轮询让进度是真的;收敛后
+ * 停表 — 一张绿卡不值得持续打 DNS。
+ */
+export function useIngress() {
+  return useQuery({
+    queryKey: ['ingress'],
+    queryFn: getIngress,
+    refetchInterval: (query) => {
+      const status = query.state.data;
+      return status?.domain && !status.probe?.tlsOk ? 5_000 : false;
+    },
+    retry: false,
+  });
+}
+
+export function useSetIngress() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: setIngress,
+    onSettled: () => queryClient.invalidateQueries({ queryKey: ['ingress'] }),
+  });
+}
diff --git a/packages/console/src/features/settings/pages/SettingsPage.tsx b/packages/console/src/features/settings/pages/SettingsPage.tsx
index 9595f9b..2bcb944 100644
--- a/packages/console/src/features/settings/pages/SettingsPage.tsx
+++ b/packages/console/src/features/settings/pages/SettingsPage.tsx
@@ -16,6 +16,7 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { formatDuration } from '@/features/sandboxes/format';
+import { IngressCard } from '../components/IngressCard';
 import { useConfig } from '../hooks/useConfig';
 
 /**
@@ -41,6 +42,10 @@ const KEY_HINTS: Record<string, string> = {
   DORMICE_RECLAIM_TIMEOUT_SECONDS: '冻结时挤内存进 swap 的最长等待',
   DORMICE_SANDBOX_DOMAIN:
     '端口预览泛域名(getHost);不配则响应里诚实缺席,代理层不启用',
+  DORMICE_INGRESS_FILE:
+    'daemon 接管的 Caddy 配置文件;配了才能在上方卡片里网页绑定域名',
+  DORMICE_INGRESS_RELOAD_CMD:
+    '改完代理配置后的重载命令;不配默认 caddy reload 托管文件本身',
   DORMICE_S3_ENDPOINT: '归档对象存储的地址;四件套齐了归档才启用',
   DORMICE_S3_BUCKET: '归档桶名',
   DORMICE_S3_ACCESS_KEY_ID: '归档存储的 Access Key(只报已设置)',
@@ -100,6 +105,8 @@ export function SettingsPage() {
         </p>
       </div>
 
+      <IngressCard />
+
       <div className="overflow-x-auto rounded-lg border">
         <Table>
           <TableHeader>
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index a405f35..380e5aa 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -2,11 +2,13 @@ import type {
   AcquireRequest,
   AcquireResponse,
   GetConfigResponse,
+  GetIngressResponse,
   GetSandboxMetricsResponse,
   HostMetricsResponse,
   ListActivityResponse,
   RegisterTemplateResponse,
   Sandbox,
+  SetIngressResponse,
   Template,
 } from '@dormice/shared';
 import { clearSessionMarker, hasSessionMarker } from './session';
@@ -103,6 +105,16 @@ export const listActivity = () => rpc<ListActivityResponse>('/listActivity');
 // their value; archive.enabled is the daemon's own adjudication.
 export const getConfig = () => rpc<GetConfigResponse>('/getConfig');
 
+// The daemon's front door: whether it manages a reverse proxy config, the
+// bound domain, and live probes (DNS record, certificate actually served).
+export const getIngress = () => rpc<GetIngressResponse>('/getIngress');
+
+// Bind (or clear, with null) the console domain. Returns once the proxy
+// accepted the config; the certificate converges afterwards — poll
+// getIngress and show the honest probes.
+export const setIngress = (domain: string | null) =>
+  rpc<SetIngressResponse>('/setIngress', { domain });
+
 export const listTemplates = () =>
   rpc<{ templates: Template[] }>('/listTemplates');
 
diff --git a/packages/console/src/lib/mock.ts b/packages/console/src/lib/mock.ts
index f5b0376..7de4375 100644
--- a/packages/console/src/lib/mock.ts
+++ b/packages/console/src/lib/mock.ts
@@ -1,9 +1,10 @@
 /**
- * The mock gate for pages whose server side does not exist yet (activity,
- * doctor, settings, per-sandbox metrics). In dev they render typed sample
- * data so the UI can be designed first; a production build hides them
- * entirely — a real deployment must never show a fake all-green health
- * report. The fixtures' TYPES are the proposed wire shapes: when the server
- * side lands, they graduate into @dormice/shared and the pages keep working.
+ * The mock gate for pages whose server side does not exist yet — today only
+ * the doctor page (activity, settings and per-sandbox metrics graduated to
+ * real endpoints 2026-07-11). In dev it renders typed sample data so the UI
+ * can be designed first; a production build hides it entirely — a real
+ * deployment must never show a fake all-green health report. The fixtures'
+ * TYPES are the proposed wire shapes: when the server side lands, they
+ * graduate into @dormice/shared and the page keeps working.
  */
 export const MOCK_PAGES_ENABLED = import.meta.env.DEV;
diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index a8309c0..dae3c39 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -35,6 +35,8 @@ export default defineConfig({
       '/getSandboxMetrics': 'http://127.0.0.1:3676',
       '/listActivity': 'http://127.0.0.1:3676',
       '/getConfig': 'http://127.0.0.1:3676',
+      '/getIngress': 'http://127.0.0.1:3676',
+      '/setIngress': 'http://127.0.0.1:3676',
       // The terminal speaks the envd surface directly, like the e2b SDK.
       '/e2b': 'http://127.0.0.1:3676',
     },
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 5a03922..58fc335 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -6,7 +6,9 @@ import {
   type ExecCommandResponse,
   execCommandResponseSchema,
   type GetConfigResponse,
+  type GetIngressResponse,
   getConfigResponseSchema,
+  getIngressResponseSchema,
   getSandboxMetricsResponseSchema,
   type HostMetricsResponse,
   hostMetricsResponseSchema,
@@ -25,6 +27,8 @@ import {
   removeTemplateResponseSchema,
   type Sandbox,
   type SandboxMetricsSample,
+  type SetIngressResponse,
+  setIngressResponseSchema,
   type Template,
   type WriteFilesResponse,
   writeFilesResponseSchema,
@@ -184,6 +188,29 @@ export class Dormice {
     return getConfigResponseSchema.parse(data);
   }
 
+  /**
+   * The daemon's managed front door (the reverse proxy in front of it):
+   * whether one is managed at all, the bound domain, and live probes — what
+   * the domain resolves to and whether the proxy serves a valid certificate
+   * for it. Probes are measured at request time, never cached.
+   */
+  async getIngress(): Promise<GetIngressResponse> {
+    const data = await this.rpc('getIngress', {});
+    return getIngressResponseSchema.parse(data);
+  }
+
+  /**
+   * Binds a domain to the daemon's front door (null unbinds): the managed
+   * Caddy config is rewritten and reloaded, and Caddy obtains the TLS
+   * certificate on its own. Returns as soon as the proxy accepted the
+   * config — poll getIngress to watch DNS and the certificate converge.
+   * Refused (400) when the daemon manages no proxy.
+   */
+  async setIngress(domain: string | null): Promise<SetIngressResponse> {
+    const data = await this.rpc('setIngress', { domain });
+    return setIngressResponseSchema.parse(data);
+  }
+
   /**
    * Swaps the sandbox's container while keeping its disk: /home/user is
    * untouched, and the next use builds a fresh container from the current
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index e79eb58..4e0c21b 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -16,12 +16,14 @@ import { registerE2bCompat } from './e2b';
 import { ProcessTable } from './e2b/process-table';
 import { WatcherTable } from './e2b/watcher-table';
 import type { Executor } from './executor/executor';
+import type { Ingress } from './ingress';
 import type { KeyedQueue } from './keyed-queue';
 import { ARCHIVE_DEFAULT_SECONDS } from './policy';
 import { activityRoutes } from './routes/activity';
 import { configRoutes } from './routes/config';
 import { consoleRoutes } from './routes/console';
 import { hostRoutes } from './routes/host';
+import { ingressRoutes } from './routes/ingress';
 import { sandboxRoutes } from './routes/sandboxes';
 import { templateRoutes } from './routes/templates';
 import { createSandboxProxy } from './sandbox-proxy';
@@ -56,6 +58,12 @@ export interface AppDeps {
    * honestly absent, never half-present).
    */
   archiver?: Archiver;
+  /**
+   * The managed reverse-proxy front door, present exactly when
+   * DORMICE_INGRESS_FILE is set (same rule as the archiver). Absent,
+   * getIngress answers { managed: false } and setIngress refuses.
+   */
+  ingress?: Ingress;
   /**
    * Which knobs came from the environment versus defaults, for getConfig.
    * Defaults to reading process.env — right for the daemon; tests that
@@ -81,6 +89,7 @@ export function buildApp({
   logger = true,
   consoleDistDir,
   archiver,
+  ingress,
   sources = configSources(),
 }: AppDeps) {
   // The archive default is adjudicated once, here, by the archiver's
@@ -169,6 +178,7 @@ export function buildApp({
     await api.register(templateRoutes, { db });
     await api.register(hostRoutes, { config, db, executor });
     await api.register(activityRoutes, { db });
+    await api.register(ingressRoutes, { db, ingress });
     await api.register(configRoutes, {
       config,
       sources,
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index f83d83f..125443c 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -74,6 +74,29 @@ const envSchema = z.object({
       },
     )
     .optional(),
+  /**
+   * The Caddy config file the daemon owns — the switch for web-based domain
+   * binding (setIngress rewrites the file, reloads Caddy, Caddy handles the
+   * certificate). install.sh sets it when it installs Caddy. Unset, the
+   * daemon never touches any proxy config and setIngress is refused — the
+   * feature is honestly absent (the SANDBOX_DOMAIN precedent). Absolute:
+   * a system file must not move with the start directory.
+   */
+  DORMICE_INGRESS_FILE: z
+    .string()
+    .refine(isAbsolute, {
+      error:
+        'DORMICE_INGRESS_FILE must be an absolute path, e.g. /etc/caddy/Caddyfile',
+    })
+    .optional(),
+  /**
+   * How the daemon tells the running proxy to re-read its config after a
+   * bind. Defaults to `caddy reload --config <DORMICE_INGRESS_FILE>` —
+   * right when the daemon owns the whole Caddyfile; an operator whose own
+   * Caddyfile imports a Dormice-owned fragment points this at the outer
+   * file instead.
+   */
+  DORMICE_INGRESS_RELOAD_CMD: z.string().min(1).optional(),
   /**
    * The S3-compatible object store behind the archiver (AWS, R2, MinIO,
    * OSS in S3-compat mode). The four core variables come as a set: with
@@ -177,6 +200,8 @@ export const CONFIG_KEYS: Record<keyof Config, { sensitive: boolean }> = {
   DORMICE_SANDBOX_PIDS_LIMIT: { sensitive: false },
   DORMICE_RECLAIM_TIMEOUT_SECONDS: { sensitive: false },
   DORMICE_SANDBOX_DOMAIN: { sensitive: false },
+  DORMICE_INGRESS_FILE: { sensitive: false },
+  DORMICE_INGRESS_RELOAD_CMD: { sensitive: false },
   DORMICE_S3_ENDPOINT: { sensitive: false },
   DORMICE_S3_BUCKET: { sensitive: false },
   DORMICE_S3_ACCESS_KEY_ID: { sensitive: true },
diff --git a/packages/server/src/ingress.test.ts b/packages/server/src/ingress.test.ts
new file mode 100644
index 0000000..9526631
--- /dev/null
+++ b/packages/server/src/ingress.test.ts
@@ -0,0 +1,261 @@
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getIngressResponseSchema } from '@dormice/shared';
+import { describe, expect, it } from 'vitest';
+import { buildApp } from './app';
+import { loadConfig } from './config';
+import { migrateDb, openDb } from './db/db';
+import { FakeExecutor } from './executor/fake';
+import { Ingress } from './ingress';
+import { KeyedQueue } from './keyed-queue';
+
+// The managed front door: the config file is the single source of truth,
+// so most of what matters is what ends up in the file — and that a failed
+// reload never leaves file and running proxy telling different stories.
+
+const MIGRATIONS = fileURLToPath(new URL('../drizzle', import.meta.url));
+const TOKEN = 'test-token-test-token-test-token';
+const authed = { authorization: `Bearer ${TOKEN}` };
+
+function tmpFile(): string {
+  return path.join(
+    mkdtempSync(path.join(tmpdir(), 'dormice-ingress-')),
+    'Caddyfile',
+  );
+}
+
+function testIngress(
+  overrides: Partial<ConstructorParameters<typeof Ingress>[0]> = {},
+) {
+  const filePath = overrides.filePath ?? tmpFile();
+  const reloads: string[] = [];
+  const ingress = new Ingress({
+    filePath,
+    upstreamPort: 3676,
+    runCommand: async (command) => {
+      reloads.push(command);
+      return { ok: true, stderr: '' };
+    },
+    resolveDomain: async () => ({ dnsAddresses: ['1.2.3.4'], dnsError: null }),
+    probeTls: async () => ({ tlsOk: true, tlsError: null }),
+    ...overrides,
+  });
+  return { ingress, filePath, reloads };
+}
+
+describe('Ingress file round-trip', () => {
+  it('binds a domain: marker, domain site, :80 catch-all — and reads it back', async () => {
+    const { ingress, filePath, reloads } = testIngress();
+    await ingress.setDomain('console.example.com');
+    const content = readFileSync(filePath, 'utf8');
+    expect(content.startsWith('# Managed by Dormice')).toBe(true);
+    expect(content).toContain('console.example.com {');
+    // The no-lockout guarantee: IP access survives every bind.
+    expect(content).toContain(':80 {');
+    expect(content).toContain('reverse_proxy 127.0.0.1:3676');
+    expect(content).toContain('flush_interval -1');
+    expect(ingress.domain()).toBe('console.example.com');
+    expect(reloads).toHaveLength(1);
+  });
+
+  it('clears back to IP-only, and reports null before any file exists', async () => {
+    const { ingress, filePath } = testIngress();
+    expect(ingress.domain()).toBeNull();
+    await ingress.setDomain('console.example.com');
+    await ingress.setDomain(null);
+    const content = readFileSync(filePath, 'utf8');
+    expect(content).not.toContain('example.com');
+    expect(content).toContain(':80 {');
+    expect(ingress.domain()).toBeNull();
+  });
+
+  it('defaults the reload command to caddy reload against its own file', async () => {
+    const filePath = tmpFile();
+    const reloads: string[] = [];
+    const ingress = new Ingress({
+      filePath,
+      upstreamPort: 3676,
+      runCommand: async (command) => {
+        reloads.push(command);
+        return { ok: true, stderr: '' };
+      },
+    });
+    await ingress.setDomain(null);
+    expect(reloads).toEqual([
+      `caddy reload --config ${filePath} --adapter caddyfile`,
+    ]);
+  });
+
+  it('serializes concurrent binds: the last write wins, reloads never interleave', async () => {
+    const filePath = tmpFile();
+    const order: string[] = [];
+    const ingress = new Ingress({
+      filePath,
+      upstreamPort: 3676,
+      runCommand: async () => {
+        order.push(
+          `reload:${readFileSync(filePath, 'utf8').includes('a.example.com') ? 'a' : 'b'}`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        return { ok: true, stderr: '' };
+      },
+    });
+    await Promise.all([
+      ingress.setDomain('a.example.com'),
+      ingress.setDomain('b.example.com'),
+    ]);
+    // Each reload observed the file its own write produced — the second
+    // write waited for the first reload instead of racing it.
+    expect(order).toEqual(['reload:a', 'reload:b']);
+    expect(ingress.domain()).toBe('b.example.com');
+  });
+});
+
+describe('Ingress refusals and rollback', () => {
+  it('refuses to overwrite a file it did not write', async () => {
+    const filePath = tmpFile();
+    writeFileSync(filePath, 'example.org {\n\trespond "mine"\n}\n');
+    const { ingress } = testIngress({ filePath });
+    await expect(ingress.setDomain('console.example.com')).rejects.toThrow(
+      /not written by Dormice/,
+    );
+    // The foreign file is untouched, and not ours to report a domain from.
+    expect(readFileSync(filePath, 'utf8')).toContain('respond "mine"');
+    expect(ingress.domain()).toBeNull();
+  });
+
+  it('restores the previous file when the reload fails', async () => {
+    const { ingress, filePath } = testIngress();
+    await ingress.setDomain('good.example.com');
+    const { ingress: failing } = testIngress({
+      filePath,
+      runCommand: async () => ({ ok: false, stderr: 'adapting config: no' }),
+    });
+    await expect(failing.setDomain('bad.example.com')).rejects.toThrow(
+      /adapting config: no/,
+    );
+    expect(readFileSync(filePath, 'utf8')).toContain('good.example.com');
+  });
+
+  it('removes the file it just created when the first-ever reload fails', async () => {
+    const { ingress, filePath } = testIngress({
+      runCommand: async () => ({ ok: false, stderr: 'caddy not running' }),
+    });
+    await expect(ingress.setDomain('x.example.com')).rejects.toThrow(
+      /caddy not running/,
+    );
+    expect(existsSync(filePath)).toBe(false);
+  });
+});
+
+describe('ingress routes', () => {
+  function testApp(ingress?: Ingress) {
+    const db = openDb(':memory:');
+    migrateDb(db, MIGRATIONS);
+    const config = loadConfig({
+      DORMICE_DB_PATH: ':memory:',
+      DORMICE_API_TOKEN: TOKEN,
+    });
+    const app = buildApp({
+      config,
+      db,
+      executor: new FakeExecutor(),
+      locks: new KeyedQueue(),
+      logger: false,
+      ingress,
+    });
+    return app;
+  }
+
+  const rpc = (
+    app: ReturnType<typeof testApp>,
+    url: string,
+    payload: Record<string, unknown> = {},
+  ) => app.inject({ method: 'POST', url, headers: authed, payload });
+
+  it('without a managed ingress: getIngress is honest, setIngress refuses', async () => {
+    const app = testApp();
+    const get = await rpc(app, '/getIngress');
+    expect(get.statusCode).toBe(200);
+    expect(getIngressResponseSchema.parse(get.json())).toEqual({
+      managed: false,
+      domain: null,
+      probe: null,
+    });
+    const set = await rpc(app, '/setIngress', { domain: 'a.example.com' });
+    expect(set.statusCode).toBe(400);
+    expect(set.json().message).toContain('DORMICE_INGRESS_FILE');
+  });
+
+  it('binds, probes, records activity, clears', async () => {
+    const { ingress } = testIngress();
+    const app = testApp(ingress);
+
+    const set = await rpc(app, '/setIngress', {
+      domain: 'console.example.com',
+    });
+    expect(set.statusCode).toBe(200);
+    expect(set.json()).toEqual({ domain: 'console.example.com' });
+
+    const get = await rpc(app, '/getIngress');
+    const status = getIngressResponseSchema.parse(get.json());
+    expect(status).toEqual({
+      managed: true,
+      domain: 'console.example.com',
+      probe: {
+        dnsAddresses: ['1.2.3.4'],
+        dnsError: null,
+        tlsOk: true,
+        tlsError: null,
+      },
+    });
+
+    const cleared = await rpc(app, '/setIngress', { domain: null });
+    expect(cleared.statusCode).toBe(200);
+    expect(cleared.json()).toEqual({ domain: null });
+
+    const activity = await rpc(app, '/listActivity');
+    const kinds = (
+      activity.json().events as Array<{ kind: string; detail: string }>
+    )
+      .filter((event) => event.kind === 'ingress-updated')
+      .map((event) => event.detail);
+    expect(kinds).toHaveLength(2);
+    expect(kinds[1]).toContain('console.example.com');
+    expect(kinds[0]).toContain('cleared');
+  });
+
+  it('rejects a domain with a scheme at the schema gate', async () => {
+    const { ingress } = testIngress();
+    const app = testApp(ingress);
+    const res = await rpc(app, '/setIngress', {
+      domain: 'https://console.example.com',
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().message).toContain('bare hostname');
+  });
+
+  it('maps a foreign file to 409 and a failed reload to 500, with the reason', async () => {
+    const filePath = tmpFile();
+    writeFileSync(filePath, 'someone-elses-site {\n}\n');
+    const foreign = testApp(testIngress({ filePath }).ingress);
+    const refused = await rpc(foreign, '/setIngress', {
+      domain: 'a.example.com',
+    });
+    expect(refused.statusCode).toBe(409);
+    expect(refused.json().message).toContain('not written by Dormice');
+
+    const broken = testApp(
+      testIngress({
+        runCommand: async () => ({ ok: false, stderr: 'connection refused' }),
+      }).ingress,
+    );
+    const failed = await rpc(broken, '/setIngress', {
+      domain: 'a.example.com',
+    });
+    expect(failed.statusCode).toBe(500);
+    expect(failed.json().message).toContain('connection refused');
+  });
+});
diff --git a/packages/server/src/ingress.ts b/packages/server/src/ingress.ts
new file mode 100644
index 0000000..47da9af
--- /dev/null
+++ b/packages/server/src/ingress.ts
@@ -0,0 +1,233 @@
+import { Resolver } from 'node:dns/promises';
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import tls from 'node:tls';
+import type { GetIngressResponse, IngressProbe } from '@dormice/shared';
+import { execa } from 'execa';
+
+/**
+ * The daemon's own front door: a Caddy config file it owns, rewritten on
+ * setIngress and reloaded into the running Caddy. The file is the single
+ * source of truth — no ledger column, no boot-time reconcile: an operator
+ * can read it, Caddy runs it, and getIngress parses it back. TLS is
+ * entirely Caddy's job (ACME issuance and renewal); this class only decides
+ * what the file says.
+ *
+ * The generated shape is two site blocks: the bound domain (Caddy obtains a
+ * certificate and auto-redirects http://<domain> to https) and a plain :80
+ * catch-all proxying by IP. The catch-all is the no-lockout guarantee — a
+ * bind that never converges (typo'd domain, missing DNS record) leaves IP
+ * access untouched. Caddy inserts its automatic HTTPS redirects after
+ * host-matched routes but before user catch-alls, so the two coexist.
+ */
+
+/**
+ * Ownership marker, line one of every file this class writes. A file the
+ * knob points at that lacks it was written by someone else — refused, never
+ * overwritten. install.sh writes the same marker (kept in sync by hand).
+ */
+const MARKER = '# Managed by Dormice — setIngress rewrites this file.';
+
+/** The knob points at a file this daemon does not own. */
+export class UnmanagedIngressFileError extends Error {}
+
+export interface IngressOptions {
+  /** The Caddy config file the daemon owns (DORMICE_INGRESS_FILE). */
+  filePath: string;
+  /** Where the proxy forwards to: the daemon's own loopback port. */
+  upstreamPort: number;
+  /**
+   * Shell command that makes the running proxy read the new config.
+   * Defaults to `caddy reload` against the standard Caddyfile — right when
+   * the daemon owns the whole file; an operator whose own Caddyfile imports
+   * a fragment overrides this to reload the outer file instead.
+   */
+  reloadCommand?: string;
+  /** Test seam; production shells out through execa. */
+  runCommand?: (command: string) => Promise<{ ok: boolean; stderr: string }>;
+  /** Test seams for the two probes; production asks DNS and 127.0.0.1:443. */
+  resolveDomain?: (
+    domain: string,
+  ) => Promise<Pick<IngressProbe, 'dnsAddresses' | 'dnsError'>>;
+  probeTls?: (
+    domain: string,
+  ) => Promise<Pick<IngressProbe, 'tlsOk' | 'tlsError'>>;
+}
+
+export class Ingress {
+  private readonly filePath: string;
+  private readonly upstreamPort: number;
+  private readonly reloadCommand: string;
+  private readonly runCommand: NonNullable<IngressOptions['runCommand']>;
+  private readonly resolveDomain: NonNullable<IngressOptions['resolveDomain']>;
+  private readonly probeTls: NonNullable<IngressOptions['probeTls']>;
+  /** Serializes writes: two concurrent binds must not interleave write+reload. */
+  private queue: Promise<unknown> = Promise.resolve();
+
+  constructor(options: IngressOptions) {
+    this.filePath = options.filePath;
+    this.upstreamPort = options.upstreamPort;
+    this.reloadCommand =
+      options.reloadCommand ??
+      `caddy reload --config ${options.filePath} --adapter caddyfile`;
+    this.runCommand = options.runCommand ?? runShellCommand;
+    this.resolveDomain = options.resolveDomain ?? resolveDomainDns;
+    this.probeTls = options.probeTls ?? probeLocalTls;
+  }
+
+  /**
+   * The currently bound domain, read back from the file. Null when nothing
+   * is bound, the file does not exist yet, or the file is not ours — a
+   * foreign file's site addresses are not this daemon's to report.
+   */
+  domain(): string | null {
+    if (!existsSync(this.filePath)) return null;
+    const content = readFileSync(this.filePath, 'utf8');
+    if (!content.includes('Managed by Dormice')) return null;
+    for (const line of content.split('\n')) {
+      // Site addresses sit at column 0 in the generated shape; indented
+      // lines are directives (`\treverse_proxy … {`), never sites.
+      const site = /^([^\s#:{][^\s{]*)\s*\{/.exec(line);
+      if (site?.[1]) return site[1];
+    }
+    return null;
+  }
+
+  /**
+   * Rewrites the file for the given domain (null = back to IP-only) and
+   * reloads the proxy. On a failed reload the previous file is restored —
+   * `caddy reload` rejects a bad config without applying it, so file and
+   * running proxy stay consistent — and the failure is thrown with Caddy's
+   * own words.
+   */
+  setDomain(domain: string | null): Promise<void> {
+    const run = this.queue.then(() => this.apply(domain));
+    this.queue = run.catch(() => {});
+    return run;
+  }
+
+  /** Everything getIngress reports: the file's word plus live probes. */
+  async status(): Promise<GetIngressResponse> {
+    const domain = this.domain();
+    if (domain === null) return { managed: true, domain: null, probe: null };
+    const [dns, cert] = await Promise.all([
+      this.resolveDomain(domain),
+      this.probeTls(domain),
+    ]);
+    return { managed: true, domain, probe: { ...dns, ...cert } };
+  }
+
+  private async apply(domain: string | null): Promise<void> {
+    const previous = existsSync(this.filePath)
+      ? readFileSync(this.filePath, 'utf8')
+      : null;
+    if (
+      previous !== null &&
+      previous.trim() !== '' &&
+      !previous.includes('Managed by Dormice')
+    ) {
+      throw new UnmanagedIngressFileError(
+        `${this.filePath} was not written by Dormice — refusing to overwrite it; ` +
+          'move your configuration elsewhere, or point DORMICE_INGRESS_FILE at a file the daemon may own',
+      );
+    }
+    writeFileSync(this.filePath, this.render(domain));
+    const reload = await this.runCommand(this.reloadCommand);
+    if (!reload.ok) {
+      if (previous === null) unlinkSync(this.filePath);
+      else writeFileSync(this.filePath, previous);
+      throw new Error(
+        `reloading the proxy failed (${this.reloadCommand}): ${reload.stderr.trim()} — the previous configuration was restored`,
+      );
+    }
+  }
+
+  private render(domain: string | null): string {
+    // flush_interval -1 streams byte-by-byte: buffering would dam the
+    // console terminal and E2B's streaming exec (measured through Caddy).
+    const site = (address: string) =>
+      `${address} {\n\treverse_proxy 127.0.0.1:${this.upstreamPort} {\n\t\tflush_interval -1\n\t}\n}\n`;
+    return [
+      `${MARKER}\n`,
+      ...(domain === null ? [] : [site(domain)]),
+      site(':80'),
+    ].join('\n');
+  }
+}
+
+async function runShellCommand(
+  command: string,
+): Promise<{ ok: boolean; stderr: string }> {
+  try {
+    await execa(command, { shell: true, timeout: 30_000 });
+    return { ok: true, stderr: '' };
+  } catch (error) {
+    const stderr =
+      error instanceof Error
+        ? ('stderr' in error && String(error.stderr)) || error.message
+        : String(error);
+    return { ok: false, stderr };
+  }
+}
+
+/**
+ * What the domain resolves to right now. "No record" (the state before the
+ * operator's A record lands or propagates) is an empty list, not an error;
+ * dnsError is reserved for the resolver itself failing.
+ */
+async function resolveDomainDns(
+  domain: string,
+): Promise<Pick<IngressProbe, 'dnsAddresses' | 'dnsError'>> {
+  const resolver = new Resolver({ timeout: 3_000, tries: 1 });
+  const lookup = async (kind: 'resolve4' | 'resolve6') => {
+    try {
+      return await resolver[kind](domain);
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === 'ENOTFOUND' || code === 'ENODATA') return [];
+      throw error;
+    }
+  };
+  try {
+    const [v4, v6] = await Promise.all([
+      lookup('resolve4'),
+      lookup('resolve6'),
+    ]);
+    return { dnsAddresses: [...v4, ...v6], dnsError: null };
+  } catch (error) {
+    return {
+      dnsAddresses: [],
+      dnsError: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Does the local proxy serve a valid trusted certificate for the domain?
+ * A handshake against 127.0.0.1:443 with the domain as SNI — deliberately
+ * not a fetch of the public URL: cloud NAT usually cannot hairpin a host's
+ * own public IP, so the honest local fact is "certificate issued and
+ * served", and public reachability stays the security group's question.
+ */
+function probeLocalTls(
+  domain: string,
+): Promise<Pick<IngressProbe, 'tlsOk' | 'tlsError'>> {
+  return new Promise((resolve) => {
+    const socket = tls.connect({
+      host: '127.0.0.1',
+      port: 443,
+      servername: domain,
+      rejectUnauthorized: true,
+    });
+    const done = (result: Pick<IngressProbe, 'tlsOk' | 'tlsError'>) => {
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(3_000, () =>
+      done({ tlsOk: false, tlsError: 'timed out connecting to 127.0.0.1:443' }),
+    );
+    socket.once('secureConnect', () => done({ tlsOk: true, tlsError: null }));
+    socket.once('error', (error) =>
+      done({ tlsOk: false, tlsError: error.message }),
+    );
+  });
+}
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index d0ba213..6294dbd 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -13,6 +13,7 @@ import { acquireSingleWriterLock } from './db/lock';
 import { DockerExecutor } from './executor/docker';
 import type { Executor } from './executor/executor';
 import { FakeExecutor } from './executor/fake';
+import { Ingress } from './ingress';
 import { KeyedQueue } from './keyed-queue';
 import { reconcile } from './reconciler';
 import { scanOnce } from './scanner';
@@ -91,6 +92,23 @@ if (s3 !== null) {
   log.info('archiver disabled: DORMICE_S3_* not configured');
 }
 
+// The managed front door exists exactly when its file knob is set (the
+// archiver's rule). The file itself is the source of truth for the bound
+// domain — nothing to reconcile at boot, Caddy is already running it.
+let ingress: Ingress | undefined;
+if (config.DORMICE_INGRESS_FILE) {
+  ingress = new Ingress({
+    filePath: config.DORMICE_INGRESS_FILE,
+    upstreamPort: config.DORMICE_PORT,
+    reloadCommand: config.DORMICE_INGRESS_RELOAD_CMD,
+  });
+  log.info(
+    `ingress managed at ${config.DORMICE_INGRESS_FILE}: ${ingress.domain() ?? 'no domain bound (IP access only)'}`,
+  );
+} else {
+  log.info('ingress not managed: DORMICE_INGRESS_FILE not configured');
+}
+
 // The web console ships beside the server in the monorepo; this file sits
 // one level under packages/server both as src/main.ts and as dist/main.js,
 // so the relative hop to packages/console/dist is the same either way. A
@@ -110,6 +128,7 @@ const app = buildApp({
   logger: log,
   consoleDistDir: existsSync(consoleDistDir) ? consoleDistDir : undefined,
   archiver,
+  ingress,
 });
 
 // Before trusting the pairing of this ledger and this reality, check it:
diff --git a/packages/server/src/routes/ingress.ts b/packages/server/src/routes/ingress.ts
new file mode 100644
index 0000000..955ce41
--- /dev/null
+++ b/packages/server/src/routes/ingress.ts
@@ -0,0 +1,76 @@
+import {
+  getIngressResponseSchema,
+  setIngressRequestSchema,
+  setIngressResponseSchema,
+} from '@dormice/shared';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import { recordActivity } from '../db/activity';
+import type { Db } from '../db/db';
+import { httpError } from '../http-error';
+import { type Ingress, UnmanagedIngressFileError } from '../ingress';
+
+export interface IngressRoutesOptions {
+  db: Db;
+  /** Present exactly when DORMICE_INGRESS_FILE is set (the archiver precedent). */
+  ingress?: Ingress;
+}
+
+/**
+ * The daemon's front door, over the wire: bind a domain from the console
+ * (or SDK) instead of hand-editing a Caddyfile over SSH. Without a managed
+ * ingress the read is honest ({ managed: false }) and the write refuses
+ * with the reason — never a silent no-op.
+ */
+export const ingressRoutes: FastifyPluginAsyncZod<
+  IngressRoutesOptions
+> = async (app, { db, ingress }) => {
+  app.post(
+    '/getIngress',
+    {
+      schema: {
+        response: { 200: getIngressResponseSchema },
+      },
+    },
+    async () =>
+      ingress
+        ? ingress.status()
+        : { managed: false, domain: null, probe: null },
+  );
+
+  app.post(
+    '/setIngress',
+    {
+      schema: {
+        body: setIngressRequestSchema,
+        response: { 200: setIngressResponseSchema },
+      },
+    },
+    async (request) => {
+      if (!ingress) {
+        throw httpError(
+          400,
+          'this daemon manages no reverse proxy — set DORMICE_INGRESS_FILE (install.sh sets up Caddy and points it at /etc/caddy/Caddyfile), or configure your proxy directly',
+        );
+      }
+      const { domain } = request.body;
+      try {
+        await ingress.setDomain(domain);
+      } catch (error) {
+        if (error instanceof UnmanagedIngressFileError) {
+          throw httpError(409, error.message);
+        }
+        throw httpError(
+          500,
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+      recordActivity(db, {
+        kind: 'ingress-updated',
+        detail: domain
+          ? `console domain bound: ${domain} — certificate issuance is Caddy's job from here`
+          : 'console domain cleared — plain-HTTP IP access only',
+      });
+      return { domain };
+    },
+  );
+};
diff --git a/packages/shared/src/activity.ts b/packages/shared/src/activity.ts
index dfdf449..4e7078c 100644
--- a/packages/shared/src/activity.ts
+++ b/packages/shared/src/activity.ts
@@ -25,6 +25,8 @@ export const ACTIVITY_KINDS = [
   /** The reconciler corrected the ledger (or reality) to match the other. */
   'reconciled',
   'daemon-started',
+  /** An operator bound or cleared the console domain through setIngress. */
+  'ingress-updated',
 ] as const;
 
 export const activityKindSchema = z.enum(ACTIVITY_KINDS);
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index daa2d9e..aa4170c 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -4,6 +4,7 @@ export * from './config';
 export * from './exec';
 export * from './files';
 export * from './host';
+export * from './ingress';
 export * from './list';
 export * from './metrics';
 export * from './policy';
diff --git a/packages/shared/src/ingress.ts b/packages/shared/src/ingress.ts
new file mode 100644
index 0000000..8c1fb7c
--- /dev/null
+++ b/packages/shared/src/ingress.ts
@@ -0,0 +1,76 @@
+import { z } from 'zod';
+
+/**
+ * getIngress()/setIngress() — the daemon's own front door. When the daemon
+ * manages a Caddy config file (DORMICE_INGRESS_FILE), setIngress rewrites it
+ * with a domain site block and reloads Caddy; Caddy then obtains and renews
+ * the TLS certificate on its own (ACME). The daemon itself keeps binding
+ * 127.0.0.1 — what these verbs manage is the reverse proxy in front of it.
+ *
+ * There is no stored state besides the config file: the file is the single
+ * source of truth, and getIngress reads it back plus probes reality (DNS,
+ * the certificate actually served) so a browser can watch a bind converge
+ * with honest progress instead of a spinner.
+ */
+
+/** Same shape rule as DORMICE_SANDBOX_DOMAIN: a bare hostname. */
+export const ingressDomainSchema = z
+  .string()
+  .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i, {
+    error:
+      'domain must be a bare hostname like console.example.com — no scheme, no port, no leading/trailing dots',
+  });
+
+export const setIngressRequestSchema = z.object({
+  /** Null unbinds: the proxy goes back to plain-HTTP IP access only. */
+  domain: ingressDomainSchema.nullable(),
+});
+
+export type SetIngressRequest = z.infer<typeof setIngressRequestSchema>;
+
+export const setIngressResponseSchema = z.object({
+  /**
+   * The domain now written into the proxy config. Certificate issuance
+   * happens after this returns — poll getIngress to watch it converge.
+   */
+  domain: z.string().nullable(),
+});
+
+export type SetIngressResponse = z.infer<typeof setIngressResponseSchema>;
+
+/**
+ * Live observations about a bound domain, measured at request time — never
+ * cached, never invented. Both can be honestly red while the operator's DNS
+ * record propagates; Caddy retries certificate issuance on its own, so a
+ * red probe needs no action beyond fixing what it names.
+ */
+export const ingressProbeSchema = z.object({
+  /** What the domain resolves to right now; empty = no record yet. */
+  dnsAddresses: z.array(z.string()),
+  /** Resolver failure (timeout, SERVFAIL) — distinct from "no record". */
+  dnsError: z.string().nullable(),
+  /**
+   * Whether the local proxy serves a valid trusted certificate for the
+   * domain (a TLS handshake against 127.0.0.1:443 with the domain as SNI).
+   * Proves issuance, not public reachability — a cloud security group can
+   * still block 443 from outside, which no probe from this host can see.
+   */
+  tlsOk: z.boolean(),
+  tlsError: z.string().nullable(),
+});
+
+export type IngressProbe = z.infer<typeof ingressProbeSchema>;
+
+export const getIngressResponseSchema = z.object({
+  /**
+   * Whether this daemon manages a proxy config at all
+   * (DORMICE_INGRESS_FILE set). False = the whole feature is honestly
+   * absent; binding attempts are refused with the reason.
+   */
+  managed: z.boolean(),
+  domain: z.string().nullable(),
+  /** Null unless a domain is bound. */
+  probe: ingressProbeSchema.nullable(),
+});
+
+export type GetIngressResponse = z.infer<typeof getIngressResponseSchema>;

From 0821d0342a2e30f9ce73bc0755b8a597e9790bcb Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 12 Jul 2026 19:09:33 +0800
Subject: [PATCH 056/133] Name the second wall a host probe cannot see: ICP
 filing interception
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Measured on the mainland test machine: with the certificate issued and
served locally, browsers still get Aliyun's "Non-compliance ICP Filing"
block on both 80 and 443 for any unfiled domain — a layer beside the
security group, invisible from the host. The bound-domain hint now names
both.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../console/src/features/settings/components/IngressCard.tsx | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/console/src/features/settings/components/IngressCard.tsx b/packages/console/src/features/settings/components/IngressCard.tsx
index 0bd8e7a..f851df0 100644
--- a/packages/console/src/features/settings/components/IngressCard.tsx
+++ b/packages/console/src/features/settings/components/IngressCard.tsx
@@ -171,8 +171,9 @@ function BoundStatus({
         />
         {tlsOk && hereOverHttp && (
           <p className="text-sm text-muted-foreground">
-            当前页面还在用明文 HTTP — 若浏览器打不开下面的 HTTPS
-            地址,通常是云安全组还没放行 443 端口。
+            当前页面还在用明文 HTTP — 若浏览器打不开下面的 HTTPS 地址,
+            通常是云安全组还没放行 443 端口;中国大陆机房还需域名有 ICP
+            备案,否则云厂商会在入口拦截(与本机配置无关)。
           </p>
         )}
       </div>

From 293a36c676ac5735170364601d35007d01757712 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 12 Jul 2026 19:37:30 +0800
Subject: [PATCH 057/133] Domains get their own console page, and the front
 door learns to serve a set
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

setIngress now takes the full domain list (set semantics: send what you
want, empty clears) — the managed Caddyfile renders one site block per
domain, each with its own ACME certificate, plus the :80 no-lockout
catch-all. getIngress probes every domain independently, so the new
运维/域名 page shows each bind converging on its own: DNS resolution,
certificate issuance, per-domain open/unbind actions, and honest notes
about the walls a host probe cannot see. The settings page goes back to
being a read-only config table.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/src/ingress.test.ts                       |  51 ++-
 packages/cli/src/doctor.test.ts               |   8 +-
 packages/cli/src/doctor.ts                    |  14 +-
 packages/console/src/components/AppShell.tsx  |   1 +
 .../console/src/components/AppSidebar.tsx     |   2 +
 .../src/features/auth/pages/LoginPage.tsx     |   2 +-
 .../{settings => ingress}/hooks/useIngress.ts |   8 +-
 .../features/ingress/pages/DomainsPage.tsx    | 330 ++++++++++++++++++
 .../settings/components/IngressCard.tsx       | 260 --------------
 .../features/settings/pages/SettingsPage.tsx  |   5 +-
 packages/console/src/lib/api.ts               |  15 +-
 packages/console/src/routeTree.gen.ts         |  21 ++
 packages/console/src/routes/_app/domains.tsx  |   6 +
 packages/sdk/src/client.ts                    |  17 +-
 packages/server/src/ingress.test.ts           | 112 +++---
 packages/server/src/ingress.ts                |  74 ++--
 packages/server/src/main.ts                   |   5 +-
 packages/server/src/routes/ingress.ts         |  28 +-
 packages/shared/src/ingress.ts                |  41 ++-
 19 files changed, 590 insertions(+), 410 deletions(-)
 rename packages/console/src/features/{settings => ingress}/hooks/useIngress.ts (72%)
 create mode 100644 packages/console/src/features/ingress/pages/DomainsPage.tsx
 delete mode 100644 packages/console/src/features/settings/components/IngressCard.tsx
 create mode 100644 packages/console/src/routes/_app/domains.tsx

diff --git a/e2e/src/ingress.test.ts b/e2e/src/ingress.test.ts
index 1334597..08f5737 100644
--- a/e2e/src/ingress.test.ts
+++ b/e2e/src/ingress.test.ts
@@ -19,44 +19,57 @@ function client() {
 }
 
 describe('ingress domain binding over a real daemon', () => {
-  it('walks bind → status → rebind → clear, with the file telling the same story', async () => {
+  it('walks bind → add → status → drop → clear, with the file telling the same story', async () => {
     const file = inject('dormiceIngressFile');
 
     // Managed but unbound: the daemon has a file knob, nothing written yet.
     const before = await client().getIngress();
-    expect(before).toMatchObject({ managed: true, domain: null, probe: null });
+    expect(before).toEqual({ managed: true, domains: [] });
 
     // Bind. The exam domain has no DNS record — binding must still be
     // accepted (write the intent, let the probes report reality honestly).
-    const bound = await client().setIngress('console.dormice-e2e.test');
-    expect(bound).toEqual({ domain: 'console.dormice-e2e.test' });
+    const bound = await client().setIngress(['console.dormice-e2e.test']);
+    expect(bound).toEqual({ domains: ['console.dormice-e2e.test'] });
+
+    // Add a second: send the full set (set semantics, not a patch).
+    await client().setIngress([
+      'console.dormice-e2e.test',
+      'api.dormice-e2e.test',
+    ]);
     const content = readFileSync(file, 'utf8');
     expect(content).toContain('# Managed by Dormice');
     expect(content).toContain('console.dormice-e2e.test {');
+    expect(content).toContain('api.dormice-e2e.test {');
     expect(content).toContain(':80 {'); // the no-lockout catch-all
 
-    // Status carries live probes; on a record-less domain they are honest
-    // reds/empties, never invented greens.
+    // Status carries live probes per domain; on record-less domains they
+    // are honest reds/empties, never invented greens.
     const status = await client().getIngress();
     expect(status.managed).toBe(true);
-    expect(status.domain).toBe('console.dormice-e2e.test');
-    expect(status.probe).not.toBeNull();
-    expect(status.probe?.tlsOk).toBe(false);
+    expect(status.domains.map((d) => d.domain)).toEqual([
+      'console.dormice-e2e.test',
+      'api.dormice-e2e.test',
+    ]);
+    for (const { probe } of status.domains) {
+      expect(probe.tlsOk).toBe(false);
+    }
 
-    // Rebind replaces the site; clear falls back to IP-only.
-    await client().setIngress('other.dormice-e2e.test');
+    // Drop one: the remaining set survives, the dropped site is gone.
+    await client().setIngress(['api.dormice-e2e.test']);
     expect(readFileSync(file, 'utf8')).not.toContain(
       'console.dormice-e2e.test',
     );
-    const cleared = await client().setIngress(null);
-    expect(cleared).toEqual({ domain: null });
-    expect((await client().getIngress()).domain).toBeNull();
+
+    // Clear falls back to IP-only.
+    const cleared = await client().setIngress([]);
+    expect(cleared).toEqual({ domains: [] });
+    expect((await client().getIngress()).domains).toEqual([]);
     expect(readFileSync(file, 'utf8')).not.toContain('dormice-e2e.test');
   });
 
   it('rejects a domain with a scheme, names the shape it wants', async () => {
     await expect(
-      client().setIngress('https://console.example.com'),
+      client().setIngress(['https://console.example.com']),
     ).rejects.toMatchObject({
       status: 400,
       message: expect.stringContaining('bare hostname'),
@@ -68,7 +81,7 @@ describe('ingress domain binding over a real daemon', () => {
     const ours = readFileSync(file, 'utf8');
     writeFileSync(file, ':80 {\n\trespond "hand-edited"\n}\n');
     await expect(
-      client().setIngress('console.dormice-e2e.test'),
+      client().setIngress(['console.dormice-e2e.test']),
     ).rejects.toMatchObject({
       status: 409,
       message: expect.stringContaining('not written by Dormice'),
@@ -76,12 +89,12 @@ describe('ingress domain binding over a real daemon', () => {
     // The operator's hand-edited file is untouched by the refusal.
     expect(readFileSync(file, 'utf8')).toContain('hand-edited');
     writeFileSync(file, ours);
-    expect((await client().getIngress()).domain).toBeNull();
+    expect((await client().getIngress()).domains).toEqual([]);
   });
 
   it('records binds in the activity window', async () => {
-    await client().setIngress('activity.dormice-e2e.test');
-    await client().setIngress(null);
+    await client().setIngress(['activity.dormice-e2e.test']);
+    await client().setIngress([]);
     const events = await client().listActivity();
     const details = events
       .filter((event) => event.kind === 'ingress-updated')
diff --git a/packages/cli/src/doctor.test.ts b/packages/cli/src/doctor.test.ts
index 48192ac..538ebbf 100644
--- a/packages/cli/src/doctor.test.ts
+++ b/packages/cli/src/doctor.test.ts
@@ -403,19 +403,21 @@ describe('the ingress check', () => {
     });
   });
 
-  it('reports the bound domain from the managed file', async () => {
+  it('reports every bound domain from the managed file', async () => {
     const { results } = await runDoctor(
       fakeHost({
         files: {
           '/etc/caddy/Caddyfile':
-            '# Managed by Dormice — setIngress rewrites this file.\n\nconsole.example.com {\n\treverse_proxy 127.0.0.1:3676\n}\n\n:80 {\n\treverse_proxy 127.0.0.1:3676\n}\n',
+            '# Managed by Dormice — setIngress rewrites this file.\n\nconsole.example.com {\n\treverse_proxy 127.0.0.1:3676\n}\n\napi.example.com {\n\treverse_proxy 127.0.0.1:3676\n}\n\n:80 {\n\treverse_proxy 127.0.0.1:3676\n}\n',
         },
       }),
       { quick: true },
     );
     expect(results.ingress).toMatchObject({
       status: 'pass',
-      detail: expect.stringContaining('domain console.example.com'),
+      detail: expect.stringContaining(
+        'domains console.example.com, api.example.com',
+      ),
     });
   });
 });
diff --git a/packages/cli/src/doctor.ts b/packages/cli/src/doctor.ts
index c74e564..1d997dd 100644
--- a/packages/cli/src/doctor.ts
+++ b/packages/cli/src/doctor.ts
@@ -434,14 +434,18 @@ const CHECKS: DoctorCheck[] = [
           'move your config elsewhere and re-run install.sh, or point DORMICE_INGRESS_FILE at a file the daemon may own',
         );
       }
-      // The generated shape puts site addresses at column 0; the first
-      // non-:80 one is the bound domain.
-      const domain = content
+      // The generated shape puts site addresses at column 0; every
+      // non-:80 one is a bound domain.
+      const domains = content
         .split('\n')
         .map((line) => /^([^\s#:{][^\s{]*)\s*\{/.exec(line)?.[1])
-        .find((match) => match !== undefined);
+        .filter((match) => match !== undefined);
       return pass(
-        `caddy ${caddy.stdout.trim().split(' ')[0]} active; ${domain ? `domain ${domain}` : 'no domain bound (IP access only)'}`,
+        `caddy ${caddy.stdout.trim().split(' ')[0]} active; ${
+          domains.length
+            ? `domain${domains.length > 1 ? 's' : ''} ${domains.join(', ')}`
+            : 'no domain bound (IP access only)'
+        }`,
       );
     },
   },
diff --git a/packages/console/src/components/AppShell.tsx b/packages/console/src/components/AppShell.tsx
index 75a7111..b6d5c54 100644
--- a/packages/console/src/components/AppShell.tsx
+++ b/packages/console/src/components/AppShell.tsx
@@ -20,6 +20,7 @@ const SEGMENT_LABELS: Record<string, string> = {
   sandboxes: '沙箱',
   templates: '模板',
   activity: '活动',
+  domains: '域名',
   doctor: '体检',
   settings: '设置',
   connect: '连接',
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index c6bb2d6..46ee423 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -1,6 +1,7 @@
 import {
   Activity01Icon,
   DashboardSquare01Icon,
+  Globe02Icon,
   Layers01Icon,
   Logout01Icon,
   Moon02Icon,
@@ -52,6 +53,7 @@ const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
     label: '运维',
     items: [
       { to: '/activity', label: '活动', icon: Activity01Icon },
+      { to: '/domains', label: '域名', icon: Globe02Icon },
       { to: '/doctor', label: '体检', icon: StethoscopeIcon, mock: true },
       { to: '/settings', label: '设置', icon: Settings01Icon },
     ],
diff --git a/packages/console/src/features/auth/pages/LoginPage.tsx b/packages/console/src/features/auth/pages/LoginPage.tsx
index 22d605a..a7c8cfd 100644
--- a/packages/console/src/features/auth/pages/LoginPage.tsx
+++ b/packages/console/src/features/auth/pages/LoginPage.tsx
@@ -78,7 +78,7 @@ export function LoginPage() {
               // 取舍,提醒但不拦:绑定域名后这行自然消失。
               <p className="text-xs text-muted-foreground">
                 当前连接是明文 HTTP,token 在网络上不加密。建议登录后在
-                设置页绑定域名启用 HTTPS。
+                域名页绑定域名启用 HTTPS。
               </p>
             )}
           </form>
diff --git a/packages/console/src/features/settings/hooks/useIngress.ts b/packages/console/src/features/ingress/hooks/useIngress.ts
similarity index 72%
rename from packages/console/src/features/settings/hooks/useIngress.ts
rename to packages/console/src/features/ingress/hooks/useIngress.ts
index 72a06bd..d5acfb3 100644
--- a/packages/console/src/features/settings/hooks/useIngress.ts
+++ b/packages/console/src/features/ingress/hooks/useIngress.ts
@@ -3,8 +3,8 @@ import { getIngress, setIngress } from '@/lib/api';
 
 /**
  * daemon 前门(反向代理)的观察与绑定。绑定后证书由 Caddy 后台申请,
- * 收敛前(域名已绑但 TLS 探测还没绿)每 5s 轮询让进度是真的;收敛后
- * 停表 — 一张绿卡不值得持续打 DNS。
+ * 只要还有域名没收敛(TLS 探测没绿)就每 5s 轮询让进度是真的;全绿后
+ * 停表 — 一排绿卡不值得持续打 DNS。
  */
 export function useIngress() {
   return useQuery({
@@ -12,7 +12,9 @@ export function useIngress() {
     queryFn: getIngress,
     refetchInterval: (query) => {
       const status = query.state.data;
-      return status?.domain && !status.probe?.tlsOk ? 5_000 : false;
+      return status?.domains.some((entry) => !entry.probe.tlsOk)
+        ? 5_000
+        : false;
     },
     retry: false,
   });
diff --git a/packages/console/src/features/ingress/pages/DomainsPage.tsx b/packages/console/src/features/ingress/pages/DomainsPage.tsx
new file mode 100644
index 0000000..8373e4e
--- /dev/null
+++ b/packages/console/src/features/ingress/pages/DomainsPage.tsx
@@ -0,0 +1,330 @@
+import type { IngressDomainStatus, IngressProbe } from '@dormice/shared';
+import {
+  Alert02Icon,
+  ArrowUpRight01Icon,
+  CheckmarkCircle01Icon,
+  Globe02Icon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { type FormEvent, useState } from 'react';
+import { toast } from 'sonner';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import { Field, FieldDescription, FieldLabel } from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import {
+  Item,
+  ItemActions,
+  ItemContent,
+  ItemDescription,
+  ItemGroup,
+  ItemMedia,
+  ItemTitle,
+} from '@/components/ui/item';
+import { Spinner } from '@/components/ui/spinner';
+import { useIngress, useSetIngress } from '../hooks/useIngress';
+
+/**
+ * 每个域名此刻的收敛阶段,从两个探测推出来:绿 = 事实成立,黄 = 还没
+ * 成立(等待中,不是故障),红 = 探测本身失败。探测是 daemon 请求时现
+ * 测的,不是缓存 — 没收敛的域名每 5s 轮询,页面上的进度是真的。
+ */
+type DomainPhase = 'ready' | 'issuing' | 'waiting-dns' | 'dns-error';
+
+function phaseOf(probe: IngressProbe): DomainPhase {
+  if (probe.tlsOk) return 'ready';
+  if (probe.dnsError) return 'dns-error';
+  if (probe.dnsAddresses.length === 0) return 'waiting-dns';
+  return 'issuing';
+}
+
+const PHASE_BADGES: Record<DomainPhase, { label: string; className: string }> =
+  {
+    ready: {
+      label: 'HTTPS 已就绪',
+      className:
+        'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+    },
+    issuing: {
+      label: '证书签发中',
+      className:
+        'border-sky-500/40 bg-sky-500/10 text-sky-600 dark:text-sky-400',
+    },
+    'waiting-dns': {
+      label: '等待 DNS 解析',
+      className:
+        'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
+    },
+    'dns-error': {
+      label: 'DNS 查询失败',
+      className:
+        'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
+    },
+  };
+
+function describeProbe(probe: IngressProbe, phase: DomainPhase): string {
+  const resolved = `已解析到 ${probe.dnsAddresses.join(', ')}`;
+  switch (phase) {
+    case 'ready':
+      return `${resolved};证书已签发,HTTPS 正常服务`;
+    case 'issuing':
+      return `${resolved};Caddy 正在申请证书 — 自动重试,通常一分钟内完成`;
+    case 'waiting-dns':
+      return '还没有解析记录 — 去域名商处加一条 A 记录指向本机公网 IP,生效通常要几分钟';
+    case 'dns-error':
+      return '解析器查询失败(超时或上游故障),会随下一轮探测自动重试';
+  }
+}
+
+/** 探测的原话(证书报错/解析报错),等待阶段的排障线索。 */
+function probeErrorLine(
+  probe: IngressProbe,
+  phase: DomainPhase,
+): string | null {
+  if (phase === 'issuing') return probe.tlsError;
+  if (phase === 'dns-error') return probe.dnsError;
+  return null;
+}
+
+function DomainItem({
+  status,
+  removing,
+  busy,
+  onRemove,
+}: {
+  status: IngressDomainStatus;
+  /** 正在解绑的是不是本行(行内 spinner 只亮在被点的那行)。 */
+  removing: boolean;
+  busy: boolean;
+  onRemove: () => void;
+}) {
+  const phase = phaseOf(status.probe);
+  const badge = PHASE_BADGES[phase];
+  const errorLine = probeErrorLine(status.probe, phase);
+  // 正从这个域名访问控制台:不用再"打开",解绑等于拆自己脚下的梯子,
+  // 但 :80 的 IP 访问兜底还在,所以只标注、不禁止。
+  const isHere = window.location.hostname === status.domain;
+
+  return (
+    <Item variant="outline">
+      <ItemMedia variant="icon">
+        {phase === 'ready' ? (
+          <HugeiconsIcon
+            icon={CheckmarkCircle01Icon}
+            className="text-emerald-600 dark:text-emerald-400"
+          />
+        ) : phase === 'issuing' ? (
+          <Spinner className="text-sky-600 dark:text-sky-400" />
+        ) : (
+          <HugeiconsIcon
+            icon={Alert02Icon}
+            className={
+              phase === 'dns-error'
+                ? 'text-red-600 dark:text-red-400'
+                : 'text-amber-600 dark:text-amber-400'
+            }
+          />
+        )}
+      </ItemMedia>
+      <ItemContent>
+        <ItemTitle className="flex flex-wrap items-center gap-2 font-mono">
+          {status.domain}
+          <Badge variant="outline" className={badge.className}>
+            {badge.label}
+          </Badge>
+          {isHere && <Badge variant="secondary">当前访问</Badge>}
+        </ItemTitle>
+        <ItemDescription>{describeProbe(status.probe, phase)}</ItemDescription>
+        {errorLine && (
+          <div className="font-mono text-xs text-muted-foreground">
+            {errorLine}
+          </div>
+        )}
+      </ItemContent>
+      <ItemActions>
+        {phase === 'ready' && !isHere && (
+          <Button
+            variant="outline"
+            size="sm"
+            nativeButton={false}
+            // 新标签页:换源意味着 cookie 换域,要重新登录 — 别把当前会话跳丢。
+            render={
+              <a
+                href={`https://${status.domain}/console/`}
+                target="_blank"
+                rel="noreferrer"
+              />
+            }
+          >
+            打开
+            <HugeiconsIcon icon={ArrowUpRight01Icon} />
+          </Button>
+        )}
+        <Button variant="ghost" size="sm" disabled={busy} onClick={onRemove}>
+          {removing && <Spinner />}
+          解绑
+        </Button>
+      </ItemActions>
+    </Item>
+  );
+}
+
+/**
+ * 域名页:setIngress 改写 daemon 托管的 Caddy 配置并热重载,证书全权
+ * 归 Caddy(ACME)。wire 是集合语义 — 增删都是"把想要的完整清单发过
+ * 去",页面在已绑清单上加一个/减一个再整体提交。绑定失败不锁门:
+ * :80 的 IP 访问在每次改写里都保留。
+ */
+export function DomainsPage() {
+  const { data, isPending, isError, error } = useIngress();
+  const mutation = useSetIngress();
+  const [draft, setDraft] = useState('');
+  const [removing, setRemoving] = useState<string | null>(null);
+
+  const statuses = data?.domains ?? [];
+  const bound = statuses.map((entry) => entry.domain);
+
+  const add = (event: FormEvent) => {
+    event.preventDefault();
+    const domain = draft.trim().toLowerCase();
+    if (domain.length === 0) return;
+    if (bound.includes(domain)) {
+      toast.info(`${domain} 已经绑定`);
+      return;
+    }
+    mutation.mutate([...bound, domain], {
+      onSuccess: () => {
+        setDraft('');
+        toast.success(`已绑定 ${domain},等待证书签发`);
+      },
+      onError: (mutationError) => toast.error(mutationError.message),
+    });
+  };
+
+  const remove = (domain: string) => {
+    setRemoving(domain);
+    mutation.mutate(
+      bound.filter((entry) => entry !== domain),
+      {
+        onSuccess: () => toast.success(`已解绑 ${domain}`),
+        onError: (mutationError) => toast.error(mutationError.message),
+        onSettled: () => setRemoving(null),
+      },
+    );
+  };
+
+  return (
+    <>
+      <div>
+        <h1 className="text-lg font-semibold">域名</h1>
+        <p className="text-sm text-muted-foreground">
+          给控制台(和 API)绑定域名,HTTPS
+          证书自动申请与续期。可以绑多个;无论绑定成败,IP
+          访问始终保留,不会被锁在门外。
+        </p>
+      </div>
+
+      {isPending ? (
+        <div className="flex items-center gap-2 text-sm text-muted-foreground">
+          <Spinner /> 读取域名配置…
+        </div>
+      ) : isError ? (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyTitle>读取失败</EmptyTitle>
+            <EmptyDescription>{error.message}</EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      ) : !data.managed ? (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyMedia variant="icon">
+              <HugeiconsIcon icon={Globe02Icon} />
+            </EmptyMedia>
+            <EmptyTitle>本 daemon 未接管反向代理</EmptyTitle>
+            <EmptyDescription>
+              DORMICE_INGRESS_FILE 未配置,网页绑定不可用。重跑 install.sh
+              会自动装配 Caddy 并打开这里;或继续自行维护你的代理配置。
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      ) : (
+        <>
+          {statuses.length > 0 && (
+            <ItemGroup className="gap-2">
+              {statuses.map((status) => (
+                <DomainItem
+                  key={status.domain}
+                  status={status}
+                  removing={removing === status.domain}
+                  busy={mutation.isPending}
+                  onRemove={() => remove(status.domain)}
+                />
+              ))}
+            </ItemGroup>
+          )}
+
+          <Card>
+            <CardHeader>
+              <CardTitle>
+                {statuses.length === 0 ? '绑定第一个域名' : '再绑一个域名'}
+              </CardTitle>
+              <CardDescription>
+                三步:去域名商处加一条 A 记录指向本机公网 IP → 在这里绑定 →
+                证书自动申请与续期,无需手动配置。
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <form className="flex flex-col gap-3" onSubmit={add}>
+                <Field>
+                  <FieldLabel htmlFor="ingress-domain">域名</FieldLabel>
+                  <Input
+                    id="ingress-domain"
+                    value={draft}
+                    onChange={(event) => setDraft(event.target.value)}
+                    placeholder="console.example.com"
+                    className="max-w-md font-mono"
+                  />
+                  <FieldDescription>
+                    裸主机名,不带 http:// 前缀和端口。
+                  </FieldDescription>
+                </Field>
+                <div>
+                  <Button
+                    type="submit"
+                    disabled={draft.trim().length === 0 || mutation.isPending}
+                  >
+                    {mutation.isPending && removing === null && <Spinner />}
+                    绑定
+                  </Button>
+                </div>
+              </form>
+            </CardContent>
+          </Card>
+
+          {statuses.length > 0 && (
+            <p className="text-sm text-muted-foreground">
+              以上探测跑在服务器本机,证明不了公网可达:若浏览器打不开 HTTPS
+              地址,通常是云安全组还没放行 443 端口;中国大陆机房还需域名有 ICP
+              备案,否则云厂商会在入口拦截(与本机配置无关)。
+            </p>
+          )}
+        </>
+      )}
+    </>
+  );
+}
diff --git a/packages/console/src/features/settings/components/IngressCard.tsx b/packages/console/src/features/settings/components/IngressCard.tsx
deleted file mode 100644
index f851df0..0000000
--- a/packages/console/src/features/settings/components/IngressCard.tsx
+++ /dev/null
@@ -1,260 +0,0 @@
-import type { GetIngressResponse } from '@dormice/shared';
-import {
-  Alert02Icon,
-  ArrowUpRight01Icon,
-  CheckmarkCircle01Icon,
-} from '@hugeicons/core-free-icons';
-import { HugeiconsIcon } from '@hugeicons/react';
-import { useState } from 'react';
-import { toast } from 'sonner';
-import { Button } from '@/components/ui/button';
-import {
-  Card,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from '@/components/ui/card';
-import { Field, FieldDescription, FieldLabel } from '@/components/ui/field';
-import { Input } from '@/components/ui/input';
-import { Spinner } from '@/components/ui/spinner';
-import { useIngress, useSetIngress } from '../hooks/useIngress';
-
-/**
- * 一行探测结果:绿 = 事实成立,黄 = 还没成立(等待中,不是故障),
- * 红 = 探测本身失败。probe 是 daemon 请求时现测的,不是缓存。
- */
-function ProbeRow({
-  label,
-  ok,
-  pendingText,
-  okText,
-  errorText,
-}: {
-  label: string;
-  ok: boolean;
-  pendingText: string;
-  okText: string;
-  errorText: string | null;
-}) {
-  return (
-    <div className="flex items-start gap-2 text-sm">
-      {ok ? (
-        <HugeiconsIcon
-          icon={CheckmarkCircle01Icon}
-          className="mt-0.5 size-4 shrink-0 text-emerald-600 dark:text-emerald-400"
-        />
-      ) : (
-        <HugeiconsIcon
-          icon={Alert02Icon}
-          className="mt-0.5 size-4 shrink-0 text-amber-600 dark:text-amber-400"
-        />
-      )}
-      <div>
-        <span className="font-medium">{label}</span>{' '}
-        <span className="text-muted-foreground">
-          {ok ? okText : pendingText}
-        </span>
-        {!ok && errorText && (
-          <div className="font-mono text-xs text-muted-foreground">
-            {errorText}
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
-
-function DomainForm({
-  initial,
-  pending,
-  onSubmit,
-  onCancel,
-}: {
-  initial: string;
-  pending: boolean;
-  onSubmit: (domain: string) => void;
-  onCancel?: () => void;
-}) {
-  const [domain, setDomain] = useState(initial);
-  return (
-    <form
-      className="flex flex-col gap-3"
-      onSubmit={(event) => {
-        event.preventDefault();
-        onSubmit(domain.trim());
-      }}
-    >
-      <Field>
-        <FieldLabel htmlFor="ingress-domain">域名</FieldLabel>
-        <Input
-          id="ingress-domain"
-          value={domain}
-          onChange={(event) => setDomain(event.target.value)}
-          placeholder="console.example.com"
-          className="font-mono"
-        />
-        <FieldDescription>
-          先去域名商处添加一条 A 记录,指向本机的公网 IP;绑定后 Caddy 会自动向
-          Let's Encrypt 申请并续期证书,无需手动配置。
-        </FieldDescription>
-      </Field>
-      <div className="flex gap-2">
-        <Button type="submit" disabled={domain.trim().length === 0 || pending}>
-          {pending && <Spinner />}
-          绑定
-        </Button>
-        {onCancel && (
-          <Button type="button" variant="ghost" onClick={onCancel}>
-            取消
-          </Button>
-        )}
-      </div>
-    </form>
-  );
-}
-
-function BoundStatus({
-  status,
-  pending,
-  onRebind,
-  onClear,
-}: {
-  status: GetIngressResponse & { domain: string };
-  pending: boolean;
-  onRebind: (domain: string) => void;
-  onClear: () => void;
-}) {
-  const [editing, setEditing] = useState(false);
-  const probe = status.probe;
-  const dnsOk = (probe?.dnsAddresses.length ?? 0) > 0 && !probe?.dnsError;
-  const tlsOk = probe?.tlsOk ?? false;
-  // 探测跑在 daemon 主机上,证明不了公网可达 — 安全组是它看不见的一层。
-  const hereOverHttp = window.location.protocol === 'http:';
-
-  if (editing) {
-    return (
-      <DomainForm
-        initial={status.domain}
-        pending={pending}
-        onSubmit={onRebind}
-        onCancel={() => setEditing(false)}
-      />
-    );
-  }
-
-  return (
-    <div className="flex flex-col gap-4">
-      <div className="font-mono text-sm">{status.domain}</div>
-      <div className="flex flex-col gap-2">
-        <ProbeRow
-          label="DNS 解析"
-          ok={dnsOk}
-          okText={`已解析到 ${probe?.dnsAddresses.join(', ')}`}
-          pendingText={
-            probe?.dnsError
-              ? 'DNS 查询失败'
-              : '还没有解析记录 — 去域名商处加 A 记录指向本机公网 IP,生效通常要几分钟'
-          }
-          errorText={probe?.dnsError ?? null}
-        />
-        <ProbeRow
-          label="HTTPS 证书"
-          ok={tlsOk}
-          okText="证书已签发,HTTPS 正常服务"
-          pendingText={
-            dnsOk
-              ? '签发中 — Caddy 会自动重试,通常一分钟内完成'
-              : '等 DNS 生效后 Caddy 自动申请,无需操作'
-          }
-          errorText={tlsOk ? null : (probe?.tlsError ?? null)}
-        />
-        {tlsOk && hereOverHttp && (
-          <p className="text-sm text-muted-foreground">
-            当前页面还在用明文 HTTP — 若浏览器打不开下面的 HTTPS 地址,
-            通常是云安全组还没放行 443 端口;中国大陆机房还需域名有 ICP
-            备案,否则云厂商会在入口拦截(与本机配置无关)。
-          </p>
-        )}
-      </div>
-      <div className="flex flex-wrap gap-2">
-        {tlsOk && hereOverHttp && (
-          <Button
-            nativeButton={false}
-            // 整页跳转:换源意味着 cookie 换域,重新登录是预期行为。
-            render={<a href={`https://${status.domain}/console/settings`} />}
-          >
-            改用 HTTPS 访问
-            <HugeiconsIcon icon={ArrowUpRight01Icon} />
-          </Button>
-        )}
-        <Button variant="outline" onClick={() => setEditing(true)}>
-          更换域名
-        </Button>
-        <Button variant="ghost" disabled={pending} onClick={onClear}>
-          {pending && <Spinner />}
-          解除绑定
-        </Button>
-      </div>
-    </div>
-  );
-}
-
-/**
- * 域名与 HTTPS:setIngress 改写 daemon 托管的 Caddy 配置并热重载,
- * 证书全权归 Caddy(ACME)。绑定失败不锁门 — :80 的 IP 访问始终保留。
- */
-export function IngressCard() {
-  const { data, isPending, isError, error } = useIngress();
-  const mutation = useSetIngress();
-
-  const submit = (domain: string | null) => {
-    mutation.mutate(domain, {
-      onSuccess: () =>
-        toast.success(
-          domain ? `已绑定 ${domain},等待证书签发` : '已解除绑定,回到 IP 访问',
-        ),
-      onError: (mutationError) => toast.error(mutationError.message),
-    });
-  };
-
-  return (
-    <Card>
-      <CardHeader>
-        <CardTitle>域名与 HTTPS</CardTitle>
-        <CardDescription>
-          给控制台(和 API)绑一个域名。证书自动申请与续期;绑定期间 IP
-          访问始终可用,不会被锁在门外。
-        </CardDescription>
-      </CardHeader>
-      <CardContent>
-        {isPending ? (
-          <div className="flex items-center gap-2 text-sm text-muted-foreground">
-            <Spinner /> 读取接入层状态…
-          </div>
-        ) : isError ? (
-          <p className="text-sm text-muted-foreground">{error.message}</p>
-        ) : !data.managed ? (
-          <p className="text-sm text-muted-foreground">
-            本 daemon 未接管反向代理(DORMICE_INGRESS_FILE
-            未配置),网页绑定不可用。重跑 install.sh 会自动装配 Caddy
-            并打开这里;或继续自行维护你的代理配置。
-          </p>
-        ) : data.domain === null ? (
-          <DomainForm
-            initial=""
-            pending={mutation.isPending}
-            onSubmit={submit}
-          />
-        ) : (
-          <BoundStatus
-            status={data as GetIngressResponse & { domain: string }}
-            pending={mutation.isPending}
-            onRebind={submit}
-            onClear={() => submit(null)}
-          />
-        )}
-      </CardContent>
-    </Card>
-  );
-}
diff --git a/packages/console/src/features/settings/pages/SettingsPage.tsx b/packages/console/src/features/settings/pages/SettingsPage.tsx
index 2bcb944..0e078d3 100644
--- a/packages/console/src/features/settings/pages/SettingsPage.tsx
+++ b/packages/console/src/features/settings/pages/SettingsPage.tsx
@@ -16,7 +16,6 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { formatDuration } from '@/features/sandboxes/format';
-import { IngressCard } from '../components/IngressCard';
 import { useConfig } from '../hooks/useConfig';
 
 /**
@@ -43,7 +42,7 @@ const KEY_HINTS: Record<string, string> = {
   DORMICE_SANDBOX_DOMAIN:
     '端口预览泛域名(getHost);不配则响应里诚实缺席,代理层不启用',
   DORMICE_INGRESS_FILE:
-    'daemon 接管的 Caddy 配置文件;配了才能在上方卡片里网页绑定域名',
+    'daemon 接管的 Caddy 配置文件;配了才能在「域名」页网页绑定域名',
   DORMICE_INGRESS_RELOAD_CMD:
     '改完代理配置后的重载命令;不配默认 caddy reload 托管文件本身',
   DORMICE_S3_ENDPOINT: '归档对象存储的地址;四件套齐了归档才启用',
@@ -105,8 +104,6 @@ export function SettingsPage() {
         </p>
       </div>
 
-      <IngressCard />
-
       <div className="overflow-x-auto rounded-lg border">
         <Table>
           <TableHeader>
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 380e5aa..d769663 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -105,15 +105,16 @@ export const listActivity = () => rpc<ListActivityResponse>('/listActivity');
 // their value; archive.enabled is the daemon's own adjudication.
 export const getConfig = () => rpc<GetConfigResponse>('/getConfig');
 
-// The daemon's front door: whether it manages a reverse proxy config, the
-// bound domain, and live probes (DNS record, certificate actually served).
+// The daemon's front door: whether it manages a reverse proxy config, and
+// every bound domain with live probes (DNS record, certificate served).
 export const getIngress = () => rpc<GetIngressResponse>('/getIngress');
 
-// Bind (or clear, with null) the console domain. Returns once the proxy
-// accepted the config; the certificate converges afterwards — poll
-// getIngress and show the honest probes.
-export const setIngress = (domain: string | null) =>
-  rpc<SetIngressResponse>('/setIngress', { domain });
+// Set the full console domain list (set semantics: send the list you want,
+// empty clears everything). Returns once the proxy accepted the config; the
+// certificates converge afterwards — poll getIngress and show the honest
+// probes.
+export const setIngress = (domains: string[]) =>
+  rpc<SetIngressResponse>('/setIngress', { domains });
 
 export const listTemplates = () =>
   rpc<{ templates: Template[] }>('/listTemplates');
diff --git a/packages/console/src/routeTree.gen.ts b/packages/console/src/routeTree.gen.ts
index 441847c..f2f5d61 100644
--- a/packages/console/src/routeTree.gen.ts
+++ b/packages/console/src/routeTree.gen.ts
@@ -14,6 +14,7 @@ import { Route as AppRouteImport } from './routes/_app'
 import { Route as AppIndexRouteImport } from './routes/_app/index'
 import { Route as AppTemplatesRouteImport } from './routes/_app/templates'
 import { Route as AppSettingsRouteImport } from './routes/_app/settings'
+import { Route as AppDomainsRouteImport } from './routes/_app/domains'
 import { Route as AppDoctorRouteImport } from './routes/_app/doctor'
 import { Route as AppConnectRouteImport } from './routes/_app/connect'
 import { Route as AppActivityRouteImport } from './routes/_app/activity'
@@ -44,6 +45,11 @@ const AppSettingsRoute = AppSettingsRouteImport.update({
   path: '/settings',
   getParentRoute: () => AppRoute,
 } as any)
+const AppDomainsRoute = AppDomainsRouteImport.update({
+  id: '/domains',
+  path: '/domains',
+  getParentRoute: () => AppRoute,
+} as any)
 const AppDoctorRoute = AppDoctorRouteImport.update({
   id: '/doctor',
   path: '/doctor',
@@ -76,6 +82,7 @@ export interface FileRoutesByFullPath {
   '/activity': typeof AppActivityRoute
   '/connect': typeof AppConnectRoute
   '/doctor': typeof AppDoctorRoute
+  '/domains': typeof AppDomainsRoute
   '/settings': typeof AppSettingsRoute
   '/templates': typeof AppTemplatesRoute
   '/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
@@ -86,6 +93,7 @@ export interface FileRoutesByTo {
   '/activity': typeof AppActivityRoute
   '/connect': typeof AppConnectRoute
   '/doctor': typeof AppDoctorRoute
+  '/domains': typeof AppDomainsRoute
   '/settings': typeof AppSettingsRoute
   '/templates': typeof AppTemplatesRoute
   '/': typeof AppIndexRoute
@@ -99,6 +107,7 @@ export interface FileRoutesById {
   '/_app/activity': typeof AppActivityRoute
   '/_app/connect': typeof AppConnectRoute
   '/_app/doctor': typeof AppDoctorRoute
+  '/_app/domains': typeof AppDomainsRoute
   '/_app/settings': typeof AppSettingsRoute
   '/_app/templates': typeof AppTemplatesRoute
   '/_app/': typeof AppIndexRoute
@@ -113,6 +122,7 @@ export interface FileRouteTypes {
     | '/activity'
     | '/connect'
     | '/doctor'
+    | '/domains'
     | '/settings'
     | '/templates'
     | '/sandboxes/$userKey'
@@ -123,6 +133,7 @@ export interface FileRouteTypes {
     | '/activity'
     | '/connect'
     | '/doctor'
+    | '/domains'
     | '/settings'
     | '/templates'
     | '/'
@@ -135,6 +146,7 @@ export interface FileRouteTypes {
     | '/_app/activity'
     | '/_app/connect'
     | '/_app/doctor'
+    | '/_app/domains'
     | '/_app/settings'
     | '/_app/templates'
     | '/_app/'
@@ -184,6 +196,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AppSettingsRouteImport
       parentRoute: typeof AppRoute
     }
+    '/_app/domains': {
+      id: '/_app/domains'
+      path: '/domains'
+      fullPath: '/domains'
+      preLoaderRoute: typeof AppDomainsRouteImport
+      parentRoute: typeof AppRoute
+    }
     '/_app/doctor': {
       id: '/_app/doctor'
       path: '/doctor'
@@ -226,6 +245,7 @@ interface AppRouteChildren {
   AppActivityRoute: typeof AppActivityRoute
   AppConnectRoute: typeof AppConnectRoute
   AppDoctorRoute: typeof AppDoctorRoute
+  AppDomainsRoute: typeof AppDomainsRoute
   AppSettingsRoute: typeof AppSettingsRoute
   AppTemplatesRoute: typeof AppTemplatesRoute
   AppIndexRoute: typeof AppIndexRoute
@@ -237,6 +257,7 @@ const AppRouteChildren: AppRouteChildren = {
   AppActivityRoute: AppActivityRoute,
   AppConnectRoute: AppConnectRoute,
   AppDoctorRoute: AppDoctorRoute,
+  AppDomainsRoute: AppDomainsRoute,
   AppSettingsRoute: AppSettingsRoute,
   AppTemplatesRoute: AppTemplatesRoute,
   AppIndexRoute: AppIndexRoute,
diff --git a/packages/console/src/routes/_app/domains.tsx b/packages/console/src/routes/_app/domains.tsx
new file mode 100644
index 0000000..88e6e4f
--- /dev/null
+++ b/packages/console/src/routes/_app/domains.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { DomainsPage } from '@/features/ingress/pages/DomainsPage';
+
+export const Route = createFileRoute('/_app/domains')({
+  component: DomainsPage,
+});
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 58fc335..c7ee753 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -190,9 +190,9 @@ export class Dormice {
 
   /**
    * The daemon's managed front door (the reverse proxy in front of it):
-   * whether one is managed at all, the bound domain, and live probes — what
-   * the domain resolves to and whether the proxy serves a valid certificate
-   * for it. Probes are measured at request time, never cached.
+   * whether one is managed at all, and every bound domain with live probes
+   * — what each domain resolves to and whether the proxy serves a valid
+   * certificate for it. Probes are measured at request time, never cached.
    */
   async getIngress(): Promise<GetIngressResponse> {
     const data = await this.rpc('getIngress', {});
@@ -200,14 +200,15 @@ export class Dormice {
   }
 
   /**
-   * Binds a domain to the daemon's front door (null unbinds): the managed
-   * Caddy config is rewritten and reloaded, and Caddy obtains the TLS
+   * Sets the full domain list on the daemon's front door (set semantics:
+   * send the list you want, empty unbinds everything): the managed Caddy
+   * config is rewritten and reloaded, and Caddy obtains each TLS
    * certificate on its own. Returns as soon as the proxy accepted the
-   * config — poll getIngress to watch DNS and the certificate converge.
+   * config — poll getIngress to watch DNS and the certificates converge.
    * Refused (400) when the daemon manages no proxy.
    */
-  async setIngress(domain: string | null): Promise<SetIngressResponse> {
-    const data = await this.rpc('setIngress', { domain });
+  async setIngress(domains: string[]): Promise<SetIngressResponse> {
+    const data = await this.rpc('setIngress', { domains });
     return setIngressResponseSchema.parse(data);
   }
 
diff --git a/packages/server/src/ingress.test.ts b/packages/server/src/ingress.test.ts
index 9526631..6073655 100644
--- a/packages/server/src/ingress.test.ts
+++ b/packages/server/src/ingress.test.ts
@@ -46,29 +46,46 @@ function testIngress(
 }
 
 describe('Ingress file round-trip', () => {
-  it('binds a domain: marker, domain site, :80 catch-all — and reads it back', async () => {
+  it('binds domains: marker, one site each, :80 catch-all — and reads them back in order', async () => {
     const { ingress, filePath, reloads } = testIngress();
-    await ingress.setDomain('console.example.com');
+    await ingress.setDomains(['console.example.com', 'api.example.com']);
     const content = readFileSync(filePath, 'utf8');
     expect(content.startsWith('# Managed by Dormice')).toBe(true);
     expect(content).toContain('console.example.com {');
+    expect(content).toContain('api.example.com {');
     // The no-lockout guarantee: IP access survives every bind.
     expect(content).toContain(':80 {');
     expect(content).toContain('reverse_proxy 127.0.0.1:3676');
     expect(content).toContain('flush_interval -1');
-    expect(ingress.domain()).toBe('console.example.com');
+    expect(ingress.domains()).toEqual([
+      'console.example.com',
+      'api.example.com',
+    ]);
     expect(reloads).toHaveLength(1);
   });
 
-  it('clears back to IP-only, and reports null before any file exists', async () => {
+  it('lowercases and dedups: hostnames are case-insensitive, the file decides once', async () => {
+    const { ingress } = testIngress();
+    await ingress.setDomains([
+      'Console.Example.COM',
+      'console.example.com',
+      'api.example.com',
+    ]);
+    expect(ingress.domains()).toEqual([
+      'console.example.com',
+      'api.example.com',
+    ]);
+  });
+
+  it('clears back to IP-only, and reports empty before any file exists', async () => {
     const { ingress, filePath } = testIngress();
-    expect(ingress.domain()).toBeNull();
-    await ingress.setDomain('console.example.com');
-    await ingress.setDomain(null);
+    expect(ingress.domains()).toEqual([]);
+    await ingress.setDomains(['console.example.com']);
+    await ingress.setDomains([]);
     const content = readFileSync(filePath, 'utf8');
     expect(content).not.toContain('example.com');
     expect(content).toContain(':80 {');
-    expect(ingress.domain()).toBeNull();
+    expect(ingress.domains()).toEqual([]);
   });
 
   it('defaults the reload command to caddy reload against its own file', async () => {
@@ -82,7 +99,7 @@ describe('Ingress file round-trip', () => {
         return { ok: true, stderr: '' };
       },
     });
-    await ingress.setDomain(null);
+    await ingress.setDomains([]);
     expect(reloads).toEqual([
       `caddy reload --config ${filePath} --adapter caddyfile`,
     ]);
@@ -103,13 +120,13 @@ describe('Ingress file round-trip', () => {
       },
     });
     await Promise.all([
-      ingress.setDomain('a.example.com'),
-      ingress.setDomain('b.example.com'),
+      ingress.setDomains(['a.example.com']),
+      ingress.setDomains(['b.example.com']),
     ]);
     // Each reload observed the file its own write produced — the second
     // write waited for the first reload instead of racing it.
     expect(order).toEqual(['reload:a', 'reload:b']);
-    expect(ingress.domain()).toBe('b.example.com');
+    expect(ingress.domains()).toEqual(['b.example.com']);
   });
 });
 
@@ -118,22 +135,22 @@ describe('Ingress refusals and rollback', () => {
     const filePath = tmpFile();
     writeFileSync(filePath, 'example.org {\n\trespond "mine"\n}\n');
     const { ingress } = testIngress({ filePath });
-    await expect(ingress.setDomain('console.example.com')).rejects.toThrow(
+    await expect(ingress.setDomains(['console.example.com'])).rejects.toThrow(
       /not written by Dormice/,
     );
-    // The foreign file is untouched, and not ours to report a domain from.
+    // The foreign file is untouched, and not ours to report domains from.
     expect(readFileSync(filePath, 'utf8')).toContain('respond "mine"');
-    expect(ingress.domain()).toBeNull();
+    expect(ingress.domains()).toEqual([]);
   });
 
   it('restores the previous file when the reload fails', async () => {
     const { ingress, filePath } = testIngress();
-    await ingress.setDomain('good.example.com');
+    await ingress.setDomains(['good.example.com']);
     const { ingress: failing } = testIngress({
       filePath,
       runCommand: async () => ({ ok: false, stderr: 'adapting config: no' }),
     });
-    await expect(failing.setDomain('bad.example.com')).rejects.toThrow(
+    await expect(failing.setDomains(['bad.example.com'])).rejects.toThrow(
       /adapting config: no/,
     );
     expect(readFileSync(filePath, 'utf8')).toContain('good.example.com');
@@ -143,7 +160,7 @@ describe('Ingress refusals and rollback', () => {
     const { ingress, filePath } = testIngress({
       runCommand: async () => ({ ok: false, stderr: 'caddy not running' }),
     });
-    await expect(ingress.setDomain('x.example.com')).rejects.toThrow(
+    await expect(ingress.setDomains(['x.example.com'])).rejects.toThrow(
       /caddy not running/,
     );
     expect(existsSync(filePath)).toBe(false);
@@ -181,57 +198,72 @@ describe('ingress routes', () => {
     expect(get.statusCode).toBe(200);
     expect(getIngressResponseSchema.parse(get.json())).toEqual({
       managed: false,
-      domain: null,
-      probe: null,
+      domains: [],
+    });
+    const set = await rpc(app, '/setIngress', {
+      domains: ['a.example.com'],
     });
-    const set = await rpc(app, '/setIngress', { domain: 'a.example.com' });
     expect(set.statusCode).toBe(400);
     expect(set.json().message).toContain('DORMICE_INGRESS_FILE');
   });
 
-  it('binds, probes, records activity, clears', async () => {
+  it('binds two, probes each, drops one, records the diffs, clears', async () => {
     const { ingress } = testIngress();
     const app = testApp(ingress);
 
     const set = await rpc(app, '/setIngress', {
-      domain: 'console.example.com',
+      domains: ['console.example.com', 'api.example.com'],
     });
     expect(set.statusCode).toBe(200);
-    expect(set.json()).toEqual({ domain: 'console.example.com' });
+    expect(set.json()).toEqual({
+      domains: ['console.example.com', 'api.example.com'],
+    });
 
     const get = await rpc(app, '/getIngress');
     const status = getIngressResponseSchema.parse(get.json());
+    const probe = {
+      dnsAddresses: ['1.2.3.4'],
+      dnsError: null,
+      tlsOk: true,
+      tlsError: null,
+    };
     expect(status).toEqual({
       managed: true,
-      domain: 'console.example.com',
-      probe: {
-        dnsAddresses: ['1.2.3.4'],
-        dnsError: null,
-        tlsOk: true,
-        tlsError: null,
-      },
+      domains: [
+        { domain: 'console.example.com', probe },
+        { domain: 'api.example.com', probe },
+      ],
+    });
+
+    const dropped = await rpc(app, '/setIngress', {
+      domains: ['api.example.com'],
     });
+    expect(dropped.json()).toEqual({ domains: ['api.example.com'] });
 
-    const cleared = await rpc(app, '/setIngress', { domain: null });
+    const cleared = await rpc(app, '/setIngress', { domains: [] });
     expect(cleared.statusCode).toBe(200);
-    expect(cleared.json()).toEqual({ domain: null });
+    expect(cleared.json()).toEqual({ domains: [] });
 
     const activity = await rpc(app, '/listActivity');
-    const kinds = (
+    const details = (
       activity.json().events as Array<{ kind: string; detail: string }>
     )
       .filter((event) => event.kind === 'ingress-updated')
       .map((event) => event.detail);
-    expect(kinds).toHaveLength(2);
-    expect(kinds[1]).toContain('console.example.com');
-    expect(kinds[0]).toContain('cleared');
+    // Newest first: clear, drop, the double bind.
+    expect(details).toHaveLength(3);
+    expect(details[2]).toContain('bound console.example.com');
+    expect(details[2]).toContain('bound api.example.com');
+    expect(details[1]).toContain('unbound console.example.com');
+    expect(details[1]).toContain('now serving api.example.com');
+    expect(details[0]).toContain('plain-HTTP IP access only');
   });
 
   it('rejects a domain with a scheme at the schema gate', async () => {
     const { ingress } = testIngress();
     const app = testApp(ingress);
     const res = await rpc(app, '/setIngress', {
-      domain: 'https://console.example.com',
+      domains: ['https://console.example.com'],
     });
     expect(res.statusCode).toBe(400);
     expect(res.json().message).toContain('bare hostname');
@@ -242,7 +274,7 @@ describe('ingress routes', () => {
     writeFileSync(filePath, 'someone-elses-site {\n}\n');
     const foreign = testApp(testIngress({ filePath }).ingress);
     const refused = await rpc(foreign, '/setIngress', {
-      domain: 'a.example.com',
+      domains: ['a.example.com'],
     });
     expect(refused.statusCode).toBe(409);
     expect(refused.json().message).toContain('not written by Dormice');
@@ -253,7 +285,7 @@ describe('ingress routes', () => {
       }).ingress,
     );
     const failed = await rpc(broken, '/setIngress', {
-      domain: 'a.example.com',
+      domains: ['a.example.com'],
     });
     expect(failed.statusCode).toBe(500);
     expect(failed.json().message).toContain('connection refused');
diff --git a/packages/server/src/ingress.ts b/packages/server/src/ingress.ts
index 47da9af..07345b2 100644
--- a/packages/server/src/ingress.ts
+++ b/packages/server/src/ingress.ts
@@ -12,12 +12,13 @@ import { execa } from 'execa';
  * entirely Caddy's job (ACME issuance and renewal); this class only decides
  * what the file says.
  *
- * The generated shape is two site blocks: the bound domain (Caddy obtains a
- * certificate and auto-redirects http://<domain> to https) and a plain :80
- * catch-all proxying by IP. The catch-all is the no-lockout guarantee — a
- * bind that never converges (typo'd domain, missing DNS record) leaves IP
- * access untouched. Caddy inserts its automatic HTTPS redirects after
- * host-matched routes but before user catch-alls, so the two coexist.
+ * The generated shape is one site block per bound domain (Caddy obtains a
+ * certificate per domain and auto-redirects http://<domain> to https) plus
+ * a plain :80 catch-all proxying by IP. The catch-all is the no-lockout
+ * guarantee — a bind that never converges (typo'd domain, missing DNS
+ * record) leaves IP access untouched. Caddy inserts its automatic HTTPS
+ * redirects after host-matched routes but before user catch-alls, so the
+ * domain sites and the catch-all coexist.
  */
 
 /**
@@ -75,48 +76,57 @@ export class Ingress {
   }
 
   /**
-   * The currently bound domain, read back from the file. Null when nothing
-   * is bound, the file does not exist yet, or the file is not ours — a
-   * foreign file's site addresses are not this daemon's to report.
+   * The currently bound domains, read back from the file in the order they
+   * are served. Empty when nothing is bound, the file does not exist yet,
+   * or the file is not ours — a foreign file's site addresses are not this
+   * daemon's to report.
    */
-  domain(): string | null {
-    if (!existsSync(this.filePath)) return null;
+  domains(): string[] {
+    if (!existsSync(this.filePath)) return [];
     const content = readFileSync(this.filePath, 'utf8');
-    if (!content.includes('Managed by Dormice')) return null;
+    if (!content.includes('Managed by Dormice')) return [];
+    const found: string[] = [];
     for (const line of content.split('\n')) {
       // Site addresses sit at column 0 in the generated shape; indented
-      // lines are directives (`\treverse_proxy … {`), never sites.
+      // lines are directives (`\treverse_proxy … {`), never sites. The
+      // leading-`:` exclusion keeps the :80 catch-all out of the answer.
       const site = /^([^\s#:{][^\s{]*)\s*\{/.exec(line);
-      if (site?.[1]) return site[1];
+      if (site?.[1]) found.push(site[1]);
     }
-    return null;
+    return found;
   }
 
   /**
-   * Rewrites the file for the given domain (null = back to IP-only) and
-   * reloads the proxy. On a failed reload the previous file is restored —
+   * Rewrites the file to serve exactly the given set (empty = back to
+   * IP-only) and reloads the proxy. Hostnames are case-insensitive, so the
+   * set is lowercased and deduped here — the one place that decides what
+   * the file says. On a failed reload the previous file is restored —
    * `caddy reload` rejects a bad config without applying it, so file and
    * running proxy stay consistent — and the failure is thrown with Caddy's
    * own words.
    */
-  setDomain(domain: string | null): Promise<void> {
-    const run = this.queue.then(() => this.apply(domain));
+  setDomains(domains: string[]): Promise<void> {
+    const wanted = [...new Set(domains.map((domain) => domain.toLowerCase()))];
+    const run = this.queue.then(() => this.apply(wanted));
     this.queue = run.catch(() => {});
     return run;
   }
 
   /** Everything getIngress reports: the file's word plus live probes. */
   async status(): Promise<GetIngressResponse> {
-    const domain = this.domain();
-    if (domain === null) return { managed: true, domain: null, probe: null };
-    const [dns, cert] = await Promise.all([
-      this.resolveDomain(domain),
-      this.probeTls(domain),
-    ]);
-    return { managed: true, domain, probe: { ...dns, ...cert } };
+    const statuses = await Promise.all(
+      this.domains().map(async (domain) => {
+        const [dns, cert] = await Promise.all([
+          this.resolveDomain(domain),
+          this.probeTls(domain),
+        ]);
+        return { domain, probe: { ...dns, ...cert } };
+      }),
+    );
+    return { managed: true, domains: statuses };
   }
 
-  private async apply(domain: string | null): Promise<void> {
+  private async apply(domains: string[]): Promise<void> {
     const previous = existsSync(this.filePath)
       ? readFileSync(this.filePath, 'utf8')
       : null;
@@ -130,7 +140,7 @@ export class Ingress {
           'move your configuration elsewhere, or point DORMICE_INGRESS_FILE at a file the daemon may own',
       );
     }
-    writeFileSync(this.filePath, this.render(domain));
+    writeFileSync(this.filePath, this.render(domains));
     const reload = await this.runCommand(this.reloadCommand);
     if (!reload.ok) {
       if (previous === null) unlinkSync(this.filePath);
@@ -141,16 +151,12 @@ export class Ingress {
     }
   }
 
-  private render(domain: string | null): string {
+  private render(domains: string[]): string {
     // flush_interval -1 streams byte-by-byte: buffering would dam the
     // console terminal and E2B's streaming exec (measured through Caddy).
     const site = (address: string) =>
       `${address} {\n\treverse_proxy 127.0.0.1:${this.upstreamPort} {\n\t\tflush_interval -1\n\t}\n}\n`;
-    return [
-      `${MARKER}\n`,
-      ...(domain === null ? [] : [site(domain)]),
-      site(':80'),
-    ].join('\n');
+    return [`${MARKER}\n`, ...domains.map(site), site(':80')].join('\n');
   }
 }
 
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 6294dbd..2eb3e0d 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -94,7 +94,7 @@ if (s3 !== null) {
 
 // The managed front door exists exactly when its file knob is set (the
 // archiver's rule). The file itself is the source of truth for the bound
-// domain — nothing to reconcile at boot, Caddy is already running it.
+// domains — nothing to reconcile at boot, Caddy is already running it.
 let ingress: Ingress | undefined;
 if (config.DORMICE_INGRESS_FILE) {
   ingress = new Ingress({
@@ -102,8 +102,9 @@ if (config.DORMICE_INGRESS_FILE) {
     upstreamPort: config.DORMICE_PORT,
     reloadCommand: config.DORMICE_INGRESS_RELOAD_CMD,
   });
+  const domains = ingress.domains();
   log.info(
-    `ingress managed at ${config.DORMICE_INGRESS_FILE}: ${ingress.domain() ?? 'no domain bound (IP access only)'}`,
+    `ingress managed at ${config.DORMICE_INGRESS_FILE}: ${domains.length ? domains.join(', ') : 'no domain bound (IP access only)'}`,
   );
 } else {
   log.info('ingress not managed: DORMICE_INGRESS_FILE not configured');
diff --git a/packages/server/src/routes/ingress.ts b/packages/server/src/routes/ingress.ts
index 955ce41..3c02f8e 100644
--- a/packages/server/src/routes/ingress.ts
+++ b/packages/server/src/routes/ingress.ts
@@ -31,10 +31,7 @@ export const ingressRoutes: FastifyPluginAsyncZod<
         response: { 200: getIngressResponseSchema },
       },
     },
-    async () =>
-      ingress
-        ? ingress.status()
-        : { managed: false, domain: null, probe: null },
+    async () => (ingress ? ingress.status() : { managed: false, domains: [] }),
   );
 
   app.post(
@@ -52,9 +49,9 @@ export const ingressRoutes: FastifyPluginAsyncZod<
           'this daemon manages no reverse proxy — set DORMICE_INGRESS_FILE (install.sh sets up Caddy and points it at /etc/caddy/Caddyfile), or configure your proxy directly',
         );
       }
-      const { domain } = request.body;
+      const previous = ingress.domains();
       try {
-        await ingress.setDomain(domain);
+        await ingress.setDomains(request.body.domains);
       } catch (error) {
         if (error instanceof UnmanagedIngressFileError) {
           throw httpError(409, error.message);
@@ -64,13 +61,24 @@ export const ingressRoutes: FastifyPluginAsyncZod<
           error instanceof Error ? error.message : String(error),
         );
       }
+      // The file (not the request) is the truth to report and to log:
+      // read back what setDomains actually wrote (lowercased, deduped).
+      const domains = ingress.domains();
+      const changes = [
+        ...domains
+          .filter((domain) => !previous.includes(domain))
+          .map((domain) => `bound ${domain}`),
+        ...previous
+          .filter((domain) => !domains.includes(domain))
+          .map((domain) => `unbound ${domain}`),
+      ];
       recordActivity(db, {
         kind: 'ingress-updated',
-        detail: domain
-          ? `console domain bound: ${domain} — certificate issuance is Caddy's job from here`
-          : 'console domain cleared — plain-HTTP IP access only',
+        detail: `${changes.join(', ') || 'domains unchanged'} — now serving ${
+          domains.length ? domains.join(', ') : 'plain-HTTP IP access only'
+        }`,
       });
-      return { domain };
+      return { domains };
     },
   );
 };
diff --git a/packages/shared/src/ingress.ts b/packages/shared/src/ingress.ts
index 8c1fb7c..76d27ac 100644
--- a/packages/shared/src/ingress.ts
+++ b/packages/shared/src/ingress.ts
@@ -3,14 +3,15 @@ import { z } from 'zod';
 /**
  * getIngress()/setIngress() — the daemon's own front door. When the daemon
  * manages a Caddy config file (DORMICE_INGRESS_FILE), setIngress rewrites it
- * with a domain site block and reloads Caddy; Caddy then obtains and renews
- * the TLS certificate on its own (ACME). The daemon itself keeps binding
- * 127.0.0.1 — what these verbs manage is the reverse proxy in front of it.
+ * with one site block per bound domain and reloads Caddy; Caddy then obtains
+ * and renews each TLS certificate on its own (ACME). The daemon itself keeps
+ * binding 127.0.0.1 — what these verbs manage is the reverse proxy in front
+ * of it.
  *
  * There is no stored state besides the config file: the file is the single
- * source of truth, and getIngress reads it back plus probes reality (DNS,
- * the certificate actually served) so a browser can watch a bind converge
- * with honest progress instead of a spinner.
+ * source of truth, and getIngress reads it back plus probes reality per
+ * domain (DNS, the certificate actually served) so a browser can watch each
+ * bind converge with honest progress instead of a spinner.
  */
 
 /** Same shape rule as DORMICE_SANDBOX_DOMAIN: a bare hostname. */
@@ -22,18 +23,24 @@ export const ingressDomainSchema = z
   });
 
 export const setIngressRequestSchema = z.object({
-  /** Null unbinds: the proxy goes back to plain-HTTP IP access only. */
-  domain: ingressDomainSchema.nullable(),
+  /**
+   * The full set of domains to serve — set semantics, not a patch: the
+   * proxy config is rewritten to exactly this list (adding and removing are
+   * both "send the list you want"). Empty = back to plain-HTTP IP access
+   * only. Hostnames are case-insensitive; the daemon lowercases and dedups.
+   */
+  domains: z.array(ingressDomainSchema),
 });
 
 export type SetIngressRequest = z.infer<typeof setIngressRequestSchema>;
 
 export const setIngressResponseSchema = z.object({
   /**
-   * The domain now written into the proxy config. Certificate issuance
-   * happens after this returns — poll getIngress to watch it converge.
+   * The domains now written into the proxy config (normalized). Certificate
+   * issuance happens after this returns — poll getIngress to watch each one
+   * converge.
    */
-  domain: z.string().nullable(),
+  domains: z.array(z.string()),
 });
 
 export type SetIngressResponse = z.infer<typeof setIngressResponseSchema>;
@@ -61,6 +68,13 @@ export const ingressProbeSchema = z.object({
 
 export type IngressProbe = z.infer<typeof ingressProbeSchema>;
 
+export const ingressDomainStatusSchema = z.object({
+  domain: z.string(),
+  probe: ingressProbeSchema,
+});
+
+export type IngressDomainStatus = z.infer<typeof ingressDomainStatusSchema>;
+
 export const getIngressResponseSchema = z.object({
   /**
    * Whether this daemon manages a proxy config at all
@@ -68,9 +82,8 @@ export const getIngressResponseSchema = z.object({
    * absent; binding attempts are refused with the reason.
    */
   managed: z.boolean(),
-  domain: z.string().nullable(),
-  /** Null unless a domain is bound. */
-  probe: ingressProbeSchema.nullable(),
+  /** Every bound domain with its live probes; empty when none are bound. */
+  domains: z.array(ingressDomainStatusSchema),
 });
 
 export type GetIngressResponse = z.infer<typeof getIngressResponseSchema>;

From 7306141f24e2313c0d0548736cf7300c06881ed8 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 12 Jul 2026 19:43:08 +0800
Subject: [PATCH 058/133] install.sh points at the domains page, where binding
 now lives

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 deploy/install.sh | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/deploy/install.sh b/deploy/install.sh
index d0134b3..d3a2be5 100644
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -352,7 +352,7 @@ if command -v caddy >/dev/null; then
 	}
 }
 EOF
-    note "wrote $CADDYFILE (plain HTTP on :80 — bind a domain in the console's settings page for HTTPS)"
+    note "wrote $CADDYFILE (plain HTTP on :80 — bind domains in the console's domains page for HTTPS)"
     INGRESS_FILE_READY=1
   elif grep -q 'Managed by Dormice' "$CADDYFILE"; then
     note "[skip] $CADDYFILE is managed by Dormice — left to the daemon"
@@ -421,8 +421,8 @@ fi
 # knob up too. The knob is what turns on web domain binding in the console.
 if [ -n "$INGRESS_FILE_READY" ] && ! grep -q '^DORMICE_INGRESS_FILE=' "$ENV_FILE"; then
   {
-    echo '# The Caddy config file the daemon owns: enables binding a domain (and'
-    echo '# getting HTTPS) from the console settings page.'
+    echo '# The Caddy config file the daemon owns: enables binding domains (and'
+    echo '# getting HTTPS) from the console domains page.'
     echo "DORMICE_INGRESS_FILE=$CADDYFILE"
   } >>"$ENV_FILE"
   note "added DORMICE_INGRESS_FILE=$CADDYFILE to $ENV_FILE"
@@ -460,5 +460,5 @@ printf '  CLI:         export DORMICE_ENDPOINT=http://127.0.0.1:%s DORMICE_API_T
 printf '  The daemon listens on 127.0.0.1 only, by design — exposing it is a reverse proxy'"'"'s job.\n'
 if [ "$(systemctl is-active caddy 2>/dev/null)" = active ]; then
   printf '  console:     http://<this-host-ip>/console (Caddy on :80 — open your cloud firewall for 80/443,\n'
-  printf '               then bind a domain in the settings page for automatic HTTPS)\n'
+  printf '               then bind domains in the domains page for automatic HTTPS)\n'
 fi

From f27ad09f01cf85095f0697b10ee6765d4f5f4f3f Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 12 Jul 2026 20:26:15 +0800
Subject: [PATCH 059/133] The domains page tells you what to type: bind dialog
 with the A record to copy, and a mismatch diagnosis
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Binding moves into a dialog that shows the exact record to add — type A,
value = this machine's public IP with a copy button. The IP comes from how
the browser reached the console (address bar during IP bootstrap, a green
domain's resolution afterwards), which beats the daemon guessing behind
cloud NAT. That same fact powers a new dns-mismatch phase: an A record
pointing at the wrong IP used to spin forever as "issuing"; now it says
what it resolved to and what it should be. copyText graduates from
ConnectPage into lib for the dialog to share.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../features/connect/pages/ConnectPage.tsx    |  21 +-
 .../ingress/components/BindDomainDialog.tsx   | 164 ++++++++++++++
 .../features/ingress/pages/DomainsPage.tsx    | 208 +++++++++---------
 packages/console/src/lib/copy.ts              |  19 ++
 4 files changed, 286 insertions(+), 126 deletions(-)
 create mode 100644 packages/console/src/features/ingress/components/BindDomainDialog.tsx
 create mode 100644 packages/console/src/lib/copy.ts

diff --git a/packages/console/src/features/connect/pages/ConnectPage.tsx b/packages/console/src/features/connect/pages/ConnectPage.tsx
index 5b0f3fb..76674d1 100644
--- a/packages/console/src/features/connect/pages/ConnectPage.tsx
+++ b/packages/console/src/features/connect/pages/ConnectPage.tsx
@@ -9,26 +9,7 @@ import {
   CardHeader,
   CardTitle,
 } from '@/components/ui/card';
-
-/**
- * The Clipboard API only exists in secure contexts, and this console is
- * deliberately reachable over plain http during the pre-TLS phase — the
- * textarea trick is the one copy mechanism browsers still allow there.
- */
-function copyText(text: string): Promise<void> {
-  if (navigator.clipboard) {
-    return navigator.clipboard.writeText(text);
-  }
-  const textarea = document.createElement('textarea');
-  textarea.value = text;
-  textarea.style.position = 'fixed';
-  textarea.style.opacity = '0';
-  document.body.appendChild(textarea);
-  textarea.select();
-  const copied = document.execCommand('copy');
-  textarea.remove();
-  return copied ? Promise.resolve() : Promise.reject(new Error('copy failed'));
-}
+import { copyText } from '@/lib/copy';
 
 function Snippet({ code }: { code: string }) {
   return (
diff --git a/packages/console/src/features/ingress/components/BindDomainDialog.tsx b/packages/console/src/features/ingress/components/BindDomainDialog.tsx
new file mode 100644
index 0000000..7c86b1d
--- /dev/null
+++ b/packages/console/src/features/ingress/components/BindDomainDialog.tsx
@@ -0,0 +1,164 @@
+import { Add01Icon, Copy01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@/components/ui/dialog';
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+} from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import { copyText } from '@/lib/copy';
+import { useSetIngress } from '../hooks/useIngress';
+
+/**
+ * 绑定就是"照抄一条 A 记录":弹窗把要填的记录值(本机公网 IP)直接给
+ * 出来带复制按钮,用户不用猜。wire 是集合语义 — 提交的是已绑清单加
+ * 这一个;失败留在弹窗里就地报错,成功关窗回列表看进度。
+ */
+export function BindDomainDialog({
+  bound,
+  publicIp,
+}: {
+  bound: string[];
+  /** 页面探测到的本机公网 IP;拿不到时(如 dev 环境)诚实退化为占位文案。 */
+  publicIp: string | null;
+}) {
+  const [open, setOpen] = useState(false);
+  const [draft, setDraft] = useState('');
+  const mutation = useSetIngress();
+
+  const domain = draft.trim().toLowerCase();
+  const duplicate = domain.length > 0 && bound.includes(domain);
+
+  const reset = () => {
+    setDraft('');
+    mutation.reset();
+  };
+
+  const submit = () => {
+    mutation.mutate([...bound, domain], {
+      onSuccess: () => {
+        toast.success(`已绑定 ${domain},证书自动申请中`);
+        setOpen(false);
+        reset();
+      },
+    });
+  };
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) reset();
+      }}
+    >
+      <DialogTrigger
+        render={
+          <Button size="sm">
+            <HugeiconsIcon icon={Add01Icon} />
+            绑定域名
+          </Button>
+        }
+      />
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>绑定域名</DialogTitle>
+          <DialogDescription>
+            HTTPS 证书自动申请与续期,无需手动配置;无论绑定成败,IP
+            访问始终保留,不会被锁在门外。
+          </DialogDescription>
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            submit();
+          }}
+        >
+          <FieldGroup>
+            <div className="rounded-md border bg-muted/30 px-4 py-3">
+              <p className="text-xs text-muted-foreground">
+                第一步:去域名商处给这个域名加一条解析记录(生效通常要
+                几分钟;先绑定也行,页面会等它转绿):
+              </p>
+              <div className="mt-2 grid grid-cols-[4.5rem_1fr] items-center gap-y-1 font-mono text-xs">
+                <span className="text-muted-foreground">类型</span>
+                <span>A</span>
+                <span className="text-muted-foreground">记录值</span>
+                {publicIp ? (
+                  <span className="flex items-center gap-1">
+                    {publicIp}
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="icon-sm"
+                      aria-label="复制 IP"
+                      onClick={() =>
+                        copyText(publicIp).then(
+                          () => toast.success('已复制'),
+                          () => toast.error('复制失败 — 请手动选中文本'),
+                        )
+                      }
+                    >
+                      <HugeiconsIcon icon={Copy01Icon} />
+                    </Button>
+                  </span>
+                ) : (
+                  <span>本机公网 IP</span>
+                )}
+              </div>
+              <p className="mt-2 text-xs text-muted-foreground">
+                主机记录(名称)填子域前缀,绑定主域名本身则填 @。
+              </p>
+            </div>
+            <Field data-invalid={duplicate || undefined}>
+              <FieldLabel htmlFor="bind-domain">域名</FieldLabel>
+              <Input
+                id="bind-domain"
+                autoFocus
+                value={draft}
+                onChange={(event) => setDraft(event.target.value)}
+                placeholder="console.example.com"
+                className="font-mono"
+                aria-invalid={duplicate || undefined}
+              />
+              {duplicate ? (
+                <FieldError>{domain} 已经绑定</FieldError>
+              ) : (
+                <FieldDescription>
+                  裸主机名,不带 http:// 前缀和端口。
+                </FieldDescription>
+              )}
+            </Field>
+            {mutation.isError && (
+              <FieldError>{mutation.error.message}</FieldError>
+            )}
+          </FieldGroup>
+          <DialogFooter className="mt-6">
+            <Button
+              type="submit"
+              disabled={domain.length === 0 || duplicate || mutation.isPending}
+            >
+              {mutation.isPending && <Spinner />}
+              绑定
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/packages/console/src/features/ingress/pages/DomainsPage.tsx b/packages/console/src/features/ingress/pages/DomainsPage.tsx
index 8373e4e..72d80a9 100644
--- a/packages/console/src/features/ingress/pages/DomainsPage.tsx
+++ b/packages/console/src/features/ingress/pages/DomainsPage.tsx
@@ -6,26 +6,18 @@ import {
   Globe02Icon,
 } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
-import { type FormEvent, useState } from 'react';
+import { useState } from 'react';
 import { toast } from 'sonner';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
-import {
-  Card,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from '@/components/ui/card';
 import {
   Empty,
+  EmptyContent,
   EmptyDescription,
   EmptyHeader,
   EmptyMedia,
   EmptyTitle,
 } from '@/components/ui/empty';
-import { Field, FieldDescription, FieldLabel } from '@/components/ui/field';
-import { Input } from '@/components/ui/input';
 import {
   Item,
   ItemActions,
@@ -36,22 +28,51 @@ import {
   ItemTitle,
 } from '@/components/ui/item';
 import { Spinner } from '@/components/ui/spinner';
+import { BindDomainDialog } from '../components/BindDomainDialog';
 import { useIngress, useSetIngress } from '../hooks/useIngress';
 
 /**
  * 每个域名此刻的收敛阶段,从两个探测推出来:绿 = 事实成立,黄 = 还没
- * 成立(等待中,不是故障),红 = 探测本身失败。探测是 daemon 请求时现
+ * 成立(等待中,不是故障),红 = 有明确的错处。探测是 daemon 请求时现
  * 测的,不是缓存 — 没收敛的域名每 5s 轮询,页面上的进度是真的。
+ *
+ * dns-mismatch 是诊断价值最高的一档:A 记录指到了别的 IP 时,证书永
+ * 远签不出来 — 没有这一档它会假装成"签发中"无限转圈。只在确知本机
+ * 公网 IP 时才敢下这个判断,拿不到就退回"签发中",不装懂。
  */
-type DomainPhase = 'ready' | 'issuing' | 'waiting-dns' | 'dns-error';
+type DomainPhase =
+  | 'ready'
+  | 'issuing'
+  | 'waiting-dns'
+  | 'dns-mismatch'
+  | 'dns-error';
 
-function phaseOf(probe: IngressProbe): DomainPhase {
+function phaseOf(probe: IngressProbe, publicIp: string | null): DomainPhase {
   if (probe.tlsOk) return 'ready';
   if (probe.dnsError) return 'dns-error';
   if (probe.dnsAddresses.length === 0) return 'waiting-dns';
+  if (publicIp && !probe.dnsAddresses.includes(publicIp)) return 'dns-mismatch';
   return 'issuing';
 }
 
+/**
+ * 本机公网 IP 的来源是"浏览器此刻怎么够到这台服务器"——这比 daemon
+ * 自己猜可靠(云上 NAT 环境 daemon 只看得见内网地址):引导期直接用
+ * IP 访问,地址栏就是答案;已经走域名访问,当前域名(或任一绿灯域名)
+ * 的解析值就是答案。两个来源都没有(如 localhost dev)则诚实返回 null。
+ */
+function detectPublicIp(statuses: IngressDomainStatus[]): string | null {
+  const host = window.location.hostname;
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) return host;
+  const here = statuses.find(
+    (status) => status.domain === host && status.probe.dnsAddresses.length > 0,
+  );
+  const ready = statuses.find(
+    (status) => status.probe.tlsOk && status.probe.dnsAddresses.length > 0,
+  );
+  return (here ?? ready)?.probe.dnsAddresses[0] ?? null;
+}
+
 const PHASE_BADGES: Record<DomainPhase, { label: string; className: string }> =
   {
     ready: {
@@ -69,6 +90,11 @@ const PHASE_BADGES: Record<DomainPhase, { label: string; className: string }> =
       className:
         'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
     },
+    'dns-mismatch': {
+      label: '解析指向了别处',
+      className:
+        'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
+    },
     'dns-error': {
       label: 'DNS 查询失败',
       className:
@@ -76,7 +102,11 @@ const PHASE_BADGES: Record<DomainPhase, { label: string; className: string }> =
     },
   };
 
-function describeProbe(probe: IngressProbe, phase: DomainPhase): string {
+function describeProbe(
+  probe: IngressProbe,
+  phase: DomainPhase,
+  publicIp: string | null,
+): string {
   const resolved = `已解析到 ${probe.dnsAddresses.join(', ')}`;
   switch (phase) {
     case 'ready':
@@ -84,7 +114,9 @@ function describeProbe(probe: IngressProbe, phase: DomainPhase): string {
     case 'issuing':
       return `${resolved};Caddy 正在申请证书 — 自动重试,通常一分钟内完成`;
     case 'waiting-dns':
-      return '还没有解析记录 — 去域名商处加一条 A 记录指向本机公网 IP,生效通常要几分钟';
+      return '还没有解析记录 — 按绑定弹窗里的指引加一条 A 记录,生效通常要几分钟';
+    case 'dns-mismatch':
+      return `解析到 ${probe.dnsAddresses.join(', ')},但本机是 ${publicIp} — 去域名商处把 A 记录的记录值改成本机 IP`;
     case 'dns-error':
       return '解析器查询失败(超时或上游故障),会随下一轮探测自动重试';
   }
@@ -102,17 +134,19 @@ function probeErrorLine(
 
 function DomainItem({
   status,
+  publicIp,
   removing,
   busy,
   onRemove,
 }: {
   status: IngressDomainStatus;
+  publicIp: string | null;
   /** 正在解绑的是不是本行(行内 spinner 只亮在被点的那行)。 */
   removing: boolean;
   busy: boolean;
   onRemove: () => void;
 }) {
-  const phase = phaseOf(status.probe);
+  const phase = phaseOf(status.probe, publicIp);
   const badge = PHASE_BADGES[phase];
   const errorLine = probeErrorLine(status.probe, phase);
   // 正从这个域名访问控制台:不用再"打开",解绑等于拆自己脚下的梯子,
@@ -133,9 +167,9 @@ function DomainItem({
           <HugeiconsIcon
             icon={Alert02Icon}
             className={
-              phase === 'dns-error'
-                ? 'text-red-600 dark:text-red-400'
-                : 'text-amber-600 dark:text-amber-400'
+              phase === 'waiting-dns'
+                ? 'text-amber-600 dark:text-amber-400'
+                : 'text-red-600 dark:text-red-400'
             }
           />
         )}
@@ -148,7 +182,9 @@ function DomainItem({
           </Badge>
           {isHere && <Badge variant="secondary">当前访问</Badge>}
         </ItemTitle>
-        <ItemDescription>{describeProbe(status.probe, phase)}</ItemDescription>
+        <ItemDescription>
+          {describeProbe(status.probe, phase, publicIp)}
+        </ItemDescription>
         {errorLine && (
           <div className="font-mono text-xs text-muted-foreground">
             {errorLine}
@@ -186,34 +222,17 @@ function DomainItem({
 /**
  * 域名页:setIngress 改写 daemon 托管的 Caddy 配置并热重载,证书全权
  * 归 Caddy(ACME)。wire 是集合语义 — 增删都是"把想要的完整清单发过
- * 去",页面在已绑清单上加一个/减一个再整体提交。绑定失败不锁门:
- * :80 的 IP 访问在每次改写里都保留。
+ * 去",绑定弹窗在已绑清单上加一个、解绑在清单上减一个再整体提交。
+ * 绑定失败不锁门::80 的 IP 访问在每次改写里都保留。
  */
 export function DomainsPage() {
   const { data, isPending, isError, error } = useIngress();
   const mutation = useSetIngress();
-  const [draft, setDraft] = useState('');
   const [removing, setRemoving] = useState<string | null>(null);
 
   const statuses = data?.domains ?? [];
   const bound = statuses.map((entry) => entry.domain);
-
-  const add = (event: FormEvent) => {
-    event.preventDefault();
-    const domain = draft.trim().toLowerCase();
-    if (domain.length === 0) return;
-    if (bound.includes(domain)) {
-      toast.info(`${domain} 已经绑定`);
-      return;
-    }
-    mutation.mutate([...bound, domain], {
-      onSuccess: () => {
-        setDraft('');
-        toast.success(`已绑定 ${domain},等待证书签发`);
-      },
-      onError: (mutationError) => toast.error(mutationError.message),
-    });
-  };
+  const publicIp = detectPublicIp(statuses);
 
   const remove = (domain: string) => {
     setRemoving(domain);
@@ -229,13 +248,16 @@ export function DomainsPage() {
 
   return (
     <>
-      <div>
-        <h1 className="text-lg font-semibold">域名</h1>
-        <p className="text-sm text-muted-foreground">
-          给控制台(和 API)绑定域名,HTTPS
-          证书自动申请与续期。可以绑多个;无论绑定成败,IP
-          访问始终保留,不会被锁在门外。
-        </p>
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div>
+          <h1 className="text-lg font-semibold">域名</h1>
+          <p className="text-sm text-muted-foreground">
+            给控制台(和 API)绑定域名,可以绑多个;HTTPS 证书自动申请与续期。
+          </p>
+        </div>
+        {data?.managed && statuses.length > 0 && (
+          <BindDomainDialog bound={bound} publicIp={publicIp} />
+        )}
       </div>
 
       {isPending ? (
@@ -262,67 +284,41 @@ export function DomainsPage() {
             </EmptyDescription>
           </EmptyHeader>
         </Empty>
+      ) : statuses.length === 0 ? (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyMedia variant="icon">
+              <HugeiconsIcon icon={Globe02Icon} />
+            </EmptyMedia>
+            <EmptyTitle>还没有绑定域名</EmptyTitle>
+            <EmptyDescription>
+              绑定后 HTTPS 证书自动申请与续期;无论绑定成败,IP
+              访问始终保留,不会被锁在门外。
+            </EmptyDescription>
+          </EmptyHeader>
+          <EmptyContent>
+            <BindDomainDialog bound={bound} publicIp={publicIp} />
+          </EmptyContent>
+        </Empty>
       ) : (
         <>
-          {statuses.length > 0 && (
-            <ItemGroup className="gap-2">
-              {statuses.map((status) => (
-                <DomainItem
-                  key={status.domain}
-                  status={status}
-                  removing={removing === status.domain}
-                  busy={mutation.isPending}
-                  onRemove={() => remove(status.domain)}
-                />
-              ))}
-            </ItemGroup>
-          )}
-
-          <Card>
-            <CardHeader>
-              <CardTitle>
-                {statuses.length === 0 ? '绑定第一个域名' : '再绑一个域名'}
-              </CardTitle>
-              <CardDescription>
-                三步:去域名商处加一条 A 记录指向本机公网 IP → 在这里绑定 →
-                证书自动申请与续期,无需手动配置。
-              </CardDescription>
-            </CardHeader>
-            <CardContent>
-              <form className="flex flex-col gap-3" onSubmit={add}>
-                <Field>
-                  <FieldLabel htmlFor="ingress-domain">域名</FieldLabel>
-                  <Input
-                    id="ingress-domain"
-                    value={draft}
-                    onChange={(event) => setDraft(event.target.value)}
-                    placeholder="console.example.com"
-                    className="max-w-md font-mono"
-                  />
-                  <FieldDescription>
-                    裸主机名,不带 http:// 前缀和端口。
-                  </FieldDescription>
-                </Field>
-                <div>
-                  <Button
-                    type="submit"
-                    disabled={draft.trim().length === 0 || mutation.isPending}
-                  >
-                    {mutation.isPending && removing === null && <Spinner />}
-                    绑定
-                  </Button>
-                </div>
-              </form>
-            </CardContent>
-          </Card>
-
-          {statuses.length > 0 && (
-            <p className="text-sm text-muted-foreground">
-              以上探测跑在服务器本机,证明不了公网可达:若浏览器打不开 HTTPS
-              地址,通常是云安全组还没放行 443 端口;中国大陆机房还需域名有 ICP
-              备案,否则云厂商会在入口拦截(与本机配置无关)。
-            </p>
-          )}
+          <ItemGroup className="gap-2">
+            {statuses.map((status) => (
+              <DomainItem
+                key={status.domain}
+                status={status}
+                publicIp={publicIp}
+                removing={removing === status.domain}
+                busy={mutation.isPending}
+                onRemove={() => remove(status.domain)}
+              />
+            ))}
+          </ItemGroup>
+          <p className="text-sm text-muted-foreground">
+            以上探测跑在服务器本机,证明不了公网可达:若浏览器打不开 HTTPS
+            地址,通常是云安全组还没放行 443 端口;中国大陆机房还需域名有 ICP
+            备案,否则云厂商会在入口拦截(与本机配置无关)。
+          </p>
         </>
       )}
     </>
diff --git a/packages/console/src/lib/copy.ts b/packages/console/src/lib/copy.ts
new file mode 100644
index 0000000..b79a2c1
--- /dev/null
+++ b/packages/console/src/lib/copy.ts
@@ -0,0 +1,19 @@
+/**
+ * The Clipboard API only exists in secure contexts, and this console is
+ * deliberately reachable over plain http during the pre-TLS phase — the
+ * textarea trick is the one copy mechanism browsers still allow there.
+ */
+export function copyText(text: string): Promise<void> {
+  if (navigator.clipboard) {
+    return navigator.clipboard.writeText(text);
+  }
+  const textarea = document.createElement('textarea');
+  textarea.value = text;
+  textarea.style.position = 'fixed';
+  textarea.style.opacity = '0';
+  document.body.appendChild(textarea);
+  textarea.select();
+  const copied = document.execCommand('copy');
+  textarea.remove();
+  return copied ? Promise.resolve() : Promise.reject(new Error('copy failed'));
+}

From 3e6df03d2c752f8de91a092c2d8cad91a93140e6 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 12 Jul 2026 22:00:59 +0800
Subject: [PATCH 060/133] setPolicy joins the verbs, and the console workspace
 grows teeth: file preview and editing, a per-sandbox history tab, humane
 duration inputs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- POST /setPolicy {userKey, policy}: patch the stored lifecycle policy in
  place — promoting a live sandbox to a never-stop resident no longer costs
  a release (and its disk). Ledger-only, no wake, no touch; merged result
  validated by the same single arbiter as acquire. New activity kind
  policy-changed. SDK method + server/sdk/e2e coverage.
- Files tab: clicking a file opens it — text previews and edits in place
  (1 MiB cap, NUL-byte binary sniff), binaries and oversizes get an honest
  download prompt. Upload goes multiple and accepts drag & drop.
- Detail page: 调整策略 dialog prefilled with current values; a 历史 tab
  filters the activity ring to this sandbox.
- Seconds inputs now translate themselves (259200 = 3天) in both dialogs;
  sandbox table sorts by userKey/idle/age; relative times reveal absolute
  ones on hover; overview fleet cards link into the sandbox list.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/src/native.test.ts                        |  28 +++
 .../features/activity/hooks/useActivity.ts    |   9 +-
 .../console/src/features/activity/kinds.ts    |  54 +++++
 .../features/activity/pages/ActivityPage.tsx  |  59 +----
 .../overview/components/OverviewCards.tsx     |  18 +-
 .../components/CreateSandboxDialog.tsx        |   5 +
 .../sandboxes/components/EditPolicyDialog.tsx | 217 ++++++++++++++++++
 .../components/FilePreviewDialog.tsx          | 196 ++++++++++++++++
 .../sandboxes/components/FilesPanel.tsx       |  85 +++++--
 .../sandboxes/components/HistoryPanel.tsx     | 116 ++++++++++
 .../console/src/features/sandboxes/format.ts  |  12 +
 .../features/sandboxes/hooks/useSandboxes.ts  |  12 +-
 .../sandboxes/pages/SandboxDetailPage.tsx     |   9 +
 .../sandboxes/pages/SandboxesPage.tsx         | 112 +++++++--
 packages/console/src/lib/api.ts               |   9 +-
 packages/sdk/src/client.test.ts               |  20 ++
 packages/sdk/src/client.ts                    |  18 ++
 packages/server/src/app.test.ts               | 102 ++++++++
 packages/server/src/db/ledger.ts              |  25 ++
 packages/server/src/routes/sandboxes.ts       | 102 ++++++++
 packages/shared/src/activity.ts               |   2 +
 packages/shared/src/index.ts                  |   1 +
 packages/shared/src/set-policy.ts             |  32 +++
 23 files changed, 1156 insertions(+), 87 deletions(-)
 create mode 100644 packages/console/src/features/activity/kinds.ts
 create mode 100644 packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
 create mode 100644 packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx
 create mode 100644 packages/console/src/features/sandboxes/components/HistoryPanel.tsx
 create mode 100644 packages/shared/src/set-policy.ts

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index 07a941b..926f507 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -126,6 +126,34 @@ describe('native API over a real daemon', () => {
     await client().releaseSandbox('rebuild-key');
   });
 
+  it('updates a lifecycle policy in place — no release, no lost disk', async () => {
+    const created = await client().acquireSandbox('set-policy-key');
+
+    // Promote to a never-stop resident agent; archive must fall with it
+    // (only a stopped sandbox can archive) — sent together, as the console does.
+    const { sandbox } = await client().setPolicy('set-policy-key', {
+      stopAfterSeconds: null,
+      archiveAfterSeconds: null,
+    });
+    expect(sandbox.sandboxId).toBe(created.sandbox.sandboxId);
+    expect(sandbox.policy.stopAfterSeconds).toBeNull();
+    expect(sandbox.policy.archiveAfterSeconds).toBeNull();
+    // Ledger-only: the sandbox itself was not woken or touched.
+    expect(sandbox.state).toBe(created.sandbox.state);
+
+    // The archive knob's front door works too on this S3-equipped daemon.
+    const back = await client().setPolicy('set-policy-key', {
+      stopAfterSeconds: 3 * 24 * 60 * 60,
+      archiveAfterSeconds: 30 * 24 * 60 * 60,
+    });
+    expect(back.sandbox.policy.archiveAfterSeconds).toBe(30 * 24 * 60 * 60);
+
+    await expect(
+      client().setPolicy('set-policy-nobody', { freezeAfterSeconds: 60 }),
+    ).rejects.toMatchObject({ name: 'DormiceApiError', status: 404 });
+    await client().releaseSandbox('set-policy-key');
+  });
+
   // The fake's files hang off the disk, so only a real container can show
   // the other half of rebuild's promise: the container layer resets.
   it.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
diff --git a/packages/console/src/features/activity/hooks/useActivity.ts b/packages/console/src/features/activity/hooks/useActivity.ts
index 0eac9ef..760ebf9 100644
--- a/packages/console/src/features/activity/hooks/useActivity.ts
+++ b/packages/console/src/features/activity/hooks/useActivity.ts
@@ -4,11 +4,14 @@ import { listActivity } from '@/lib/api';
 /**
  * 活动流是观察窗:5 秒轮询即可 — 事件写在动作发生处,读只是翻账本,
  * 比沙箱列表的 2 秒松一档(历史不像状态那样急着看)。
+ *
+ * limit 缺省用 wire 默认(200);详情页历史 tab 要按 userKey 过滤,
+ * 传环形表上限(1000)把一个沙箱的事件尽量捞全。
  */
-export function useActivity() {
+export function useActivity(limit?: number) {
   return useQuery({
-    queryKey: ['activity'],
-    queryFn: listActivity,
+    queryKey: ['activity', limit ?? null],
+    queryFn: () => listActivity(limit),
     refetchInterval: 5000,
     retry: false,
   });
diff --git a/packages/console/src/features/activity/kinds.ts b/packages/console/src/features/activity/kinds.ts
new file mode 100644
index 0000000..44150a5
--- /dev/null
+++ b/packages/console/src/features/activity/kinds.ts
@@ -0,0 +1,54 @@
+import type { ActivityKind } from '@dormice/shared';
+
+/**
+ * 事件的中文名与徽章配色 — 与 wire 上的 kind 一比一,这里是唯一的翻译点。
+ * 活动页与沙箱详情页的历史 tab 共用,不各自翻译。
+ */
+export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
+  created: '创建',
+  woken: '唤醒',
+  frozen: '冻结',
+  stopped: '停止',
+  rebuilt: '重建',
+  released: '释放',
+  'expired-killed': '到期销毁',
+  archived: '归档',
+  'restore-started': '开始恢复',
+  restored: '恢复完成',
+  'restore-failed': '恢复失败',
+  reconciled: '对账修复',
+  'policy-changed': '策略调整',
+  'daemon-started': 'daemon 启动',
+  'ingress-updated': '域名配置',
+};
+
+// 事件色与沙箱状态徽章同一色系:落到哪个状态就穿哪个颜色;
+// 配置类事件(策略、域名)统一紫色。
+export const ACTIVITY_KIND_STYLES: Record<ActivityKind, string> = {
+  created:
+    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+  woken:
+    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+  frozen: 'border-sky-500/40 bg-sky-500/10 text-sky-600 dark:text-sky-400',
+  stopped: 'border-border bg-muted text-muted-foreground',
+  rebuilt:
+    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  released: 'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
+  'expired-killed':
+    'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
+  archived:
+    'border-indigo-500/40 bg-indigo-500/10 text-indigo-600 dark:text-indigo-400',
+  'restore-started':
+    'border-indigo-500/40 bg-indigo-500/10 text-indigo-600 dark:text-indigo-400',
+  restored:
+    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+  'restore-failed':
+    'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
+  reconciled:
+    'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
+  'policy-changed':
+    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  'daemon-started': 'border-border bg-muted text-muted-foreground',
+  'ingress-updated':
+    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+};
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index 4f36ef6..43337e0 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -1,4 +1,3 @@
-import type { ActivityKind } from '@dormice/shared';
 import { Link } from '@tanstack/react-router';
 import { Badge } from '@/components/ui/badge';
 import {
@@ -19,52 +18,7 @@ import {
 import { since } from '@/features/sandboxes/format';
 import { cn } from '@/lib/utils';
 import { useActivity } from '../hooks/useActivity';
-
-/** 事件的中文名 — 与 wire 上的 kind 一比一,这里是唯一的翻译点。 */
-export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
-  created: '创建',
-  woken: '唤醒',
-  frozen: '冻结',
-  stopped: '停止',
-  rebuilt: '重建',
-  released: '释放',
-  'expired-killed': '到期销毁',
-  archived: '归档',
-  'restore-started': '开始恢复',
-  restored: '恢复完成',
-  'restore-failed': '恢复失败',
-  reconciled: '对账修复',
-  'daemon-started': 'daemon 启动',
-  'ingress-updated': '域名配置',
-};
-
-// 事件色与沙箱状态徽章同一色系:落到哪个状态就穿哪个颜色。
-const KIND_STYLES: Record<ActivityKind, string> = {
-  created:
-    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
-  woken:
-    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
-  frozen: 'border-sky-500/40 bg-sky-500/10 text-sky-600 dark:text-sky-400',
-  stopped: 'border-border bg-muted text-muted-foreground',
-  rebuilt:
-    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
-  released: 'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
-  'expired-killed':
-    'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
-  archived:
-    'border-indigo-500/40 bg-indigo-500/10 text-indigo-600 dark:text-indigo-400',
-  'restore-started':
-    'border-indigo-500/40 bg-indigo-500/10 text-indigo-600 dark:text-indigo-400',
-  restored:
-    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
-  'restore-failed':
-    'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
-  reconciled:
-    'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
-  'daemon-started': 'border-border bg-muted text-muted-foreground',
-  'ingress-updated':
-    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
-};
+import { ACTIVITY_KIND_LABELS, ACTIVITY_KIND_STYLES } from '../kinds';
 
 /**
  * 「我不在的时候发生了什么」:daemon 每一次生命周期动作(创建、降温、
@@ -117,13 +71,20 @@ export function ActivityPage() {
             <TableBody>
               {data.events.map((event) => (
                 <TableRow key={event.id}>
-                  <TableCell className="tabular-nums text-muted-foreground">
+                  <TableCell
+                    className="tabular-nums text-muted-foreground"
+                    // 相对时间好扫读,绝对时间才对得上日志 — hover 给后者。
+                    title={new Date(event.at).toLocaleString()}
+                  >
                     {since(event.at)}前
                   </TableCell>
                   <TableCell>
                     <Badge
                       variant="outline"
-                      className={cn('font-medium', KIND_STYLES[event.kind])}
+                      className={cn(
+                        'font-medium',
+                        ACTIVITY_KIND_STYLES[event.kind],
+                      )}
                     >
                       {ACTIVITY_KIND_LABELS[event.kind]}
                     </Badge>
diff --git a/packages/console/src/features/overview/components/OverviewCards.tsx b/packages/console/src/features/overview/components/OverviewCards.tsx
index bdea545..747eb30 100644
--- a/packages/console/src/features/overview/components/OverviewCards.tsx
+++ b/packages/console/src/features/overview/components/OverviewCards.tsx
@@ -8,6 +8,7 @@ import {
   SnowIcon,
 } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
+import { Link } from '@tanstack/react-router';
 import type { ReactNode } from 'react';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import { Card, CardContent } from '@/components/ui/card';
@@ -47,6 +48,7 @@ function StatCard({
   value,
   hint,
   pct,
+  to,
 }: {
   icon: NonNullable<HugeiconsProps['icon']>;
   label: string;
@@ -54,8 +56,10 @@ function StatCard({
   hint: ReactNode;
   /** Meter percentage; null renders an empty track, undefined no meter. */
   pct?: number | null;
+  /** Route this card drills into; only cards with a real destination get one. */
+  to?: string;
 }) {
-  return (
+  const card = (
     <Card size="sm">
       <CardContent className="flex flex-col gap-2">
         <div className="flex items-center gap-1.5 text-sm text-muted-foreground">
@@ -68,6 +72,16 @@ function StatCard({
       </CardContent>
     </Card>
   );
+  if (!to) return card;
+  // Radius mirrors the Card's own, so the focus/hover ring hugs the shape.
+  return (
+    <Link
+      to={to}
+      className="block rounded-[min(var(--radius-4xl),24px)] transition-shadow hover:ring-2 hover:ring-primary/30"
+    >
+      {card}
+    </Link>
+  );
 }
 
 // The lifecycle rungs shown in the fleet card, coldest last — same hues as
@@ -216,6 +230,7 @@ export function OverviewCards() {
           value={`${sandboxes.total} / ${sandboxes.maxSandboxes}`}
           hint={<StateCounts byState={sandboxes.byState} />}
           pct={pctOf(sandboxes.total, sandboxes.maxSandboxes)}
+          to="/sandboxes"
         />
         <StatCard
           icon={Database01Icon}
@@ -223,6 +238,7 @@ export function OverviewCards() {
           value={formatBytes(sandboxDisks.actualBytes)}
           hint={`${sandboxDisks.count} 块盘共许诺 ${formatBytes(sandboxDisks.nominalBytes)} — 稀疏镜像只为真实内容付费`}
           pct={pctOf(sandboxDisks.actualBytes, sandboxDisks.nominalBytes)}
+          to="/sandboxes"
         />
       </div>
     </section>
diff --git a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
index 9dc4be1..8f81dc1 100644
--- a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
+++ b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
@@ -29,6 +29,7 @@ import { Spinner } from '@/components/ui/spinner';
 import { Switch } from '@/components/ui/switch';
 import { useConfig } from '@/features/settings/hooks/useConfig';
 import { useTemplates } from '@/features/templates/hooks/useTemplates';
+import { durationHint } from '../format';
 import { useAcquireSandbox } from '../hooks/useSandboxes';
 
 /**
@@ -174,6 +175,7 @@ export function CreateSandboxDialog() {
               />
               <FieldDescription>
                 运行中 → 已冻结的空闲阈值:内存挤入 swap,唤醒约 50ms。
+                {durationHint(freezeAfter) && ` ${durationHint(freezeAfter)}`}
               </FieldDescription>
             </Field>
             <Field orientation="horizontal">
@@ -201,6 +203,7 @@ export function CreateSandboxDialog() {
                 />
                 <FieldDescription>
                   已冻结 → 已停止的空闲阈值:只留磁盘,唤醒是冷启动。
+                  {durationHint(stopAfter) && ` ${durationHint(stopAfter)}`}
                 </FieldDescription>
               </Field>
             )}
@@ -232,6 +235,8 @@ export function CreateSandboxDialog() {
                     <FieldDescription>
                       已停止 → 已归档:磁盘压缩上传 S3,本地零占用;
                       唤醒要下载解压,慢但有真进度。
+                      {durationHint(archiveAfter) &&
+                        ` ${durationHint(archiveAfter)}`}
                     </FieldDescription>
                   </Field>
                 )}
diff --git a/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx b/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
new file mode 100644
index 0000000..462a7f4
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
@@ -0,0 +1,217 @@
+import type { Sandbox } from '@dormice/shared';
+import { Settings02Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@/components/ui/dialog';
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+} from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import { Switch } from '@/components/ui/switch';
+import { useConfig } from '@/features/settings/hooks/useConfig';
+import { durationHint } from '../format';
+import { useSetPolicy } from '../hooks/useSandboxes';
+
+/**
+ * acquire 只在创建时收策略,这个弹窗是之后的正门:setPolicy 纯改账本,
+ * 不唤醒、不重置空闲时钟 — 把跑了几天的沙箱升格成常驻 agent 不再需要
+ * 释放重建(那会销毁磁盘)。三个旋钮整体提交:界面上看到什么就写下什么,
+ * 关掉"永不停止"时归档旋钮的取舍也一并说清,不留隐式合并的悬念。
+ */
+export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
+  const [open, setOpen] = useState(false);
+  const [freezeAfter, setFreezeAfter] = useState('');
+  const [neverStop, setNeverStop] = useState(false);
+  const [stopAfter, setStopAfter] = useState('');
+  const [neverArchive, setNeverArchive] = useState(false);
+  const [archiveAfter, setArchiveAfter] = useState('');
+  const mutation = useSetPolicy();
+  const archive = useConfig().data?.archive;
+
+  // 每次打开都从沙箱的现值起步 — 编辑的是"现在是什么",不是空表单。
+  const loadCurrent = () => {
+    const { policy } = sandbox;
+    setFreezeAfter(String(policy.freezeAfterSeconds));
+    setNeverStop(policy.stopAfterSeconds === null);
+    setStopAfter(
+      policy.stopAfterSeconds === null ? '' : String(policy.stopAfterSeconds),
+    );
+    setNeverArchive(policy.archiveAfterSeconds === null);
+    setArchiveAfter(
+      policy.archiveAfterSeconds === null
+        ? ''
+        : String(policy.archiveAfterSeconds),
+    );
+    mutation.reset();
+  };
+
+  const submit = () => {
+    mutation.mutate(
+      {
+        userKey: sandbox.userKey,
+        policy: {
+          freezeAfterSeconds: Number(freezeAfter),
+          stopAfterSeconds: neverStop ? null : Number(stopAfter),
+          // 永不停止连带永不归档(没停过就没得归档);归档未启用时保持
+          // 现值不动 — 一个 daemon 没资格许诺的旋钮,这里也不碰。
+          ...(archive?.enabled
+            ? {
+                archiveAfterSeconds:
+                  neverStop || neverArchive ? null : Number(archiveAfter),
+              }
+            : {}),
+        },
+      },
+      {
+        onSuccess: () => {
+          toast.success(`「${sandbox.userKey}」的策略已更新`);
+          setOpen(false);
+        },
+      },
+    );
+  };
+
+  const filled = (raw: string) => raw.trim() !== '' && Number(raw) > 0;
+  const valid =
+    filled(freezeAfter) &&
+    (neverStop || filled(stopAfter)) &&
+    (!archive?.enabled || neverStop || neverArchive || filled(archiveAfter));
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (next) loadCurrent();
+      }}
+    >
+      <DialogTrigger
+        render={
+          <Button variant="outline" size="sm">
+            <HugeiconsIcon icon={Settings02Icon} />
+            调整策略
+          </Button>
+        }
+      />
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>调整「{sandbox.userKey}」的生命周期策略</DialogTitle>
+          <DialogDescription>
+            立即生效,只改账本 — 沉睡的沙箱不会被吵醒,空闲计时也不重置
+            (新阈值按已累积的空闲时间判定)。
+          </DialogDescription>
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            submit();
+          }}
+        >
+          <FieldGroup>
+            <Field>
+              <FieldLabel htmlFor="policy-freeze-after">
+                空闲多久后冻结(秒)
+              </FieldLabel>
+              <Input
+                id="policy-freeze-after"
+                type="number"
+                min={1}
+                value={freezeAfter}
+                onChange={(event) => setFreezeAfter(event.target.value)}
+              />
+              <FieldDescription>
+                运行中 → 已冻结:内存挤入 swap,唤醒约 50ms。
+                {durationHint(freezeAfter) && ` ${durationHint(freezeAfter)}`}
+              </FieldDescription>
+            </Field>
+            <Field orientation="horizontal">
+              <Switch
+                id="policy-never-stop"
+                checked={neverStop}
+                onCheckedChange={setNeverStop}
+              />
+              <FieldLabel htmlFor="policy-never-stop">
+                永不停止(常驻 agent)
+              </FieldLabel>
+            </Field>
+            {!neverStop && (
+              <Field>
+                <FieldLabel htmlFor="policy-stop-after">
+                  空闲多久后停止(秒)
+                </FieldLabel>
+                <Input
+                  id="policy-stop-after"
+                  type="number"
+                  min={1}
+                  value={stopAfter}
+                  onChange={(event) => setStopAfter(event.target.value)}
+                />
+                <FieldDescription>
+                  已冻结 → 已停止:只留磁盘,唤醒是冷启动。
+                  {durationHint(stopAfter) && ` ${durationHint(stopAfter)}`}
+                </FieldDescription>
+              </Field>
+            )}
+            {archive?.enabled && !neverStop && (
+              <>
+                <Field orientation="horizontal">
+                  <Switch
+                    id="policy-never-archive"
+                    checked={neverArchive}
+                    onCheckedChange={setNeverArchive}
+                  />
+                  <FieldLabel htmlFor="policy-never-archive">
+                    永不归档
+                  </FieldLabel>
+                </Field>
+                {!neverArchive && (
+                  <Field>
+                    <FieldLabel htmlFor="policy-archive-after">
+                      空闲多久后归档(秒)
+                    </FieldLabel>
+                    <Input
+                      id="policy-archive-after"
+                      type="number"
+                      min={1}
+                      value={archiveAfter}
+                      onChange={(event) => setArchiveAfter(event.target.value)}
+                    />
+                    <FieldDescription>
+                      已停止 → 已归档:磁盘压缩上传 S3,本地零占用。
+                      {durationHint(archiveAfter) &&
+                        ` ${durationHint(archiveAfter)}`}
+                    </FieldDescription>
+                  </Field>
+                )}
+              </>
+            )}
+            {mutation.isError && (
+              <FieldError>{mutation.error.message}</FieldError>
+            )}
+          </FieldGroup>
+          <DialogFooter className="mt-6">
+            <Button type="submit" disabled={!valid || mutation.isPending}>
+              {mutation.isPending && <Spinner />}
+              保存
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx b/packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx
new file mode 100644
index 0000000..4cde883
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx
@@ -0,0 +1,196 @@
+import { Download01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useQuery } from '@tanstack/react-query';
+import { useEffect, useState } from 'react';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import { Spinner } from '@/components/ui/spinner';
+import { Textarea } from '@/components/ui/textarea';
+import { formatBytes } from '@/lib/format';
+import { downloadFile, type EnvdAuth, type EnvdEntry } from '../envd-client';
+import { useFileMutations } from '../hooks/useEnvd';
+
+/**
+ * 在线看得过来的才在线看:预览上限之上只给下载 — 编辑器不是给日志
+ * 大文件准备的。上限取 1 MiB:够看配置、代码、多数日志尾巴,又不至于
+ * 把整段内存交给一个 textarea。
+ */
+const PREVIEW_CAP_BYTES = 1024 * 1024;
+
+/**
+ * 文本判定:头 8 KiB 里出现 NUL 字节即视为二进制。与 git 同一招 —
+ * 不猜编码不读魔数,便宜且几乎不会冤枉文本文件。
+ */
+function looksBinary(bytes: Uint8Array): boolean {
+  const head = bytes.subarray(0, 8192);
+  return head.includes(0);
+}
+
+/**
+ * 点开文件先看内容,小文本顺手改完保存 — 排查 agent 产物最高频的动作,
+ * 不该绕道"下载到本地再打开"。读写都走 envd 的文件面(与官方 e2b SDK
+ * 同一条 wire):读是 GET /files,存是同路径的整文件覆写上传。
+ */
+export function FilePreviewDialog({
+  auth,
+  entry,
+  onClose,
+}: {
+  auth: EnvdAuth | undefined;
+  /** 正在预览的文件;null = 关闭。 */
+  entry: EnvdEntry | null;
+  onClose: () => void;
+}) {
+  const [draft, setDraft] = useState('');
+  const mutations = useFileMutations(auth);
+  const tooLarge = entry !== null && Number(entry.size) > PREVIEW_CAP_BYTES;
+
+  const content = useQuery({
+    queryKey: ['envdFileContent', auth?.sandboxId, entry?.path],
+    queryFn: async () => {
+      if (!auth || !entry) throw new Error('缺少 envd 凭证');
+      const blob = await downloadFile(auth, entry.path);
+      const bytes = new Uint8Array(await blob.arrayBuffer());
+      if (looksBinary(bytes)) return { binary: true as const };
+      return { binary: false as const, text: new TextDecoder().decode(bytes) };
+    },
+    enabled: entry !== null && !tooLarge && auth !== undefined,
+    // 文件内容随沙箱里的进程随时在变,每次打开都重读,不吃缓存。
+    gcTime: 0,
+    staleTime: 0,
+    retry: false,
+  });
+
+  // 读到文本后灌入编辑区;依赖 entry.path 使换文件时必然重灌。
+  useEffect(() => {
+    if (content.data && !content.data.binary) {
+      setDraft(content.data.text);
+    }
+  }, [content.data]);
+
+  const dirty =
+    content.data !== undefined &&
+    !content.data.binary &&
+    draft !== content.data.text;
+
+  const download = () => {
+    if (!entry) return;
+    mutations.download.mutate(
+      { path: entry.path, name: entry.name },
+      { onError: (error) => toast.error(error.message) },
+    );
+  };
+
+  const save = () => {
+    if (!entry) return;
+    mutations.upload.mutate(
+      { path: entry.path, file: new File([draft], entry.name) },
+      {
+        onSuccess: () => {
+          toast.success(`已保存 ${entry.name}`);
+          onClose();
+        },
+        onError: (error) => toast.error(error.message),
+      },
+    );
+  };
+
+  return (
+    <Dialog
+      open={entry !== null}
+      onOpenChange={(open) => {
+        if (!open) onClose();
+      }}
+    >
+      <DialogContent className="sm:max-w-3xl">
+        <DialogHeader>
+          <DialogTitle className="font-mono">{entry?.name}</DialogTitle>
+          <DialogDescription className="font-mono text-xs">
+            {entry?.path} · {formatBytes(Number(entry?.size ?? 0))}
+          </DialogDescription>
+        </DialogHeader>
+
+        {tooLarge || content.data?.binary ? (
+          <Empty className="border border-dashed">
+            <EmptyHeader>
+              <EmptyTitle>
+                {tooLarge ? '文件太大,不在线预览' : '二进制文件,没法当文本看'}
+              </EmptyTitle>
+              <EmptyDescription>
+                {tooLarge
+                  ? `在线预览上限 ${formatBytes(PREVIEW_CAP_BYTES)} — 下载后用本地工具打开。`
+                  : '内容里有 NUL 字节 — 下载后用对应的工具打开。'}
+              </EmptyDescription>
+            </EmptyHeader>
+            <EmptyContent>
+              <Button
+                variant="outline"
+                size="sm"
+                disabled={mutations.download.isPending}
+                onClick={download}
+              >
+                <HugeiconsIcon icon={Download01Icon} />
+                下载
+              </Button>
+            </EmptyContent>
+          </Empty>
+        ) : content.isError ? (
+          <Empty className="border border-dashed">
+            <EmptyHeader>
+              <EmptyTitle>读取失败</EmptyTitle>
+              <EmptyDescription>{content.error.message}</EmptyDescription>
+            </EmptyHeader>
+          </Empty>
+        ) : content.isPending ? (
+          <div className="flex items-center gap-2 text-sm text-muted-foreground">
+            <Spinner /> 读取文件…
+          </div>
+        ) : (
+          <Textarea
+            value={draft}
+            onChange={(event) => setDraft(event.target.value)}
+            spellCheck={false}
+            className="h-[55vh] resize-none font-mono text-xs leading-relaxed"
+          />
+        )}
+
+        {content.data !== undefined && !content.data.binary && (
+          <DialogFooter>
+            <Button
+              variant="outline"
+              size="sm"
+              disabled={mutations.download.isPending}
+              onClick={download}
+            >
+              <HugeiconsIcon icon={Download01Icon} />
+              下载
+            </Button>
+            <Button
+              size="sm"
+              disabled={!dirty || mutations.upload.isPending}
+              onClick={save}
+            >
+              {mutations.upload.isPending && <Spinner />}
+              保存
+            </Button>
+          </DialogFooter>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/components/FilesPanel.tsx b/packages/console/src/features/sandboxes/components/FilesPanel.tsx
index a417ddc..67e6d6d 100644
--- a/packages/console/src/features/sandboxes/components/FilesPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/FilesPanel.tsx
@@ -63,9 +63,11 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { formatBytes } from '@/lib/format';
+import { cn } from '@/lib/utils';
 import type { EnvdEntry } from '../envd-client';
 import { STATE_LABELS } from '../format';
 import { useDirectory, useEnvdAuth, useFileMutations } from '../hooks/useEnvd';
+import { FilePreviewDialog } from './FilePreviewDialog';
 
 const HOME = '/home/user';
 
@@ -102,12 +104,15 @@ export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
   const mutations = useFileMutations(auth.data);
   const fileInputRef = useRef<HTMLInputElement | null>(null);
 
-  // 对话框状态:新建文件夹 / 重命名 / 删除,一次只开一个。
+  // 对话框状态:预览 / 新建文件夹 / 重命名 / 删除,一次只开一个。
+  const [viewing, setViewing] = useState<EnvdEntry | null>(null);
   const [mkdirOpen, setMkdirOpen] = useState(false);
   const [mkdirName, setMkdirName] = useState('');
   const [renaming, setRenaming] = useState<EnvdEntry | null>(null);
   const [renameTo, setRenameTo] = useState('');
   const [deleting, setDeleting] = useState<EnvdEntry | null>(null);
+  // 拖拽悬停的视觉反馈;计数器抵消子元素间的 dragenter/dragleave 抖动。
+  const [dragDepth, setDragDepth] = useState(0);
 
   if (!unlocked) {
     return (
@@ -131,18 +136,52 @@ export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
 
   const entries = sortEntries(directory.data ?? []);
 
-  const upload = (file: File) => {
-    mutations.upload.mutate(
-      { path: `${path}/${file.name}`, file },
-      {
-        onSuccess: () => toast.success(`已上传 ${file.name}`),
-        onError: (error) => toast.error(error.message),
-      },
-    );
+  // 逐个串行上传:一次汇报总成败,失败点名到文件。
+  const upload = async (files: File[]) => {
+    const failures: string[] = [];
+    for (const file of files) {
+      try {
+        await mutations.upload.mutateAsync({
+          path: `${path}/${file.name}`,
+          file,
+        });
+      } catch {
+        failures.push(file.name);
+      }
+    }
+    if (failures.length === 0) {
+      const only = files.length === 1 ? files[0] : undefined;
+      toast.success(
+        only ? `已上传 ${only.name}` : `已上传 ${files.length} 个文件`,
+      );
+    } else {
+      toast.error(`${failures.length} 个上传失败:${failures.join('、')}`);
+    }
   };
 
   return (
-    <div className="flex flex-col gap-3">
+    // 拖放只是「上传」按钮的增强,不是唯一入口;section 让辅助技术
+    // 知道这一块是文件工作区,而不是把版面 div 假装成控件。
+    <section
+      aria-label="文件浏览器(支持拖放上传)"
+      className={cn(
+        'flex flex-col gap-3 rounded-lg transition-shadow',
+        dragDepth > 0 && 'ring-2 ring-primary/60',
+      )}
+      // 拖文件进来直接落到当前目录 — 和上传按钮同一条路。
+      onDragOver={(event) => event.preventDefault()}
+      onDragEnter={(event) => {
+        event.preventDefault();
+        setDragDepth((depth) => depth + 1);
+      }}
+      onDragLeave={() => setDragDepth((depth) => Math.max(0, depth - 1))}
+      onDrop={(event) => {
+        event.preventDefault();
+        setDragDepth(0);
+        const files = Array.from(event.dataTransfer.files);
+        if (files.length > 0) void upload(files);
+      }}
+    >
       <div className="flex flex-wrap items-center justify-between gap-2">
         <Breadcrumb>
           <BreadcrumbList>
@@ -172,10 +211,11 @@ export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
           <input
             ref={fileInputRef}
             type="file"
+            multiple
             className="hidden"
             onChange={(event) => {
-              const file = event.target.files?.[0];
-              if (file) upload(file);
+              const files = Array.from(event.target.files ?? []);
+              if (files.length > 0) void upload(files);
               event.target.value = '';
             }}
           />
@@ -232,7 +272,9 @@ export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
         <Empty className="border border-dashed">
           <EmptyHeader>
             <EmptyTitle>空目录</EmptyTitle>
-            <EmptyDescription>上传一个文件试试。</EmptyDescription>
+            <EmptyDescription>
+              上传一个文件试试 — 拖进这个区域也行。
+            </EmptyDescription>
           </EmptyHeader>
         </Empty>
       )}
@@ -268,13 +310,17 @@ export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
                           {entry.name}
                         </button>
                       ) : (
-                        <span className="inline-flex items-center gap-2">
+                        <button
+                          type="button"
+                          className="inline-flex items-center gap-2 hover:underline"
+                          onClick={() => setViewing(entry)}
+                        >
                           <HugeiconsIcon
                             icon={File01Icon}
                             className="size-4 text-muted-foreground"
                           />
                           {entry.name}
-                        </span>
+                        </button>
                       )}
                     </TableCell>
                     <TableCell className="tabular-nums text-muted-foreground">
@@ -343,6 +389,13 @@ export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
         </div>
       )}
 
+      {/* 预览/编辑 */}
+      <FilePreviewDialog
+        auth={auth.data}
+        entry={viewing}
+        onClose={() => setViewing(null)}
+      />
+
       {/* 新建文件夹 */}
       <Dialog open={mkdirOpen} onOpenChange={setMkdirOpen}>
         <DialogContent className="sm:max-w-sm">
@@ -462,6 +515,6 @@ export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
           </AlertDialogFooter>
         </AlertDialogContent>
       </AlertDialog>
-    </div>
+    </section>
   );
 }
diff --git a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
new file mode 100644
index 0000000..6cc29dc
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
@@ -0,0 +1,116 @@
+import { Clock01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { Badge } from '@/components/ui/badge';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import { Spinner } from '@/components/ui/spinner';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { useActivity } from '@/features/activity/hooks/useActivity';
+import {
+  ACTIVITY_KIND_LABELS,
+  ACTIVITY_KIND_STYLES,
+} from '@/features/activity/kinds';
+import { cn } from '@/lib/utils';
+import { since } from '../format';
+
+/**
+ * 「我的沙箱昨晚为什么停了」— 活动环里只属于这个沙箱的那几行。纯前端
+ * 过滤:活动事件本来就带 userKey,不发明新端点;按环形表上限(1000)
+ * 拉取,把这个沙箱的事件尽量捞全,再老的已经滚出环了。
+ */
+export function HistoryPanel({ userKey }: { userKey: string }) {
+  const { data, isPending, isError, error } = useActivity(1000);
+  const events = (data?.events ?? []).filter(
+    (event) => event.userKey === userKey,
+  );
+
+  if (isPending) {
+    return (
+      <div className="flex items-center gap-2 text-sm text-muted-foreground">
+        <Spinner /> 读取历史…
+      </div>
+    );
+  }
+  if (isError) {
+    return (
+      <Empty className="border border-dashed">
+        <EmptyHeader>
+          <EmptyTitle>读取失败</EmptyTitle>
+          <EmptyDescription>{error.message}</EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    );
+  }
+  if (events.length === 0) {
+    return (
+      <Empty className="border border-dashed">
+        <EmptyHeader>
+          <EmptyMedia variant="icon">
+            <HugeiconsIcon icon={Clock01Icon} />
+          </EmptyMedia>
+          <EmptyTitle>最近没有这个沙箱的事件</EmptyTitle>
+          <EmptyDescription>
+            活动环只保留全局最近 1000 条 — 它更早的历史已经滚出去了。
+          </EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="overflow-x-auto rounded-lg border">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead className="w-28">时间</TableHead>
+              <TableHead className="w-28">事件</TableHead>
+              <TableHead>详情</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {events.map((event) => (
+              <TableRow key={event.id}>
+                <TableCell
+                  className="tabular-nums text-muted-foreground"
+                  title={new Date(event.at).toLocaleString()}
+                >
+                  {since(event.at)}前
+                </TableCell>
+                <TableCell>
+                  <Badge
+                    variant="outline"
+                    className={cn(
+                      'font-medium',
+                      ACTIVITY_KIND_STYLES[event.kind],
+                    )}
+                  >
+                    {ACTIVITY_KIND_LABELS[event.kind]}
+                  </Badge>
+                </TableCell>
+                <TableCell className="text-muted-foreground">
+                  {event.detail}
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+      <p className="text-sm text-muted-foreground">
+        释放沙箱后 key 会重新可用 — 这里可能同时看到新旧两代沙箱的事件。
+      </p>
+    </div>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/format.ts b/packages/console/src/features/sandboxes/format.ts
index ab2dc58..8c65028 100644
--- a/packages/console/src/features/sandboxes/format.ts
+++ b/packages/console/src/features/sandboxes/format.ts
@@ -31,6 +31,18 @@ export function formatDuration(totalSeconds: number): string {
     : `${Math.floor(s / 86400)}天${rest}小时`;
 }
 
+/**
+ * 秒数输入框旁的实时换算:"259200" → "= 3天"。展示侧全说人话,输入侧
+ * 不该让用户心算 — 空值或非法值返回 null,让固定文案独自站着。
+ */
+export function durationHint(raw: string): string | null {
+  const seconds = Number(raw);
+  if (raw.trim() === '' || !Number.isFinite(seconds) || seconds <= 0) {
+    return null;
+  }
+  return `= ${formatDuration(seconds)}`;
+}
+
 /** 距离某时刻过去了多久:"3分12秒"(调用方自己加"前")。 */
 export function since(iso: string): string {
   return formatDuration((Date.now() - Date.parse(iso)) / 1000);
diff --git a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
index 30f2655..3dcd2d1 100644
--- a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
+++ b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
@@ -1,4 +1,4 @@
-import type { AcquireRequest } from '@dormice/shared';
+import type { AcquireRequest, LifecyclePolicyOverride } from '@dormice/shared';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import {
   acquireSandbox,
@@ -6,6 +6,7 @@ import {
   listSandboxes,
   rebuildSandbox,
   releaseSandbox,
+  setPolicy,
 } from '@/lib/api';
 
 /**
@@ -54,6 +55,15 @@ export function useAcquireSandbox() {
   });
 }
 
+export function useSetPolicy() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (args: { userKey: string; policy: LifecyclePolicyOverride }) =>
+      setPolicy(args.userKey, args.policy),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
+  });
+}
+
 export function useRebuildSandbox() {
   const queryClient = useQueryClient();
   return useMutation({
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index 93fd04c..071b033 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -15,7 +15,9 @@ import {
   EmptyTitle,
 } from '@/components/ui/empty';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { EditPolicyDialog } from '../components/EditPolicyDialog';
 import { FilesPanel } from '../components/FilesPanel';
+import { HistoryPanel } from '../components/HistoryPanel';
 import { MetricsPanel } from '../components/MetricsPanel';
 import { ProcessesPanel } from '../components/ProcessesPanel';
 import { RebuildSandboxButton } from '../components/RebuildSandboxButton';
@@ -32,6 +34,7 @@ export const DETAIL_TABS = [
   'files',
   'processes',
   'metrics',
+  'history',
 ] as const;
 export type DetailTab = (typeof DETAIL_TABS)[number];
 
@@ -87,6 +90,7 @@ export function SandboxDetailPage() {
           <SandboxStateBadge state={sandbox.state} />
         </div>
         <div className="flex items-center gap-2">
+          <EditPolicyDialog sandbox={sandbox} />
           <RebuildSandboxButton userKey={sandbox.userKey} />
           <ReleaseSandboxButton
             userKey={sandbox.userKey}
@@ -114,6 +118,7 @@ export function SandboxDetailPage() {
           <TabsTrigger value="files">文件</TabsTrigger>
           <TabsTrigger value="processes">进程</TabsTrigger>
           <TabsTrigger value="metrics">指标</TabsTrigger>
+          <TabsTrigger value="history">历史</TabsTrigger>
         </TabsList>
 
         <TabsContent value="overview">
@@ -162,6 +167,10 @@ export function SandboxDetailPage() {
         <TabsContent value="metrics">
           <MetricsPanel sandbox={sandbox} />
         </TabsContent>
+
+        <TabsContent value="history">
+          <HistoryPanel userKey={sandbox.userKey} />
+        </TabsContent>
       </Tabs>
     </>
   );
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index 9e7fb3d..08410f1 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -1,5 +1,10 @@
 import type { Sandbox, SandboxState } from '@dormice/shared';
-import { PackageIcon, Search01Icon } from '@hugeicons/core-free-icons';
+import {
+  ArrowDown01Icon,
+  ArrowUp01Icon,
+  PackageIcon,
+  Search01Icon,
+} from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
 import { Link } from '@tanstack/react-router';
 import { useMemo, useState } from 'react';
@@ -59,6 +64,43 @@ const STATE_FILTERS: Array<SandboxState> = [
   'restoring',
 ];
 
+/** 可排序的列:字符串比较对 userKey 和 ISO 时间戳同样成立。 */
+type SortKey = 'userKey' | 'lastActiveAt' | 'createdAt';
+type Sort = { key: SortKey; dir: 1 | -1 };
+
+/**
+ * 表头的排序按钮:点一下升序,再点反向。"空闲最久的是谁"不该靠肉眼
+ * 扫一张会自己刷新的表。
+ */
+function SortableHead({
+  label,
+  sortKey,
+  sort,
+  onSort,
+}: {
+  label: string;
+  sortKey: SortKey;
+  sort: Sort | null;
+  onSort: (key: SortKey) => void;
+}) {
+  const active = sort?.key === sortKey;
+  return (
+    <button
+      type="button"
+      className="inline-flex items-center gap-1 transition-colors hover:text-foreground"
+      onClick={() => onSort(sortKey)}
+    >
+      {label}
+      {active && (
+        <HugeiconsIcon
+          icon={sort.dir === 1 ? ArrowUp01Icon : ArrowDown01Icon}
+          className="size-3.5"
+        />
+      )}
+    </button>
+  );
+}
+
 /**
  * 批量释放:逐个调用 releaseSandbox(daemon 的 per-key 锁本来就是逐个
  * 裁决的,并发只是把失败搅在一起),结束后一次性汇报成败。
@@ -127,17 +169,27 @@ export function SandboxesPage() {
   const [search, setSearch] = useState('');
   const [stateFilter, setStateFilter] = useState<'all' | SandboxState>('all');
   const [selected, setSelected] = useState<Set<string>>(new Set());
+  const [sort, setSort] = useState<Sort | null>(null);
 
-  const filtered = useMemo(
-    () =>
-      sandboxes.filter(
-        (sandbox) =>
-          (stateFilter === 'all' || sandbox.state === stateFilter) &&
-          (search === '' ||
-            sandbox.userKey.toLowerCase().includes(search.toLowerCase())),
-      ),
-    [sandboxes, stateFilter, search],
-  );
+  const toggleSort = (key: SortKey) =>
+    setSort((prev) =>
+      prev?.key === key
+        ? { key, dir: prev.dir === 1 ? -1 : 1 }
+        : { key, dir: 1 },
+    );
+
+  const filtered = useMemo(() => {
+    const matched = sandboxes.filter(
+      (sandbox) =>
+        (stateFilter === 'all' || sandbox.state === stateFilter) &&
+        (search === '' ||
+          sandbox.userKey.toLowerCase().includes(search.toLowerCase())),
+    );
+    if (!sort) return matched;
+    return [...matched].sort(
+      (a, b) => a[sort.key].localeCompare(b[sort.key]) * sort.dir,
+    );
+  }, [sandboxes, stateFilter, search, sort]);
 
   // 选中集随现实收敛:被别处释放的沙箱不该留在选中里撑数字。
   const selectedVisible = filtered.filter((s) => selected.has(s.userKey));
@@ -252,12 +304,34 @@ export function SandboxesPage() {
                     onCheckedChange={toggleAll}
                   />
                 </TableHead>
-                <TableHead>userKey</TableHead>
+                <TableHead>
+                  <SortableHead
+                    label="userKey"
+                    sortKey="userKey"
+                    sort={sort}
+                    onSort={toggleSort}
+                  />
+                </TableHead>
                 <TableHead>状态</TableHead>
                 <TableHead>模板</TableHead>
-                <TableHead>空闲</TableHead>
+                <TableHead>
+                  {/* 升序 = 最久没动的排最前:回收磁盘时先看这里。 */}
+                  <SortableHead
+                    label="空闲"
+                    sortKey="lastActiveAt"
+                    sort={sort}
+                    onSort={toggleSort}
+                  />
+                </TableHead>
                 <TableHead>生命周期策略</TableHead>
-                <TableHead>存活</TableHead>
+                <TableHead>
+                  <SortableHead
+                    label="存活"
+                    sortKey="createdAt"
+                    sort={sort}
+                    onSort={toggleSort}
+                  />
+                </TableHead>
                 <TableHead className="text-right">操作</TableHead>
               </TableRow>
             </TableHeader>
@@ -292,13 +366,19 @@ export function SandboxesPage() {
                   <TableCell className="text-muted-foreground">
                     {sandbox.template ?? '基础镜像'}
                   </TableCell>
-                  <TableCell className="tabular-nums text-muted-foreground">
+                  <TableCell
+                    className="tabular-nums text-muted-foreground"
+                    title={`最近活动:${new Date(sandbox.lastActiveAt).toLocaleString()}`}
+                  >
                     {since(sandbox.lastActiveAt)}
                   </TableCell>
                   <TableCell className="text-xs text-muted-foreground">
                     {policyLine(sandbox.policy)}
                   </TableCell>
-                  <TableCell className="tabular-nums text-muted-foreground">
+                  <TableCell
+                    className="tabular-nums text-muted-foreground"
+                    title={`创建于:${new Date(sandbox.createdAt).toLocaleString()}`}
+                  >
                     {since(sandbox.createdAt)}
                   </TableCell>
                   <TableCell className="text-right">
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index d769663..16338da 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -5,6 +5,7 @@ import type {
   GetIngressResponse,
   GetSandboxMetricsResponse,
   HostMetricsResponse,
+  LifecyclePolicyOverride,
   ListActivityResponse,
   RegisterTemplateResponse,
   Sandbox,
@@ -99,7 +100,8 @@ export const getSandboxMetrics = (userKey: string) =>
 
 // The ledger's recent history, newest first — a bounded ring, not an audit
 // log. The daemon records at the moves themselves; this only reads.
-export const listActivity = () => rpc<ListActivityResponse>('/listActivity');
+export const listActivity = (limit?: number) =>
+  rpc<ListActivityResponse>('/listActivity', limit ? { limit } : {});
 
 // Effective configuration, read-only. Secrets come back as "set", never as
 // their value; archive.enabled is the daemon's own adjudication.
@@ -140,6 +142,11 @@ export const releaseSandbox = (userKey: string) =>
 export const rebuildSandbox = (userKey: string) =>
   rpc<{ sandbox: Sandbox }>('/rebuildSandbox', { userKey });
 
+// Patch the stored lifecycle policy in place — the update verb acquire is
+// not. Ledger-only: nothing wakes, the idle clock keeps running.
+export const setPolicy = (userKey: string, policy: LifecyclePolicyOverride) =>
+  rpc<{ sandbox: Sandbox }>('/setPolicy', { userKey, policy });
+
 // The terminal's key: trades the session cookie for one sandbox's envd
 // access token, so the browser can speak to the envd surface directly.
 export const mintEnvdToken = (sandboxId: string) =>
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 54bf3f8..fae421e 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -292,6 +292,26 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
     });
   });
 
+  it('patches a lifecycle policy in place, keeping the untouched knobs', async () => {
+    const created = await client.acquireSandbox('policy-key');
+    const { sandbox } = await client.setPolicy('policy-key', {
+      stopAfterSeconds: null,
+    });
+    expect(sandbox.sandboxId).toBe(created.sandbox.sandboxId);
+    expect(sandbox.policy).toEqual({
+      ...DEFAULT_LIFECYCLE_POLICY,
+      stopAfterSeconds: null,
+    });
+
+    await expect(
+      client.setPolicy('no-such-key', { freezeAfterSeconds: 60 }),
+    ).rejects.toMatchObject({ name: 'DormiceApiError', status: 404 });
+    await expect(
+      // Merged with the stored policy this breaks the ordering rule.
+      client.setPolicy('policy-key', { archiveAfterSeconds: 1 }),
+    ).rejects.toMatchObject({ status: 400 });
+  });
+
   it('releases a sandbox and reports idempotently', async () => {
     const created = await client.acquireSandbox('frank');
     expect(await client.releaseSandbox('frank')).toEqual({ released: true });
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index c7ee753..b0a80f6 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -28,7 +28,9 @@ import {
   type Sandbox,
   type SandboxMetricsSample,
   type SetIngressResponse,
+  type SetPolicyResponse,
   setIngressResponseSchema,
+  setPolicyResponseSchema,
   type Template,
   type WriteFilesResponse,
   writeFilesResponseSchema,
@@ -226,6 +228,22 @@ export class Dormice {
     return rebuildSandboxResponseSchema.parse(data);
   }
 
+  /**
+   * Updates the sandbox's lifecycle policy in place — the update verb
+   * acquire deliberately is not. Patch semantics over the stored policy:
+   * omitted fields keep their current values, `null` means "never take
+   * that step" (e.g. `{stopAfterSeconds: null}` promotes a sandbox to a
+   * never-stop resident agent). A pure ledger write: nothing is woken, and
+   * the idle clock is not refreshed. Unknown key: 404 — not a creator.
+   */
+  async setPolicy(
+    userKey: string,
+    policy: LifecyclePolicyOverride,
+  ): Promise<SetPolicyResponse> {
+    const data = await this.rpc('setPolicy', { userKey, policy });
+    return setPolicyResponseSchema.parse(data);
+  }
+
   /**
    * Destroys the sandbox behind a user key — container and disk are gone
    * for good. Idempotent like acquire: a key that has no sandbox is not an
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index c860dd1..c3d5ff4 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -839,6 +839,108 @@ describe('POST /rebuildSandbox', () => {
   });
 });
 
+describe('POST /setPolicy', () => {
+  it('patches one knob, keeps the rest, and does not refresh the idle clock', async () => {
+    const { app } = testApp();
+    const created = (await acquire(app, { userKey: 'alice' })).json();
+
+    const res = await rpc(app, '/setPolicy', {
+      userKey: 'alice',
+      policy: { freezeAfterSeconds: 120 },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().sandbox.policy).toEqual({
+      ...DEFAULT_LIFECYCLE_POLICY,
+      freezeAfterSeconds: 120,
+    });
+    // Adjusting a knob is not activity: the idle countdown keeps running.
+    expect(res.json().sandbox.lastActiveAt).toBe(created.sandbox.lastActiveAt);
+
+    const events = (await rpc(app, '/listActivity')).json().events;
+    expect(events[0]).toMatchObject({
+      kind: 'policy-changed',
+      userKey: 'alice',
+      detail: 'freeze 600s -> 120s',
+    });
+  });
+
+  it('promotes a frozen sandbox to never-stop without waking it', async () => {
+    const { app, db, executor, locks } = testApp();
+    const created = (await acquire(app, { userKey: 'alice' })).json();
+    await scanOnce(
+      db,
+      executor,
+      locks,
+      after(
+        created.sandbox.lastActiveAt,
+        DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
+      ),
+    );
+    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+
+    const res = await rpc(app, '/setPolicy', {
+      userKey: 'alice',
+      policy: { stopAfterSeconds: null },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().sandbox.policy.stopAfterSeconds).toBeNull();
+    // Ledger-only: the sandbox slept through its own promotion.
+    expect(res.json().sandbox.state).toBe('frozen');
+    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+  });
+
+  it('rejects a patch whose merged result breaks the ordering rule', async () => {
+    const { app } = testApp();
+    await acquire(app, { userKey: 'alice' });
+    // freeze pushed past the stored stop threshold.
+    const res = await rpc(app, '/setPolicy', {
+      userKey: 'alice',
+      policy: {
+        freezeAfterSeconds:
+          (DEFAULT_LIFECYCLE_POLICY.stopAfterSeconds ?? 0) + 1,
+      },
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().message).toMatch(/stopAfterSeconds/);
+  });
+
+  it('refuses to promise archiving on a daemon without S3', async () => {
+    const { app } = testApp();
+    await acquire(app, { userKey: 'alice' });
+    const res = await rpc(app, '/setPolicy', {
+      userKey: 'alice',
+      policy: { archiveAfterSeconds: 30 * 24 * 60 * 60 },
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().message).toMatch(/DORMICE_S3_/);
+  });
+
+  it('answers 404 for an unknown key — setPolicy is not a creator', async () => {
+    const res = await rpc(testApp().app, '/setPolicy', {
+      userKey: 'nobody',
+      policy: { freezeAfterSeconds: 60 },
+    });
+    expect(res.statusCode).toBe(404);
+    expect(res.json().message).toMatch(/acquire it first/);
+  });
+
+  it('treats a no-change patch as the goal state and writes no history', async () => {
+    const { app } = testApp();
+    await acquire(app, { userKey: 'alice' });
+    const res = await rpc(app, '/setPolicy', {
+      userKey: 'alice',
+      policy: {
+        freezeAfterSeconds: DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
+      },
+    });
+    expect(res.statusCode).toBe(200);
+    const events = (await rpc(app, '/listActivity')).json().events;
+    expect(
+      events.some((e: { kind: string }) => e.kind === 'policy-changed'),
+    ).toBe(false);
+  });
+});
+
 describe('POST /releaseSandbox', () => {
   it('destroys the container and forgets the key', async () => {
     const { app, executor } = testApp();
diff --git a/packages/server/src/db/ledger.ts b/packages/server/src/db/ledger.ts
index 0845c12..f2cdac8 100644
--- a/packages/server/src/db/ledger.ts
+++ b/packages/server/src/db/ledger.ts
@@ -158,6 +158,31 @@ export function setDeadline(
     .run();
 }
 
+/**
+ * Rewrites the three lifecycle thresholds. Ledger-only: no container work,
+ * no state change, and deliberately no touch — setPolicy is not activity,
+ * the new thresholds judge the idle time already on the clock.
+ */
+export function updatePolicy(
+  db: Db,
+  sandboxId: string,
+  policy: LifecyclePolicy,
+): SandboxRow {
+  db.update(sandboxes)
+    .set({
+      freezeAfterSeconds: policy.freezeAfterSeconds,
+      stopAfterSeconds: policy.stopAfterSeconds,
+      archiveAfterSeconds: policy.archiveAfterSeconds,
+    })
+    .where(eq(sandboxes.sandboxId, sandboxId))
+    .run();
+  const row = findBySandboxId(db, sandboxId);
+  if (!row) {
+    throw new Error(`sandbox ${sandboxId} not found`);
+  }
+  return row;
+}
+
 /** Marks an explicit E2B pause; wakes clear it (an awake sandbox is not paused). */
 export function setPausedByUser(
   db: Db,
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index da1197e..0ae22a1 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -7,6 +7,7 @@ import {
   getSandboxMetricsRequestSchema,
   getSandboxMetricsResponseSchema,
   type LifecyclePolicy,
+  lifecyclePolicySchema,
   listSandboxesResponseSchema,
   readFileRequestSchema,
   readFileResponseSchema,
@@ -16,6 +17,8 @@ import {
   releaseSandboxResponseSchema,
   resolveSandboxPath,
   type Sandbox,
+  setPolicyRequestSchema,
+  setPolicyResponseSchema,
   WRITE_FILES_BODY_LIMIT_BYTES,
   writeFilesRequestSchema,
   writeFilesResponseSchema,
@@ -24,6 +27,7 @@ import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import { ZodError, z } from 'zod';
 import type { Archiver, RestoreProgress } from '../archive/archiver';
 import type { Config } from '../config';
+import { recordActivity } from '../db/activity';
 import type { Db } from '../db/db';
 import {
   countSandboxes,
@@ -31,6 +35,7 @@ import {
   findByUserKey,
   listSandboxes,
   touch,
+  updatePolicy,
 } from '../db/ledger';
 import type { SandboxRow } from '../db/schema';
 import { findTemplate, resolveImage } from '../db/templates';
@@ -469,6 +474,103 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     },
   );
 
+  app.post(
+    '/setPolicy',
+    {
+      schema: {
+        body: setPolicyRequestSchema,
+        response: {
+          200: setPolicyResponseSchema,
+          400: z.object({ message: z.string() }),
+        },
+      },
+    },
+    async (request, reply) => {
+      const { userKey, policy: patch } = request.body;
+      // Unlike acquire, the merge base is the STORED policy, so validation
+      // must wait for the row — it runs inside the slot, which also keeps a
+      // concurrent release from deleting the row between check and write.
+      const outcome = await locks.run<{ error: string } | { row: SandboxRow }>(
+        userKey,
+        async () => {
+          const existing = findByUserKey(db, userKey);
+          if (!existing) {
+            // Not a creator: an unknown key is a typo, same manners as rebuild.
+            throw httpError(
+              404,
+              `no sandbox for key "${userKey}" — acquire it first`,
+            );
+          }
+          // Legal in every state: policy is a ledger attribute, not a container
+          // one — even an archived sandbox's thresholds matter after restore.
+          const merged = lifecyclePolicySchema.safeParse({
+            freezeAfterSeconds:
+              patch.freezeAfterSeconds ?? existing.freezeAfterSeconds,
+            stopAfterSeconds:
+              patch.stopAfterSeconds !== undefined
+                ? patch.stopAfterSeconds
+                : existing.stopAfterSeconds,
+            archiveAfterSeconds:
+              patch.archiveAfterSeconds !== undefined
+                ? patch.archiveAfterSeconds
+                : existing.archiveAfterSeconds,
+          });
+          if (!merged.success) {
+            return {
+              error: `invalid lifecycle policy: ${merged.error.issues
+                .map((issue) => issue.message)
+                .join('; ')}`,
+            };
+          }
+          if (
+            archiveDefaultSeconds === null &&
+            merged.data.archiveAfterSeconds !== null
+          ) {
+            return {
+              error:
+                'invalid lifecycle policy: archiving requires S3 (DORMICE_S3_*) to be configured',
+            };
+          }
+          const before = {
+            freezeAfterSeconds: existing.freezeAfterSeconds,
+            stopAfterSeconds: existing.stopAfterSeconds,
+            archiveAfterSeconds: existing.archiveAfterSeconds,
+          } as const;
+          const changed = (
+            [
+              'freezeAfterSeconds',
+              'stopAfterSeconds',
+              'archiveAfterSeconds',
+            ] as const
+          ).filter((knob) => before[knob] !== merged.data[knob]);
+          if (changed.length === 0) {
+            // The goal state already holds; a no-op writes no history.
+            return { row: existing };
+          }
+          const row = updatePolicy(db, existing.sandboxId, merged.data);
+          const fmt = (seconds: number | null) =>
+            seconds === null ? 'never' : `${seconds}s`;
+          recordActivity(db, {
+            kind: 'policy-changed',
+            userKey,
+            sandboxId: row.sandboxId,
+            detail: changed
+              .map(
+                (knob) =>
+                  `${knob.replace('AfterSeconds', '')} ${fmt(before[knob])} -> ${fmt(merged.data[knob])}`,
+              )
+              .join(', '),
+          });
+          return { row };
+        },
+      );
+      if ('error' in outcome) {
+        return reply.code(400).send({ message: outcome.error });
+      }
+      return { sandbox: toSandbox(outcome.row, endpoint) };
+    },
+  );
+
   app.post(
     '/releaseSandbox',
     {
diff --git a/packages/shared/src/activity.ts b/packages/shared/src/activity.ts
index 4e7078c..1b7ddd6 100644
--- a/packages/shared/src/activity.ts
+++ b/packages/shared/src/activity.ts
@@ -24,6 +24,8 @@ export const ACTIVITY_KINDS = [
   'restore-failed',
   /** The reconciler corrected the ledger (or reality) to match the other. */
   'reconciled',
+  /** setPolicy rewrote a sandbox's lifecycle thresholds (ledger-only). */
+  'policy-changed',
   'daemon-started',
   /** An operator bound or cleared the console domain through setIngress. */
   'ingress-updated',
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index aa4170c..fd1d656 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -11,5 +11,6 @@ export * from './policy';
 export * from './rebuild';
 export * from './release';
 export * from './sandbox';
+export * from './set-policy';
 export * from './states';
 export * from './templates';
diff --git a/packages/shared/src/set-policy.ts b/packages/shared/src/set-policy.ts
new file mode 100644
index 0000000..c115ecc
--- /dev/null
+++ b/packages/shared/src/set-policy.ts
@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { lifecyclePolicyOverrideSchema } from './policy';
+import { sandboxSchema, userKeySchema } from './sandbox';
+
+/**
+ * setPolicy(userKey, policy) — the update verb acquire deliberately is not.
+ * Without it, changing a live sandbox's lifecycle (say, promoting it to a
+ * never-stop resident agent) would require release + re-acquire, and release
+ * destroys the disk — the one thing this platform promises to keep.
+ *
+ * Patch semantics over the STORED policy: omitted fields keep their current
+ * values, `null` still means "never take that step". The merged result is
+ * validated by `lifecyclePolicySchema` — the same single arbiter as acquire —
+ * so an update can never leave a policy acquire would have refused.
+ *
+ * A pure ledger write: no container is touched, no wake, and the idle clock
+ * is NOT refreshed — adjusting a knob is not sandbox activity, and the new
+ * thresholds apply to the idle time already accumulated.
+ */
+export const setPolicyRequestSchema = z.object({
+  userKey: userKeySchema,
+  policy: lifecyclePolicyOverrideSchema,
+});
+
+export type SetPolicyRequest = z.infer<typeof setPolicyRequestSchema>;
+
+/** The sandbox as it stands after the update (state untouched). */
+export const setPolicyResponseSchema = z.object({
+  sandbox: sandboxSchema,
+});
+
+export type SetPolicyResponse = z.infer<typeof setPolicyResponseSchema>;

From d79ac07f573d0a85d9154bfc590715a4749b0b30 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 12 Jul 2026 23:10:28 +0800
Subject: [PATCH 061/133] =?UTF-8?q?The=20dev=20proxy=20learns=20setPolicy?=
 =?UTF-8?q?=20=E2=80=94=20the=20verb=20landed=20but=20the=20Vite=20table?=
 =?UTF-8?q?=20missed=20it?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/console/vite.config.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index dae3c39..304f06e 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -28,6 +28,7 @@ export default defineConfig({
       '/releaseSandbox': 'http://127.0.0.1:3676',
       '/acquireSandbox': 'http://127.0.0.1:3676',
       '/rebuildSandbox': 'http://127.0.0.1:3676',
+      '/setPolicy': 'http://127.0.0.1:3676',
       '/listTemplates': 'http://127.0.0.1:3676',
       '/registerTemplate': 'http://127.0.0.1:3676',
       '/removeTemplate': 'http://127.0.0.1:3676',

From 2be481844806df351e38d3df5d1ade7b80d42aa9 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Mon, 13 Jul 2026 02:07:46 +0800
Subject: [PATCH 062/133] The console learns what the fleet costs:
 listSandboxMetrics feeds three resource columns, and the workspace grows a
 countdown, trend lines, filters, watch-refresh, and a command palette
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One wire verb, five console teeth. POST /listSandboxMetrics answers every
measurable sandbox in one call — readings run in parallel (one docker-stats
sample costs a second), vanished containers are skipped, colder states are
absent rather than null-stuffed. The sandbox list turns it into CPU/memory/
disk columns with warning colors past 75/90%.

Console-only teeth: the detail header counts down to the next lifecycle
rung with the scanner's own semantics; the metrics tab accumulates a
browser-side rolling window (the daemon still keeps no history) into three
single-series trend charts; the activity page filters by kind and userKey
over the ring it already holds; ⌘K opens a command palette (pages + jump
to sandbox by key — navigation only, destructive verbs stay behind their
dialogs); and the files panel arms an envd watcher so changes made inside
the sandbox appear within 2s. Watch discipline: GetWatcherEvents never
wakes, Create/Remove need the container up — so the panel only arms and
disarms while the sandbox is active, and never wakes one to tidy up.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/console/src/components/AppShell.tsx  |   2 +
 .../console/src/components/AppSidebar.tsx     |   3 +-
 .../console/src/components/CommandMenu.tsx    | 129 +++++++++++++++
 .../features/activity/pages/ActivityPage.tsx  |  77 ++++++++-
 .../sandboxes/components/FilesPanel.tsx       |  12 +-
 .../components/LifecycleCountdown.tsx         |  29 ++++
 .../sandboxes/components/MetricsPanel.tsx     | 150 +++++++++++++++++-
 .../src/features/sandboxes/envd-client.ts     |  29 ++++
 .../console/src/features/sandboxes/format.ts  |  41 +++++
 .../src/features/sandboxes/hooks/useEnvd.ts   |  75 +++++++++
 .../features/sandboxes/hooks/useSandboxes.ts  |  16 ++
 .../sandboxes/pages/SandboxDetailPage.tsx     |   2 +
 .../sandboxes/pages/SandboxesPage.tsx         |  78 ++++++++-
 packages/console/src/lib/api.ts               |   6 +
 packages/console/vite.config.ts               |   1 +
 packages/sdk/src/client.test.ts               |  16 ++
 packages/sdk/src/client.ts                    |  13 ++
 .../server/src/routes/observability.test.ts   |  60 +++++++
 packages/server/src/routes/sandboxes.ts       |  38 +++++
 packages/shared/src/metrics.ts                |  27 ++++
 20 files changed, 798 insertions(+), 6 deletions(-)
 create mode 100644 packages/console/src/components/CommandMenu.tsx
 create mode 100644 packages/console/src/features/sandboxes/components/LifecycleCountdown.tsx

diff --git a/packages/console/src/components/AppShell.tsx b/packages/console/src/components/AppShell.tsx
index b6d5c54..89a9971 100644
--- a/packages/console/src/components/AppShell.tsx
+++ b/packages/console/src/components/AppShell.tsx
@@ -1,6 +1,7 @@
 import { Outlet, useRouterState } from '@tanstack/react-router';
 import { Fragment } from 'react';
 import { AppSidebar } from '@/components/AppSidebar';
+import { CommandMenu } from '@/components/CommandMenu';
 import {
   Breadcrumb,
   BreadcrumbItem,
@@ -72,6 +73,7 @@ export function AppShell() {
               ))}
             </BreadcrumbList>
           </Breadcrumb>
+          <CommandMenu />
         </header>
         <div className="flex flex-1 flex-col gap-4 p-4 md:p-6">
           <Outlet />
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index 46ee423..46f7fa5 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -40,7 +40,8 @@ interface NavItem {
 }
 
 // 平台 = 管的对象(沙箱/模板),运维 = 管这台机器;连接页是给要接 SDK 的人。
-const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
+// 导出给命令面板(⌘K)复用 — 页面清单只有这一份,两处永远一致。
+export const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
   {
     label: '平台',
     items: [
diff --git a/packages/console/src/components/CommandMenu.tsx b/packages/console/src/components/CommandMenu.tsx
new file mode 100644
index 0000000..362f97f
--- /dev/null
+++ b/packages/console/src/components/CommandMenu.tsx
@@ -0,0 +1,129 @@
+import {
+  ArrowRight01Icon,
+  PackageIcon,
+  Search01Icon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useNavigate } from '@tanstack/react-router';
+import { useEffect, useState } from 'react';
+import { NAV_GROUPS } from '@/components/AppSidebar';
+import { Button } from '@/components/ui/button';
+import {
+  CommandDialog,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@/components/ui/command';
+import { Kbd } from '@/components/ui/kbd';
+import { STATE_LABELS } from '@/features/sandboxes/format';
+import { useSandboxes } from '@/features/sandboxes/hooks/useSandboxes';
+import { MOCK_PAGES_ENABLED } from '@/lib/mock';
+
+/**
+ * 沙箱条目单拆一个组件:useSandboxes 的 2 秒轮询只在面板打开时才该跑,
+ * hook 不能条件调用,但组件可以条件挂载。缓存和列表页共享同一个 key,
+ * 打开面板时多半直接命中。
+ */
+function SandboxItems({ onGo }: { onGo: (userKey: string) => void }) {
+  const query = useSandboxes();
+  const sandboxes = query.data?.sandboxes ?? [];
+  if (sandboxes.length === 0) return null;
+  return (
+    <CommandGroup heading="沙箱">
+      {sandboxes.map((sandbox) => (
+        <CommandItem
+          key={sandbox.sandboxId}
+          value={`sandbox ${sandbox.userKey}`}
+          onSelect={() => onGo(sandbox.userKey)}
+        >
+          <HugeiconsIcon icon={PackageIcon} strokeWidth={1.8} />
+          <span className="font-mono">{sandbox.userKey}</span>
+          <span className="ml-auto text-xs text-muted-foreground">
+            {STATE_LABELS[sandbox.state]}
+          </span>
+        </CommandItem>
+      ))}
+    </CommandGroup>
+  );
+}
+
+/**
+ * ⌘K / Ctrl+K 命令面板:跳页面、按 userKey 跳沙箱。挂在 AppShell 上,
+ * 登录后全站可用;它只做导航 — 动作(释放/重建)留在各自页面的确认
+ * 流程里,快捷键不该绕过"删了就没有了"的那道闸。
+ */
+export function CommandMenu() {
+  const [open, setOpen] = useState(false);
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'k' && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault();
+        setOpen((prev) => !prev);
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, []);
+
+  const goPage = (to: string) => {
+    setOpen(false);
+    void navigate({ to });
+  };
+  const goSandbox = (userKey: string) => {
+    setOpen(false);
+    void navigate({
+      to: '/sandboxes/$userKey',
+      params: { userKey },
+      search: { tab: 'overview' },
+    });
+  };
+
+  return (
+    <>
+      <Button
+        variant="ghost"
+        size="sm"
+        className="ml-auto text-muted-foreground"
+        onClick={() => setOpen(true)}
+      >
+        <HugeiconsIcon icon={Search01Icon} className="size-4" />
+        搜索
+        <Kbd>⌘K</Kbd>
+      </Button>
+      <CommandDialog
+        open={open}
+        onOpenChange={setOpen}
+        title="命令面板"
+        description="跳转到页面或沙箱"
+      >
+        <CommandInput placeholder="搜页面、沙箱…" />
+        <CommandList>
+          <CommandEmpty>没有匹配的结果。</CommandEmpty>
+          <CommandGroup heading="页面">
+            {NAV_GROUPS.flatMap((group) => group.items)
+              .filter((item) => !item.mock || MOCK_PAGES_ENABLED)
+              .map((item) => (
+                <CommandItem
+                  key={item.to}
+                  value={`page ${item.label}`}
+                  onSelect={() => goPage(item.to)}
+                >
+                  <HugeiconsIcon icon={item.icon} strokeWidth={1.8} />
+                  {item.label}
+                  <HugeiconsIcon
+                    icon={ArrowRight01Icon}
+                    className="ml-auto size-3.5 text-muted-foreground"
+                  />
+                </CommandItem>
+              ))}
+          </CommandGroup>
+          {open && <SandboxItems onGo={goSandbox} />}
+        </CommandList>
+      </CommandDialog>
+    </>
+  );
+}
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index 43337e0..fe64762 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -1,4 +1,8 @@
+import type { ActivityKind } from '@dormice/shared';
+import { Search01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
 import { Link } from '@tanstack/react-router';
+import { useMemo, useState } from 'react';
 import { Badge } from '@/components/ui/badge';
 import {
   Empty,
@@ -6,6 +10,15 @@ import {
   EmptyHeader,
   EmptyTitle,
 } from '@/components/ui/empty';
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupInput,
+} from '@/components/ui/input-group';
+import {
+  NativeSelect,
+  NativeSelectOption,
+} from '@/components/ui/native-select';
 import { Spinner } from '@/components/ui/spinner';
 import {
   Table,
@@ -23,9 +36,25 @@ import { ACTIVITY_KIND_LABELS, ACTIVITY_KIND_STYLES } from '../kinds';
 /**
  * 「我不在的时候发生了什么」:daemon 每一次生命周期动作(创建、降温、
  * 唤醒、销毁)和对账修复的有界环形记录 — 事件写在动作发生处,这里只读。
+ * 筛选是纯前端的:环一共就 1000 条,全在手里,没必要为过滤发明服务端
+ * 参数。
  */
 export function ActivityPage() {
   const { data, isPending, isError, error } = useActivity();
+  const [search, setSearch] = useState('');
+  const [kindFilter, setKindFilter] = useState<'all' | ActivityKind>('all');
+
+  const events = data?.events ?? [];
+  const filtered = useMemo(
+    () =>
+      events.filter(
+        (event) =>
+          (kindFilter === 'all' || event.kind === kindFilter) &&
+          (search === '' ||
+            (event.userKey ?? '').toLowerCase().includes(search.toLowerCase())),
+      ),
+    [events, kindFilter, search],
+  );
 
   return (
     <>
@@ -37,6 +66,43 @@ export function ActivityPage() {
         </p>
       </div>
 
+      <div className="flex flex-wrap items-center gap-2">
+        <InputGroup className="w-64">
+          <InputGroupAddon>
+            <HugeiconsIcon
+              icon={Search01Icon}
+              className="size-4 text-muted-foreground"
+            />
+          </InputGroupAddon>
+          <InputGroupInput
+            value={search}
+            onChange={(event) => setSearch(event.target.value)}
+            placeholder="按 userKey 搜索"
+          />
+        </InputGroup>
+        <NativeSelect
+          aria-label="按事件类型筛选"
+          value={kindFilter}
+          onChange={(event) =>
+            setKindFilter(event.target.value as 'all' | ActivityKind)
+          }
+        >
+          <NativeSelectOption value="all">全部事件</NativeSelectOption>
+          {(
+            Object.entries(ACTIVITY_KIND_LABELS) as Array<
+              [ActivityKind, string]
+            >
+          ).map(([kind, label]) => (
+            <NativeSelectOption key={kind} value={kind}>
+              {label}
+            </NativeSelectOption>
+          ))}
+        </NativeSelect>
+        <span className="text-sm text-muted-foreground">
+          {filtered.length} / {events.length} 条
+        </span>
+      </div>
+
       {isPending ? (
         <div className="flex items-center gap-2 text-sm text-muted-foreground">
           <Spinner /> 读取活动…
@@ -48,7 +114,7 @@ export function ActivityPage() {
             <EmptyDescription>{error.message}</EmptyDescription>
           </EmptyHeader>
         </Empty>
-      ) : data.events.length === 0 ? (
+      ) : events.length === 0 ? (
         <Empty className="border border-dashed">
           <EmptyHeader>
             <EmptyTitle>还没有活动</EmptyTitle>
@@ -57,6 +123,13 @@ export function ActivityPage() {
             </EmptyDescription>
           </EmptyHeader>
         </Empty>
+      ) : filtered.length === 0 ? (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyTitle>没有匹配的事件</EmptyTitle>
+            <EmptyDescription>换个关键词或事件类型试试。</EmptyDescription>
+          </EmptyHeader>
+        </Empty>
       ) : (
         <div className="overflow-x-auto rounded-lg border">
           <Table>
@@ -69,7 +142,7 @@ export function ActivityPage() {
               </TableRow>
             </TableHeader>
             <TableBody>
-              {data.events.map((event) => (
+              {filtered.map((event) => (
                 <TableRow key={event.id}>
                   <TableCell
                     className="tabular-nums text-muted-foreground"
diff --git a/packages/console/src/features/sandboxes/components/FilesPanel.tsx b/packages/console/src/features/sandboxes/components/FilesPanel.tsx
index 67e6d6d..f3eafbd 100644
--- a/packages/console/src/features/sandboxes/components/FilesPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/FilesPanel.tsx
@@ -66,7 +66,12 @@ import { formatBytes } from '@/lib/format';
 import { cn } from '@/lib/utils';
 import type { EnvdEntry } from '../envd-client';
 import { STATE_LABELS } from '../format';
-import { useDirectory, useEnvdAuth, useFileMutations } from '../hooks/useEnvd';
+import {
+  useDirectory,
+  useDirectoryWatch,
+  useEnvdAuth,
+  useFileMutations,
+} from '../hooks/useEnvd';
 import { FilePreviewDialog } from './FilePreviewDialog';
 
 const HOME = '/home/user';
@@ -101,6 +106,11 @@ export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
   const [path, setPath] = useState(HOME);
   const auth = useEnvdAuth(sandbox.sandboxId);
   const directory = useDirectory(auth.data, path, unlocked);
+  // 沙箱里(agent、终端)动了文件,这张表 2 秒内自己跟上 — 不用手点刷新。
+  useDirectoryWatch(auth.data, path, {
+    enabled: unlocked,
+    active: sandbox.state === 'active',
+  });
   const mutations = useFileMutations(auth.data);
   const fileInputRef = useRef<HTMLInputElement | null>(null);
 
diff --git a/packages/console/src/features/sandboxes/components/LifecycleCountdown.tsx b/packages/console/src/features/sandboxes/components/LifecycleCountdown.tsx
new file mode 100644
index 0000000..27b6f44
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/LifecycleCountdown.tsx
@@ -0,0 +1,29 @@
+import type { Sandbox } from '@dormice/shared';
+import { useEffect, useState } from 'react';
+import { formatDuration, nextLifecycleStep } from '../format';
+
+/**
+ * 详情页头部的"下一步降温"倒计时:把生命周期引擎从一张策略表变成看得
+ * 见的东西 — "再空闲 4分12秒 冻结"。逐秒走字纯属前端(列表缓存里的
+ * lastActiveAt + 策略就能算),到 0 不是异常而是"等下一轮扫描"。
+ */
+export function LifecycleCountdown({ sandbox }: { sandbox: Sandbox }) {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const timer = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(timer);
+  }, []);
+
+  const step = nextLifecycleStep(sandbox, now);
+  if (!step) return null;
+
+  return (
+    <span className="text-sm tabular-nums text-muted-foreground">
+      {step.remainingSeconds === null
+        ? `永不${step.action}`
+        : step.remainingSeconds === 0
+          ? `即将${step.action}(等下一轮扫描)`
+          : `再空闲 ${formatDuration(step.remainingSeconds)} 就${step.action}`}
+    </span>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
index dc10dfd..7b43369 100644
--- a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
@@ -1,11 +1,19 @@
-import type { Sandbox } from '@dormice/shared';
+import type { Sandbox, SandboxMetricsSample } from '@dormice/shared';
 import {
   CpuIcon,
   HardDriveIcon,
   RamMemoryIcon,
 } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
+import { useEffect, useState } from 'react';
+import { CartesianGrid, Line, LineChart, XAxis, YAxis } from 'recharts';
 import { Card, CardContent } from '@/components/ui/card';
+import {
+  type ChartConfig,
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+} from '@/components/ui/chart';
 import {
   Empty,
   EmptyDescription,
@@ -64,6 +72,110 @@ function MetricCard({
   );
 }
 
+/** 滚动窗口容量:5 秒一拍 × 120 点 ≈ 最近 10 分钟。 */
+const HISTORY_CAP = 120;
+
+/**
+ * 面板打开期间的采样累积。daemon 刻意不存指标历史(观察窗不是监控
+ * 系统),但"刚才那一下是不是内存尖峰"值得回答 — 历史就攒在浏览器里,
+ * 换沙箱清零,关面板即忘。
+ */
+function useSampleHistory(
+  sandboxId: string,
+  latest: SandboxMetricsSample | null | undefined,
+): SandboxMetricsSample[] {
+  const [history, setHistory] = useState<SandboxMetricsSample[]>([]);
+  // 换沙箱清零:render 期重置(React 官方推荐形),不多跑一轮 effect。
+  const [prevId, setPrevId] = useState(sandboxId);
+  if (prevId !== sandboxId) {
+    setPrevId(sandboxId);
+    setHistory([]);
+  }
+  useEffect(() => {
+    if (!latest) return;
+    setHistory((prev) =>
+      prev.at(-1)?.timestamp === latest.timestamp
+        ? prev
+        : [...prev.slice(-(HISTORY_CAP - 1)), latest],
+    );
+  }, [latest]);
+  return history;
+}
+
+/** 时间轴刻度:HH:MM:SS,窗口只有分钟级,日期是噪声。 */
+const clock = (ms: number) =>
+  new Date(ms).toLocaleTimeString('zh-CN', { hour12: false });
+
+/**
+ * 一个度量一张小图,单系列单轴(不同量纲绝不共轴)。线色用主题的
+ * chart-2(已过明暗两面的对比度验证),身份由标题承担 — 单系列不需要
+ * 图例。
+ */
+function HistoryChart({
+  title,
+  data,
+  tickFormatter,
+  valueFormatter,
+  domainMax,
+}: {
+  title: string;
+  data: Array<{ at: number; value: number }>;
+  tickFormatter: (value: number) => string;
+  valueFormatter: (value: number) => string;
+  domainMax?: number;
+}) {
+  const config = {
+    value: { label: title, color: 'var(--chart-2)' },
+  } satisfies ChartConfig;
+  return (
+    <Card size="sm">
+      <CardContent className="flex flex-col gap-2">
+        <div className="text-sm text-muted-foreground">{title}</div>
+        <ChartContainer config={config} className="aspect-[2/1] w-full">
+          <LineChart data={data} margin={{ left: 4, right: 12, top: 4 }}>
+            <CartesianGrid vertical={false} />
+            <XAxis
+              dataKey="at"
+              type="number"
+              domain={['dataMin', 'dataMax']}
+              tickFormatter={clock}
+              tickLine={false}
+              axisLine={false}
+              minTickGap={48}
+            />
+            <YAxis
+              width={44}
+              domain={[0, domainMax ?? 'auto']}
+              tickFormatter={tickFormatter}
+              tickLine={false}
+              axisLine={false}
+              tickCount={3}
+            />
+            <ChartTooltip
+              content={
+                <ChartTooltipContent
+                  labelFormatter={(_, payload) =>
+                    clock((payload?.[0]?.payload as { at: number }).at)
+                  }
+                  formatter={(value) => valueFormatter(Number(value))}
+                />
+              }
+            />
+            <Line
+              dataKey="value"
+              type="monotone"
+              stroke="var(--color-value)"
+              strokeWidth={2}
+              dot={false}
+              isAnimationActive={false}
+            />
+          </LineChart>
+        </ChartContainer>
+      </CardContent>
+    </Card>
+  );
+}
+
 /**
  * 单沙箱指标:5 秒一拍的单次快照(观察窗不是监控系统)。观察不唤醒 —
  * 冻结的沙箱睡着也能读(cgroup 记账还在),停了的沙箱没有容器可测,
@@ -73,6 +185,8 @@ export function MetricsPanel({ sandbox }: { sandbox: Sandbox }) {
   const { data, isPending, isError, error } = useSandboxMetrics(
     sandbox.userKey,
   );
+  // Hook 在任何 early return 之前:面板打开期间持续累积,换沙箱清零。
+  const history = useSampleHistory(sandbox.sandboxId, data?.sample);
 
   if (isPending) {
     return (
@@ -131,8 +245,42 @@ export function MetricsPanel({ sandbox }: { sandbox: Sandbox }) {
           pct={pctOf(sample.diskUsedBytes, sample.diskTotalBytes)}
         />
       </div>
+      {history.length >= 2 && (
+        <div className="grid gap-4 xl:grid-cols-3">
+          <HistoryChart
+            title="CPU 走势"
+            data={history.map((s) => ({
+              at: Date.parse(s.timestamp),
+              value: Math.round(s.cpuUsedPct),
+            }))}
+            tickFormatter={(v) => `${v}%`}
+            valueFormatter={(v) => `${v}%(按单核计)`}
+          />
+          <HistoryChart
+            title="内存走势"
+            data={history.map((s) => ({
+              at: Date.parse(s.timestamp),
+              value: s.memUsedBytes,
+            }))}
+            tickFormatter={(v) => formatBytes(v)}
+            valueFormatter={(v) => formatBytes(v)}
+            domainMax={sample.memTotalBytes}
+          />
+          <HistoryChart
+            title="磁盘走势"
+            data={history.map((s) => ({
+              at: Date.parse(s.timestamp),
+              value: s.diskUsedBytes,
+            }))}
+            tickFormatter={(v) => formatBytes(v)}
+            valueFormatter={(v) => formatBytes(v)}
+          />
+        </div>
+      )}
       <p className="text-xs text-muted-foreground">
         单次快照,5 秒刷新;本次读数取自 {since(sample.timestamp)}前。
+        {history.length >= 2 &&
+          `走势为本面板打开以来的采样(最多约 ${Math.round((HISTORY_CAP * 5) / 60)} 分钟),daemon 不存历史。`}
       </p>
     </div>
   );
diff --git a/packages/console/src/features/sandboxes/envd-client.ts b/packages/console/src/features/sandboxes/envd-client.ts
index b647303..99e71cb 100644
--- a/packages/console/src/features/sandboxes/envd-client.ts
+++ b/packages/console/src/features/sandboxes/envd-client.ts
@@ -93,6 +93,35 @@ export const moveEntry = (
 export const removeEntry = (auth: EnvdAuth, path: string) =>
   unary<Record<string, never>>(auth, 'filesystem.Filesystem/Remove', { path });
 
+// ---- 目录监听(轮询三动词:create → drain → remove)------------------------
+//
+// 与官方 SDK 的流式 WatchDir 同一张水源,轮询形态对浏览器更顺:没有长连
+// 接要养,GetWatcherEvents 一次拿走积压(drained means drained),404 =
+// 监听器随容器一起没了(冻结/重建都会),调用方重建一个就是。
+
+export interface EnvdWatchEvent {
+  name: string;
+  type: string;
+}
+
+export const createWatcher = (auth: EnvdAuth, path: string) =>
+  unary<{ watcherId: string }>(auth, 'filesystem.Filesystem/CreateWatcher', {
+    path,
+  }).then((r) => r.watcherId);
+
+/** 只读不唤醒(与 Process/List 同一原则):挂着监听不养沙箱的体温。 */
+export const getWatcherEvents = (auth: EnvdAuth, watcherId: string) =>
+  unary<{ events?: EnvdWatchEvent[] }>(
+    auth,
+    'filesystem.Filesystem/GetWatcherEvents',
+    { watcherId },
+  ).then((r) => r.events ?? []);
+
+export const removeWatcher = (auth: EnvdAuth, watcherId: string) =>
+  unary<Record<string, never>>(auth, 'filesystem.Filesystem/RemoveWatcher', {
+    watcherId,
+  });
+
 // ---- 文件本体进出(纯 HTTP 面,流式无大小上限)---------------------------
 
 /** 下载整个文件为 Blob,交给浏览器落盘。 */
diff --git a/packages/console/src/features/sandboxes/format.ts b/packages/console/src/features/sandboxes/format.ts
index 8c65028..065bdee 100644
--- a/packages/console/src/features/sandboxes/format.ts
+++ b/packages/console/src/features/sandboxes/format.ts
@@ -48,6 +48,47 @@ export function since(iso: string): string {
   return formatDuration((Date.now() - Date.parse(iso)) / 1000);
 }
 
+/**
+ * 沙箱的下一步降温:与 daemon 扫描器同一套语义 — 空闲时长从
+ * lastActiveAt 起算,按当前状态取对应旋钮,一次只降一档。旋钮为 null
+ * 表示这一档永不发生(常驻);active 的冻结旋钮不可为 null。到点未动
+ * 是正常态(等下一轮扫描),remainingSeconds 为 0 而不是负数。
+ * archived/restoring 没有下一步,返回 null。
+ */
+export function nextLifecycleStep(
+  sandbox: Pick<Sandbox, 'state' | 'lastActiveAt' | 'policy'>,
+  nowMs: number,
+): {
+  action: '冻结' | '停止' | '归档';
+  remainingSeconds: number | null;
+} | null {
+  const idle = (nowMs - Date.parse(sandbox.lastActiveAt)) / 1000;
+  const remaining = (threshold: number) => Math.max(0, threshold - idle);
+  switch (sandbox.state) {
+    case 'active':
+      return {
+        action: '冻结',
+        remainingSeconds: remaining(sandbox.policy.freezeAfterSeconds),
+      };
+    case 'frozen':
+      return sandbox.policy.stopAfterSeconds === null
+        ? { action: '停止', remainingSeconds: null }
+        : {
+            action: '停止',
+            remainingSeconds: remaining(sandbox.policy.stopAfterSeconds),
+          };
+    case 'stopped':
+      return sandbox.policy.archiveAfterSeconds === null
+        ? { action: '归档', remainingSeconds: null }
+        : {
+            action: '归档',
+            remainingSeconds: remaining(sandbox.policy.archiveAfterSeconds),
+          };
+    default:
+      return null;
+  }
+}
+
 /** 一个旋钮的文字形:"冻结 5分钟" / "停止 永不"。 */
 export function policyStep(label: string, seconds: number | null): string {
   return seconds === null
diff --git a/packages/console/src/features/sandboxes/hooks/useEnvd.ts b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
index 1e98e1d..b7cde65 100644
--- a/packages/console/src/features/sandboxes/hooks/useEnvd.ts
+++ b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
@@ -1,14 +1,18 @@
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useEffect, useRef } from 'react';
 import { mintEnvdToken } from '@/lib/api';
 import {
+  createWatcher,
   downloadFile,
   type EnvdAuth,
+  getWatcherEvents,
   killProcess,
   listDir,
   listProcesses,
   makeDir,
   moveEntry,
   removeEntry,
+  removeWatcher,
   uploadFile,
 } from '../envd-client';
 
@@ -97,6 +101,77 @@ export function useFileMutations(auth: EnvdAuth | undefined) {
   return { mkdir, move, remove, upload, download };
 }
 
+/**
+ * 当前目录的实时刷新:envd 的轮询三动词(CreateWatcher → GetWatcherEvents
+ * → RemoveWatcher),沙箱里(agent、终端)动了文件,面板 2 秒内自己跟上。
+ *
+ * 唤醒纪律是这个 hook 的全部难点:GetWatcherEvents 不唤醒(读 daemon
+ * 内存,冻结沙箱的盘也不会变),可以放心轮询;但 Create/Remove 都要容器
+ * 活着(容器里有个 inotifywait 要起/停)— 所以**只在沙箱 active 时武装
+ * 或拆除**。沙箱睡了就让监听器随容器一起消亡(404 是预期收场),等它下
+ * 次因真实使用而醒来再重新武装;绝不为"接着看"或"收拾干净"把沙箱吵醒。
+ * active 走 ref:降温/回暖不重跑 effect,轮询循环自己看当下的状态。
+ */
+export function useDirectoryWatch(
+  auth: EnvdAuth | undefined,
+  path: string,
+  opts: { enabled: boolean; active: boolean },
+) {
+  const queryClient = useQueryClient();
+  const activeRef = useRef(opts.active);
+  activeRef.current = opts.active;
+
+  useEffect(() => {
+    if (!opts.enabled || !auth) return;
+    let watcherId: string | null = null;
+    let busy = false;
+
+    const arm = async () => {
+      if (!activeRef.current) return; // 冻结/停止:武装会唤醒,等真实使用
+      try {
+        watcherId = await createWatcher(auth, path);
+      } catch {
+        watcherId = null; // 冷启动窗口或目录暂不可达;下一拍再试
+      }
+    };
+
+    void arm();
+    const timer = setInterval(() => {
+      if (busy) return;
+      busy = true;
+      void (async () => {
+        if (watcherId === null) {
+          await arm();
+          return;
+        }
+        try {
+          const events = await getWatcherEvents(auth, watcherId);
+          if (events.length > 0) {
+            void queryClient.invalidateQueries({
+              queryKey: ['envdDir', auth.sandboxId, path],
+            });
+          }
+        } catch {
+          // 404:监听器随容器没了(停止/重建)。回到未武装态,由 arm
+          // 的 active 闸决定何时重来 — 绝不在这里直接重建。
+          watcherId = null;
+        }
+      })().finally(() => {
+        busy = false;
+      });
+    }, 2000);
+
+    return () => {
+      clearInterval(timer);
+      // 只有沙箱还醒着才顺手拆(RemoveWatcher 要容器活着);睡了就留给
+      // 容器回收 — 一个 inotifywait 活不过下一次停止。
+      if (watcherId !== null && activeRef.current) {
+        void removeWatcher(auth, watcherId).catch(() => undefined);
+      }
+    };
+  }, [auth, path, opts.enabled, queryClient]);
+}
+
 /**
  * 进程表。List 在服务端刻意不唤醒(读 daemon 内存),所以这里可以放心
  * 轮询;只在沙箱有物理容器时开启(active/frozen),停机沙箱没有进程表。
diff --git a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
index 3dcd2d1..f80d016 100644
--- a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
+++ b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
@@ -4,6 +4,7 @@ import {
   acquireSandbox,
   getSandboxMetrics,
   listSandboxes,
+  listSandboxMetrics,
   rebuildSandbox,
   releaseSandbox,
   setPolicy,
@@ -47,6 +48,21 @@ export function useSandboxMetrics(userKey: string) {
   });
 }
 
+/**
+ * 全部可测沙箱的资源快照,一个请求管一整张表(逐行发 getSandboxMetrics
+ * 是 N 倍浪费)。答案里没出现 = 没有容器可测(停止/归档),不是 0。
+ * 5 秒一拍与列表的 2 秒分开定:daemon 侧一次 docker stats 读数约一秒,
+ * 这口锅比读 SQLite 贵。只在列表页挂载时跑,页面一关轮询即停。
+ */
+export function useFleetMetrics() {
+  return useQuery({
+    queryKey: ['fleet-metrics'],
+    queryFn: listSandboxMetrics,
+    refetchInterval: 5000,
+    retry: false,
+  });
+}
+
 export function useAcquireSandbox() {
   const queryClient = useQueryClient();
   return useMutation({
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index 071b033..6c68b59 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -18,6 +18,7 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { EditPolicyDialog } from '../components/EditPolicyDialog';
 import { FilesPanel } from '../components/FilesPanel';
 import { HistoryPanel } from '../components/HistoryPanel';
+import { LifecycleCountdown } from '../components/LifecycleCountdown';
 import { MetricsPanel } from '../components/MetricsPanel';
 import { ProcessesPanel } from '../components/ProcessesPanel';
 import { RebuildSandboxButton } from '../components/RebuildSandboxButton';
@@ -88,6 +89,7 @@ export function SandboxDetailPage() {
         <div className="flex items-center gap-3">
           <h1 className="font-mono text-lg font-semibold">{sandbox.userKey}</h1>
           <SandboxStateBadge state={sandbox.state} />
+          <LifecycleCountdown sandbox={sandbox} />
         </div>
         <div className="flex items-center gap-2">
           <EditPolicyDialog sandbox={sandbox} />
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index 08410f1..2e7b98f 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -49,12 +49,14 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { releaseSandbox } from '@/lib/api';
+import { formatBytes, pctOf } from '@/lib/format';
 import { queryClient } from '@/lib/queryClient';
+import { cn } from '@/lib/utils';
 import { CreateSandboxDialog } from '../components/CreateSandboxDialog';
 import { ReleaseSandboxButton } from '../components/ReleaseSandboxButton';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
 import { policyLine, STATE_LABELS, since } from '../format';
-import { useSandboxes } from '../hooks/useSandboxes';
+import { useFleetMetrics, useSandboxes } from '../hooks/useSandboxes';
 
 const STATE_FILTERS: Array<SandboxState> = [
   'active',
@@ -68,6 +70,39 @@ const STATE_FILTERS: Array<SandboxState> = [
 type SortKey = 'userKey' | 'lastActiveAt' | 'createdAt';
 type Sort = { key: SortKey; dir: 1 | -1 };
 
+/**
+ * 资源列的一格:数值紧凑,细节挂 hover;占比过线换警示色,和指标 tab
+ * 的 Meter 同一套阈值。value 为 null = 这行没被测到(没有容器可测)。
+ */
+function UsageCell({
+  value,
+  pct,
+  title,
+}: {
+  value: string | null;
+  pct: number;
+  title?: string;
+}) {
+  if (value === null) {
+    return <TableCell className="text-muted-foreground">—</TableCell>;
+  }
+  return (
+    <TableCell
+      className={cn(
+        'tabular-nums',
+        pct >= 90
+          ? 'text-red-600 dark:text-red-400'
+          : pct >= 75
+            ? 'text-amber-600 dark:text-amber-400'
+            : 'text-muted-foreground',
+      )}
+      title={title}
+    >
+      {value}
+    </TableCell>
+  );
+}
+
 /**
  * 表头的排序按钮:点一下升序,再点反向。"空闲最久的是谁"不该靠肉眼
  * 扫一张会自己刷新的表。
@@ -166,6 +201,13 @@ function BulkReleaseButton({
 export function SandboxesPage() {
   const query = useSandboxes();
   const sandboxes = query.data?.sandboxes ?? [];
+  // 资源快照批量拉(一个请求管全表);读不到就整列出 —,不挡列表本身。
+  const fleet = useFleetMetrics();
+  const metricsOf = useMemo(
+    () =>
+      new Map((fleet.data?.samples ?? []).map((s) => [s.userKey, s.sample])),
+    [fleet.data],
+  );
   const [search, setSearch] = useState('');
   const [stateFilter, setStateFilter] = useState<'all' | SandboxState>('all');
   const [selected, setSelected] = useState<Set<string>>(new Set());
@@ -314,6 +356,9 @@ export function SandboxesPage() {
                 </TableHead>
                 <TableHead>状态</TableHead>
                 <TableHead>模板</TableHead>
+                <TableHead>CPU</TableHead>
+                <TableHead>内存</TableHead>
+                <TableHead>磁盘</TableHead>
                 <TableHead>
                   {/* 升序 = 最久没动的排最前:回收磁盘时先看这里。 */}
                   <SortableHead
@@ -366,6 +411,37 @@ export function SandboxesPage() {
                   <TableCell className="text-muted-foreground">
                     {sandbox.template ?? '基础镜像'}
                   </TableCell>
+                  {(() => {
+                    const m = metricsOf.get(sandbox.userKey);
+                    if (!m) {
+                      return (
+                        <>
+                          <UsageCell value={null} pct={0} />
+                          <UsageCell value={null} pct={0} />
+                          <UsageCell value={null} pct={0} />
+                        </>
+                      );
+                    }
+                    return (
+                      <>
+                        <UsageCell
+                          value={`${Math.round(m.cpuUsedPct)}%`}
+                          pct={m.cpuUsedPct / m.cpuCount}
+                          title={`${m.cpuCount} 核 · 百分比按单核计`}
+                        />
+                        <UsageCell
+                          value={formatBytes(m.memUsedBytes)}
+                          pct={pctOf(m.memUsedBytes, m.memTotalBytes)}
+                          title={`共 ${formatBytes(m.memTotalBytes)}`}
+                        />
+                        <UsageCell
+                          value={formatBytes(m.diskUsedBytes)}
+                          pct={pctOf(m.diskUsedBytes, m.diskTotalBytes)}
+                          title={`名义 ${formatBytes(m.diskTotalBytes)}`}
+                        />
+                      </>
+                    );
+                  })()}
                   <TableCell
                     className="tabular-nums text-muted-foreground"
                     title={`最近活动:${new Date(sandbox.lastActiveAt).toLocaleString()}`}
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 16338da..e01a51b 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -7,6 +7,7 @@ import type {
   HostMetricsResponse,
   LifecyclePolicyOverride,
   ListActivityResponse,
+  ListSandboxMetricsResponse,
   RegisterTemplateResponse,
   Sandbox,
   SetIngressResponse,
@@ -98,6 +99,11 @@ export const getHostMetrics = () => rpc<HostMetricsResponse>('/getHostMetrics');
 export const getSandboxMetrics = (userKey: string) =>
   rpc<GetSandboxMetricsResponse>('/getSandboxMetrics', { userKey });
 
+// Every measurable sandbox in one answer — the list view's food. Presence
+// means measured: colder states are simply absent.
+export const listSandboxMetrics = () =>
+  rpc<ListSandboxMetricsResponse>('/listSandboxMetrics');
+
 // The ledger's recent history, newest first — a bounded ring, not an audit
 // log. The daemon records at the moves themselves; this only reads.
 export const listActivity = (limit?: number) =>
diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index 304f06e..2797e35 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -34,6 +34,7 @@ export default defineConfig({
       '/removeTemplate': 'http://127.0.0.1:3676',
       '/getHostMetrics': 'http://127.0.0.1:3676',
       '/getSandboxMetrics': 'http://127.0.0.1:3676',
+      '/listSandboxMetrics': 'http://127.0.0.1:3676',
       '/listActivity': 'http://127.0.0.1:3676',
       '/getConfig': 'http://127.0.0.1:3676',
       '/getIngress': 'http://127.0.0.1:3676',
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index fae421e..62cccf1 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -384,6 +384,22 @@ describe('the observability verbs over real HTTP', () => {
     });
   });
 
+  it('listSandboxMetrics answers every measurable sandbox in one call', async () => {
+    await client.acquireSandbox('fleet-a');
+    await client.acquireSandbox('fleet-b');
+    const samples = await client.listSandboxMetrics();
+    const mine = samples.filter((s) => s.userKey.startsWith('fleet-'));
+    expect(mine.map((s) => s.userKey).sort()).toEqual(['fleet-a', 'fleet-b']);
+    for (const entry of mine) {
+      expect(entry.sample.memTotalBytes).toBeGreaterThan(0);
+    }
+    await client.releaseSandbox('fleet-a');
+    await client.releaseSandbox('fleet-b');
+    // Released means gone from the measurable set, not null-stuffed.
+    const after = await client.listSandboxMetrics();
+    expect(after.filter((s) => s.userKey.startsWith('fleet-'))).toEqual([]);
+  });
+
   it('listActivity tells the story just written, newest first', async () => {
     await client.acquireSandbox('story-sdk');
     await client.releaseSandbox('story-sdk');
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index b0a80f6..d952ef7 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -13,8 +13,10 @@ import {
   type HostMetricsResponse,
   hostMetricsResponseSchema,
   type LifecyclePolicyOverride,
+  type ListSandboxMetricsResponse,
   listActivityResponseSchema,
   listSandboxesResponseSchema,
+  listSandboxMetricsResponseSchema,
   listTemplatesResponseSchema,
   type RebuildSandboxResponse,
   type RegisterTemplateResponse,
@@ -167,6 +169,17 @@ export class Dormice {
     return getSandboxMetricsResponseSchema.parse(data).sample;
   }
 
+  /**
+   * Every measurable sandbox's reading in one answer — a view over N
+   * sandboxes costs one request instead of N. Presence means measured:
+   * only physically running/paused sandboxes appear; colder states are
+   * absent (getSandboxMetrics's null, expressed as absence).
+   */
+  async listSandboxMetrics(): Promise<ListSandboxMetricsResponse['samples']> {
+    const data = await this.rpc('listSandboxMetrics', {});
+    return listSandboxMetricsResponseSchema.parse(data).samples;
+  }
+
   /**
    * The daemon's recent history, newest first: who was created, cooled,
    * woken, destroyed, and what reconciliation repaired. A bounded ring —
diff --git a/packages/server/src/routes/observability.test.ts b/packages/server/src/routes/observability.test.ts
index 31c105c..c12f2b2 100644
--- a/packages/server/src/routes/observability.test.ts
+++ b/packages/server/src/routes/observability.test.ts
@@ -8,6 +8,7 @@ import {
   getConfigResponseSchema,
   getSandboxMetricsResponseSchema,
   listActivityResponseSchema,
+  listSandboxMetricsResponseSchema,
 } from '@dormice/shared';
 import { count } from 'drizzle-orm';
 import { describe, expect, it } from 'vitest';
@@ -272,3 +273,62 @@ describe('getSandboxMetrics', () => {
     expect(res.statusCode).toBe(404);
   });
 });
+
+describe('listSandboxMetrics', () => {
+  it('measures active and frozen sandboxes; colder states are absent', async () => {
+    const { app, db, executor } = testApp();
+    await rpc(app, '/acquireSandbox', { userKey: 'hot' });
+    const frozen = await rpc(app, '/acquireSandbox', { userKey: 'napping' });
+    await freezeSandbox(db, executor, frozen.json().sandbox.sandboxId);
+    const cold = await rpc(app, '/acquireSandbox', { userKey: 'cold' });
+    const coldId = cold.json().sandbox.sandboxId;
+    await freezeSandbox(db, executor, coldId);
+    await stopSandbox(db, executor, coldId);
+
+    const res = await rpc(app, '/listSandboxMetrics', {});
+    expect(res.statusCode).toBe(200);
+    const { samples } = listSandboxMetricsResponseSchema.parse(res.json());
+    const keys = samples.map((s) => s.userKey).sort();
+    // The frozen sandbox is measured as it sleeps; the stopped one has no
+    // container to measure and is honestly absent, not null-stuffed.
+    expect(keys).toEqual(['hot', 'napping']);
+    for (const entry of samples) {
+      expect(entry.sample.memTotalBytes).toBeGreaterThan(0);
+      expect(entry.sample.diskTotalBytes).toBeGreaterThan(0);
+    }
+    // Observation is not activity: nobody woke or cooled further.
+    const { sandboxes } = (await rpc(app, '/listSandboxes')).json();
+    const byKey = new Map<string, string>(
+      sandboxes.map((s: { userKey: string; state: string }) => [
+        s.userKey,
+        s.state,
+      ]),
+    );
+    expect(byKey.get('napping')).toBe('frozen');
+    expect(byKey.get('cold')).toBe('stopped');
+  });
+
+  it('skips a sandbox whose container vanished instead of failing the sweep', async () => {
+    const { app, executor } = testApp();
+    await rpc(app, '/acquireSandbox', { userKey: 'alive' });
+    const doomed = await rpc(app, '/acquireSandbox', { userKey: 'doomed' });
+    // The container dies physically, past the ledger (gVisor OOM does this
+    // for real) — the row still says active, the reading throws, the sweep
+    // reports what it could see.
+    const doomedId = doomed.json().sandbox.sandboxId;
+    await executor.freeze(doomedId);
+    await executor.stop(doomedId);
+
+    const res = await rpc(app, '/listSandboxMetrics', {});
+    const { samples } = listSandboxMetricsResponseSchema.parse(res.json());
+    expect(samples.map((s) => s.userKey)).toEqual(['alive']);
+  });
+
+  it('answers an empty list on an empty ledger', async () => {
+    const { app } = testApp();
+    const res = await rpc(app, '/listSandboxMetrics', {});
+    expect(listSandboxMetricsResponseSchema.parse(res.json()).samples).toEqual(
+      [],
+    );
+  });
+});
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index 0ae22a1..3ac58a5 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -9,6 +9,8 @@ import {
   type LifecyclePolicy,
   lifecyclePolicySchema,
   listSandboxesResponseSchema,
+  listSandboxMetricsRequestSchema,
+  listSandboxMetricsResponseSchema,
   readFileRequestSchema,
   readFileResponseSchema,
   rebuildSandboxRequestSchema,
@@ -318,6 +320,42 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     },
   );
 
+  // Every measurable sandbox in one answer: the list view's food. Readings
+  // run in parallel because one docker-stats sample costs about a second —
+  // serial would scale the answer with the fleet. Presence means measured:
+  // colder states are absent (same honesty as getSandboxMetrics's null),
+  // and a container that vanishes mid-reading is skipped, not invented —
+  // any code must expect containers to disappear at any moment.
+  app.post(
+    '/listSandboxMetrics',
+    {
+      schema: {
+        body: listSandboxMetricsRequestSchema,
+        response: { 200: listSandboxMetricsResponseSchema },
+      },
+    },
+    async () => {
+      const rows = listSandboxes(db).filter(
+        (row) => row.state === 'active' || row.state === 'frozen',
+      );
+      const samples = await Promise.all(
+        rows.map(async (row) => {
+          try {
+            const m = await executor.metrics(row.sandboxId);
+            return {
+              userKey: row.userKey,
+              sandboxId: row.sandboxId,
+              sample: { timestamp: new Date().toISOString(), ...m },
+            };
+          } catch {
+            return null;
+          }
+        }),
+      );
+      return { samples: samples.filter((s) => s !== null) };
+    },
+  );
+
   app.post(
     '/execCommand',
     {
diff --git a/packages/shared/src/metrics.ts b/packages/shared/src/metrics.ts
index c12c5e0..a0266dd 100644
--- a/packages/shared/src/metrics.ts
+++ b/packages/shared/src/metrics.ts
@@ -42,3 +42,30 @@ export const getSandboxMetricsResponseSchema = z.object({
 export type GetSandboxMetricsResponse = z.infer<
   typeof getSandboxMetricsResponseSchema
 >;
+
+/**
+ * listSandboxMetrics() — every measurable sandbox in one answer, so a list
+ * view showing N sandboxes costs one request instead of N. Presence means
+ * measured: only physically running/paused sandboxes appear (the same
+ * honesty as getSandboxMetrics's null, expressed as absence), and a
+ * container that vanishes mid-reading is skipped rather than invented.
+ */
+export const listSandboxMetricsRequestSchema = z.object({});
+
+export type ListSandboxMetricsRequest = z.infer<
+  typeof listSandboxMetricsRequestSchema
+>;
+
+export const listSandboxMetricsResponseSchema = z.object({
+  samples: z.array(
+    z.object({
+      userKey: z.string(),
+      sandboxId: z.string(),
+      sample: sandboxMetricsSampleSchema,
+    }),
+  ),
+});
+
+export type ListSandboxMetricsResponse = z.infer<
+  typeof listSandboxMetricsResponseSchema
+>;

From ebd40641de967235caa33fa2f608b48c5f8ea9ce Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Mon, 13 Jul 2026 02:54:05 +0800
Subject: [PATCH 063/133] =?UTF-8?q?The=20sidebar=20learns=20the=20openasi?=
 =?UTF-8?q?=20look:=20inset=20floating=20card,=20pill=20nav,=20plain=20wor?=
 =?UTF-8?q?dmark=20=E2=80=94=20and=20the=20top-bar=20separator=20finally?=
 =?UTF-8?q?=20sits=20centered?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/console/src/components/AppShell.tsx  |  6 ++++-
 .../console/src/components/AppSidebar.tsx     | 27 +++++++++----------
 2 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/packages/console/src/components/AppShell.tsx b/packages/console/src/components/AppShell.tsx
index 89a9971..026c48f 100644
--- a/packages/console/src/components/AppShell.tsx
+++ b/packages/console/src/components/AppShell.tsx
@@ -51,7 +51,11 @@ export function AppShell() {
       <SidebarInset>
         <header className="flex h-14 shrink-0 items-center gap-2 border-b px-4">
           <SidebarTrigger className="-ml-1" />
-          <Separator orientation="vertical" className="mr-2 !h-4" />
+          {/* 组件自带 data-vertical:self-stretch,限高后会钉在顶栏上沿 — 压回居中。 */}
+          <Separator
+            orientation="vertical"
+            className="mr-2 !h-4 !self-center"
+          />
           <Breadcrumb>
             <BreadcrumbList>
               {crumbs.map((crumb, index) => (
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index 46f7fa5..11c7008 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -72,6 +72,9 @@ async function signOut() {
   window.location.href = '/console/login';
 }
 
+// 侧栏按钮统一药丸形 + medium 字重(风格参考 openasi 侧栏,2026-07-12)。
+const menuButtonClass = 'rounded-full font-medium';
+
 function isActivePath(pathname: string, to: string): boolean {
   if (to === '/') return pathname === '/';
   return pathname === to || pathname.startsWith(`${to}/`);
@@ -84,21 +87,13 @@ export function AppSidebar() {
   const { resolvedTheme, setTheme } = useTheme();
 
   return (
-    <Sidebar>
+    <Sidebar variant="inset" className="px-1">
       <SidebarHeader>
-        <SidebarMenu>
-          <SidebarMenuItem>
-            <SidebarMenuButton size="lg" render={<Link to="/" />}>
-              <div className="flex size-8 items-center justify-center rounded-lg bg-primary text-primary-foreground">
-                <HugeiconsIcon icon={PackageIcon} className="size-4" />
-              </div>
-              <div className="grid leading-tight">
-                <span className="font-semibold">Dormice</span>
-                <span className="text-xs text-muted-foreground">控制台</span>
-              </div>
-            </SidebarMenuButton>
-          </SidebarMenuItem>
-        </SidebarMenu>
+        {/* 纯文字 wordmark:侧栏融在页面底色里,不需要图标方块撑品牌。 */}
+        <Link to="/" className="flex items-baseline gap-1.5 px-2.5 pt-2 pb-1.5">
+          <span className="text-lg font-semibold leading-none">Dormice</span>
+          <span className="text-xs text-muted-foreground">控制台</span>
+        </Link>
       </SidebarHeader>
 
       <SidebarContent>
@@ -115,6 +110,7 @@ export function AppSidebar() {
                   {items.map((item) => (
                     <SidebarMenuItem key={item.to}>
                       <SidebarMenuButton
+                        className={menuButtonClass}
                         isActive={isActivePath(pathname, item.to)}
                         render={<Link to={item.to} />}
                       >
@@ -135,6 +131,7 @@ export function AppSidebar() {
         <SidebarMenu>
           <SidebarMenuItem>
             <SidebarMenuButton
+              className={menuButtonClass}
               onClick={() =>
                 setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')
               }
@@ -147,7 +144,7 @@ export function AppSidebar() {
             </SidebarMenuButton>
           </SidebarMenuItem>
           <SidebarMenuItem>
-            <SidebarMenuButton onClick={signOut}>
+            <SidebarMenuButton className={menuButtonClass} onClick={signOut}>
               <HugeiconsIcon icon={Logout01Icon} strokeWidth={1.8} />
               <span>退出登录</span>
             </SidebarMenuButton>

From c4e6a8567cafa36ac8e558e561cbcc51d6d0ca87 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Mon, 13 Jul 2026 13:07:18 +0800
Subject: [PATCH 064/133] The console learns who you are: username/password
 login atop the token
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The API token stays the root of trust (SDK/CLI/E2B untouched); the console
grows a single human account on top. Setup presents the token — closing the
first-visitor registration race — and doubles as password change and
forgot-password, since re-presenting the token overwrites the account.
Sessions keep the stateless HMAC shape but key off a per-account secret, so
resetting the account voids every session while rotating the token no longer
logs the console out. Passwords are scrypt (node:crypto, zero deps) and the
login/setup pair shares an in-memory failure backoff — the half a
human-entropy credential must ship with.
---
 e2e/src/console.test.ts                       | 137 ++++++--
 .../src/features/auth/pages/LoginPage.tsx     | 316 ++++++++++++++----
 packages/console/src/lib/api.ts               |  31 +-
 .../server/drizzle/0005_console-account.sql   |   8 +
 .../server/drizzle/meta/0005_snapshot.json    | 277 +++++++++++++++
 packages/server/drizzle/meta/_journal.json    |   7 +
 packages/server/src/app.ts                    |  24 +-
 packages/server/src/auth.ts                   | 114 ++++++-
 packages/server/src/db/account.ts             |  51 +++
 packages/server/src/db/schema.ts              |  23 ++
 packages/server/src/login-throttle.test.ts    |  53 +++
 packages/server/src/login-throttle.ts         |  76 +++++
 packages/server/src/routes/console.test.ts    | 226 ++++++++++---
 packages/server/src/routes/console.ts         | 139 +++++++-
 14 files changed, 1322 insertions(+), 160 deletions(-)
 create mode 100644 packages/server/drizzle/0005_console-account.sql
 create mode 100644 packages/server/drizzle/meta/0005_snapshot.json
 create mode 100644 packages/server/src/db/account.ts
 create mode 100644 packages/server/src/login-throttle.test.ts
 create mode 100644 packages/server/src/login-throttle.ts

diff --git a/e2e/src/console.test.ts b/e2e/src/console.test.ts
index 654bdc7..81e84ec 100644
--- a/e2e/src/console.test.ts
+++ b/e2e/src/console.test.ts
@@ -4,24 +4,49 @@ import { describe, expect, inject, it } from 'vitest';
 // same requests a browser would make. The daemon serves packages/console/dist
 // (pnpm build ran before this suite), so this also proves the monorepo
 // path hop in main.ts survives the dist layout.
+//
+// The tests run in file order on purpose: they walk the account's real
+// story — no account, setup with the token, password logins, reset — and
+// only this file touches the account, so the other suites (Bearer-only)
+// never race it.
 
 const endpoint = () => inject('dormiceEndpoint');
 
-async function loginCookie(token: string): Promise<string> {
-  const res = await fetch(`${endpoint()}/console/auth/login`, {
+const USERNAME = 'operator';
+const PASSWORD = 'e2e console password';
+
+async function post(path: string, body: unknown, cookie?: string) {
+  return fetch(`${endpoint()}${path}`, {
     method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ token }),
+    headers: {
+      'content-type': 'application/json',
+      ...(cookie ? { cookie } : {}),
+    },
+    body: JSON.stringify(body),
   });
-  expect(res.status).toBe(200);
+}
+
+/** "name=value" from the login/setup response, what a browser would send back. */
+function cookieOf(res: Response): string {
   const setCookie = res.headers.getSetCookie();
   expect(setCookie).toHaveLength(1);
-  // "name=value; Path=/; ..." -> "name=value", what a browser would send back.
   const cookie = setCookie[0]?.split(';')[0];
-  if (!cookie) throw new Error('no session cookie in login response');
+  if (!cookie) throw new Error('no session cookie in response');
   return cookie;
 }
 
+async function listSandboxes(cookie: string, withHeader = true) {
+  return fetch(`${endpoint()}/listSandboxes`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      cookie,
+      ...(withHeader ? { 'x-dormice-console': '1' } : {}),
+    },
+    body: '{}',
+  });
+}
+
 describe('web console over a real daemon', () => {
   it('serves the built SPA at /console/, with assets under /console/', async () => {
     const res = await fetch(`${endpoint()}/console/`);
@@ -40,39 +65,95 @@ describe('web console over a real daemon', () => {
     expect(await res.text()).toContain('<title>Dormice 控制台</title>');
   });
 
-  it('rejects a login with the wrong token', async () => {
-    const res = await fetch(`${endpoint()}/console/auth/login`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ token: 'w'.repeat(64) }),
+  it('starts with no account, and login says so honestly', async () => {
+    const status = await post('/console/auth/status', {});
+    expect(await status.json()).toEqual({ accountExists: false });
+    const res = await post('/console/auth/login', {
+      username: USERNAME,
+      password: PASSWORD,
+    });
+    expect(res.status).toBe(409);
+  });
+
+  it('refuses setup with a wrong token', async () => {
+    const res = await post('/console/auth/setup', {
+      token: 'w'.repeat(64),
+      username: USERNAME,
+      password: PASSWORD,
+    });
+    expect(res.status).toBe(401);
+    expect(res.headers.getSetCookie()).toHaveLength(0);
+  });
+
+  it('setup with the API token creates the account and signs in', async () => {
+    const res = await post('/console/auth/setup', {
+      token: inject('dormiceToken'),
+      username: USERNAME,
+      password: PASSWORD,
+    });
+    expect(res.status).toBe(200);
+    const list = await listSandboxes(cookieOf(res));
+    expect(list.status).toBe(200);
+    const status = await post('/console/auth/status', {});
+    expect(await status.json()).toEqual({ accountExists: true });
+  });
+
+  it('rejects a login with the wrong password', async () => {
+    const res = await post('/console/auth/login', {
+      username: USERNAME,
+      password: 'not the password',
     });
     expect(res.status).toBe(401);
     expect(res.headers.getSetCookie()).toHaveLength(0);
   });
 
   it('login yields a session cookie that opens the native API', async () => {
-    const cookie = await loginCookie(inject('dormiceToken'));
-    const res = await fetch(`${endpoint()}/listSandboxes`, {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        cookie,
-        'x-dormice-console': '1',
-      },
-      body: '{}',
+    const res = await post('/console/auth/login', {
+      username: USERNAME,
+      password: PASSWORD,
     });
     expect(res.status).toBe(200);
-    const body = (await res.json()) as { sandboxes: unknown[] };
+    const list = await listSandboxes(cookieOf(res));
+    expect(list.status).toBe(200);
+    const body = (await list.json()) as { sandboxes: unknown[] };
     expect(Array.isArray(body.sandboxes)).toBe(true);
   });
 
   it('the cookie without the console header stays locked out', async () => {
-    const cookie = await loginCookie(inject('dormiceToken'));
-    const res = await fetch(`${endpoint()}/listSandboxes`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json', cookie },
-      body: '{}',
+    const res = await post('/console/auth/login', {
+      username: USERNAME,
+      password: PASSWORD,
     });
-    expect(res.status).toBe(401);
+    const list = await listSandboxes(cookieOf(res), false);
+    expect(list.status).toBe(401);
+  });
+
+  it('re-setup with the token resets the account and voids old sessions', async () => {
+    const before = cookieOf(
+      await post('/console/auth/login', {
+        username: USERNAME,
+        password: PASSWORD,
+      }),
+    );
+    const reset = await post('/console/auth/setup', {
+      token: inject('dormiceToken'),
+      username: 'renamed',
+      password: 'a brand new password',
+    });
+    expect(reset.status).toBe(200);
+    // The forgot-password semantics, observed on the wire: the old session
+    // and the old password are both dead, the new pair works.
+    expect((await listSandboxes(before)).status).toBe(401);
+    const oldLogin = await post('/console/auth/login', {
+      username: USERNAME,
+      password: PASSWORD,
+    });
+    expect(oldLogin.status).toBe(401);
+    const newLogin = await post('/console/auth/login', {
+      username: 'renamed',
+      password: 'a brand new password',
+    });
+    expect(newLogin.status).toBe(200);
+    expect((await listSandboxes(cookieOf(newLogin))).status).toBe(200);
   });
 });
diff --git a/packages/console/src/features/auth/pages/LoginPage.tsx b/packages/console/src/features/auth/pages/LoginPage.tsx
index a7c8cfd..6c46514 100644
--- a/packages/console/src/features/auth/pages/LoginPage.tsx
+++ b/packages/console/src/features/auth/pages/LoginPage.tsx
@@ -1,4 +1,4 @@
-import { useMutation } from '@tanstack/react-query';
+import { useMutation, useQuery } from '@tanstack/react-query';
 import { useSearch } from '@tanstack/react-router';
 import { useState } from 'react';
 import { Button } from '@/components/ui/button';
@@ -12,78 +12,274 @@ import {
 import { Field, FieldError, FieldLabel } from '@/components/ui/field';
 import { Input } from '@/components/ui/input';
 import { Spinner } from '@/components/ui/spinner';
-import { login } from '@/lib/api';
+import { ApiError, authStatus, login, setup } from '@/lib/api';
 import { setSessionMarker } from '@/lib/session';
 
 /**
- * One field, one button. The token is posted once and comes back as an
- * httpOnly session cookie — it is never stored anywhere the page can read.
+ * One page, two forms, forked by whether the account exists. First run
+ * shows initialization (API token as proof of ownership + choose the
+ * credentials — the token requirement is what closes the "first visitor
+ * becomes admin" race); afterwards it is username + password. Re-running
+ * initialization is also the forgot-password path, hence the hint below
+ * the login form.
+ *
  * Success does a full-page jump (not a client-side navigate): the cookie is
  * brand new, and a reload guarantees every query starts from it.
  */
 export function LoginPage() {
   const { redirect } = useSearch({ from: '/login' });
-  const [token, setToken] = useState('');
-  const mutation = useMutation({
-    mutationFn: login,
-    onSuccess: () => {
-      setSessionMarker();
-      window.location.href = redirect ?? '/console/';
-    },
-  });
+  const status = useQuery({ queryKey: ['authStatus'], queryFn: authStatus });
+  // Forgot password: the same setup form, entered deliberately — the API
+  // token overwrites the account, so reset needs no flow of its own.
+  const [resetting, setResetting] = useState(false);
+
+  const enter = () => {
+    setSessionMarker();
+    window.location.href = redirect ?? '/console/';
+  };
 
   return (
     <main className="flex min-h-screen items-center justify-center p-4">
       <Card className="w-full max-w-sm">
-        <CardHeader>
-          <CardTitle className="text-2xl">Dormice</CardTitle>
-          <CardDescription>
-            粘贴 daemon 的 API token 进入控制台。
-          </CardDescription>
-        </CardHeader>
-        <CardContent>
-          <form
-            onSubmit={(event) => {
-              event.preventDefault();
-              mutation.mutate(token);
-            }}
-            className="flex flex-col gap-6"
-          >
-            <Field data-invalid={mutation.isError || undefined}>
-              <FieldLabel htmlFor="api-token">API token</FieldLabel>
-              <Input
-                id="api-token"
-                type="password"
-                autoFocus
-                value={token}
-                onChange={(event) => setToken(event.target.value)}
-                placeholder="DORMICE_API_TOKEN"
-                className="font-mono"
-                aria-invalid={mutation.isError || undefined}
-              />
-              {mutation.isError && (
-                <FieldError>{mutation.error.message}</FieldError>
-              )}
-            </Field>
-            <Button
-              type="submit"
-              disabled={token.length === 0 || mutation.isPending}
-              className="w-full"
-            >
-              {mutation.isPending && <Spinner />}
-              登录
-            </Button>
-            {!window.isSecureContext && (
-              // 明文 HTTP 下 token 在链路上裸奔 — 引导期(IP 访问)的已知
-              // 取舍,提醒但不拦:绑定域名后这行自然消失。
-              <p className="text-xs text-muted-foreground">
-                当前连接是明文 HTTP,token 在网络上不加密。建议登录后在
-                域名页绑定域名启用 HTTPS。
-              </p>
-            )}
-          </form>
-        </CardContent>
+        {status.isPending ? (
+          <CardContent className="flex justify-center py-10">
+            <Spinner />
+          </CardContent>
+        ) : status.isError ? (
+          <CardContent className="py-10 text-center text-sm text-muted-foreground">
+            无法连接 daemon：{status.error.message}
+          </CardContent>
+        ) : status.data.accountExists && !resetting ? (
+          <LoginForm onSuccess={enter} onForgot={() => setResetting(true)} />
+        ) : (
+          <SetupForm
+            onSuccess={enter}
+            onBack={resetting ? () => setResetting(false) : undefined}
+          />
+        )}
       </Card>
     </main>
   );
 }
+
+// The wire speaks English by design; the Chinese is UI copy, translated at
+// the edge — the same rule the activity page follows.
+function errorText(error: unknown, invalidCredential: string): string {
+  if (error instanceof ApiError) {
+    if (error.status === 401) return invalidCredential;
+    if (error.status === 409) return '账号尚未初始化，请刷新页面完成初始化。';
+    if (error.status === 429) {
+      const seconds = /retry in (\d+)s/.exec(error.message)?.[1];
+      return seconds
+        ? `失败次数过多，请 ${seconds} 秒后再试。`
+        : '失败次数过多，请稍后再试。';
+    }
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+function InsecureContextHint() {
+  if (window.isSecureContext) return null;
+  return (
+    // 明文 HTTP 下凭证在链路上裸奔 — 引导期(IP 访问)的已知取舍,
+    // 提醒但不拦:绑定域名后这行自然消失。
+    <p className="text-xs text-muted-foreground">
+      当前连接是明文 HTTP,凭证在网络上不加密。建议登录后在域名页绑定域名启用
+      HTTPS。
+    </p>
+  );
+}
+
+function LoginForm({
+  onSuccess,
+  onForgot,
+}: {
+  onSuccess: () => void;
+  onForgot: () => void;
+}) {
+  const [username, setUsername] = useState('');
+  const [password, setPassword] = useState('');
+  const mutation = useMutation({ mutationFn: login, onSuccess });
+
+  return (
+    <>
+      <CardHeader>
+        <CardTitle className="text-2xl">Dormice</CardTitle>
+        <CardDescription>输入账号密码进入控制台。</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            mutation.mutate({ username, password });
+          }}
+          className="flex flex-col gap-6"
+        >
+          <Field>
+            <FieldLabel htmlFor="username">用户名</FieldLabel>
+            <Input
+              id="username"
+              autoFocus
+              autoComplete="username"
+              value={username}
+              onChange={(event) => setUsername(event.target.value)}
+            />
+          </Field>
+          <Field data-invalid={mutation.isError || undefined}>
+            <FieldLabel htmlFor="password">密码</FieldLabel>
+            <Input
+              id="password"
+              type="password"
+              autoComplete="current-password"
+              value={password}
+              onChange={(event) => setPassword(event.target.value)}
+              aria-invalid={mutation.isError || undefined}
+            />
+            {mutation.isError && (
+              <FieldError>
+                {errorText(mutation.error, '用户名或密码不对。')}
+              </FieldError>
+            )}
+          </Field>
+          <Button
+            type="submit"
+            disabled={
+              username.length === 0 ||
+              password.length === 0 ||
+              mutation.isPending
+            }
+            className="w-full"
+          >
+            {mutation.isPending && <Spinner />}
+            登录
+          </Button>
+          <button
+            type="button"
+            onClick={onForgot}
+            className="text-xs text-muted-foreground underline-offset-4 hover:underline"
+          >
+            忘记密码?用 API token 重置账号
+          </button>
+          <InsecureContextHint />
+        </form>
+      </CardContent>
+    </>
+  );
+}
+
+function SetupForm({
+  onSuccess,
+  onBack,
+}: {
+  onSuccess: () => void;
+  /** Present when reached via "forgot password" — offers a way back. */
+  onBack?: () => void;
+}) {
+  const [token, setToken] = useState('');
+  const [username, setUsername] = useState('');
+  const [password, setPassword] = useState('');
+  const [confirm, setConfirm] = useState('');
+  const mutation = useMutation({ mutationFn: setup, onSuccess });
+
+  const mismatch = confirm.length > 0 && confirm !== password;
+  const tooShort = password.length > 0 && password.length < 8;
+  const ready =
+    token.length > 0 &&
+    username.trim().length > 0 &&
+    password.length >= 8 &&
+    confirm === password;
+
+  return (
+    <>
+      <CardHeader>
+        <CardTitle className="text-2xl">
+          {onBack ? '重置控制台账号' : '初始化 Dormice 控制台'}
+        </CardTitle>
+        <CardDescription>
+          {onBack
+            ? '粘贴 daemon 的 API token 证明这台机器是你的,重新设置账号密码。原账号会被覆盖,所有已登录会话立即失效。'
+            : '还没有账号。粘贴 daemon 的 API token 证明这台机器是你的,并设置之后日常登录用的账号密码。'}
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            mutation.mutate({ token, username: username.trim(), password });
+          }}
+          className="flex flex-col gap-6"
+        >
+          <Field data-invalid={mutation.isError || undefined}>
+            <FieldLabel htmlFor="api-token">API token</FieldLabel>
+            <Input
+              id="api-token"
+              type="password"
+              autoFocus
+              value={token}
+              onChange={(event) => setToken(event.target.value)}
+              placeholder="DORMICE_API_TOKEN"
+              className="font-mono"
+              aria-invalid={mutation.isError || undefined}
+            />
+            {mutation.isError && (
+              <FieldError>
+                {errorText(mutation.error, 'API token 不对。')}
+              </FieldError>
+            )}
+          </Field>
+          <Field>
+            <FieldLabel htmlFor="new-username">用户名</FieldLabel>
+            <Input
+              id="new-username"
+              autoComplete="username"
+              value={username}
+              onChange={(event) => setUsername(event.target.value)}
+            />
+          </Field>
+          <Field data-invalid={tooShort || undefined}>
+            <FieldLabel htmlFor="new-password">密码</FieldLabel>
+            <Input
+              id="new-password"
+              type="password"
+              autoComplete="new-password"
+              value={password}
+              onChange={(event) => setPassword(event.target.value)}
+              aria-invalid={tooShort || undefined}
+            />
+            {tooShort && <FieldError>密码至少 8 位。</FieldError>}
+          </Field>
+          <Field data-invalid={mismatch || undefined}>
+            <FieldLabel htmlFor="confirm-password">确认密码</FieldLabel>
+            <Input
+              id="confirm-password"
+              type="password"
+              autoComplete="new-password"
+              value={confirm}
+              onChange={(event) => setConfirm(event.target.value)}
+              aria-invalid={mismatch || undefined}
+            />
+            {mismatch && <FieldError>两次输入的密码不一致。</FieldError>}
+          </Field>
+          <Button
+            type="submit"
+            disabled={!ready || mutation.isPending}
+            className="w-full"
+          >
+            {mutation.isPending && <Spinner />}
+            {onBack ? '重置并登录' : '初始化并登录'}
+          </Button>
+          {onBack && (
+            <button
+              type="button"
+              onClick={onBack}
+              className="text-xs text-muted-foreground underline-offset-4 hover:underline"
+            >
+              返回登录
+            </button>
+          )}
+          <InsecureContextHint />
+        </form>
+      </CardContent>
+    </>
+  );
+}
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index e01a51b..fbd6756 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -75,15 +75,34 @@ async function rpc<T>(
   return res.json() as Promise<T>;
 }
 
-// Login's own 401 means "wrong token", a form error to show in place — the
-// interceptor is for sessions dying mid-flight, not for failed sign-ins.
-export const login = (token: string) =>
-  rpc<{ loggedIn: true }>(
-    '/console/auth/login',
-    { token },
+// Whether setup has happened — the login page's fork: no account yet means
+// it renders the initialization form instead of username/password.
+export const authStatus = () =>
+  rpc<{ accountExists: boolean }>(
+    '/console/auth/status',
+    {},
     { intercept401: false },
   );
 
+// First-run initialization, password change and forgot-password are all this
+// one verb: the API token is the root of trust, presenting it (re)writes the
+// single account and signs the caller in.
+export const setup = (input: {
+  token: string;
+  username: string;
+  password: string;
+}) =>
+  rpc<{ loggedIn: true }>('/console/auth/setup', input, {
+    intercept401: false,
+  });
+
+// Login's own 401 means "wrong credentials", a form error to show in place —
+// the interceptor is for sessions dying mid-flight, not for failed sign-ins.
+export const login = (input: { username: string; password: string }) =>
+  rpc<{ loggedIn: true }>('/console/auth/login', input, {
+    intercept401: false,
+  });
+
 export const logout = () =>
   rpc<{ loggedIn: false }>('/console/auth/logout', {}, { intercept401: false });
 
diff --git a/packages/server/drizzle/0005_console-account.sql b/packages/server/drizzle/0005_console-account.sql
new file mode 100644
index 0000000..88a6f98
--- /dev/null
+++ b/packages/server/drizzle/0005_console-account.sql
@@ -0,0 +1,8 @@
+CREATE TABLE `console_account` (
+	`id` integer PRIMARY KEY NOT NULL,
+	`username` text NOT NULL,
+	`password_hash` text NOT NULL,
+	`session_secret` text NOT NULL,
+	`created_at` text NOT NULL,
+	`updated_at` text NOT NULL
+);
diff --git a/packages/server/drizzle/meta/0005_snapshot.json b/packages/server/drizzle/meta/0005_snapshot.json
new file mode 100644
index 0000000..feab2df
--- /dev/null
+++ b/packages/server/drizzle/meta/0005_snapshot.json
@@ -0,0 +1,277 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "9b340170-fa6d-448d-872c-9c4c356574ae",
+  "prevId": "f54d106b-2995-448f-828a-898e1fd9f948",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "user_key": {
+          "name": "user_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "user_key": {
+          "name": "user_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_user_key_unique": {
+          "name": "sandboxes_user_key_unique",
+          "columns": [
+            "user_key"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index c88d2ed..f103e67 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -36,6 +36,13 @@
       "when": 1783744976921,
       "tag": "0004_activity-ring",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "6",
+      "when": 1783917759390,
+      "tag": "0005_console-account",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 4e0c21b..d8b691f 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -11,6 +11,7 @@ import { z } from 'zod';
 import type { Archiver } from './archive/archiver';
 import { requireApiAuth } from './auth';
 import { type Config, type ConfigSources, configSources } from './config';
+import { getConsoleAccount } from './db/account';
 import type { Db } from './db/db';
 import { registerE2bCompat } from './e2b';
 import { ProcessTable } from './e2b/process-table';
@@ -165,8 +166,17 @@ export function buildApp({
   // cookie on the native routes, the /console surface mints and clears it.
   app.register(fastifyCookie);
 
+  // Built once, used by every guarded surface. The secret getter reads the
+  // ledger per request because setup can replace the account (and void its
+  // sessions) while the daemon runs — a captured value would keep dead
+  // sessions alive until restart.
+  const apiAuth = requireApiAuth(
+    config.DORMICE_API_TOKEN,
+    () => getConsoleAccount(db)?.sessionSecret ?? null,
+  );
+
   app.register(async (api) => {
-    api.addHook('onRequest', requireApiAuth(config.DORMICE_API_TOKEN));
+    api.addHook('onRequest', apiAuth);
     await api.register(sandboxRoutes, {
       config,
       db,
@@ -186,10 +196,16 @@ export function buildApp({
     });
   });
 
-  // The web console: session endpoints (open — login carries the token
-  // itself) and the static SPA. Its API calls go through the routes above.
+  // The web console: account + session endpoints (open — setup and login
+  // carry the credentials themselves) and the static SPA. Its API calls go
+  // through the routes above.
   app.register(async (scope) => {
-    await scope.register(consoleRoutes, { config, consoleDistDir });
+    await scope.register(consoleRoutes, {
+      config,
+      db,
+      apiAuth,
+      consoleDistDir,
+    });
   });
 
   // The E2B compatibility surface lives beside the native API with its own
diff --git a/packages/server/src/auth.ts b/packages/server/src/auth.ts
index dd47190..e37cae3 100644
--- a/packages/server/src/auth.ts
+++ b/packages/server/src/auth.ts
@@ -1,6 +1,28 @@
-import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import {
+  createHash,
+  createHmac,
+  randomBytes,
+  type ScryptOptions,
+  scrypt,
+  timingSafeEqual,
+} from 'node:crypto';
 import type { onRequestAsyncHookHandler } from 'fastify';
 
+// Hand-rolled instead of util.promisify: promisify picks the overload
+// without the options argument, and the cost parameters live there.
+function scryptAsync(
+  password: string,
+  salt: Buffer,
+  keylen: number,
+  options: ScryptOptions,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    scrypt(password, salt, keylen, options, (err, key) =>
+      err ? reject(err) : resolve(key),
+    );
+  });
+}
+
 const sha256 = (value: string) => createHash('sha256').update(value).digest();
 
 /** Constant-time string comparison; both sides hashed so lengths never leak. */
@@ -8,12 +30,72 @@ export function tokensEqual(presented: string, expected: string): boolean {
   return timingSafeEqual(sha256(presented), sha256(expected));
 }
 
+/**
+ * Password hashing for the console account: scrypt (in node:crypto, zero
+ * dependencies — the whole reason it wins over bcrypt/argon2 here). The
+ * parameters ride inside the stored string, so they can change later
+ * without invalidating old hashes.
+ *
+ * N=2^14, r=8, p=1 (~16 MiB, tens of ms): the standard interactive-login
+ * cost. The online-guessing defense is the login throttle; this cost is
+ * for the offline case, a stolen ledger file.
+ */
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const SCRYPT_KEYLEN = 32;
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(16);
+  const hash = await scryptAsync(password, salt, SCRYPT_KEYLEN, {
+    N: SCRYPT_N,
+    r: SCRYPT_R,
+    p: SCRYPT_P,
+  });
+  return [
+    'scrypt',
+    SCRYPT_N,
+    SCRYPT_R,
+    SCRYPT_P,
+    salt.toString('base64'),
+    hash.toString('base64'),
+  ].join('$');
+}
+
+export async function verifyPassword(
+  password: string,
+  stored: string,
+): Promise<boolean> {
+  const [scheme, n, r, p, saltB64, hashB64] = stored.split('$');
+  if (scheme !== 'scrypt' || !n || !r || !p || !saltB64 || !hashB64) {
+    return false;
+  }
+  const expected = Buffer.from(hashB64, 'base64');
+  const actual = await scryptAsync(
+    password,
+    Buffer.from(saltB64, 'base64'),
+    expected.length,
+    { N: Number(n), r: Number(r), p: Number(p) },
+  );
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+
+/** The session-cookie HMAC key: random, stored on the account row. */
+export function mintSessionSecret(): string {
+  return randomBytes(32).toString('hex');
+}
+
 /**
  * The web console's session cookie. Stateless on purpose: the daemon is
  * crash-only, and an in-memory session table would log every operator out
  * on each restart. The value carries its own expiry and an HMAC over it —
- * the same pattern as the envd access token — so a restart changes nothing
- * and rotating the API token invalidates every session at once.
+ * the same pattern as the envd access token — so a restart changes nothing.
+ *
+ * The HMAC key is the account's sessionSecret, not the API token: the two
+ * credentials rotate independently. Re-running setup (password change or
+ * reset) regenerates the secret and voids every session — the semantics a
+ * password change should have — while rotating the API token leaves the
+ * console signed in.
  */
 export const SESSION_COOKIE = 'dormice_session';
 export const SESSION_TTL_SECONDS = 7 * 24 * 60 * 60;
@@ -26,19 +108,19 @@ export const SESSION_TTL_SECONDS = 7 * 24 * 60 * 60;
  */
 export const CONSOLE_HEADER = 'x-dormice-console';
 
-function sessionHmac(apiToken: string, expiresAtSeconds: number): string {
-  return createHmac('sha256', apiToken)
+function sessionHmac(secret: string, expiresAtSeconds: number): string {
+  return createHmac('sha256', secret)
     .update(`console-session:${expiresAtSeconds}`)
     .digest('hex');
 }
 
-export function mintSession(apiToken: string, nowMs = Date.now()): string {
+export function mintSession(secret: string, nowMs = Date.now()): string {
   const expiresAt = Math.floor(nowMs / 1000) + SESSION_TTL_SECONDS;
-  return `${expiresAt}.${sessionHmac(apiToken, expiresAt)}`;
+  return `${expiresAt}.${sessionHmac(secret, expiresAt)}`;
 }
 
 export function verifySession(
-  apiToken: string,
+  secret: string,
   value: string,
   nowMs = Date.now(),
 ): boolean {
@@ -48,7 +130,7 @@ export function verifySession(
   // The expiry is plaintext in the cookie — nothing secret to compare in
   // constant time. The HMAC comparison below is the constant-time one.
   if (!Number.isInteger(expiresAt) || expiresAt * 1000 <= nowMs) return false;
-  return tokensEqual(value.slice(dot + 1), sessionHmac(apiToken, expiresAt));
+  return tokensEqual(value.slice(dot + 1), sessionHmac(secret, expiresAt));
 }
 
 /**
@@ -57,17 +139,27 @@ export function verifySession(
  * the Bearer token (SDK, CLI, curl) and the web console's session cookie
  * (which additionally requires the console header, see above). A second
  * route surface with its own auth would be a second truth.
+ *
+ * The session secret is fetched per request, not captured at startup: setup
+ * can replace the account (and its secret) while the daemon runs, and the
+ * arbiter must judge against the current one. Null means no account exists
+ * yet — no cookie can be valid.
  */
-export function requireApiAuth(token: string): onRequestAsyncHookHandler {
+export function requireApiAuth(
+  token: string,
+  getSessionSecret: () => string | null,
+): onRequestAsyncHookHandler {
   return async (request, reply) => {
     if (tokensEqual(request.headers.authorization ?? '', `Bearer ${token}`)) {
       return;
     }
     const cookie = request.cookies?.[SESSION_COOKIE];
+    const secret = getSessionSecret();
     if (
       cookie &&
+      secret !== null &&
       request.headers[CONSOLE_HEADER] !== undefined &&
-      verifySession(token, cookie)
+      verifySession(secret, cookie)
     ) {
       return;
     }
diff --git a/packages/server/src/db/account.ts b/packages/server/src/db/account.ts
new file mode 100644
index 0000000..bdabf81
--- /dev/null
+++ b/packages/server/src/db/account.ts
@@ -0,0 +1,51 @@
+import { eq } from 'drizzle-orm';
+import type { Db } from './db';
+import { type ConsoleAccountRow, consoleAccount } from './schema';
+
+/**
+ * The console's single human account (see the schema comment for why it is
+ * a singleton). The fixed id makes setup an upsert: presenting the API
+ * token overwrites whatever is there — account creation, password change
+ * and forgot-password are all the same verb.
+ */
+const ACCOUNT_ID = 1;
+
+export function getConsoleAccount(db: Db): ConsoleAccountRow | undefined {
+  return db
+    .select()
+    .from(consoleAccount)
+    .where(eq(consoleAccount.id, ACCOUNT_ID))
+    .get();
+}
+
+export function setConsoleAccount(
+  db: Db,
+  input: { username: string; passwordHash: string; sessionSecret: string },
+): ConsoleAccountRow {
+  const now = new Date().toISOString();
+  const row: ConsoleAccountRow = {
+    id: ACCOUNT_ID,
+    username: input.username,
+    passwordHash: input.passwordHash,
+    sessionSecret: input.sessionSecret,
+    createdAt: now,
+    updatedAt: now,
+  };
+  db.insert(consoleAccount)
+    .values(row)
+    .onConflictDoUpdate({
+      target: consoleAccount.id,
+      set: {
+        username: input.username,
+        passwordHash: input.passwordHash,
+        sessionSecret: input.sessionSecret,
+        updatedAt: now,
+      },
+    })
+    .run();
+  const stored = getConsoleAccount(db);
+  if (!stored) {
+    throw new Error('console account vanished mid-setup');
+  }
+  return stored;
+}
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index 63bd95f..e45df72 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -88,3 +88,26 @@ export const activity = sqliteTable('activity', {
 });
 
 export type ActivityRow = typeof activity.$inferSelect;
+
+/**
+ * The console's one human account (the fixed id makes "at most one row" a
+ * schema fact, not a convention). The API token stays the root of trust:
+ * presenting it (re)creates this row — that IS the forgot-password path —
+ * while day-to-day console logins are username + password.
+ *
+ * sessionSecret is the HMAC key for session cookies. It lives here and not
+ * in the token so the two credentials rotate independently: re-running
+ * setup regenerates it (every session out — correct for a password reset),
+ * rotating the API token leaves console sessions alone.
+ */
+export const consoleAccount = sqliteTable('console_account', {
+  id: integer('id').primaryKey(),
+  username: text('username').notNull(),
+  /** Self-describing scrypt string: scrypt$N$r$p$<salt b64>$<hash b64>. */
+  passwordHash: text('password_hash').notNull(),
+  sessionSecret: text('session_secret').notNull(),
+  createdAt: text('created_at').notNull(),
+  updatedAt: text('updated_at').notNull(),
+});
+
+export type ConsoleAccountRow = typeof consoleAccount.$inferSelect;
diff --git a/packages/server/src/login-throttle.test.ts b/packages/server/src/login-throttle.test.ts
new file mode 100644
index 0000000..35ae249
--- /dev/null
+++ b/packages/server/src/login-throttle.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { LoginThrottle } from './login-throttle';
+
+const T0 = 1_700_000_000_000;
+
+describe('LoginThrottle', () => {
+  it('allows the free failures without any delay', () => {
+    const throttle = new LoginThrottle();
+    for (let i = 0; i < 5; i++) {
+      expect(throttle.retryAfterSeconds('ip', T0)).toBe(0);
+      throttle.recordFailure('ip', T0);
+    }
+    expect(throttle.retryAfterSeconds('ip', T0)).toBe(0);
+  });
+
+  it('backs off exponentially past the free failures, capped', () => {
+    const throttle = new LoginThrottle();
+    for (let i = 0; i < 5; i++) throttle.recordFailure('ip', T0);
+    throttle.recordFailure('ip', T0); // 6th: 1s
+    expect(throttle.retryAfterSeconds('ip', T0)).toBe(1);
+    throttle.recordFailure('ip', T0); // 7th: 2s
+    expect(throttle.retryAfterSeconds('ip', T0)).toBe(2);
+    for (let i = 0; i < 20; i++) throttle.recordFailure('ip', T0);
+    // Deep in: capped at 5 minutes, never unbounded.
+    expect(throttle.retryAfterSeconds('ip', T0)).toBe(300);
+  });
+
+  it('the delay drains with time', () => {
+    const throttle = new LoginThrottle();
+    for (let i = 0; i < 7; i++) throttle.recordFailure('ip', T0);
+    expect(throttle.retryAfterSeconds('ip', T0 + 500)).toBe(2);
+    expect(throttle.retryAfterSeconds('ip', T0 + 2_000)).toBe(0);
+  });
+
+  it('success clears the counter; keys are independent', () => {
+    const throttle = new LoginThrottle();
+    for (let i = 0; i < 8; i++) throttle.recordFailure('a', T0);
+    expect(throttle.retryAfterSeconds('a', T0)).toBeGreaterThan(0);
+    expect(throttle.retryAfterSeconds('b', T0)).toBe(0);
+    throttle.clear('a');
+    expect(throttle.retryAfterSeconds('a', T0)).toBe(0);
+  });
+
+  it('forgets idle counters after an hour', () => {
+    const throttle = new LoginThrottle();
+    for (let i = 0; i < 8; i++) throttle.recordFailure('ip', T0);
+    const later = T0 + 61 * 60 * 1000;
+    expect(throttle.retryAfterSeconds('ip', later)).toBe(0);
+    // And the slate is genuinely clean: the next failure is a free one.
+    throttle.recordFailure('ip', later);
+    expect(throttle.retryAfterSeconds('ip', later)).toBe(0);
+  });
+});
diff --git a/packages/server/src/login-throttle.ts b/packages/server/src/login-throttle.ts
new file mode 100644
index 0000000..ad060ce
--- /dev/null
+++ b/packages/server/src/login-throttle.ts
@@ -0,0 +1,76 @@
+/**
+ * Failure backoff for the console's credential endpoints. Passwords are
+ * human-chosen (low entropy, unlike the 128-bit API token), so online
+ * guessing became a real surface the moment they arrived — this is the
+ * counterpart the password design must ship with.
+ *
+ * In-memory on purpose: crash-only means a restart honestly forgets the
+ * counters, and persisting attacker state in the ledger would be a second
+ * database to babysit for no real gain. Keyed by client IP; behind the
+ * usual single reverse proxy every client shares 127.0.0.1, collapsing this
+ * into a global throttle — acceptable and arguably right for a single
+ * account (it is the account being guessed at, not the caller).
+ */
+
+/** Free attempts before delays start: typos are not attacks. */
+const FREE_FAILURES = 5;
+/** Delay doubles per failure past the free ones, capped here. */
+const MAX_DELAY_SECONDS = 300;
+/** Counters idle this long are forgotten (also the sweep horizon). */
+const FORGET_AFTER_MS = 60 * 60 * 1000;
+
+interface Entry {
+  failures: number;
+  /** Epoch ms before which further attempts are refused. */
+  blockedUntil: number;
+  lastFailureAt: number;
+}
+
+export class LoginThrottle {
+  private entries = new Map<string, Entry>();
+
+  /** Seconds the caller must still wait, or 0 when an attempt is allowed. */
+  retryAfterSeconds(key: string, nowMs = Date.now()): number {
+    const entry = this.entries.get(key);
+    if (!entry) return 0;
+    if (nowMs - entry.lastFailureAt > FORGET_AFTER_MS) {
+      this.entries.delete(key);
+      return 0;
+    }
+    return Math.max(0, Math.ceil((entry.blockedUntil - nowMs) / 1000));
+  }
+
+  recordFailure(key: string, nowMs = Date.now()): void {
+    this.sweep(nowMs);
+    const entry = this.entries.get(key) ?? {
+      failures: 0,
+      blockedUntil: 0,
+      lastFailureAt: 0,
+    };
+    entry.failures += 1;
+    entry.lastFailureAt = nowMs;
+    const past = entry.failures - FREE_FAILURES;
+    if (past > 0) {
+      const delay = Math.min(2 ** (past - 1), MAX_DELAY_SECONDS);
+      entry.blockedUntil = nowMs + delay * 1000;
+    }
+    this.entries.set(key, entry);
+  }
+
+  clear(key: string): void {
+    this.entries.delete(key);
+  }
+
+  /**
+   * Drops idle counters on the write path — no timer to manage, and the map
+   * stays bounded by "distinct keys failing within the last hour", which a
+   * loopback-bound daemon can always afford.
+   */
+  private sweep(nowMs: number): void {
+    for (const [key, entry] of this.entries) {
+      if (nowMs - entry.lastFailureAt > FORGET_AFTER_MS) {
+        this.entries.delete(key);
+      }
+    }
+  }
+}
diff --git a/packages/server/src/routes/console.test.ts b/packages/server/src/routes/console.test.ts
index 4fbe8a1..78c98ca 100644
--- a/packages/server/src/routes/console.test.ts
+++ b/packages/server/src/routes/console.test.ts
@@ -6,9 +6,12 @@ import { describe, expect, it } from 'vitest';
 import { buildApp } from '../app';
 import {
   CONSOLE_HEADER,
+  hashPassword,
   mintSession,
+  mintSessionSecret,
   SESSION_COOKIE,
   SESSION_TTL_SECONDS,
+  verifyPassword,
   verifySession,
 } from '../auth';
 import { loadConfig } from '../config';
@@ -19,6 +22,8 @@ import { KeyedQueue } from '../keyed-queue';
 
 const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
 const TOKEN = 'test-token-test-token-test-token';
+const USERNAME = 'operator';
+const PASSWORD = 'correct horse battery';
 
 function testApp(consoleDistDir?: string) {
   const db = openDb(':memory:');
@@ -37,6 +42,8 @@ function testApp(consoleDistDir?: string) {
   });
 }
 
+type TestApp = ReturnType<typeof testApp>;
+
 /** A minimal built console: an index.html and one hashed asset. */
 function fixtureDist(): string {
   const dir = mkdtempSync(join(tmpdir(), 'dormice-consoledist-'));
@@ -46,11 +53,25 @@ function fixtureDist(): string {
   return dir;
 }
 
-async function login(app: ReturnType<typeof testApp>, token = TOKEN) {
+async function setup(
+  app: TestApp,
+  { token = TOKEN, username = USERNAME, password = PASSWORD } = {},
+) {
+  return app.inject({
+    method: 'POST',
+    url: '/console/auth/setup',
+    payload: { token, username, password },
+  });
+}
+
+async function login(
+  app: TestApp,
+  { username = USERNAME, password = PASSWORD } = {},
+) {
   return app.inject({
     method: 'POST',
     url: '/console/auth/login',
-    payload: { token },
+    payload: { username, password },
   });
 }
 
@@ -61,68 +82,186 @@ function sessionCookie(res: { cookies: Array<Record<string, unknown>> }) {
   return cookie as { value: string } & Record<string, unknown>;
 }
 
+describe('password hashing', () => {
+  it('round-trips and rejects a wrong password', async () => {
+    const stored = await hashPassword(PASSWORD);
+    expect(stored.startsWith('scrypt$')).toBe(true);
+    expect(await verifyPassword(PASSWORD, stored)).toBe(true);
+    expect(await verifyPassword('not the password', stored)).toBe(false);
+  });
+
+  it('salts: two hashes of the same password differ', async () => {
+    expect(await hashPassword(PASSWORD)).not.toBe(await hashPassword(PASSWORD));
+  });
+
+  it('rejects garbage stored values instead of throwing', async () => {
+    expect(await verifyPassword(PASSWORD, '')).toBe(false);
+    expect(await verifyPassword(PASSWORD, 'bcrypt$whatever')).toBe(false);
+  });
+});
+
 describe('session mint/verify', () => {
+  const SECRET = mintSessionSecret();
+
   it('round-trips a fresh session', () => {
-    expect(verifySession(TOKEN, mintSession(TOKEN))).toBe(true);
+    expect(verifySession(SECRET, mintSession(SECRET))).toBe(true);
   });
 
   it('rejects an expired session', () => {
     const past = Date.now() - (SESSION_TTL_SECONDS + 10) * 1000;
-    expect(verifySession(TOKEN, mintSession(TOKEN, past))).toBe(false);
+    expect(verifySession(SECRET, mintSession(SECRET, past))).toBe(false);
   });
 
   it('rejects a tampered expiry: the HMAC covers it', () => {
-    const value = mintSession(TOKEN);
+    const value = mintSession(SECRET);
     const [exp, mac] = value.split('.');
     const later = `${Number(exp) + 3600}.${mac}`;
-    expect(verifySession(TOKEN, later)).toBe(false);
+    expect(verifySession(SECRET, later)).toBe(false);
   });
 
-  it('rejects garbage and sessions minted under another token', () => {
-    expect(verifySession(TOKEN, 'not-a-session')).toBe(false);
-    expect(verifySession(TOKEN, '')).toBe(false);
-    expect(
-      verifySession(TOKEN, mintSession('other-token-other-token-other-tk')),
-    ).toBe(false);
+  it('rejects garbage and sessions minted under another secret', () => {
+    expect(verifySession(SECRET, 'not-a-session')).toBe(false);
+    expect(verifySession(SECRET, '')).toBe(false);
+    expect(verifySession(SECRET, mintSession(mintSessionSecret()))).toBe(false);
   });
 });
 
-describe('POST /console/auth/login', () => {
-  it('rejects a wrong token without setting a cookie', async () => {
-    const res = await login(testApp(), 'wrong-token-wrong-token-wrong-tk');
+describe('POST /console/auth/status', () => {
+  it('reports whether setup has happened', async () => {
+    const app = testApp();
+    const before = await app.inject({
+      method: 'POST',
+      url: '/console/auth/status',
+      payload: {},
+    });
+    expect(before.json()).toEqual({ accountExists: false });
+    await setup(app);
+    const after = await app.inject({
+      method: 'POST',
+      url: '/console/auth/status',
+      payload: {},
+    });
+    expect(after.json()).toEqual({ accountExists: true });
+  });
+});
+
+describe('POST /console/auth/setup', () => {
+  it('rejects a wrong token without creating anything', async () => {
+    const app = testApp();
+    const res = await setup(app, { token: 'wrong-token-wrong-token-wrong-tk' });
     expect(res.statusCode).toBe(401);
     expect(res.cookies).toHaveLength(0);
+    expect((await login(app)).statusCode).toBe(409);
   });
 
-  it('sets an httpOnly strict session cookie for the right token', async () => {
-    const res = await login(testApp());
+  it('creates the account and signs the caller in', async () => {
+    const app = testApp();
+    const res = await setup(app);
     expect(res.statusCode).toBe(200);
     const cookie = sessionCookie(res);
     expect(cookie.httpOnly).toBe(true);
     expect(cookie.sameSite).toBe('Strict');
     expect(cookie.path).toBe('/');
     expect(cookie.maxAge).toBe(SESSION_TTL_SECONDS);
-    expect(verifySession(TOKEN, cookie.value)).toBe(true);
   });
-});
 
-describe('cookie-authenticated API access', () => {
-  async function list(
-    app: ReturnType<typeof testApp>,
-    cookieValue: string,
-    headers: Record<string, string> = { [CONSOLE_HEADER]: '1' },
-  ) {
-    return app.inject({
-      method: 'POST',
-      url: '/listSandboxes',
-      cookies: { [SESSION_COOKIE]: cookieValue },
-      headers,
-      payload: {},
+  it('refuses a short password', async () => {
+    const res = await setup(testApp(), { password: 'short' });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('re-setup overwrites the account and voids old sessions', async () => {
+    const app = testApp();
+    const first = sessionCookie(await setup(app));
+    // The recovery path: the token alone resets username and password.
+    const res = await setup(app, {
+      username: 'renamed',
+      password: 'brand-new-pass',
     });
-  }
+    expect(res.statusCode).toBe(200);
+    expect((await list(app, first.value)).statusCode).toBe(401);
+    expect(
+      (await login(app, { username: 'renamed', password: 'brand-new-pass' }))
+        .statusCode,
+    ).toBe(200);
+    expect((await login(app)).statusCode).toBe(401);
+  });
+});
+
+async function list(
+  app: TestApp,
+  cookieValue: string,
+  headers: Record<string, string> = { [CONSOLE_HEADER]: '1' },
+) {
+  return app.inject({
+    method: 'POST',
+    url: '/listSandboxes',
+    cookies: { [SESSION_COOKIE]: cookieValue },
+    headers,
+    payload: {},
+  });
+}
+
+describe('POST /console/auth/login', () => {
+  it('answers 409 before setup — an honest pointer, not a guess counted', async () => {
+    const res = await login(testApp());
+    expect(res.statusCode).toBe(409);
+    expect(res.json().message).toContain('setup');
+  });
+
+  it('rejects wrong credentials without setting a cookie', async () => {
+    const app = testApp();
+    await setup(app);
+    const wrongPass = await login(app, { password: 'wrong password' });
+    expect(wrongPass.statusCode).toBe(401);
+    expect(wrongPass.cookies).toHaveLength(0);
+    const wrongUser = await login(app, { username: 'someone-else' });
+    expect(wrongUser.statusCode).toBe(401);
+  });
+
+  it('signs in with the right credentials', async () => {
+    const app = testApp();
+    await setup(app);
+    const res = await login(app);
+    expect(res.statusCode).toBe(200);
+    const cookie = sessionCookie(res);
+    expect(cookie.httpOnly).toBe(true);
+    expect(cookie.maxAge).toBe(SESSION_TTL_SECONDS);
+  });
+});
+
+describe('login throttle over the wire', () => {
+  it('backs off after repeated failures — even the right credential waits', async () => {
+    const app = testApp();
+    await setup(app);
+    for (let i = 0; i < 8; i++) {
+      const res = await login(app, { password: 'wrong password' });
+      expect([401, 429]).toContain(res.statusCode);
+    }
+    const blocked = await login(app);
+    expect(blocked.statusCode).toBe(429);
+    expect(blocked.json().message).toContain('retry in');
+    // Setup shares the same counters: guessing tokens is the same game.
+    expect((await setup(app)).statusCode).toBe(429);
+  });
 
+  it('a success clears the slate', async () => {
+    const app = testApp();
+    await setup(app);
+    for (let i = 0; i < 4; i++) {
+      await login(app, { password: 'wrong password' });
+    }
+    expect((await login(app)).statusCode).toBe(200);
+    expect((await login(app, { password: 'wrong password' })).statusCode).toBe(
+      401,
+    );
+  });
+});
+
+describe('cookie-authenticated API access', () => {
   it('a fresh session cookie opens the native API', async () => {
     const app = testApp();
+    await setup(app);
     const cookie = sessionCookie(await login(app));
     const res = await list(app, cookie.value);
     expect(res.statusCode).toBe(200);
@@ -131,24 +270,30 @@ describe('cookie-authenticated API access', () => {
 
   it('the cookie alone is not enough: the console header is required', async () => {
     const app = testApp();
+    await setup(app);
     const cookie = sessionCookie(await login(app));
     const res = await list(app, cookie.value, {});
     expect(res.statusCode).toBe(401);
   });
 
   it('rejects a tampered cookie', async () => {
-    const res = await list(testApp(), `${mintSession(TOKEN)}ff`);
+    const app = testApp();
+    await setup(app);
+    const cookie = sessionCookie(await login(app));
+    const res = await list(app, `${cookie.value}ff`);
     expect(res.statusCode).toBe(401);
   });
 
-  it('rejects an expired cookie', async () => {
-    const past = Date.now() - (SESSION_TTL_SECONDS + 10) * 1000;
-    const res = await list(testApp(), mintSession(TOKEN, past));
+  it('rejects any cookie while no account exists', async () => {
+    // A cookie minted under some secret proves nothing when the ledger has
+    // no account (e.g. the ledger was recreated).
+    const res = await list(testApp(), mintSession(mintSessionSecret()));
     expect(res.statusCode).toBe(401);
   });
 
   it('does not open the E2B surface: that has its own auth', async () => {
     const app = testApp();
+    await setup(app);
     const cookie = sessionCookie(await login(app));
     const res = await app.inject({
       method: 'GET',
@@ -162,7 +307,7 @@ describe('cookie-authenticated API access', () => {
 
 describe('POST /console/envdToken', () => {
   async function mint(
-    app: ReturnType<typeof testApp>,
+    app: TestApp,
     cookieValue: string,
     headers: Record<string, string> = { [CONSOLE_HEADER]: '1' },
   ) {
@@ -177,6 +322,7 @@ describe('POST /console/envdToken', () => {
 
   it('a session cookie mints the exact token the envd surface verifies', async () => {
     const app = testApp();
+    await setup(app);
     const cookie = sessionCookie(await login(app));
     const res = await mint(app, cookie.value);
     expect(res.statusCode).toBe(200);
@@ -188,13 +334,17 @@ describe('POST /console/envdToken', () => {
 
   it('goes through the API-wide arbiter: no console header, no token', async () => {
     const app = testApp();
+    await setup(app);
     const cookie = sessionCookie(await login(app));
     const res = await mint(app, cookie.value, {});
     expect(res.statusCode).toBe(401);
   });
 
   it('rejects a tampered cookie', async () => {
-    const res = await mint(testApp(), `${mintSession(TOKEN)}ff`);
+    const app = testApp();
+    await setup(app);
+    const cookie = sessionCookie(await login(app));
+    const res = await mint(app, `${cookie.value}ff`);
     expect(res.statusCode).toBe(401);
   });
 });
diff --git a/packages/server/src/routes/console.ts b/packages/server/src/routes/console.ts
index 0fa0c86..373226d 100644
--- a/packages/server/src/routes/console.ts
+++ b/packages/server/src/routes/console.ts
@@ -1,18 +1,27 @@
 import fastifyStatic from '@fastify/static';
+import type { FastifyReply, onRequestAsyncHookHandler } from 'fastify';
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import { z } from 'zod';
 import {
+  hashPassword,
   mintSession,
-  requireApiAuth,
+  mintSessionSecret,
   SESSION_COOKIE,
   SESSION_TTL_SECONDS,
   tokensEqual,
+  verifyPassword,
 } from '../auth';
 import type { Config } from '../config';
+import { getConsoleAccount, setConsoleAccount } from '../db/account';
+import type { Db } from '../db/db';
 import { mintEnvdToken } from '../e2b/protocol';
+import { LoginThrottle } from '../login-throttle';
 
 export interface ConsoleRoutesOptions {
   config: Config;
+  db: Db;
+  /** The API-wide auth arbiter, built once in app.ts — one truth. */
+  apiAuth: onRequestAsyncHookHandler;
   /**
    * Where the built web console lives (packages/console/dist). Injected so
    * tests point it at a fixture and embedders can omit it; absent means
@@ -29,34 +38,138 @@ const COOKIE_OPTIONS = {
   path: '/',
 } as const;
 
+const messageResponse = z.object({ message: z.string() });
+
 /**
- * The web console's own surface: session endpoints and the static SPA.
- * Everything else the console does goes through the native RPC routes with
- * the session cookie — same routes, same truth as the SDK and CLI.
+ * The web console's own surface: account + session endpoints and the static
+ * SPA. Everything else the console does goes through the native RPC routes
+ * with the session cookie — same routes, same truth as the SDK and CLI.
+ *
+ * The credential model: the API token is the root of trust (machine
+ * credential, lives in server env), the account is the human convenience
+ * derived from it. Setup requires the token and overwrites the account —
+ * first-run initialization, password change and forgot-password are all
+ * that one verb, so there is no registration race (an open "first visitor
+ * becomes admin" door on a public URL) and no recovery flow to build.
  */
 export const consoleRoutes: FastifyPluginAsyncZod<
   ConsoleRoutesOptions
-> = async (app, { config, consoleDistDir }) => {
+> = async (app, { config, db, apiAuth, consoleDistDir }) => {
+  // Per-app, not module-global: each daemon (and each test app) gets its
+  // own counters. Shared by login and setup — both are credential guesses.
+  const throttle = new LoginThrottle();
+
+  const setSessionCookie = (reply: FastifyReply, sessionSecret: string) => {
+    reply.setCookie(SESSION_COOKIE, mintSession(sessionSecret), {
+      ...COOKIE_OPTIONS,
+      // The cookie lives exactly as long as the HMAC inside it is valid.
+      maxAge: SESSION_TTL_SECONDS,
+    });
+  };
+
+  // Open by design: it answers only "is setup still pending", which the
+  // login page needs before any credential exists. An attacker learns
+  // nothing usable — completing setup requires the API token either way.
   app.post(
-    '/console/auth/login',
+    '/console/auth/status',
+    {
+      schema: {
+        response: { 200: z.object({ accountExists: z.boolean() }) },
+      },
+    },
+    async () => ({ accountExists: getConsoleAccount(db) !== undefined }),
+  );
+
+  app.post(
+    '/console/auth/setup',
     {
       schema: {
-        body: z.object({ token: z.string() }),
+        body: z.object({
+          token: z.string().min(1),
+          username: z.string().trim().min(1).max(64),
+          // Length is the only strength rule: composition rules push people
+          // toward Password1! and help nobody.
+          password: z.string().min(8).max(128),
+        }),
         response: {
           200: z.object({ loggedIn: z.literal(true) }),
-          401: z.object({ message: z.string() }),
+          401: messageResponse,
+          429: messageResponse,
         },
       },
     },
     async (request, reply) => {
+      const wait = throttle.retryAfterSeconds(request.ip);
+      if (wait > 0) {
+        return reply.code(429).send({
+          message: `too many failed attempts — retry in ${wait}s`,
+        });
+      }
       if (!tokensEqual(request.body.token, config.DORMICE_API_TOKEN)) {
+        throttle.recordFailure(request.ip);
         return reply.code(401).send({ message: 'invalid API token' });
       }
-      reply.setCookie(SESSION_COOKIE, mintSession(config.DORMICE_API_TOKEN), {
-        ...COOKIE_OPTIONS,
-        // The cookie lives exactly as long as the HMAC inside it is valid.
-        maxAge: SESSION_TTL_SECONDS,
+      throttle.clear(request.ip);
+      const account = setConsoleAccount(db, {
+        username: request.body.username,
+        passwordHash: await hashPassword(request.body.password),
+        // A fresh secret voids every existing session — the semantics a
+        // password (re)set should have.
+        sessionSecret: mintSessionSecret(),
       });
+      setSessionCookie(reply, account.sessionSecret);
+      return { loggedIn: true as const };
+    },
+  );
+
+  app.post(
+    '/console/auth/login',
+    {
+      schema: {
+        // min(1) only: the password policy is enforced where passwords are
+        // set; login must accept whatever was stored.
+        body: z.object({
+          username: z.string().min(1),
+          password: z.string().min(1),
+        }),
+        response: {
+          200: z.object({ loggedIn: z.literal(true) }),
+          401: messageResponse,
+          409: messageResponse,
+          429: messageResponse,
+        },
+      },
+    },
+    async (request, reply) => {
+      const wait = throttle.retryAfterSeconds(request.ip);
+      if (wait > 0) {
+        return reply.code(429).send({
+          message: `too many failed attempts — retry in ${wait}s`,
+        });
+      }
+      const account = getConsoleAccount(db);
+      if (!account) {
+        // Not a failed guess (nothing exists to guess at), so no throttle
+        // hit — an honest pointer to setup instead.
+        return reply.code(409).send({
+          message: 'no account exists yet — complete setup with the API token',
+        });
+      }
+      // Evaluate both factors unconditionally so a wrong username costs the
+      // same time as a wrong password.
+      const usernameOk = tokensEqual(request.body.username, account.username);
+      const passwordOk = await verifyPassword(
+        request.body.password,
+        account.passwordHash,
+      );
+      if (!usernameOk || !passwordOk) {
+        throttle.recordFailure(request.ip);
+        return reply
+          .code(401)
+          .send({ message: 'invalid username or password' });
+      }
+      throttle.clear(request.ip);
+      setSessionCookie(reply, account.sessionSecret);
       return { loggedIn: true as const };
     },
   );
@@ -84,7 +197,7 @@ export const consoleRoutes: FastifyPluginAsyncZod<
   app.post(
     '/console/envdToken',
     {
-      onRequest: requireApiAuth(config.DORMICE_API_TOKEN),
+      onRequest: apiAuth,
       schema: {
         body: z.object({ sandboxId: z.string().min(1) }),
         response: {

From 8557a54c6e8b4367cfc8fe016f02f1c1ac8f98bb Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Mon, 13 Jul 2026 13:37:55 +0800
Subject: [PATCH 065/133] The API learns to say what it means: destroySandbox,
 updatePolicy, externalId, and files in four verbs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three renames, taken while the wire can still break (npm unpublished).
releaseSandbox -> destroySandbox: a verb that erases the disk — the
sandbox's body — must not borrow the pool idiom's gentle word; release
promises the resource survives, and this one is the opposite. setPolicy ->
updatePolicy: the behavior is a patch (omitted knobs keep their stored
values), and set implies replacement. userKey -> externalId: the caller's
identifier from their own system, the SaaS external_id pattern — user
narrowed the meaning, key collided with API keys; sandboxId stays the
internal identity. The E2B extension key moves too: metadata.externalId.

The file surface grows to four verbs: writeFile is the single form of
writeFiles (same executor path, no array ceremony), and readFiles is the
batch read — all or nothing, one missing path fails the whole call, with a
48 MiB total gate mirroring the write side's body limit.

Migration 0006 renames the ledger columns, rebuilds the unique index, and
rewrites historical 'released' activity rows to 'destroyed'; verified
against a simulated legacy ledger with old data in place.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/python/test_e2b_sync.py                   |   4 +-
 e2e/src/archive.test.ts                       |  18 +-
 e2e/src/cli.test.ts                           |  12 +-
 e2e/src/e2b.test.ts                           |  18 +-
 e2e/src/native.test.ts                        |  96 ++++--
 examples/README.md                            |   4 +-
 examples/e2b-compat.mjs                       |   2 +-
 examples/native-lifecycle.mjs                 |   4 +-
 examples/resident-agent.mjs                   |   2 +-
 packages/cli/src/commands.test.ts             |  26 +-
 packages/cli/src/commands.ts                  |  44 +--
 packages/cli/src/main.ts                      |  36 +-
 packages/console/scripts/seed.mjs             |  26 +-
 packages/console/src/components/AppShell.tsx  |   2 +-
 .../console/src/components/CommandMenu.tsx    |  18 +-
 .../features/activity/hooks/useActivity.ts    |   2 +-
 .../console/src/features/activity/kinds.ts    |   4 +-
 .../features/activity/pages/ActivityPage.tsx  |  14 +-
 .../features/connect/pages/ConnectPage.tsx    |   4 +-
 .../components/CreateSandboxDialog.tsx        |  16 +-
 ...boxButton.tsx => DestroySandboxButton.tsx} |  34 +-
 .../sandboxes/components/EditPolicyDialog.tsx |  14 +-
 .../sandboxes/components/HistoryPanel.tsx     |   8 +-
 .../sandboxes/components/MetricsPanel.tsx     |   2 +-
 .../components/RebuildSandboxButton.tsx       |   8 +-
 .../sandboxes/components/RestoreCard.tsx      |   8 +-
 .../features/sandboxes/hooks/useSandboxes.ts  |  26 +-
 .../sandboxes/pages/SandboxDetailPage.tsx     |  26 +-
 .../sandboxes/pages/SandboxesPage.tsx         |  80 ++---
 .../templates/pages/TemplatesPage.tsx         |   2 +-
 packages/console/src/lib/api.ts               |  16 +-
 packages/console/src/routeTree.gen.ts         |  34 +-
 .../{$userKey.tsx => $externalId.tsx}         |   2 +-
 packages/console/vite.config.ts               |   4 +-
 packages/sdk/src/client.test.ts               |  34 +-
 packages/sdk/src/client.ts                    |  99 ++++--
 packages/server/drizzle/0006_external-id.sql  |   5 +
 .../server/drizzle/meta/0006_snapshot.json    | 277 +++++++++++++++
 packages/server/drizzle/meta/_journal.json    |   7 +
 packages/server/src/app.test.ts               | 320 +++++++++---------
 packages/server/src/archive/archiver.test.ts  |  40 +--
 packages/server/src/archive/archiver.ts       |  24 +-
 packages/server/src/db/activity.ts            |   4 +-
 packages/server/src/db/ledger.test.ts         |  16 +-
 packages/server/src/db/ledger.ts              |  14 +-
 packages/server/src/db/schema.ts              |   6 +-
 packages/server/src/db/templates.ts           |   8 +-
 packages/server/src/e2b/compat.test.ts        |  30 +-
 packages/server/src/e2b/control.ts            |  50 +--
 packages/server/src/e2b/envd/process.ts       |   2 +-
 packages/server/src/e2b/envd/shared.ts        |   6 +-
 packages/server/src/e2b/view.test.ts          |   2 +-
 packages/server/src/exec-heartbeat.ts         |   2 +-
 packages/server/src/executor/docker.ts        |   2 +-
 packages/server/src/keyed-queue.ts            |   6 +-
 packages/server/src/lifecycle.ts              |  22 +-
 packages/server/src/reconciler.test.ts        |  50 +--
 packages/server/src/reconciler.ts             |  10 +-
 .../server/src/routes/observability.test.ts   |  42 +--
 packages/server/src/routes/sandboxes.ts       | 206 +++++++----
 packages/server/src/routes/templates.ts       |   8 +-
 packages/server/src/sandbox-proxy.ts          |   4 +-
 packages/server/src/scanner.test.ts           |  72 ++--
 packages/server/src/scanner.ts                |  14 +-
 packages/shared/src/acquire.ts                |   6 +-
 packages/shared/src/activity.ts               |   6 +-
 packages/shared/src/destroy.ts                |  23 ++
 packages/shared/src/exec.ts                   |   6 +-
 packages/shared/src/files.ts                  |  68 +++-
 packages/shared/src/index.ts                  |   4 +-
 packages/shared/src/metrics.ts                |   8 +-
 packages/shared/src/rebuild.ts                |   8 +-
 packages/shared/src/release.ts                |  23 --
 packages/shared/src/sandbox.ts                |  12 +-
 packages/shared/src/templates.ts              |   2 +-
 .../src/{set-policy.ts => update-policy.ts}   |  18 +-
 website/content/docs/cli.mdx                  |  10 +-
 website/content/docs/commands.mdx             |   2 +-
 website/content/docs/e2b-differences.mdx      |   2 +-
 website/content/docs/e2b-sdks.mdx             |   6 +-
 website/content/docs/files.mdx                |  17 +-
 website/content/docs/http-api.mdx             |  20 +-
 website/content/docs/index.mdx                |   2 +-
 website/content/docs/persistence.mdx          |   2 +-
 website/content/docs/quickstart.mdx           |   4 +-
 website/content/docs/upgrading.mdx            |   2 +-
 website/src/components/sections/Features.tsx  |   2 +-
 87 files changed, 1382 insertions(+), 869 deletions(-)
 rename packages/console/src/features/sandboxes/components/{ReleaseSandboxButton.tsx => DestroySandboxButton.tsx} (65%)
 rename packages/console/src/routes/_app/sandboxes/{$userKey.tsx => $externalId.tsx} (87%)
 create mode 100644 packages/server/drizzle/0006_external-id.sql
 create mode 100644 packages/server/drizzle/meta/0006_snapshot.json
 create mode 100644 packages/shared/src/destroy.ts
 delete mode 100644 packages/shared/src/release.ts
 rename packages/shared/src/{set-policy.ts => update-policy.ts} (58%)

diff --git a/e2e/python/test_e2b_sync.py b/e2e/python/test_e2b_sync.py
index a388893..db83aa2 100644
--- a/e2e/python/test_e2b_sync.py
+++ b/e2e/python/test_e2b_sync.py
@@ -99,8 +99,8 @@ def test_list_filters(conn, make_sandbox):
 
 
 def test_userkey_extension_is_idempotent(conn, make_sandbox):
-    first = make_sandbox(metadata={"userKey": "py-idem"})
-    second = Sandbox.create(metadata={"userKey": "py-idem"}, **conn)
+    first = make_sandbox(metadata={"externalId": "py-idem"})
+    second = Sandbox.create(metadata={"externalId": "py-idem"}, **conn)
     # Same key, same sandbox — the Dormice extension speaks Python too.
     assert second.sandbox_id == first.sandbox_id
 
diff --git a/e2e/src/archive.test.ts b/e2e/src/archive.test.ts
index 476d85f..0727c11 100644
--- a/e2e/src/archive.test.ts
+++ b/e2e/src/archive.test.ts
@@ -38,7 +38,7 @@ describe('the archive lifecycle over a real daemon', () => {
     const deadline = Date.now() + 15_000;
     for (;;) {
       const sandboxes = await dormice.listSandboxes();
-      const mine = sandboxes.find((s) => s.userKey === 'archive-key');
+      const mine = sandboxes.find((s) => s.externalId === 'archive-key');
       if (mine?.state === 'archived') break;
       if (Date.now() > deadline) {
         throw new Error(`never archived; last observed: ${mine?.state}`);
@@ -68,12 +68,12 @@ describe('the archive lifecycle over a real daemon', () => {
     const read = await dormice.readFile('archive-key', 'kept.txt');
     expect(Buffer.from(read.content).toString()).toBe('survived the bucket');
 
-    await dormice.releaseSandbox('archive-key');
+    await dormice.destroySandbox('archive-key');
   });
 
-  it('a released archived sandbox is gone for good', async () => {
+  it('a destroyed archived sandbox is gone for good', async () => {
     const dormice = client();
-    await dormice.acquireSandbox('archive-release-key', {
+    await dormice.acquireSandbox('archive-destroy-key', {
       policy: {
         freezeAfterSeconds: 1,
         stopAfterSeconds: 2,
@@ -83,7 +83,7 @@ describe('the archive lifecycle over a real daemon', () => {
     const deadline = Date.now() + 15_000;
     for (;;) {
       const sandboxes = await dormice.listSandboxes();
-      const mine = sandboxes.find((s) => s.userKey === 'archive-release-key');
+      const mine = sandboxes.find((s) => s.externalId === 'archive-destroy-key');
       if (mine?.state === 'archived') break;
       if (Date.now() > deadline) {
         throw new Error(`never archived; last observed: ${mine?.state}`);
@@ -91,11 +91,11 @@ describe('the archive lifecycle over a real daemon', () => {
       await sleep(0.25);
     }
 
-    const released = await dormice.releaseSandbox('archive-release-key');
-    expect(released.released).toBe(true);
+    const destroyed = await dormice.destroySandbox('archive-destroy-key');
+    expect(destroyed.destroyed).toBe(true);
     // The key is free again: the next acquire is a brand-new sandbox.
-    const fresh = await dormice.acquireSandbox('archive-release-key');
+    const fresh = await dormice.acquireSandbox('archive-destroy-key');
     expect(fresh.status).toBe('ready');
-    await dormice.releaseSandbox('archive-release-key');
+    await dormice.destroySandbox('archive-destroy-key');
   });
 });
diff --git a/e2e/src/cli.test.ts b/e2e/src/cli.test.ts
index 711034a..d63d273 100644
--- a/e2e/src/cli.test.ts
+++ b/e2e/src/cli.test.ts
@@ -44,17 +44,17 @@ describe('dor CLI against a real daemon', () => {
     expect(stdout).toContain(created.sandbox.sandboxId);
   });
 
-  it('sandbox release destroys and is idempotent', async () => {
+  it('sandbox destroy destroys and is idempotent', async () => {
     const sdk = new Dormice({
       endpoint: inject('dormiceEndpoint'),
       token: inject('dormiceToken'),
     });
-    await sdk.acquireSandbox('cli-release-key');
+    await sdk.acquireSandbox('cli-destroy-key');
 
-    const first = await cli('sandbox', 'release', 'cli-release-key');
-    expect(first.stdout).toContain('Released the sandbox');
-    const second = await cli('sandbox', 'release', 'cli-release-key');
-    expect(second.stdout).toContain('nothing to release');
+    const first = await cli('sandbox', 'destroy', 'cli-destroy-key');
+    expect(first.stdout).toContain('Destroyed the sandbox');
+    const second = await cli('sandbox', 'destroy', 'cli-destroy-key');
+    expect(second.stdout).toContain('nothing to destroy');
   });
 
   it('sandbox exec prints the output and passes the exit code through', async () => {
diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 026fa65..cacc892 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -530,15 +530,15 @@ describe('official e2b SDK against the daemon', () => {
       endpoint: inject('dormiceEndpoint'),
       token: inject('dormiceToken'),
     });
-    const userKey = `watch-freeze-${Date.now()}`;
+    const externalId = `watch-freeze-${Date.now()}`;
     // Native acquire sets the second-scale policy; the e2b face then joins
-    // the same sandbox through the userKey extension.
-    await dormice.acquireSandbox(userKey, {
+    // the same sandbox through the externalId extension.
+    await dormice.acquireSandbox(externalId, {
       policy: { freezeAfterSeconds: 1, stopAfterSeconds: null },
     });
     const sbx = await Sandbox.create({
       ...connection(),
-      metadata: { userKey },
+      metadata: { externalId },
     });
     try {
       const events: Array<{ name: string; type: string }> = [];
@@ -552,7 +552,7 @@ describe('official e2b SDK against the daemon', () => {
       // The real wall-clock scanner freezes the sandbox under the open watch.
       const frozen = async () => {
         const sandboxes = await dormice.listSandboxes();
-        return sandboxes.find((s) => s.userKey === userKey)?.state;
+        return sandboxes.find((s) => s.externalId === externalId)?.state;
       };
       const deadline = Date.now() + 15_000;
       while ((await frozen()) !== 'frozen') {
@@ -568,7 +568,7 @@ describe('official e2b SDK against the daemon', () => {
       );
       await handle.stop();
     } finally {
-      await dormice.releaseSandbox(userKey);
+      await dormice.destroySandbox(externalId);
     }
   });
 
@@ -629,16 +629,16 @@ describe('official e2b SDK against the daemon', () => {
     }
   });
 
-  it('the Dormice extension: metadata.userKey makes create idempotent, data persists', async () => {
+  it('the Dormice extension: metadata.externalId makes create idempotent, data persists', async () => {
     const first = await Sandbox.create({
       ...connection(),
-      metadata: { userKey: 'e2e-agent-key' },
+      metadata: { externalId: 'e2e-agent-key' },
     });
     try {
       await first.files.write('persistent.txt', 'same sandbox every time');
       const second = await Sandbox.create({
         ...connection(),
-        metadata: { userKey: 'e2e-agent-key' },
+        metadata: { externalId: 'e2e-agent-key' },
       });
       expect(second.sandboxId).toBe(first.sandboxId);
       expect(await second.files.read('persistent.txt')).toBe(
diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index 926f507..b46a728 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -1,7 +1,7 @@
 import { DEFAULT_LIFECYCLE_POLICY, Dormice } from '@dormice/sdk';
 import { describe, expect, inject, it } from 'vitest';
 
-// One daemon serves the whole run, so every test uses its own user key to
+// One daemon serves the whole run, so every test uses its own external id to
 // stay independent of the others.
 function client(token = inject('dormiceToken')) {
   return new Dormice({ endpoint: inject('dormiceEndpoint'), token });
@@ -30,7 +30,7 @@ describe('native API over a real daemon', () => {
     const res = await client().acquireSandbox('fresh-key');
     expect(res.status).toBe('ready');
     expect(res.sandbox.state).toBe('active');
-    expect(res.sandbox.userKey).toBe('fresh-key');
+    expect(res.sandbox.externalId).toBe('fresh-key');
     // The exam daemon runs with S3 configured (see setup/daemon.ts), so the
     // archive default is live: a week from stopped to archived.
     expect(res.sandbox.policy).toEqual({
@@ -83,22 +83,22 @@ describe('native API over a real daemon', () => {
     ).resolves.toBe(400);
   });
 
-  it('releases a sandbox: destroyed, forgotten, idempotent', async () => {
-    const created = await client().acquireSandbox('release-key');
+  it('destroys a sandbox: gone, forgotten, idempotent', async () => {
+    const created = await client().acquireSandbox('destroy-key');
 
-    expect(await client().releaseSandbox('release-key')).toEqual({
-      released: true,
+    expect(await client().destroySandbox('destroy-key')).toEqual({
+      destroyed: true,
     });
     const listed = await client().listSandboxes();
     expect(listed.some((s) => s.sandboxId === created.sandbox.sandboxId)).toBe(
       false,
     );
-    expect(await client().releaseSandbox('release-key')).toEqual({
-      released: false,
+    expect(await client().destroySandbox('destroy-key')).toEqual({
+      destroyed: false,
     });
 
     // The key is free again: the next acquire builds a brand-new sandbox.
-    const again = await client().acquireSandbox('release-key');
+    const again = await client().acquireSandbox('destroy-key');
     expect(again.sandbox.sandboxId).not.toBe(created.sandbox.sandboxId);
   });
 
@@ -123,15 +123,15 @@ describe('native API over a real daemon', () => {
       name: 'DormiceApiError',
       status: 404,
     });
-    await client().releaseSandbox('rebuild-key');
+    await client().destroySandbox('rebuild-key');
   });
 
   it('updates a lifecycle policy in place — no release, no lost disk', async () => {
-    const created = await client().acquireSandbox('set-policy-key');
+    const created = await client().acquireSandbox('update-policy-key');
 
     // Promote to a never-stop resident agent; archive must fall with it
     // (only a stopped sandbox can archive) — sent together, as the console does.
-    const { sandbox } = await client().setPolicy('set-policy-key', {
+    const { sandbox } = await client().updatePolicy('update-policy-key', {
       stopAfterSeconds: null,
       archiveAfterSeconds: null,
     });
@@ -142,16 +142,16 @@ describe('native API over a real daemon', () => {
     expect(sandbox.state).toBe(created.sandbox.state);
 
     // The archive knob's front door works too on this S3-equipped daemon.
-    const back = await client().setPolicy('set-policy-key', {
+    const back = await client().updatePolicy('update-policy-key', {
       stopAfterSeconds: 3 * 24 * 60 * 60,
       archiveAfterSeconds: 30 * 24 * 60 * 60,
     });
     expect(back.sandbox.policy.archiveAfterSeconds).toBe(30 * 24 * 60 * 60);
 
     await expect(
-      client().setPolicy('set-policy-nobody', { freezeAfterSeconds: 60 }),
+      client().updatePolicy('update-policy-nobody', { freezeAfterSeconds: 60 }),
     ).rejects.toMatchObject({ name: 'DormiceApiError', status: 404 });
-    await client().releaseSandbox('set-policy-key');
+    await client().destroySandbox('update-policy-key');
   });
 
   // The fake's files hang off the disk, so only a real container can show
@@ -174,7 +174,7 @@ describe('native API over a real daemon', () => {
       expect(check.stdout).toContain('kept');
       expect(check.stdout).not.toContain('ephemeral');
       expect(check.stderr).toMatch(/No such file/);
-      await client().releaseSandbox('rebuild-layers-key');
+      await client().destroySandbox('rebuild-layers-key');
     },
   );
 
@@ -217,7 +217,7 @@ describe('native API over a real daemon', () => {
     const result = await client().execCommand('exec-busy-key', 'sleep 3');
     expect(result.exitCode).toBe(0);
     const observed = (await client().listSandboxes()).find(
-      (s) => s.userKey === 'exec-busy-key',
+      (s) => s.externalId === 'exec-busy-key',
     );
     expect(observed?.state).toBe('active');
   });
@@ -234,7 +234,7 @@ describe('native API over a real daemon', () => {
     const deadline = Date.now() + 15_000;
     for (;;) {
       const cold = (await client().listSandboxes()).find(
-        (s) => s.userKey === 'exec-wake-key',
+        (s) => s.externalId === 'exec-wake-key',
       );
       if (cold?.state === 'frozen') break;
       if (Date.now() > deadline) {
@@ -251,7 +251,7 @@ describe('native API over a real daemon', () => {
     expect(result.exitCode).toBe(0);
     expect(result.stdout).toBe('woke\n');
     const observed = (await client().listSandboxes()).find(
-      (s) => s.userKey === 'exec-wake-key',
+      (s) => s.externalId === 'exec-wake-key',
     );
     expect(observed?.state).toBe('active');
   });
@@ -275,7 +275,7 @@ describe('native API over a real daemon', () => {
     const deadline = Date.now() + 15_000;
     for (;;) {
       const asleep = (await client().listSandboxes()).find(
-        (s) => s.userKey === 'sleeper-key',
+        (s) => s.externalId === 'sleeper-key',
       );
       if (asleep?.state === 'stopped') break;
       if (Date.now() > deadline) {
@@ -313,6 +313,38 @@ describe('native API over a real daemon', () => {
     expect(blob.content).toEqual(bytes);
   });
 
+  it('writeFile and readFiles: the single and batch forms hold the same contract', async () => {
+    await client().acquireSandbox('files-key');
+    await client().writeFiles('files-key', [
+      { path: 'hello.txt', content: 'hello from e2e\n' },
+    ]);
+
+    const one = await client().writeFile('files-key', 'single.txt', 'just me\n');
+    expect(one).toEqual({ path: '/home/user/single.txt' });
+
+    // Batch read comes back in request order, paths resolved.
+    const batch = await client().readFiles('files-key', [
+      'single.txt',
+      '/home/user/hello.txt',
+    ]);
+    expect(batch.map((f) => f.path)).toEqual([
+      '/home/user/single.txt',
+      '/home/user/hello.txt',
+    ]);
+    expect(batch.map((f) => new TextDecoder().decode(f.content))).toEqual([
+      'just me\n',
+      'hello from e2e\n',
+    ]);
+
+    // All or nothing: one missing path fails the whole batch, naming it.
+    await expect(
+      client().readFiles('files-key', ['single.txt', 'absent.txt']),
+    ).rejects.toMatchObject({
+      status: 404,
+      message: 'no such file: /home/user/absent.txt',
+    });
+  });
+
   it('surfaces the honest errors: missing file 404, directory 400', async () => {
     await client().acquireSandbox('files-err-key');
     await expect(
@@ -340,7 +372,7 @@ describe('native API over a real daemon', () => {
     });
     expect(created.sandbox.template).toBe('native-tpl');
     const listed = (await client().listSandboxes()).find(
-      (s) => s.userKey === 'tpl-key',
+      (s) => s.externalId === 'tpl-key',
     );
     expect(listed?.template).toBe('native-tpl');
 
@@ -349,7 +381,7 @@ describe('native API over a real daemon', () => {
       status: 409,
       message: expect.stringMatching(/tpl-key/),
     });
-    await client().releaseSandbox('tpl-key');
+    await client().destroySandbox('tpl-key');
     expect(await client().removeTemplate('native-tpl')).toEqual({
       removed: true,
     });
@@ -371,8 +403,8 @@ describe('native API over a real daemon', () => {
         ),
       });
       // Nothing was created: the key is still free, the template removable.
-      expect(await client().releaseSandbox('hollow-key')).toEqual({
-        released: false,
+      expect(await client().destroySandbox('hollow-key')).toEqual({
+        destroyed: false,
       });
       expect(await client().removeTemplate('hollow-tpl')).toEqual({
         removed: true,
@@ -395,7 +427,7 @@ describe('native API over a real daemon', () => {
     const deadline = Date.now() + 15_000;
     for (;;) {
       const cold = (await client().listSandboxes()).find(
-        (s) => s.userKey === 'files-wake-key',
+        (s) => s.externalId === 'files-wake-key',
       );
       if (cold?.state === 'frozen') break;
       if (Date.now() > deadline) {
@@ -409,7 +441,7 @@ describe('native API over a real daemon', () => {
     const read = await client().readFile('files-wake-key', 'keep.txt');
     expect(new TextDecoder().decode(read.content)).toBe('still here');
     const observed = (await client().listSandboxes()).find(
-      (s) => s.userKey === 'files-wake-key',
+      (s) => s.externalId === 'files-wake-key',
     );
     expect(observed?.state).toBe('active');
   });
@@ -430,7 +462,7 @@ describe('native API over a real daemon', () => {
     expect(metrics.sandboxDisks.nominalBytes).toBeGreaterThan(
       metrics.sandboxDisks.actualBytes,
     );
-    await client().releaseSandbox('host-metrics-key');
+    await client().destroySandbox('host-metrics-key');
   });
 });
 
@@ -449,14 +481,14 @@ describe('the observability verbs over a real daemon', () => {
     });
   });
 
-  it('getSandboxMetrics samples a live sandbox and 404s after release', async () => {
+  it('getSandboxMetrics samples a live sandbox and 404s after destroy', async () => {
     await client().acquireSandbox('obs-metrics-key');
     const sample = await client().getSandboxMetrics('obs-metrics-key');
     expect(sample).not.toBeNull();
     expect(sample?.memTotalBytes).toBeGreaterThan(0);
     expect(sample?.diskTotalBytes).toBeGreaterThan(0);
 
-    await client().releaseSandbox('obs-metrics-key');
+    await client().destroySandbox('obs-metrics-key');
     await expect(
       client().getSandboxMetrics('obs-metrics-key'),
     ).rejects.toMatchObject({ name: 'DormiceApiError', status: 404 });
@@ -464,10 +496,10 @@ describe('the observability verbs over a real daemon', () => {
 
   it("listActivity tells one sandbox's story, newest first", async () => {
     await client().acquireSandbox('obs-story-key');
-    await client().releaseSandbox('obs-story-key');
+    await client().destroySandbox('obs-story-key');
     const events = await client().listActivity({ limit: 500 });
-    const mine = events.filter((e) => e.userKey === 'obs-story-key');
-    expect(mine.map((e) => e.kind)).toEqual(['released', 'created']);
+    const mine = events.filter((e) => e.externalId === 'obs-story-key');
+    expect(mine.map((e) => e.kind)).toEqual(['destroyed', 'created']);
     expect(mine[1]?.detail).toContain('acquireSandbox');
   });
 });
diff --git a/examples/README.md b/examples/README.md
index 69f3d57..e1b8e29 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -5,7 +5,7 @@ self-contained — read it top to bottom, then run it.
 
 | File | What it shows |
 | --- | --- |
-| [`native-lifecycle.mjs`](native-lifecycle.mjs) | The native SDK end to end: idempotent `acquireSandbox`, command execution, file I/O, `releaseSandbox` |
+| [`native-lifecycle.mjs`](native-lifecycle.mjs) | The native SDK end to end: idempotent `acquireSandbox`, command execution, file I/O, `destroySandbox` |
 | [`e2b-compat.mjs`](e2b-compat.mjs) | The **official `e2b` package**, unmodified, pointed at Dormice by two URLs — with live output streaming |
 | [`resident-agent.mjs`](resident-agent.mjs) | A permanent per-agent sandbox (`stopAfterSeconds: null`): run it repeatedly, its state survives |
 
@@ -45,4 +45,4 @@ after `npm install @dormice/sdk e2b`.
 
 `resident-agent.mjs` deliberately leaves its sandbox running; when you are
 done playing, remove it with `dor sandbox release example-resident-agent`
-(or `releaseSandbox` from the SDK).
+(or `destroySandbox` from the SDK).
diff --git a/examples/e2b-compat.mjs b/examples/e2b-compat.mjs
index ba6f6b6..c1cf1c6 100644
--- a/examples/e2b-compat.mjs
+++ b/examples/e2b-compat.mjs
@@ -41,7 +41,7 @@ try {
   console.log('killed');
 }
 
-// Dormice extension worth knowing: Sandbox.create({ metadata: { userKey } })
+// Dormice extension worth knowing: Sandbox.create({ metadata: { externalId } })
 // makes create idempotent — the same key returns the same sandbox instead of
 // a new one, which is how an E2B application picks up permanent sandboxes
 // without leaving the e2b package.
diff --git a/examples/native-lifecycle.mjs b/examples/native-lifecycle.mjs
index f8bdc2b..4f495d1 100644
--- a/examples/native-lifecycle.mjs
+++ b/examples/native-lifecycle.mjs
@@ -48,5 +48,5 @@ console.log(
 );
 
 // release() destroys container and disk — the only verb that loses data.
-await client.releaseSandbox(key);
-console.log('released');
+await client.destroySandbox(key);
+console.log('destroyed');
diff --git a/examples/resident-agent.mjs b/examples/resident-agent.mjs
index 92b2c95..4f6e80e 100644
--- a/examples/resident-agent.mjs
+++ b/examples/resident-agent.mjs
@@ -38,7 +38,7 @@ const visit = await client.execCommand(
 );
 console.log(visit.stdout.trimEnd());
 
-// Deliberately NOT released — a resident agent's sandbox outlives every run
+// Deliberately NOT destroyed — a resident agent's sandbox outlives every run
 // of this script. When you are done playing:
 //   dor sandbox release example-resident-agent
 console.log('\nleft running; the journal will still be here tomorrow.');
diff --git a/packages/cli/src/commands.test.ts b/packages/cli/src/commands.test.ts
index 2b92160..06f0dfc 100644
--- a/packages/cli/src/commands.test.ts
+++ b/packages/cli/src/commands.test.ts
@@ -17,7 +17,7 @@ import {
   sandboxPull,
   sandboxPush,
   sandboxRebuild,
-  sandboxRelease,
+  sandboxDestroy,
   templateAdd,
   templateLs,
   templateRm,
@@ -109,14 +109,14 @@ describe('sandbox commands over real HTTP', () => {
     expect(output).toContain(alice.sandbox.sandboxId);
   });
 
-  it('neutralizes control characters a hostile user key smuggles in', async () => {
-    // The protocol keeps userKey opaque, so an ESC sequence is a legal key;
+  it('neutralizes control characters a hostile external id smuggles in', async () => {
+    // The protocol keeps externalId opaque, so an ESC sequence is a legal key;
     // printed raw it would rewrite the operator's terminal.
     await client.acquireSandbox('evil\u001b[31mkey');
     const output = await sandboxLs(client);
     expect(output).not.toContain('\u001b');
     expect(output).toContain('evil?[31mkey');
-    await client.releaseSandbox('evil\u001b[31mkey');
+    await client.destroySandbox('evil\u001b[31mkey');
   });
 
   it('exec hands back the three channels untouched', async () => {
@@ -129,7 +129,7 @@ describe('sandbox commands over real HTTP', () => {
     // The exit code passes through as data; main.ts turns it into the
     // process's own.
     expect((await sandboxExec(client, 'dave', 'exit 3')).exitCode).toBe(3);
-    await client.releaseSandbox('dave');
+    await client.destroySandbox('dave');
   });
 
   it('push reports the resolved path and byte count', async () => {
@@ -141,7 +141,7 @@ describe('sandbox commands over real HTTP', () => {
       'notes.txt',
     );
     expect(message).toBe('Wrote /home/user/notes.txt (2 bytes).');
-    await client.releaseSandbox('pusher');
+    await client.destroySandbox('pusher');
   });
 
   it('pull hands back the exact bytes; the save message is separate', async () => {
@@ -155,7 +155,7 @@ describe('sandbox commands over real HTTP', () => {
     expect(pullSavedMessage(result, 'local.bin')).toBe(
       'Pulled /home/user/data.bin -> local.bin (4 bytes).',
     );
-    await client.releaseSandbox('puller');
+    await client.destroySandbox('puller');
   });
 
   it('rebuild reports the swap and surfaces the 404 for an unknown key', async () => {
@@ -167,16 +167,16 @@ describe('sandbox commands over real HTTP', () => {
     await expect(sandboxRebuild(client, 'nobody')).rejects.toThrow(
       /acquire it first/,
     );
-    await client.releaseSandbox('rebuilder');
+    await client.destroySandbox('rebuilder');
   });
 
-  it('release reports both outcomes of the idempotent destroy', async () => {
+  it('destroy reports both outcomes of the idempotent destroy', async () => {
     await client.acquireSandbox('carol');
-    expect(await sandboxRelease(client, 'carol')).toBe(
-      'Released the sandbox for key "carol".',
+    expect(await sandboxDestroy(client, 'carol')).toBe(
+      'Destroyed the sandbox for key "carol".',
     );
-    expect(await sandboxRelease(client, 'carol')).toBe(
-      'No sandbox for key "carol" — nothing to release.',
+    expect(await sandboxDestroy(client, 'carol')).toBe(
+      'No sandbox for key "carol" — nothing to destroy.',
     );
   });
 });
diff --git a/packages/cli/src/commands.ts b/packages/cli/src/commands.ts
index fe8e86f..a7caab4 100644
--- a/packages/cli/src/commands.ts
+++ b/packages/cli/src/commands.ts
@@ -32,14 +32,14 @@ export function clientFromEnv(
 }
 
 const COLUMNS: { header: string; value: (s: Sandbox) => string }[] = [
-  { header: 'USER KEY', value: (s) => s.userKey },
+  { header: 'USER KEY', value: (s) => s.externalId },
   { header: 'STATE', value: (s) => s.state },
   { header: 'SANDBOX ID', value: (s) => s.sandboxId },
   { header: 'LAST ACTIVE', value: (s) => s.lastActiveAt },
 ];
 
 /**
- * The protocol keeps userKey opaque, so a hostile key can carry control
+ * The protocol keeps externalId opaque, so a hostile key can carry control
  * characters — printed raw, ESC sequences would let one sandbox's name
  * rewrite the operator's terminal. Neutralized here, at the output layer,
  * where the terminal risk lives.
@@ -80,7 +80,7 @@ export interface ExecOutput {
 }
 
 /**
- * `dor sandbox exec <userKey> <command>`: run a shell command in the
+ * `dor sandbox exec <externalId> <command>`: run a shell command in the
  * sandbox, buffered. Three channels instead of one string: the command's
  * stdout and stderr must reach the operator's matching streams untouched
  * (this is their own command's output, like ssh — unlike the ls table,
@@ -89,11 +89,11 @@ export interface ExecOutput {
  */
 export async function sandboxExec(
   client: Dormice,
-  userKey: string,
+  externalId: string,
   command: string,
   timeoutSeconds?: number,
 ): Promise<ExecOutput> {
-  const result = await client.execCommand(userKey, command, {
+  const result = await client.execCommand(externalId, command, {
     timeoutSeconds,
   });
   let stderr = result.stderr;
@@ -103,17 +103,17 @@ export async function sandboxExec(
 }
 
 /**
- * `dor sandbox push <userKey> <localPath> [remotePath]`: one local file into
+ * `dor sandbox push <externalId> <localPath> [remotePath]`: one local file into
  * the sandbox. The bytes arrive here already read — main.ts owns the
  * filesystem, this function owns the API call and the message.
  */
 export async function sandboxPush(
   client: Dormice,
-  userKey: string,
+  externalId: string,
   content: Uint8Array,
   remotePath: string,
 ): Promise<string> {
-  const { files } = await client.writeFiles(userKey, [
+  const { files } = await client.writeFiles(externalId, [
     { path: remotePath, content },
   ]);
   const written = files[0]?.path ?? remotePath;
@@ -121,17 +121,17 @@ export async function sandboxPush(
 }
 
 /**
- * `dor sandbox pull <userKey> <remotePath> [localPath]`: one file out of the
+ * `dor sandbox pull <externalId> <remotePath> [localPath]`: one file out of the
  * sandbox. Returns the exact bytes; main.ts decides between a local file and
  * raw stdout — raw on purpose, the same rule as exec output: these are the
  * operator's own bytes, not a place to strip control characters.
  */
 export async function sandboxPull(
   client: Dormice,
-  userKey: string,
+  externalId: string,
   remotePath: string,
 ): Promise<ReadFileResult> {
-  return client.readFile(userKey, remotePath);
+  return client.readFile(externalId, remotePath);
 }
 
 /** The message printed instead of raw bytes when pull saves to a local file. */
@@ -143,33 +143,33 @@ export function pullSavedMessage(
 }
 
 /**
- * `dor sandbox rebuild <userKey>`: swap the sandbox's container, keep its
+ * `dor sandbox rebuild <externalId>`: swap the sandbox's container, keep its
  * disk. /home/user survives; everything else resets onto the current image
  * of the sandbox's template (or the base image) at the next use.
  */
 export async function sandboxRebuild(
   client: Dormice,
-  userKey: string,
+  externalId: string,
 ): Promise<string> {
-  const { sandbox } = await client.rebuildSandbox(userKey);
+  const { sandbox } = await client.rebuildSandbox(externalId);
   const target = sandbox.template
     ? `template "${printable(sandbox.template)}"'s current image`
     : 'the current base image';
   return (
-    `Rebuilt the sandbox for key "${printable(userKey)}" — /home/user kept, ` +
+    `Rebuilt the sandbox for key "${printable(externalId)}" — /home/user kept, ` +
     `now ${sandbox.state}; its next use starts on ${target}.`
   );
 }
 
-/** `dor sandbox release <userKey>`: destroy the sandbox behind a key, idempotently. */
-export async function sandboxRelease(
+/** `dor sandbox destroy <externalId>`: destroy the sandbox behind a key, idempotently. */
+export async function sandboxDestroy(
   client: Dormice,
-  userKey: string,
+  externalId: string,
 ): Promise<string> {
-  const { released } = await client.releaseSandbox(userKey);
-  return released
-    ? `Released the sandbox for key "${printable(userKey)}".`
-    : `No sandbox for key "${printable(userKey)}" — nothing to release.`;
+  const { destroyed } = await client.destroySandbox(externalId);
+  return destroyed
+    ? `Destroyed the sandbox for key "${printable(externalId)}".`
+    : `No sandbox for key "${printable(externalId)}" — nothing to destroy.`;
 }
 
 /**
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index ae07267..16b5113 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -14,7 +14,7 @@ import {
   sandboxPull,
   sandboxPush,
   sandboxRebuild,
-  sandboxRelease,
+  sandboxDestroy,
   templateAdd,
   templateLs,
   templateRm,
@@ -53,7 +53,7 @@ sandbox
   .description(
     'Run a shell command inside the sandbox behind a key (wakes it first)',
   )
-  .argument('<userKey>', 'the user key whose sandbox runs the command')
+  .argument('<externalId>', 'the external id whose sandbox runs the command')
   .argument(
     '<command>',
     'shell command, quoted as one argument (runs as bash -c)',
@@ -64,10 +64,10 @@ sandbox
     (value: string) => Number(value),
   )
   .action(
-    async (userKey: string, command: string, opts: { timeout?: number }) => {
+    async (externalId: string, command: string, opts: { timeout?: number }) => {
       const result = await sandboxExec(
         clientFromEnv(process.env),
-        userKey,
+        externalId,
         command,
         opts.timeout,
       );
@@ -82,18 +82,18 @@ sandbox
   .description(
     'Copy a local file into the sandbox behind a key (wakes it first)',
   )
-  .argument('<userKey>', 'the user key whose sandbox receives the file')
+  .argument('<externalId>', 'the external id whose sandbox receives the file')
   .argument('<localPath>', 'local file to send')
   .argument(
     '[remotePath]',
     'destination inside the sandbox; relative paths land under /home/user (default: the local file name)',
   )
-  .action(async (userKey: string, localPath: string, remotePath?: string) => {
+  .action(async (externalId: string, localPath: string, remotePath?: string) => {
     const content = await readFile(localPath);
     console.log(
       await sandboxPush(
         clientFromEnv(process.env),
-        userKey,
+        externalId,
         content,
         remotePath ?? path.basename(localPath),
       ),
@@ -103,13 +103,13 @@ sandbox
 sandbox
   .command('pull')
   .description('Copy a file out of the sandbox behind a key (wakes it first)')
-  .argument('<userKey>', 'the user key whose sandbox holds the file')
+  .argument('<externalId>', 'the external id whose sandbox holds the file')
   .argument('<remotePath>', 'file inside the sandbox; relative to /home/user')
   .argument('[localPath]', 'where to save it; omitted = raw bytes to stdout')
-  .action(async (userKey: string, remotePath: string, localPath?: string) => {
+  .action(async (externalId: string, remotePath: string, localPath?: string) => {
     const result = await sandboxPull(
       clientFromEnv(process.env),
-      userKey,
+      externalId,
       remotePath,
     );
     if (localPath === undefined) {
@@ -126,17 +126,17 @@ sandbox
   .description(
     "Swap the container, keep /home/user — next use starts on the template's current image (or the base image)",
   )
-  .argument('<userKey>', 'the user key whose sandbox to rebuild')
-  .action(async (userKey: string) => {
-    console.log(await sandboxRebuild(clientFromEnv(process.env), userKey));
+  .argument('<externalId>', 'the external id whose sandbox to rebuild')
+  .action(async (externalId: string) => {
+    console.log(await sandboxRebuild(clientFromEnv(process.env), externalId));
   });
 
 sandbox
-  .command('release')
-  .description('Destroy the sandbox behind a user key (idempotent)')
-  .argument('<userKey>', 'the user key whose sandbox to destroy')
-  .action(async (userKey: string) => {
-    console.log(await sandboxRelease(clientFromEnv(process.env), userKey));
+  .command('destroy')
+  .description('Destroy the sandbox behind an external id (idempotent)')
+  .argument('<externalId>', 'the external id whose sandbox to destroy')
+  .action(async (externalId: string) => {
+    console.log(await sandboxDestroy(clientFromEnv(process.env), externalId));
   });
 
 const template = program
diff --git a/packages/console/scripts/seed.mjs b/packages/console/scripts/seed.mjs
index 413a65e..844713b 100644
--- a/packages/console/scripts/seed.mjs
+++ b/packages/console/scripts/seed.mjs
@@ -41,9 +41,9 @@ async function rpc(path, body = {}) {
   return res.json();
 }
 
-const write = (userKey, files) =>
+const write = (externalId, files) =>
   rpc('/writeFiles', {
-    userKey,
+    externalId,
     files: files.map(([path, text]) => ({
       path,
       contentBase64: Buffer.from(text, 'utf8').toString('base64'),
@@ -66,46 +66,46 @@ for (const [name, image] of templates) {
 // stopAfterSeconds: null 是常驻 agent 档,永远停在 frozen。
 const sandboxes = [
   {
-    userKey: 'demo-agent',
+    externalId: 'demo-agent',
     policy: { freezeAfterSeconds: 300, stopAfterSeconds: null },
     template: 'claude-code',
   },
   {
-    userKey: 'web-scraper',
+    externalId: 'web-scraper',
     policy: { freezeAfterSeconds: 5 },
     template: 'python-ml',
   },
   {
-    userKey: 'build-runner',
+    externalId: 'build-runner',
     policy: { freezeAfterSeconds: 3, stopAfterSeconds: 8 },
   },
   {
-    userKey: 'docs-writer',
+    externalId: 'docs-writer',
     policy: { freezeAfterSeconds: 5 },
     template: 'node-agent',
   },
   {
-    userKey: 'email-triage',
+    externalId: 'email-triage',
     policy: { freezeAfterSeconds: 600, stopAfterSeconds: null },
   },
   {
-    userKey: 'ci-check',
+    externalId: 'ci-check',
     policy: { freezeAfterSeconds: 4, stopAfterSeconds: 10 },
   },
   {
-    userKey: 'data-pipeline',
+    externalId: 'data-pipeline',
     policy: { freezeAfterSeconds: 900 },
     template: 'python-ml',
   },
-  { userKey: 'scratch' },
+  { externalId: 'scratch' },
 ];
-for (const { userKey, policy, template } of sandboxes) {
+for (const { externalId, policy, template } of sandboxes) {
   await rpc('/acquireSandbox', {
-    userKey,
+    externalId,
     ...(policy ? { policy } : {}),
     ...(template ? { template } : {}),
   });
-  console.log(`沙箱  ${userKey}`);
+  console.log(`沙箱  ${externalId}`);
 }
 
 // ---- 文件(给文件浏览器一些可看的内容)---------------------------------
diff --git a/packages/console/src/components/AppShell.tsx b/packages/console/src/components/AppShell.tsx
index 026c48f..99d6f95 100644
--- a/packages/console/src/components/AppShell.tsx
+++ b/packages/console/src/components/AppShell.tsx
@@ -16,7 +16,7 @@ import {
   SidebarTrigger,
 } from '@/components/ui/sidebar';
 
-// 路径段 → 中文名。没在表里的段(比如 userKey)原样展示 — 它就是名字本身。
+// 路径段 → 中文名。没在表里的段(比如 externalId)原样展示 — 它就是名字本身。
 const SEGMENT_LABELS: Record<string, string> = {
   sandboxes: '沙箱',
   templates: '模板',
diff --git a/packages/console/src/components/CommandMenu.tsx b/packages/console/src/components/CommandMenu.tsx
index 362f97f..b3ec778 100644
--- a/packages/console/src/components/CommandMenu.tsx
+++ b/packages/console/src/components/CommandMenu.tsx
@@ -26,7 +26,7 @@ import { MOCK_PAGES_ENABLED } from '@/lib/mock';
  * hook 不能条件调用,但组件可以条件挂载。缓存和列表页共享同一个 key,
  * 打开面板时多半直接命中。
  */
-function SandboxItems({ onGo }: { onGo: (userKey: string) => void }) {
+function SandboxItems({ onGo }: { onGo: (externalId: string) => void }) {
   const query = useSandboxes();
   const sandboxes = query.data?.sandboxes ?? [];
   if (sandboxes.length === 0) return null;
@@ -35,11 +35,11 @@ function SandboxItems({ onGo }: { onGo: (userKey: string) => void }) {
       {sandboxes.map((sandbox) => (
         <CommandItem
           key={sandbox.sandboxId}
-          value={`sandbox ${sandbox.userKey}`}
-          onSelect={() => onGo(sandbox.userKey)}
+          value={`sandbox ${sandbox.externalId}`}
+          onSelect={() => onGo(sandbox.externalId)}
         >
           <HugeiconsIcon icon={PackageIcon} strokeWidth={1.8} />
-          <span className="font-mono">{sandbox.userKey}</span>
+          <span className="font-mono">{sandbox.externalId}</span>
           <span className="ml-auto text-xs text-muted-foreground">
             {STATE_LABELS[sandbox.state]}
           </span>
@@ -50,8 +50,8 @@ function SandboxItems({ onGo }: { onGo: (userKey: string) => void }) {
 }
 
 /**
- * ⌘K / Ctrl+K 命令面板:跳页面、按 userKey 跳沙箱。挂在 AppShell 上,
- * 登录后全站可用;它只做导航 — 动作(释放/重建)留在各自页面的确认
+ * ⌘K / Ctrl+K 命令面板:跳页面、按 externalId 跳沙箱。挂在 AppShell 上,
+ * 登录后全站可用;它只做导航 — 动作(销毁/重建)留在各自页面的确认
  * 流程里,快捷键不该绕过"删了就没有了"的那道闸。
  */
 export function CommandMenu() {
@@ -73,11 +73,11 @@ export function CommandMenu() {
     setOpen(false);
     void navigate({ to });
   };
-  const goSandbox = (userKey: string) => {
+  const goSandbox = (externalId: string) => {
     setOpen(false);
     void navigate({
-      to: '/sandboxes/$userKey',
-      params: { userKey },
+      to: '/sandboxes/$externalId',
+      params: { externalId },
       search: { tab: 'overview' },
     });
   };
diff --git a/packages/console/src/features/activity/hooks/useActivity.ts b/packages/console/src/features/activity/hooks/useActivity.ts
index 760ebf9..e6fd931 100644
--- a/packages/console/src/features/activity/hooks/useActivity.ts
+++ b/packages/console/src/features/activity/hooks/useActivity.ts
@@ -5,7 +5,7 @@ import { listActivity } from '@/lib/api';
  * 活动流是观察窗:5 秒轮询即可 — 事件写在动作发生处,读只是翻账本,
  * 比沙箱列表的 2 秒松一档(历史不像状态那样急着看)。
  *
- * limit 缺省用 wire 默认(200);详情页历史 tab 要按 userKey 过滤,
+ * limit 缺省用 wire 默认(200);详情页历史 tab 要按 externalId 过滤,
  * 传环形表上限(1000)把一个沙箱的事件尽量捞全。
  */
 export function useActivity(limit?: number) {
diff --git a/packages/console/src/features/activity/kinds.ts b/packages/console/src/features/activity/kinds.ts
index 44150a5..29a57f1 100644
--- a/packages/console/src/features/activity/kinds.ts
+++ b/packages/console/src/features/activity/kinds.ts
@@ -10,7 +10,7 @@ export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
   frozen: '冻结',
   stopped: '停止',
   rebuilt: '重建',
-  released: '释放',
+  destroyed: '销毁',
   'expired-killed': '到期销毁',
   archived: '归档',
   'restore-started': '开始恢复',
@@ -33,7 +33,7 @@ export const ACTIVITY_KIND_STYLES: Record<ActivityKind, string> = {
   stopped: 'border-border bg-muted text-muted-foreground',
   rebuilt:
     'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
-  released: 'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
+  destroyed: 'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
   'expired-killed':
     'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
   archived:
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index fe64762..21d54cb 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -51,7 +51,7 @@ export function ActivityPage() {
         (event) =>
           (kindFilter === 'all' || event.kind === kindFilter) &&
           (search === '' ||
-            (event.userKey ?? '').toLowerCase().includes(search.toLowerCase())),
+            (event.externalId ?? '').toLowerCase().includes(search.toLowerCase())),
       ),
     [events, kindFilter, search],
   );
@@ -77,7 +77,7 @@ export function ActivityPage() {
           <InputGroupInput
             value={search}
             onChange={(event) => setSearch(event.target.value)}
-            placeholder="按 userKey 搜索"
+            placeholder="按 externalId 搜索"
           />
         </InputGroup>
         <NativeSelect
@@ -137,7 +137,7 @@ export function ActivityPage() {
               <TableRow>
                 <TableHead className="w-28">时间</TableHead>
                 <TableHead className="w-28">事件</TableHead>
-                <TableHead className="w-40">userKey</TableHead>
+                <TableHead className="w-40">externalId</TableHead>
                 <TableHead>详情</TableHead>
               </TableRow>
             </TableHeader>
@@ -163,14 +163,14 @@ export function ActivityPage() {
                     </Badge>
                   </TableCell>
                   <TableCell>
-                    {event.userKey ? (
+                    {event.externalId ? (
                       <Link
-                        to="/sandboxes/$userKey"
-                        params={{ userKey: event.userKey }}
+                        to="/sandboxes/$externalId"
+                        params={{ externalId: event.externalId }}
                         search={{ tab: 'overview' as const }}
                         className="font-mono hover:underline"
                       >
-                        {event.userKey}
+                        {event.externalId}
                       </Link>
                     ) : (
                       <span className="text-muted-foreground">—</span>
diff --git a/packages/console/src/features/connect/pages/ConnectPage.tsx b/packages/console/src/features/connect/pages/ConnectPage.tsx
index 76674d1..ab4ba46 100644
--- a/packages/console/src/features/connect/pages/ConnectPage.tsx
+++ b/packages/console/src/features/connect/pages/ConnectPage.tsx
@@ -51,8 +51,8 @@ const sandbox = await Sandbox.create({
   apiKey: 'e2b_<your API token>',
   apiUrl: '${origin}/e2b/api',
   sandboxUrl: '${origin}/e2b/envd',
-  // Dormice 扩展:同一个 userKey 永远回到同一个沙箱。
-  metadata: { userKey: 'my-project' },
+  // Dormice 扩展:同一个 externalId 永远回到同一个沙箱。
+  metadata: { externalId: 'my-project' },
 });
 
 const result = await sandbox.commands.run('echo hello from dormice');`;
diff --git a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
index 8f81dc1..8aeb314 100644
--- a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
+++ b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
@@ -45,7 +45,7 @@ import { useAcquireSandbox } from '../hooks/useSandboxes';
  */
 export function CreateSandboxDialog() {
   const [open, setOpen] = useState(false);
-  const [userKey, setUserKey] = useState('');
+  const [externalId, setExternalId] = useState('');
   const [template, setTemplate] = useState('');
   const [freezeAfter, setFreezeAfter] = useState('');
   const [neverStop, setNeverStop] = useState(false);
@@ -57,7 +57,7 @@ export function CreateSandboxDialog() {
   const archive = useConfig().data?.archive;
 
   const reset = () => {
-    setUserKey('');
+    setExternalId('');
     setTemplate('');
     setFreezeAfter('');
     setNeverStop(false);
@@ -80,13 +80,13 @@ export function CreateSandboxDialog() {
 
     mutation.mutate(
       {
-        userKey,
+        externalId,
         ...(template !== '' ? { template } : {}),
         ...(Object.keys(policy).length > 0 ? { policy } : {}),
       },
       {
         onSuccess: ({ sandbox }) => {
-          toast.success(`「${sandbox.userKey}」的沙箱已就绪`);
+          toast.success(`「${sandbox.externalId}」的沙箱已就绪`);
           setOpen(false);
           reset();
         },
@@ -126,11 +126,11 @@ export function CreateSandboxDialog() {
         >
           <FieldGroup>
             <Field>
-              <FieldLabel htmlFor="create-user-key">userKey</FieldLabel>
+              <FieldLabel htmlFor="create-user-key">externalId</FieldLabel>
               <Input
                 id="create-user-key"
-                value={userKey}
-                onChange={(event) => setUserKey(event.target.value)}
+                value={externalId}
+                onChange={(event) => setExternalId(event.target.value)}
                 placeholder="my-agent"
                 maxLength={128}
                 className="font-mono"
@@ -249,7 +249,7 @@ export function CreateSandboxDialog() {
           <DialogFooter className="mt-6">
             <Button
               type="submit"
-              disabled={userKey.length === 0 || mutation.isPending}
+              disabled={externalId.length === 0 || mutation.isPending}
             >
               {mutation.isPending && <Spinner />}
               创建
diff --git a/packages/console/src/features/sandboxes/components/ReleaseSandboxButton.tsx b/packages/console/src/features/sandboxes/components/DestroySandboxButton.tsx
similarity index 65%
rename from packages/console/src/features/sandboxes/components/ReleaseSandboxButton.tsx
rename to packages/console/src/features/sandboxes/components/DestroySandboxButton.tsx
index 6d6ede2..fd73f3b 100644
--- a/packages/console/src/features/sandboxes/components/ReleaseSandboxButton.tsx
+++ b/packages/console/src/features/sandboxes/components/DestroySandboxButton.tsx
@@ -12,28 +12,28 @@ import {
 } from '@/components/ui/alert-dialog';
 import { Button } from '@/components/ui/button';
 import { Spinner } from '@/components/ui/spinner';
-import { useReleaseSandbox } from '../hooks/useSandboxes';
+import { useDestroySandbox } from '../hooks/useSandboxes';
 
 /**
- * Release destroys the sandbox AND its disk — the one irreversible action in
+ * Destroy removes the sandbox AND its disk — the one irreversible action in
  * the console, so it is the one action behind a confirmation dialog.
  */
-export function ReleaseSandboxButton({
-  userKey,
-  onReleased,
+export function DestroySandboxButton({
+  externalId,
+  onDestroyed,
 }: {
-  userKey: string;
-  onReleased?: () => void;
+  externalId: string;
+  onDestroyed?: () => void;
 }) {
-  const mutation = useReleaseSandbox();
+  const mutation = useDestroySandbox();
 
-  const release = () =>
-    mutation.mutate(userKey, {
-      onSuccess: ({ released }) => {
+  const destroy = () =>
+    mutation.mutate(externalId, {
+      onSuccess: ({ destroyed }) => {
         toast.success(
-          released ? `已释放 ${userKey}` : `${userKey} 本来就不存在`,
+          destroyed ? `已销毁 ${externalId}` : `${externalId} 本来就不存在`,
         );
-        onReleased?.();
+        onDestroyed?.();
       },
       onError: (error) => toast.error(error.message),
     });
@@ -44,13 +44,13 @@ export function ReleaseSandboxButton({
         render={
           <Button variant="destructive" size="sm" disabled={mutation.isPending}>
             {mutation.isPending && <Spinner />}
-            释放
+            销毁
           </Button>
         }
       />
       <AlertDialogContent>
         <AlertDialogHeader>
-          <AlertDialogTitle>释放「{userKey}」?</AlertDialogTitle>
+          <AlertDialogTitle>销毁「{externalId}」?</AlertDialogTitle>
           <AlertDialogDescription>
             沙箱连同磁盘一起销毁,不可恢复。key 依然有效 — 下次 acquire
             会得到一个全新的空白沙箱。
@@ -58,8 +58,8 @@ export function ReleaseSandboxButton({
         </AlertDialogHeader>
         <AlertDialogFooter>
           <AlertDialogCancel>先留着</AlertDialogCancel>
-          <AlertDialogAction variant="destructive" onClick={release}>
-            释放
+          <AlertDialogAction variant="destructive" onClick={destroy}>
+            销毁
           </AlertDialogAction>
         </AlertDialogFooter>
       </AlertDialogContent>
diff --git a/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx b/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
index 462a7f4..3897197 100644
--- a/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
+++ b/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
@@ -25,12 +25,12 @@ import { Spinner } from '@/components/ui/spinner';
 import { Switch } from '@/components/ui/switch';
 import { useConfig } from '@/features/settings/hooks/useConfig';
 import { durationHint } from '../format';
-import { useSetPolicy } from '../hooks/useSandboxes';
+import { useUpdatePolicy } from '../hooks/useSandboxes';
 
 /**
- * acquire 只在创建时收策略,这个弹窗是之后的正门:setPolicy 纯改账本,
+ * acquire 只在创建时收策略,这个弹窗是之后的正门:updatePolicy 纯改账本,
  * 不唤醒、不重置空闲时钟 — 把跑了几天的沙箱升格成常驻 agent 不再需要
- * 释放重建(那会销毁磁盘)。三个旋钮整体提交:界面上看到什么就写下什么,
+ * 销毁重建(那会销毁磁盘)。三个旋钮整体提交:界面上看到什么就写下什么,
  * 关掉"永不停止"时归档旋钮的取舍也一并说清,不留隐式合并的悬念。
  */
 export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
@@ -40,7 +40,7 @@ export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
   const [stopAfter, setStopAfter] = useState('');
   const [neverArchive, setNeverArchive] = useState(false);
   const [archiveAfter, setArchiveAfter] = useState('');
-  const mutation = useSetPolicy();
+  const mutation = useUpdatePolicy();
   const archive = useConfig().data?.archive;
 
   // 每次打开都从沙箱的现值起步 — 编辑的是"现在是什么",不是空表单。
@@ -63,7 +63,7 @@ export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
   const submit = () => {
     mutation.mutate(
       {
-        userKey: sandbox.userKey,
+        externalId: sandbox.externalId,
         policy: {
           freezeAfterSeconds: Number(freezeAfter),
           stopAfterSeconds: neverStop ? null : Number(stopAfter),
@@ -79,7 +79,7 @@ export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
       },
       {
         onSuccess: () => {
-          toast.success(`「${sandbox.userKey}」的策略已更新`);
+          toast.success(`「${sandbox.externalId}」的策略已更新`);
           setOpen(false);
         },
       },
@@ -110,7 +110,7 @@ export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
       />
       <DialogContent className="sm:max-w-md">
         <DialogHeader>
-          <DialogTitle>调整「{sandbox.userKey}」的生命周期策略</DialogTitle>
+          <DialogTitle>调整「{sandbox.externalId}」的生命周期策略</DialogTitle>
           <DialogDescription>
             立即生效,只改账本 — 沉睡的沙箱不会被吵醒,空闲计时也不重置
             (新阈值按已累积的空闲时间判定)。
diff --git a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
index 6cc29dc..1a374cd 100644
--- a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
@@ -27,13 +27,13 @@ import { since } from '../format';
 
 /**
  * 「我的沙箱昨晚为什么停了」— 活动环里只属于这个沙箱的那几行。纯前端
- * 过滤:活动事件本来就带 userKey,不发明新端点;按环形表上限(1000)
+ * 过滤:活动事件本来就带 externalId,不发明新端点;按环形表上限(1000)
  * 拉取,把这个沙箱的事件尽量捞全,再老的已经滚出环了。
  */
-export function HistoryPanel({ userKey }: { userKey: string }) {
+export function HistoryPanel({ externalId }: { externalId: string }) {
   const { data, isPending, isError, error } = useActivity(1000);
   const events = (data?.events ?? []).filter(
-    (event) => event.userKey === userKey,
+    (event) => event.externalId === externalId,
   );
 
   if (isPending) {
@@ -109,7 +109,7 @@ export function HistoryPanel({ userKey }: { userKey: string }) {
         </Table>
       </div>
       <p className="text-sm text-muted-foreground">
-        释放沙箱后 key 会重新可用 — 这里可能同时看到新旧两代沙箱的事件。
+        销毁沙箱后 key 会重新可用 — 这里可能同时看到新旧两代沙箱的事件。
       </p>
     </div>
   );
diff --git a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
index 7b43369..d24f311 100644
--- a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
@@ -183,7 +183,7 @@ function HistoryChart({
  */
 export function MetricsPanel({ sandbox }: { sandbox: Sandbox }) {
   const { data, isPending, isError, error } = useSandboxMetrics(
-    sandbox.userKey,
+    sandbox.externalId,
   );
   // Hook 在任何 early return 之前:面板打开期间持续累积,换沙箱清零。
   const history = useSampleHistory(sandbox.sandboxId, data?.sample);
diff --git a/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx b/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx
index 0876a2c..90976a6 100644
--- a/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx
+++ b/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx
@@ -19,14 +19,14 @@ import { useRebuildSandbox } from '../hooks/useSandboxes';
  * does kill everything running inside and resets anything installed outside
  * the home directory, so it still asks first.
  */
-export function RebuildSandboxButton({ userKey }: { userKey: string }) {
+export function RebuildSandboxButton({ externalId }: { externalId: string }) {
   const mutation = useRebuildSandbox();
 
   const rebuild = () =>
-    mutation.mutate(userKey, {
+    mutation.mutate(externalId, {
       onSuccess: () =>
         toast.success(
-          `已重建 ${userKey} — /home/user 保留,下次使用跑在当前镜像上`,
+          `已重建 ${externalId} — /home/user 保留,下次使用跑在当前镜像上`,
         ),
       onError: (error) => toast.error(error.message),
     });
@@ -43,7 +43,7 @@ export function RebuildSandboxButton({ userKey }: { userKey: string }) {
       />
       <AlertDialogContent>
         <AlertDialogHeader>
-          <AlertDialogTitle>重建「{userKey}」?</AlertDialogTitle>
+          <AlertDialogTitle>重建「{externalId}」?</AlertDialogTitle>
           <AlertDialogDescription>
             换壳保盘:下次使用跑在 daemon 当前的镜像上。/home/user 一字节
             不丢;正在跑的进程和家目录之外的改动随旧壳蒸发。
diff --git a/packages/console/src/features/sandboxes/components/RestoreCard.tsx b/packages/console/src/features/sandboxes/components/RestoreCard.tsx
index 2fd10fa..705f4e7 100644
--- a/packages/console/src/features/sandboxes/components/RestoreCard.tsx
+++ b/packages/console/src/features/sandboxes/components/RestoreCard.tsx
@@ -21,14 +21,14 @@ export function RestoreCard({ sandbox }: { sandbox: Sandbox }) {
   const restoring = sandbox.state === 'restoring';
 
   const progressQuery = useQuery({
-    queryKey: ['restore-progress', sandbox.userKey],
-    queryFn: () => acquireSandbox({ userKey: sandbox.userKey }),
+    queryKey: ['restore-progress', sandbox.externalId],
+    queryFn: () => acquireSandbox({ externalId: sandbox.externalId }),
     enabled: restoring,
     refetchInterval: 1500,
     retry: false,
   });
   const begin = useMutation({
-    mutationFn: () => acquireSandbox({ userKey: sandbox.userKey }),
+    mutationFn: () => acquireSandbox({ externalId: sandbox.externalId }),
     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
     onError: (error) => toast.error(`恢复没能开始:${error.message}`),
   });
@@ -49,7 +49,7 @@ export function RestoreCard({ sandbox }: { sandbox: Sandbox }) {
           </div>
           <Progress value={progress?.percent ?? 0} />
           <p className="text-xs text-muted-foreground">
-            恢复完成后自动回到「运行中」;期间释放会被拒绝(409),等它跑完。
+            恢复完成后自动回到「运行中」;期间销毁会被拒绝(409),等它跑完。
           </p>
         </CardContent>
       </Card>
diff --git a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
index f80d016..5296247 100644
--- a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
+++ b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
@@ -6,8 +6,8 @@ import {
   listSandboxes,
   listSandboxMetrics,
   rebuildSandbox,
-  releaseSandbox,
-  setPolicy,
+  destroySandbox,
+  updatePolicy,
 } from '@/lib/api';
 
 /**
@@ -27,11 +27,11 @@ export function useSandboxes() {
   });
 }
 
-export function useSandbox(userKey: string) {
+export function useSandbox(externalId: string) {
   const query = useSandboxes();
   return {
     ...query,
-    sandbox: query.data?.sandboxes.find((s) => s.userKey === userKey),
+    sandbox: query.data?.sandboxes.find((s) => s.externalId === externalId),
   };
 }
 
@@ -39,10 +39,10 @@ export function useSandbox(userKey: string) {
  * 单沙箱指标,5 秒一拍。观察不唤醒:停着的沙箱答 sample: null,面板
  * 据此出空态而不是把沙箱吵醒。只在指标 tab 挂载时才跑(面板卸载即停)。
  */
-export function useSandboxMetrics(userKey: string) {
+export function useSandboxMetrics(externalId: string) {
   return useQuery({
-    queryKey: ['sandbox-metrics', userKey],
-    queryFn: () => getSandboxMetrics(userKey),
+    queryKey: ['sandbox-metrics', externalId],
+    queryFn: () => getSandboxMetrics(externalId),
     refetchInterval: 5000,
     retry: false,
   });
@@ -71,11 +71,11 @@ export function useAcquireSandbox() {
   });
 }
 
-export function useSetPolicy() {
+export function useUpdatePolicy() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: (args: { userKey: string; policy: LifecyclePolicyOverride }) =>
-      setPolicy(args.userKey, args.policy),
+    mutationFn: (args: { externalId: string; policy: LifecyclePolicyOverride }) =>
+      updatePolicy(args.externalId, args.policy),
     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
   });
 }
@@ -83,15 +83,15 @@ export function useSetPolicy() {
 export function useRebuildSandbox() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: (userKey: string) => rebuildSandbox(userKey),
+    mutationFn: (externalId: string) => rebuildSandbox(externalId),
     onSettled: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
   });
 }
 
-export function useReleaseSandbox() {
+export function useDestroySandbox() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: (userKey: string) => releaseSandbox(userKey),
+    mutationFn: (externalId: string) => destroySandbox(externalId),
     onSettled: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
   });
 }
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index 6c68b59..4394816 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -22,7 +22,7 @@ import { LifecycleCountdown } from '../components/LifecycleCountdown';
 import { MetricsPanel } from '../components/MetricsPanel';
 import { ProcessesPanel } from '../components/ProcessesPanel';
 import { RebuildSandboxButton } from '../components/RebuildSandboxButton';
-import { ReleaseSandboxButton } from '../components/ReleaseSandboxButton';
+import { DestroySandboxButton } from '../components/DestroySandboxButton';
 import { RestoreCard } from '../components/RestoreCard';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
 import { SandboxTerminalCard } from '../components/SandboxTerminal';
@@ -54,18 +54,18 @@ function Row({ label, children }: { label: string; children: ReactNode }) {
  * SDK 同一条 wire。tab 记在 URL 里,刷新与分享都停在原面板。
  */
 export function SandboxDetailPage() {
-  const { userKey } = useParams({ from: '/_app/sandboxes/$userKey' });
-  const { tab } = useSearch({ from: '/_app/sandboxes/$userKey' });
-  const navigate = useNavigate({ from: '/sandboxes/$userKey' });
-  const { sandbox, isSuccess } = useSandbox(userKey);
+  const { externalId } = useParams({ from: '/_app/sandboxes/$externalId' });
+  const { tab } = useSearch({ from: '/_app/sandboxes/$externalId' });
+  const navigate = useNavigate({ from: '/sandboxes/$externalId' });
+  const { sandbox, isSuccess } = useSandbox(externalId);
 
   if (!sandbox) {
     return isSuccess ? (
       <Empty className="border border-dashed">
         <EmptyHeader>
-          <EmptyTitle>没有叫「{userKey}」的沙箱</EmptyTitle>
+          <EmptyTitle>没有叫「{externalId}」的沙箱</EmptyTitle>
           <EmptyDescription>
-            可能已被释放 — 这个 key 依然有效,下次 acquire 会得到一个
+            可能已被销毁 — 这个 key 依然有效,下次 acquire 会得到一个
             全新的沙箱。
           </EmptyDescription>
         </EmptyHeader>
@@ -87,16 +87,16 @@ export function SandboxDetailPage() {
     <>
       <div className="flex flex-wrap items-center justify-between gap-3">
         <div className="flex items-center gap-3">
-          <h1 className="font-mono text-lg font-semibold">{sandbox.userKey}</h1>
+          <h1 className="font-mono text-lg font-semibold">{sandbox.externalId}</h1>
           <SandboxStateBadge state={sandbox.state} />
           <LifecycleCountdown sandbox={sandbox} />
         </div>
         <div className="flex items-center gap-2">
           <EditPolicyDialog sandbox={sandbox} />
-          <RebuildSandboxButton userKey={sandbox.userKey} />
-          <ReleaseSandboxButton
-            userKey={sandbox.userKey}
-            onReleased={() => navigate({ to: '/sandboxes' })}
+          <RebuildSandboxButton externalId={sandbox.externalId} />
+          <DestroySandboxButton
+            externalId={sandbox.externalId}
+            onDestroyed={() => navigate({ to: '/sandboxes' })}
           />
         </div>
       </div>
@@ -171,7 +171,7 @@ export function SandboxDetailPage() {
         </TabsContent>
 
         <TabsContent value="history">
-          <HistoryPanel userKey={sandbox.userKey} />
+          <HistoryPanel externalId={sandbox.externalId} />
         </TabsContent>
       </Tabs>
     </>
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index 2e7b98f..aafab7b 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -48,12 +48,12 @@ import {
   TableHeader,
   TableRow,
 } from '@/components/ui/table';
-import { releaseSandbox } from '@/lib/api';
+import { destroySandbox } from '@/lib/api';
 import { formatBytes, pctOf } from '@/lib/format';
 import { queryClient } from '@/lib/queryClient';
 import { cn } from '@/lib/utils';
 import { CreateSandboxDialog } from '../components/CreateSandboxDialog';
-import { ReleaseSandboxButton } from '../components/ReleaseSandboxButton';
+import { DestroySandboxButton } from '../components/DestroySandboxButton';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
 import { policyLine, STATE_LABELS, since } from '../format';
 import { useFleetMetrics, useSandboxes } from '../hooks/useSandboxes';
@@ -66,8 +66,8 @@ const STATE_FILTERS: Array<SandboxState> = [
   'restoring',
 ];
 
-/** 可排序的列:字符串比较对 userKey 和 ISO 时间戳同样成立。 */
-type SortKey = 'userKey' | 'lastActiveAt' | 'createdAt';
+/** 可排序的列:字符串比较对 externalId 和 ISO 时间戳同样成立。 */
+type SortKey = 'externalId' | 'lastActiveAt' | 'createdAt';
 type Sort = { key: SortKey; dir: 1 | -1 };
 
 /**
@@ -137,34 +137,34 @@ function SortableHead({
 }
 
 /**
- * 批量释放:逐个调用 releaseSandbox(daemon 的 per-key 锁本来就是逐个
+ * 批量销毁:逐个调用 destroySandbox(daemon 的 per-key 锁本来就是逐个
  * 裁决的,并发只是把失败搅在一起),结束后一次性汇报成败。
  */
-function BulkReleaseButton({
-  userKeys,
+function BulkDestroyButton({
+  externalIds,
   onDone,
 }: {
-  userKeys: string[];
+  externalIds: string[];
   onDone: () => void;
 }) {
   const [pending, setPending] = useState(false);
 
-  const releaseAll = async () => {
+  const destroyAll = async () => {
     setPending(true);
     const failures: string[] = [];
-    for (const userKey of userKeys) {
+    for (const externalId of externalIds) {
       try {
-        await releaseSandbox(userKey);
+        await destroySandbox(externalId);
       } catch {
-        failures.push(userKey);
+        failures.push(externalId);
       }
     }
     setPending(false);
     void queryClient.invalidateQueries({ queryKey: ['sandboxes'] });
     if (failures.length === 0) {
-      toast.success(`已释放 ${userKeys.length} 个沙箱`);
+      toast.success(`已销毁  个沙箱`);
     } else {
-      toast.error(`${failures.length} 个释放失败:${failures.join('、')}`);
+      toast.error(`${failures.length} 个销毁失败:${failures.join('、')}`);
     }
     onDone();
   };
@@ -175,13 +175,13 @@ function BulkReleaseButton({
         render={
           <Button variant="destructive" size="sm" disabled={pending}>
             {pending && <Spinner />}
-            释放选中({userKeys.length})
+            销毁选中({externalIds.length})
           </Button>
         }
       />
       <AlertDialogContent>
         <AlertDialogHeader>
-          <AlertDialogTitle>释放 {userKeys.length} 个沙箱?</AlertDialogTitle>
+          <AlertDialogTitle>销毁 {externalIds.length} 个沙箱?</AlertDialogTitle>
           <AlertDialogDescription>
             沙箱连同磁盘一起销毁,不可恢复。key 依然有效 — 下次 acquire
             会得到一个全新的空白沙箱。
@@ -189,8 +189,8 @@ function BulkReleaseButton({
         </AlertDialogHeader>
         <AlertDialogFooter>
           <AlertDialogCancel>先留着</AlertDialogCancel>
-          <AlertDialogAction variant="destructive" onClick={releaseAll}>
-            释放
+          <AlertDialogAction variant="destructive" onClick={destroyAll}>
+            销毁
           </AlertDialogAction>
         </AlertDialogFooter>
       </AlertDialogContent>
@@ -205,7 +205,7 @@ export function SandboxesPage() {
   const fleet = useFleetMetrics();
   const metricsOf = useMemo(
     () =>
-      new Map((fleet.data?.samples ?? []).map((s) => [s.userKey, s.sample])),
+      new Map((fleet.data?.samples ?? []).map((s) => [s.externalId, s.sample])),
     [fleet.data],
   );
   const [search, setSearch] = useState('');
@@ -225,7 +225,7 @@ export function SandboxesPage() {
       (sandbox) =>
         (stateFilter === 'all' || sandbox.state === stateFilter) &&
         (search === '' ||
-          sandbox.userKey.toLowerCase().includes(search.toLowerCase())),
+          sandbox.externalId.toLowerCase().includes(search.toLowerCase())),
     );
     if (!sort) return matched;
     return [...matched].sort(
@@ -233,21 +233,21 @@ export function SandboxesPage() {
     );
   }, [sandboxes, stateFilter, search, sort]);
 
-  // 选中集随现实收敛:被别处释放的沙箱不该留在选中里撑数字。
-  const selectedVisible = filtered.filter((s) => selected.has(s.userKey));
+  // 选中集随现实收敛:被别处销毁的沙箱不该留在选中里撑数字。
+  const selectedVisible = filtered.filter((s) => selected.has(s.externalId));
   const allVisibleSelected =
     filtered.length > 0 && selectedVisible.length === filtered.length;
 
   const toggleAll = () => {
     setSelected(
-      allVisibleSelected ? new Set() : new Set(filtered.map((s) => s.userKey)),
+      allVisibleSelected ? new Set() : new Set(filtered.map((s) => s.externalId)),
     );
   };
-  const toggleOne = (userKey: string) => {
+  const toggleOne = (externalId: string) => {
     setSelected((prev) => {
       const next = new Set(prev);
-      if (next.has(userKey)) next.delete(userKey);
-      else next.add(userKey);
+      if (next.has(externalId)) next.delete(externalId);
+      else next.add(externalId);
       return next;
     });
   };
@@ -275,7 +275,7 @@ export function SandboxesPage() {
           <InputGroupInput
             value={search}
             onChange={(event) => setSearch(event.target.value)}
-            placeholder="按 userKey 搜索"
+            placeholder="按 externalId 搜索"
           />
         </InputGroup>
         <NativeSelect
@@ -297,8 +297,8 @@ export function SandboxesPage() {
         </span>
         {selectedVisible.length > 0 && (
           <div className="ml-auto">
-            <BulkReleaseButton
-              userKeys={selectedVisible.map((s) => s.userKey)}
+            <BulkDestroyButton
+              externalIds={selectedVisible.map((s) => s.externalId)}
               onDone={() => setSelected(new Set())}
             />
           </div>
@@ -348,8 +348,8 @@ export function SandboxesPage() {
                 </TableHead>
                 <TableHead>
                   <SortableHead
-                    label="userKey"
-                    sortKey="userKey"
+                    label="externalId"
+                    sortKey="externalId"
                     sort={sort}
                     onSort={toggleSort}
                   />
@@ -385,24 +385,24 @@ export function SandboxesPage() {
                 <TableRow
                   key={sandbox.sandboxId}
                   data-state={
-                    selected.has(sandbox.userKey) ? 'selected' : undefined
+                    selected.has(sandbox.externalId) ? 'selected' : undefined
                   }
                 >
                   <TableCell>
                     <Checkbox
-                      aria-label={`选中 ${sandbox.userKey}`}
-                      checked={selected.has(sandbox.userKey)}
-                      onCheckedChange={() => toggleOne(sandbox.userKey)}
+                      aria-label={`选中 ${sandbox.externalId}`}
+                      checked={selected.has(sandbox.externalId)}
+                      onCheckedChange={() => toggleOne(sandbox.externalId)}
                     />
                   </TableCell>
                   <TableCell>
                     <Link
-                      to="/sandboxes/$userKey"
-                      params={{ userKey: sandbox.userKey }}
+                      to="/sandboxes/$externalId"
+                      params={{ externalId: sandbox.externalId }}
                       search={{ tab: 'overview' }}
                       className="font-mono font-medium hover:underline"
                     >
-                      {sandbox.userKey}
+                      {sandbox.externalId}
                     </Link>
                   </TableCell>
                   <TableCell>
@@ -412,7 +412,7 @@ export function SandboxesPage() {
                     {sandbox.template ?? '基础镜像'}
                   </TableCell>
                   {(() => {
-                    const m = metricsOf.get(sandbox.userKey);
+                    const m = metricsOf.get(sandbox.externalId);
                     if (!m) {
                       return (
                         <>
@@ -458,7 +458,7 @@ export function SandboxesPage() {
                     {since(sandbox.createdAt)}
                   </TableCell>
                   <TableCell className="text-right">
-                    <ReleaseSandboxButton userKey={sandbox.userKey} />
+                    <DestroySandboxButton externalId={sandbox.externalId} />
                   </TableCell>
                 </TableRow>
               ))}
diff --git a/packages/console/src/features/templates/pages/TemplatesPage.tsx b/packages/console/src/features/templates/pages/TemplatesPage.tsx
index ed0c47b..5b7c929 100644
--- a/packages/console/src/features/templates/pages/TemplatesPage.tsx
+++ b/packages/console/src/features/templates/pages/TemplatesPage.tsx
@@ -173,7 +173,7 @@ function RemoveTemplateButton({ name }: { name: string }) {
         toast.success(
           removed ? `已删除「${name}」` : `「${name}」本来就不存在`,
         ),
-      // 还有沙箱引用时 daemon 回 409 并点名 userKey — 原文转达。
+      // 还有沙箱引用时 daemon 回 409 并点名 externalId — 原文转达。
       onError: (error) => toast.error(error.message),
     });
 
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index fbd6756..b9c3586 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -115,8 +115,8 @@ export const getHostMetrics = () => rpc<HostMetricsResponse>('/getHostMetrics');
 
 // One sandbox's point-in-time reading. Same principle: a frozen sandbox is
 // measured as it sleeps, a stopped one answers sample: null — never woken.
-export const getSandboxMetrics = (userKey: string) =>
-  rpc<GetSandboxMetricsResponse>('/getSandboxMetrics', { userKey });
+export const getSandboxMetrics = (externalId: string) =>
+  rpc<GetSandboxMetricsResponse>('/getSandboxMetrics', { externalId });
 
 // Every measurable sandbox in one answer — the list view's food. Presence
 // means measured: colder states are simply absent.
@@ -159,18 +159,18 @@ export const removeTemplate = (name: string) =>
 export const acquireSandbox = (request: AcquireRequest) =>
   rpc<AcquireResponse>('/acquireSandbox', request);
 
-export const releaseSandbox = (userKey: string) =>
-  rpc<{ released: boolean }>('/releaseSandbox', { userKey });
+export const destroySandbox = (externalId: string) =>
+  rpc<{ destroyed: boolean }>('/destroySandbox', { externalId });
 
 // Swap the container, keep /home/user: the next use starts on the daemon's
 // current base image.
-export const rebuildSandbox = (userKey: string) =>
-  rpc<{ sandbox: Sandbox }>('/rebuildSandbox', { userKey });
+export const rebuildSandbox = (externalId: string) =>
+  rpc<{ sandbox: Sandbox }>('/rebuildSandbox', { externalId });
 
 // Patch the stored lifecycle policy in place — the update verb acquire is
 // not. Ledger-only: nothing wakes, the idle clock keeps running.
-export const setPolicy = (userKey: string, policy: LifecyclePolicyOverride) =>
-  rpc<{ sandbox: Sandbox }>('/setPolicy', { userKey, policy });
+export const updatePolicy = (externalId: string, policy: LifecyclePolicyOverride) =>
+  rpc<{ sandbox: Sandbox }>('/updatePolicy', { externalId, policy });
 
 // The terminal's key: trades the session cookie for one sandbox's envd
 // access token, so the browser can speak to the envd surface directly.
diff --git a/packages/console/src/routeTree.gen.ts b/packages/console/src/routeTree.gen.ts
index f2f5d61..8eff25b 100644
--- a/packages/console/src/routeTree.gen.ts
+++ b/packages/console/src/routeTree.gen.ts
@@ -19,7 +19,7 @@ import { Route as AppDoctorRouteImport } from './routes/_app/doctor'
 import { Route as AppConnectRouteImport } from './routes/_app/connect'
 import { Route as AppActivityRouteImport } from './routes/_app/activity'
 import { Route as AppSandboxesIndexRouteImport } from './routes/_app/sandboxes/index'
-import { Route as AppSandboxesUserKeyRouteImport } from './routes/_app/sandboxes/$userKey'
+import { Route as AppSandboxesExternalIdRouteImport } from './routes/_app/sandboxes/$externalId'
 
 const LoginRoute = LoginRouteImport.update({
   id: '/login',
@@ -70,9 +70,9 @@ const AppSandboxesIndexRoute = AppSandboxesIndexRouteImport.update({
   path: '/sandboxes/',
   getParentRoute: () => AppRoute,
 } as any)
-const AppSandboxesUserKeyRoute = AppSandboxesUserKeyRouteImport.update({
-  id: '/sandboxes/$userKey',
-  path: '/sandboxes/$userKey',
+const AppSandboxesExternalIdRoute = AppSandboxesExternalIdRouteImport.update({
+  id: '/sandboxes/$externalId',
+  path: '/sandboxes/$externalId',
   getParentRoute: () => AppRoute,
 } as any)
 
@@ -85,7 +85,7 @@ export interface FileRoutesByFullPath {
   '/domains': typeof AppDomainsRoute
   '/settings': typeof AppSettingsRoute
   '/templates': typeof AppTemplatesRoute
-  '/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
+  '/sandboxes/$externalId': typeof AppSandboxesExternalIdRoute
   '/sandboxes/': typeof AppSandboxesIndexRoute
 }
 export interface FileRoutesByTo {
@@ -97,7 +97,7 @@ export interface FileRoutesByTo {
   '/settings': typeof AppSettingsRoute
   '/templates': typeof AppTemplatesRoute
   '/': typeof AppIndexRoute
-  '/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
+  '/sandboxes/$externalId': typeof AppSandboxesExternalIdRoute
   '/sandboxes': typeof AppSandboxesIndexRoute
 }
 export interface FileRoutesById {
@@ -111,7 +111,7 @@ export interface FileRoutesById {
   '/_app/settings': typeof AppSettingsRoute
   '/_app/templates': typeof AppTemplatesRoute
   '/_app/': typeof AppIndexRoute
-  '/_app/sandboxes/$userKey': typeof AppSandboxesUserKeyRoute
+  '/_app/sandboxes/$externalId': typeof AppSandboxesExternalIdRoute
   '/_app/sandboxes/': typeof AppSandboxesIndexRoute
 }
 export interface FileRouteTypes {
@@ -125,7 +125,7 @@ export interface FileRouteTypes {
     | '/domains'
     | '/settings'
     | '/templates'
-    | '/sandboxes/$userKey'
+    | '/sandboxes/$externalId'
     | '/sandboxes/'
   fileRoutesByTo: FileRoutesByTo
   to:
@@ -137,7 +137,7 @@ export interface FileRouteTypes {
     | '/settings'
     | '/templates'
     | '/'
-    | '/sandboxes/$userKey'
+    | '/sandboxes/$externalId'
     | '/sandboxes'
   id:
     | '__root__'
@@ -150,7 +150,7 @@ export interface FileRouteTypes {
     | '/_app/settings'
     | '/_app/templates'
     | '/_app/'
-    | '/_app/sandboxes/$userKey'
+    | '/_app/sandboxes/$externalId'
     | '/_app/sandboxes/'
   fileRoutesById: FileRoutesById
 }
@@ -231,11 +231,11 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AppSandboxesIndexRouteImport
       parentRoute: typeof AppRoute
     }
-    '/_app/sandboxes/$userKey': {
-      id: '/_app/sandboxes/$userKey'
-      path: '/sandboxes/$userKey'
-      fullPath: '/sandboxes/$userKey'
-      preLoaderRoute: typeof AppSandboxesUserKeyRouteImport
+    '/_app/sandboxes/$externalId': {
+      id: '/_app/sandboxes/$externalId'
+      path: '/sandboxes/$externalId'
+      fullPath: '/sandboxes/$externalId'
+      preLoaderRoute: typeof AppSandboxesExternalIdRouteImport
       parentRoute: typeof AppRoute
     }
   }
@@ -249,7 +249,7 @@ interface AppRouteChildren {
   AppSettingsRoute: typeof AppSettingsRoute
   AppTemplatesRoute: typeof AppTemplatesRoute
   AppIndexRoute: typeof AppIndexRoute
-  AppSandboxesUserKeyRoute: typeof AppSandboxesUserKeyRoute
+  AppSandboxesExternalIdRoute: typeof AppSandboxesExternalIdRoute
   AppSandboxesIndexRoute: typeof AppSandboxesIndexRoute
 }
 
@@ -261,7 +261,7 @@ const AppRouteChildren: AppRouteChildren = {
   AppSettingsRoute: AppSettingsRoute,
   AppTemplatesRoute: AppTemplatesRoute,
   AppIndexRoute: AppIndexRoute,
-  AppSandboxesUserKeyRoute: AppSandboxesUserKeyRoute,
+  AppSandboxesExternalIdRoute: AppSandboxesExternalIdRoute,
   AppSandboxesIndexRoute: AppSandboxesIndexRoute,
 }
 
diff --git a/packages/console/src/routes/_app/sandboxes/$userKey.tsx b/packages/console/src/routes/_app/sandboxes/$externalId.tsx
similarity index 87%
rename from packages/console/src/routes/_app/sandboxes/$userKey.tsx
rename to packages/console/src/routes/_app/sandboxes/$externalId.tsx
index 92996a6..6e2092b 100644
--- a/packages/console/src/routes/_app/sandboxes/$userKey.tsx
+++ b/packages/console/src/routes/_app/sandboxes/$externalId.tsx
@@ -6,7 +6,7 @@ import {
 } from '@/features/sandboxes/pages/SandboxDetailPage';
 
 // tab 进 URL:刷新、分享、返回键都停在同一个工作区面板上。
-export const Route = createFileRoute('/_app/sandboxes/$userKey')({
+export const Route = createFileRoute('/_app/sandboxes/$externalId')({
   validateSearch: (search: Record<string, unknown>): { tab: DetailTab } => ({
     tab: DETAIL_TABS.includes(search.tab as DetailTab)
       ? (search.tab as DetailTab)
diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index 2797e35..7672c3c 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -25,10 +25,10 @@ export default defineConfig({
       '/console/auth': 'http://127.0.0.1:3676',
       '/console/envdToken': 'http://127.0.0.1:3676',
       '/listSandboxes': 'http://127.0.0.1:3676',
-      '/releaseSandbox': 'http://127.0.0.1:3676',
+      '/destroySandbox': 'http://127.0.0.1:3676',
       '/acquireSandbox': 'http://127.0.0.1:3676',
       '/rebuildSandbox': 'http://127.0.0.1:3676',
-      '/setPolicy': 'http://127.0.0.1:3676',
+      '/updatePolicy': 'http://127.0.0.1:3676',
       '/listTemplates': 'http://127.0.0.1:3676',
       '/registerTemplate': 'http://127.0.0.1:3676',
       '/removeTemplate': 'http://127.0.0.1:3676',
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 62cccf1..26bd9cb 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -166,7 +166,7 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
   it('lists sandboxes with their lifecycle states', async () => {
     await client.acquireSandbox('erin');
     const sandboxes = await client.listSandboxes();
-    const erin = sandboxes.find((s) => s.userKey === 'erin');
+    const erin = sandboxes.find((s) => s.externalId === 'erin');
     expect(erin?.state).toBe('active');
   });
 
@@ -216,7 +216,7 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
             authorization: `Bearer ${TOKEN}`,
             'content-type': 'application/json',
           },
-          body: JSON.stringify({ userKey: 'henry', command: 'sleep 1' }),
+          body: JSON.stringify({ externalId: 'henry', command: 'sleep 1' }),
         }),
       ).rejects.toThrow(/fetch failed/);
       // The SDK carries its own dispatcher, so the same call sails through.
@@ -294,7 +294,7 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
 
   it('patches a lifecycle policy in place, keeping the untouched knobs', async () => {
     const created = await client.acquireSandbox('policy-key');
-    const { sandbox } = await client.setPolicy('policy-key', {
+    const { sandbox } = await client.updatePolicy('policy-key', {
       stopAfterSeconds: null,
     });
     expect(sandbox.sandboxId).toBe(created.sandbox.sandboxId);
@@ -304,19 +304,19 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
     });
 
     await expect(
-      client.setPolicy('no-such-key', { freezeAfterSeconds: 60 }),
+      client.updatePolicy('no-such-key', { freezeAfterSeconds: 60 }),
     ).rejects.toMatchObject({ name: 'DormiceApiError', status: 404 });
     await expect(
       // Merged with the stored policy this breaks the ordering rule.
-      client.setPolicy('policy-key', { archiveAfterSeconds: 1 }),
+      client.updatePolicy('policy-key', { archiveAfterSeconds: 1 }),
     ).rejects.toMatchObject({ status: 400 });
   });
 
   it('releases a sandbox and reports idempotently', async () => {
     const created = await client.acquireSandbox('frank');
-    expect(await client.releaseSandbox('frank')).toEqual({ released: true });
+    expect(await client.destroySandbox('frank')).toEqual({ destroyed: true });
     expect(executor.stateOf(created.sandbox.sandboxId)).toBeUndefined();
-    expect(await client.releaseSandbox('frank')).toEqual({ released: false });
+    expect(await client.destroySandbox('frank')).toEqual({ destroyed: false });
 
     const again = await client.acquireSandbox('frank');
     expect(again.sandbox.sandboxId).not.toBe(created.sandbox.sandboxId);
@@ -343,7 +343,7 @@ describe('templates over real HTTP', () => {
       message: expect.stringMatching(/tpl-user/),
     });
 
-    await client.releaseSandbox('tpl-user');
+    await client.destroySandbox('tpl-user');
     expect(await client.removeTemplate('tpl-sdk')).toEqual({ removed: true });
     expect(await client.removeTemplate('tpl-sdk')).toEqual({ removed: false });
   });
@@ -374,7 +374,7 @@ describe('the observability verbs over real HTTP', () => {
     await client.acquireSandbox('metrics-sdk');
     const sample = await client.getSandboxMetrics('metrics-sdk');
     expect(sample?.memTotalBytes).toBeGreaterThan(0);
-    await client.releaseSandbox('metrics-sdk');
+    await client.destroySandbox('metrics-sdk');
 
     await expect(
       client.getSandboxMetrics('metrics-nobody'),
@@ -388,23 +388,23 @@ describe('the observability verbs over real HTTP', () => {
     await client.acquireSandbox('fleet-a');
     await client.acquireSandbox('fleet-b');
     const samples = await client.listSandboxMetrics();
-    const mine = samples.filter((s) => s.userKey.startsWith('fleet-'));
-    expect(mine.map((s) => s.userKey).sort()).toEqual(['fleet-a', 'fleet-b']);
+    const mine = samples.filter((s) => s.externalId.startsWith('fleet-'));
+    expect(mine.map((s) => s.externalId).sort()).toEqual(['fleet-a', 'fleet-b']);
     for (const entry of mine) {
       expect(entry.sample.memTotalBytes).toBeGreaterThan(0);
     }
-    await client.releaseSandbox('fleet-a');
-    await client.releaseSandbox('fleet-b');
+    await client.destroySandbox('fleet-a');
+    await client.destroySandbox('fleet-b');
     // Released means gone from the measurable set, not null-stuffed.
     const after = await client.listSandboxMetrics();
-    expect(after.filter((s) => s.userKey.startsWith('fleet-'))).toEqual([]);
+    expect(after.filter((s) => s.externalId.startsWith('fleet-'))).toEqual([]);
   });
 
   it('listActivity tells the story just written, newest first', async () => {
     await client.acquireSandbox('story-sdk');
-    await client.releaseSandbox('story-sdk');
+    await client.destroySandbox('story-sdk');
     const log = await client.listActivity({ limit: 10 });
-    const mine = log.filter((e) => e.userKey === 'story-sdk');
-    expect(mine.map((e) => e.kind)).toEqual(['released', 'created']);
+    const mine = log.filter((e) => e.externalId === 'story-sdk');
+    expect(mine.map((e) => e.kind)).toEqual(['destroyed', 'created']);
   });
 });
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index d952ef7..4c57a4b 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -20,21 +20,24 @@ import {
   listTemplatesResponseSchema,
   type RebuildSandboxResponse,
   type RegisterTemplateResponse,
-  type ReleaseSandboxResponse,
+  type DestroySandboxResponse,
   type RemoveTemplateResponse,
   readFileResponseSchema,
   rebuildSandboxResponseSchema,
   registerTemplateResponseSchema,
-  releaseSandboxResponseSchema,
+  destroySandboxResponseSchema,
   removeTemplateResponseSchema,
+  readFilesResponseSchema,
   type Sandbox,
   type SandboxMetricsSample,
   type SetIngressResponse,
-  type SetPolicyResponse,
+  type UpdatePolicyResponse,
   setIngressResponseSchema,
-  setPolicyResponseSchema,
+  updatePolicyResponseSchema,
   type Template,
+  type WriteFileResponse,
   type WriteFilesResponse,
+  writeFileResponseSchema,
   writeFilesResponseSchema,
 } from '@dormice/shared';
 import { Agent, fetch, type Response } from 'undici';
@@ -119,17 +122,17 @@ export class Dormice {
   }
 
   /**
-   * acquire(userKey): the platform's single entry point, idempotent — the
+   * acquire(externalId): the platform's single entry point, idempotent — the
    * same key always comes back to the same sandbox, whatever state it was
    * in. A `restoring` status means the sandbox is being pulled back from
    * the archive; poll until it flips to `ready`.
    */
   async acquireSandbox(
-    userKey: string,
+    externalId: string,
     options?: AcquireSandboxOptions,
   ): Promise<AcquireResponse> {
     const data = await this.rpc('acquireSandbox', {
-      userKey,
+      externalId,
       policy: options?.policy,
       template: options?.template,
     });
@@ -163,9 +166,9 @@ export class Dormice {
    * container (stopped, archived, restoring) the sample is null.
    */
   async getSandboxMetrics(
-    userKey: string,
+    externalId: string,
   ): Promise<SandboxMetricsSample | null> {
-    const data = await this.rpc('getSandboxMetrics', { userKey });
+    const data = await this.rpc('getSandboxMetrics', { externalId });
     return getSandboxMetricsResponseSchema.parse(data).sample;
   }
 
@@ -236,8 +239,8 @@ export class Dormice {
    * or exec wakes it, paying one cold start. Unknown key: 404 — rebuild is
    * not a creator.
    */
-  async rebuildSandbox(userKey: string): Promise<RebuildSandboxResponse> {
-    const data = await this.rpc('rebuildSandbox', { userKey });
+  async rebuildSandbox(externalId: string): Promise<RebuildSandboxResponse> {
+    const data = await this.rpc('rebuildSandbox', { externalId });
     return rebuildSandboxResponseSchema.parse(data);
   }
 
@@ -249,22 +252,22 @@ export class Dormice {
    * never-stop resident agent). A pure ledger write: nothing is woken, and
    * the idle clock is not refreshed. Unknown key: 404 — not a creator.
    */
-  async setPolicy(
-    userKey: string,
+  async updatePolicy(
+    externalId: string,
     policy: LifecyclePolicyOverride,
-  ): Promise<SetPolicyResponse> {
-    const data = await this.rpc('setPolicy', { userKey, policy });
-    return setPolicyResponseSchema.parse(data);
+  ): Promise<UpdatePolicyResponse> {
+    const data = await this.rpc('updatePolicy', { externalId, policy });
+    return updatePolicyResponseSchema.parse(data);
   }
 
   /**
-   * Destroys the sandbox behind a user key — container and disk are gone
+   * Destroys the sandbox behind an external id — container and disk are gone
    * for good. Idempotent like acquire: a key that has no sandbox is not an
-   * error, the response just says `released: false`.
+   * error, the response just says `destroyed: false`.
    */
-  async releaseSandbox(userKey: string): Promise<ReleaseSandboxResponse> {
-    const data = await this.rpc('releaseSandbox', { userKey });
-    return releaseSandboxResponseSchema.parse(data);
+  async destroySandbox(externalId: string): Promise<DestroySandboxResponse> {
+    const data = await this.rpc('destroySandbox', { externalId });
+    return destroySandboxResponseSchema.parse(data);
   }
 
   /**
@@ -297,14 +300,14 @@ export class Dormice {
   }
 
   /**
-   * Runs a shell command inside the sandbox behind a user key and returns
+   * Runs a shell command inside the sandbox behind an external id and returns
    * the buffered result: honest exit code (a nonzero exit is a result, not
    * an error), stdout/stderr capped at 1 MiB per stream. Wakes a cold
    * sandbox first, and counts as activity for the whole run — the idle
    * scanner never freezes a sandbox mid-command.
    */
   async execCommand(
-    userKey: string,
+    externalId: string,
     command: string,
     options?: ExecCommandOptions,
   ): Promise<ExecCommandResponse> {
@@ -316,7 +319,7 @@ export class Dormice {
     const data = await this.rpc(
       'execCommand',
       {
-        userKey,
+        externalId,
         command,
         timeoutSeconds,
         cwd: options?.cwd,
@@ -329,17 +332,17 @@ export class Dormice {
   }
 
   /**
-   * Writes a batch of files into the sandbox behind a user key, waking a
+   * Writes a batch of files into the sandbox behind an external id, waking a
    * cold sandbox first. Parents are created, existing files overwritten.
    * Per-file cap is 16 MiB — content travels as base64 inside JSON; a big
    * batch on a slow link may need a larger client `timeoutMs`.
    */
   async writeFiles(
-    userKey: string,
+    externalId: string,
     files: FileToWrite[],
   ): Promise<WriteFilesResponse> {
     const data = await this.rpc('writeFiles', {
-      userKey,
+      externalId,
       files: files.map((file) => ({
         path: file.path,
         contentBase64: Buffer.from(
@@ -352,12 +355,33 @@ export class Dormice {
     return writeFilesResponseSchema.parse(data);
   }
 
+  /**
+   * Writes one file into the sandbox — the single-file form of writeFiles,
+   * same rules (parents created, existing file overwritten, 16 MiB cap).
+   */
+  async writeFile(
+    externalId: string,
+    path: string,
+    content: string | Uint8Array,
+  ): Promise<WriteFileResponse> {
+    const data = await this.rpc('writeFile', {
+      externalId,
+      path,
+      contentBase64: Buffer.from(
+        typeof content === 'string'
+          ? new TextEncoder().encode(content)
+          : content,
+      ).toString('base64'),
+    });
+    return writeFileResponseSchema.parse(data);
+  }
+
   /**
    * Reads one file's bytes out of the sandbox. A file over the 16 MiB cap
    * is refused by the daemon (413), never truncated.
    */
-  async readFile(userKey: string, path: string): Promise<ReadFileResult> {
-    const data = await this.rpc('readFile', { userKey, path });
+  async readFile(externalId: string, path: string): Promise<ReadFileResult> {
+    const data = await this.rpc('readFile', { externalId, path });
     const parsed = readFileResponseSchema.parse(data);
     return {
       path: parsed.path,
@@ -365,6 +389,23 @@ export class Dormice {
     };
   }
 
+  /**
+   * Reads a batch of files, all or nothing: one missing path fails the
+   * whole call (404 naming it) — a caller that can tolerate absence asks
+   * file by file. Files come back in request order; the batch total is
+   * capped at 48 MiB by the daemon (413).
+   */
+  async readFiles(
+    externalId: string,
+    paths: string[],
+  ): Promise<ReadFileResult[]> {
+    const data = await this.rpc('readFiles', { externalId, paths });
+    return readFilesResponseSchema.parse(data).files.map((file) => ({
+      path: file.path,
+      content: new Uint8Array(Buffer.from(file.contentBase64, 'base64')),
+    }));
+  }
+
   /** Native API convention: every operation is POST /<method>, body in, body out. */
   private async rpc(
     method: string,
diff --git a/packages/server/drizzle/0006_external-id.sql b/packages/server/drizzle/0006_external-id.sql
new file mode 100644
index 0000000..3ab9cfc
--- /dev/null
+++ b/packages/server/drizzle/0006_external-id.sql
@@ -0,0 +1,5 @@
+ALTER TABLE `sandboxes` RENAME COLUMN `user_key` TO `external_id`;--> statement-breakpoint
+DROP INDEX `sandboxes_user_key_unique`;--> statement-breakpoint
+CREATE UNIQUE INDEX `sandboxes_external_id_unique` ON `sandboxes` (`external_id`);--> statement-breakpoint
+ALTER TABLE `activity` RENAME COLUMN `user_key` TO `external_id`;--> statement-breakpoint
+UPDATE `activity` SET `kind` = 'destroyed' WHERE `kind` = 'released';
diff --git a/packages/server/drizzle/meta/0006_snapshot.json b/packages/server/drizzle/meta/0006_snapshot.json
new file mode 100644
index 0000000..3476cd1
--- /dev/null
+++ b/packages/server/drizzle/meta/0006_snapshot.json
@@ -0,0 +1,277 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "d0819d46-b25a-4912-9417-22b2cf192b7c",
+  "prevId": "9b340170-fa6d-448d-872c-9c4c356574ae",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_id": {
+          "name": "external_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_id": {
+          "name": "external_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_external_id_unique": {
+          "name": "sandboxes_external_id_unique",
+          "columns": [
+            "external_id"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index f103e67..188bf61 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -43,6 +43,13 @@
       "when": 1783917759390,
       "tag": "0005_console-account",
       "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "6",
+      "when": 1783919540066,
+      "tag": "0006_external-id",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index c3d5ff4..02307fa 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -78,14 +78,14 @@ describe('auth', () => {
   });
 
   it('rejects API calls without a token', async () => {
-    const res = await acquire(testApp().app, { userKey: 'u' }, {});
+    const res = await acquire(testApp().app, { externalId: 'u' }, {});
     expect(res.statusCode).toBe(401);
   });
 
   it('rejects API calls with a wrong token', async () => {
     const res = await acquire(
       testApp().app,
-      { userKey: 'u' },
+      { externalId: 'u' },
       { authorization: 'Bearer wrong-token-wrong-token-wrong-token' },
     );
     expect(res.statusCode).toBe(401);
@@ -95,35 +95,35 @@ describe('auth', () => {
 describe('POST /acquireSandbox', () => {
   it('creates a sandbox on first acquire, with default policy', async () => {
     const { app, executor } = testApp();
-    const res = await acquire(app, { userKey: 'alice' });
+    const res = await acquire(app, { externalId: 'alice' });
     expect(res.statusCode).toBe(200);
     const body = res.json();
     expect(body.status).toBe('ready');
     expect(body.sandbox.state).toBe('active');
-    expect(body.sandbox.userKey).toBe('alice');
+    expect(body.sandbox.externalId).toBe('alice');
     expect(body.sandbox.policy).toEqual(DEFAULT_LIFECYCLE_POLICY);
     expect(body.sandbox.endpoint).toBe('http://127.0.0.1:3676');
     // The ledger and reality agree: the container is actually running.
     expect(executor.stateOf(body.sandbox.sandboxId)).toBe('running');
   });
 
-  it('is idempotent: same user key returns the same sandbox', async () => {
+  it('is idempotent: same external id returns the same sandbox', async () => {
     const { app } = testApp();
-    const first = (await acquire(app, { userKey: 'alice' })).json();
-    const second = (await acquire(app, { userKey: 'alice' })).json();
+    const first = (await acquire(app, { externalId: 'alice' })).json();
+    const second = (await acquire(app, { externalId: 'alice' })).json();
     expect(second.sandbox.sandboxId).toBe(first.sandbox.sandboxId);
   });
 
-  it('gives different user keys different sandboxes', async () => {
+  it('gives different external ids different sandboxes', async () => {
     const { app } = testApp();
-    const alice = (await acquire(app, { userKey: 'alice' })).json();
-    const bob = (await acquire(app, { userKey: 'bob' })).json();
+    const alice = (await acquire(app, { externalId: 'alice' })).json();
+    const bob = (await acquire(app, { externalId: 'bob' })).json();
     expect(bob.sandbox.sandboxId).not.toBe(alice.sandbox.sandboxId);
   });
 
   it('stores a policy override, including explicit null for archive', async () => {
     const res = await acquire(testApp().app, {
-      userKey: 'alice',
+      externalId: 'alice',
       policy: { freezeAfterSeconds: 60, archiveAfterSeconds: null },
     });
     expect(res.json().sandbox.policy).toEqual({
@@ -135,7 +135,7 @@ describe('POST /acquireSandbox', () => {
 
   it('rejects an override whose merged result breaks the ordering rule', async () => {
     const res = await acquire(testApp().app, {
-      userKey: 'alice',
+      externalId: 'alice',
       policy: { freezeAfterSeconds: 61, stopAfterSeconds: 60 },
     });
     expect(res.statusCode).toBe(400);
@@ -146,7 +146,7 @@ describe('POST /acquireSandbox', () => {
     // Without an archiver a stored archive threshold would be a standing
     // lie; the daemon refuses rather than nodding along.
     const res = await acquire(testApp().app, {
-      userKey: 'alice',
+      externalId: 'alice',
       policy: { archiveAfterSeconds: 3600 },
     });
     expect(res.statusCode).toBe(400);
@@ -162,7 +162,7 @@ describe('POST /acquireSandbox', () => {
 
   it('stores stopAfterSeconds: null — the never-stop resident policy', async () => {
     const res = await acquire(testApp().app, {
-      userKey: 'resident',
+      externalId: 'resident',
       policy: { stopAfterSeconds: null },
     });
     expect(res.statusCode).toBe(200);
@@ -171,11 +171,11 @@ describe('POST /acquireSandbox', () => {
 
   it('rejects an invalid override even when the sandbox already exists', async () => {
     const { app } = testApp();
-    await acquire(app, { userKey: 'alice' });
+    await acquire(app, { externalId: 'alice' });
     // The override would not apply (the sandbox exists), but it is still
     // the caller's mistake — a 400, never a silent ignore.
     const res = await acquire(app, {
-      userKey: 'alice',
+      externalId: 'alice',
       policy: { archiveAfterSeconds: 1 },
     });
     expect(res.statusCode).toBe(400);
@@ -184,9 +184,9 @@ describe('POST /acquireSandbox', () => {
 
 describe('error shape', () => {
   it('answers validation failures with the protocol {message} body on every route', async () => {
-    // releaseSandbox declares no error schema; without the global error
+    // destroySandbox declares no error schema; without the global error
     // handler Fastify's native multi-field shape leaked here.
-    const res = await rpc(testApp().app, '/releaseSandbox', {});
+    const res = await rpc(testApp().app, '/destroySandbox', {});
     expect(res.statusCode).toBe(400);
     expect(Object.keys(res.json())).toEqual(['message']);
   });
@@ -201,17 +201,17 @@ describe('error shape', () => {
 describe('sandbox capacity', () => {
   it('caps creation at DORMICE_MAX_SANDBOXES with an honest 429', async () => {
     const { app } = testApp(undefined, { DORMICE_MAX_SANDBOXES: '1' });
-    expect((await acquire(app, { userKey: 'alice' })).statusCode).toBe(200);
+    expect((await acquire(app, { externalId: 'alice' })).statusCode).toBe(200);
 
-    const capped = await acquire(app, { userKey: 'bob' });
+    const capped = await acquire(app, { externalId: 'bob' });
     expect(capped.statusCode).toBe(429);
     expect(capped.json().message).toMatch(/DORMICE_MAX_SANDBOXES/);
 
     // Existing sandboxes always wake — the cap only guards creation.
-    expect((await acquire(app, { userKey: 'alice' })).statusCode).toBe(200);
+    expect((await acquire(app, { externalId: 'alice' })).statusCode).toBe(200);
     // Releasing frees the slot.
-    await rpc(app, '/releaseSandbox', { userKey: 'alice' });
-    expect((await acquire(app, { userKey: 'bob' })).statusCode).toBe(200);
+    await rpc(app, '/destroySandbox', { externalId: 'alice' });
+    expect((await acquire(app, { externalId: 'bob' })).statusCode).toBe(200);
   });
 });
 
@@ -229,8 +229,8 @@ describe('concurrent acquires', () => {
     const executor = new SlowCreateExecutor();
     const { app } = testApp(executor);
     const [first, second] = await Promise.all([
-      acquire(app, { userKey: 'alice' }),
-      acquire(app, { userKey: 'alice' }),
+      acquire(app, { externalId: 'alice' }),
+      acquire(app, { externalId: 'alice' }),
     ]);
     expect(first.statusCode).toBe(200);
     expect(second.statusCode).toBe(200);
@@ -246,8 +246,8 @@ describe('concurrent acquires', () => {
     const executor = new SlowCreateExecutor();
     const { app } = testApp(executor);
     const [alice, bob] = await Promise.all([
-      acquire(app, { userKey: 'alice' }),
-      acquire(app, { userKey: 'bob' }),
+      acquire(app, { externalId: 'alice' }),
+      acquire(app, { externalId: 'bob' }),
     ]);
     expect(bob.json().sandbox.sandboxId).not.toBe(
       alice.json().sandbox.sandboxId,
@@ -259,7 +259,7 @@ describe('concurrent acquires', () => {
 describe('acquire wakes cold sandboxes', () => {
   it('unfreezes a frozen sandbox back to active', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
     const id = created.sandbox.sandboxId;
 
     await scanOnce(
@@ -273,7 +273,7 @@ describe('acquire wakes cold sandboxes', () => {
     );
     expect(executor.stateOf(id)).toBe('paused');
 
-    const woken = (await acquire(app, { userKey: 'alice' })).json();
+    const woken = (await acquire(app, { externalId: 'alice' })).json();
     expect(woken.sandbox.sandboxId).toBe(id);
     expect(woken.sandbox.state).toBe('active');
     expect(executor.stateOf(id)).toBe('running');
@@ -283,7 +283,7 @@ describe('acquire wakes cold sandboxes', () => {
     const { app, db, executor, locks } = testApp();
     const created = (
       await acquire(app, {
-        userKey: 'alice',
+        externalId: 'alice',
         policy: { freezeAfterSeconds: 60, stopAfterSeconds: 120 },
       })
     ).json();
@@ -294,7 +294,7 @@ describe('acquire wakes cold sandboxes', () => {
     await scanOnce(db, executor, locks, after(lastActiveAt, 120));
     expect(executor.stateOf(id)).toBe('stopped');
 
-    const woken = (await acquire(app, { userKey: 'alice' })).json();
+    const woken = (await acquire(app, { externalId: 'alice' })).json();
     expect(woken.sandbox.sandboxId).toBe(id);
     expect(woken.sandbox.state).toBe('active');
     expect(executor.stateOf(id)).toBe('running');
@@ -302,7 +302,7 @@ describe('acquire wakes cold sandboxes', () => {
 
   it('waking refreshes the idle clock', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
 
     await scanOnce(
       db,
@@ -315,7 +315,7 @@ describe('acquire wakes cold sandboxes', () => {
     );
     // touch() stamps real wall-clock time, so give it a distinct millisecond.
     await new Promise((resolve) => setTimeout(resolve, 5));
-    const woken = (await acquire(app, { userKey: 'alice' })).json();
+    const woken = (await acquire(app, { externalId: 'alice' })).json();
     expect(Date.parse(woken.sandbox.lastActiveAt)).toBeGreaterThan(
       Date.parse(created.sandbox.lastActiveAt),
     );
@@ -334,7 +334,7 @@ describe('scanner vs acquire on the same key', () => {
   it('an acquire during a freeze waits its turn and gets a running sandbox', async () => {
     const executor = new SlowFreezeExecutor();
     const { app, db, locks } = testApp(executor);
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
     const id = created.sandbox.sandboxId;
 
     // The scanner decides to freeze; the acquire lands mid-freeze.
@@ -350,7 +350,7 @@ describe('scanner vs acquire on the same key', () => {
         DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
       ),
     );
-    const woken = acquire(app, { userKey: 'alice' });
+    const woken = acquire(app, { externalId: 'alice' });
     const [sweepResult, res] = await Promise.all([sweep, woken]);
 
     expect(sweepResult.frozen).toBe(1);
@@ -372,15 +372,15 @@ describe('concurrent releases of the same key', () => {
   it('one reports released, the other reports the goal state — no 500', async () => {
     const executor = new SlowDestroyExecutor();
     const { app } = testApp(executor);
-    await acquire(app, { userKey: 'alice' });
+    await acquire(app, { externalId: 'alice' });
 
     const [a, b] = await Promise.all([
-      rpc(app, '/releaseSandbox', { userKey: 'alice' }),
-      rpc(app, '/releaseSandbox', { userKey: 'alice' }),
+      rpc(app, '/destroySandbox', { externalId: 'alice' }),
+      rpc(app, '/destroySandbox', { externalId: 'alice' }),
     ]);
     expect(a.statusCode).toBe(200);
     expect(b.statusCode).toBe(200);
-    const released = [a.json().released, b.json().released];
+    const released = [a.json().destroyed, b.json().destroyed];
     expect(released.filter(Boolean)).toHaveLength(1);
   });
 });
@@ -388,7 +388,7 @@ describe('concurrent releases of the same key', () => {
 describe('acquire after reality moved behind the ledger', () => {
   it('returns a fresh sandbox when container and disk are truly gone', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
     // Container and disk wiped behind the daemon's back — the end state of
     // a release that crashed after the executor's work, before the ledger's.
     await executor.destroy(created.sandbox.sandboxId);
@@ -397,7 +397,7 @@ describe('acquire after reality moved behind the ledger', () => {
     // within one interval, freeing the key.
     await reconcile(db, executor, locks, new Set());
 
-    const again = (await acquire(app, { userKey: 'alice' })).json();
+    const again = (await acquire(app, { externalId: 'alice' })).json();
     expect(again.status).toBe('ready');
     expect(again.sandbox.sandboxId).not.toBe(created.sandbox.sandboxId);
     // This time the sandbox is real.
@@ -413,7 +413,7 @@ describe('acquire after reality moved behind the ledger', () => {
     const { app, db, executor, locks } = testApp();
     const created = (
       await acquire(app, {
-        userKey: 'alice',
+        externalId: 'alice',
         policy: { freezeAfterSeconds: 60, stopAfterSeconds: 120 },
       })
     ).json();
@@ -425,7 +425,7 @@ describe('acquire after reality moved behind the ledger', () => {
 
     await reconcile(db, executor, locks, new Set());
 
-    const again = (await acquire(app, { userKey: 'alice' })).json();
+    const again = (await acquire(app, { externalId: 'alice' })).json();
     expect(again.sandbox.sandboxId).toBe(id);
     expect(again.sandbox.state).toBe('active');
     expect(executor.stateOf(id)).toBe('running');
@@ -435,10 +435,10 @@ describe('acquire after reality moved behind the ledger', () => {
 describe('POST /execCommand', () => {
   it('runs a command in the sandbox and returns the buffered result', async () => {
     const { app } = testApp();
-    await acquire(app, { userKey: 'alice' });
+    await acquire(app, { externalId: 'alice' });
     // No timeoutSeconds sent: the schema default fills it in server-side.
     const res = await rpc(app, '/execCommand', {
-      userKey: 'alice',
+      externalId: 'alice',
       command: 'echo hi',
     });
     expect(res.statusCode).toBe(200);
@@ -453,7 +453,7 @@ describe('POST /execCommand', () => {
 
   it('answers an unknown key with a 404, never a silent create', async () => {
     const res = await rpc(testApp().app, '/execCommand', {
-      userKey: 'nobody',
+      externalId: 'nobody',
       command: 'echo hi',
     });
     expect(res.statusCode).toBe(404);
@@ -462,7 +462,7 @@ describe('POST /execCommand', () => {
 
   it('wakes a frozen sandbox before running the command', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
     const id = created.sandbox.sandboxId;
     await scanOnce(
       db,
@@ -478,7 +478,7 @@ describe('POST /execCommand', () => {
     // A paused container cannot even receive an exec (Docker refuses); the
     // route must wake it first, exactly like acquire does.
     const res = await rpc(app, '/execCommand', {
-      userKey: 'alice',
+      externalId: 'alice',
       command: 'echo woke',
     });
     expect(res.statusCode).toBe(200);
@@ -492,7 +492,7 @@ describe('POST /execCommand', () => {
     const { app, db, executor, locks } = testApp();
     const created = (
       await acquire(app, {
-        userKey: 'alice',
+        externalId: 'alice',
         policy: { freezeAfterSeconds: 1 },
       })
     ).json();
@@ -503,7 +503,7 @@ describe('POST /execCommand', () => {
     // touch (~0ms) is stale against that clock — only the 500ms heartbeat
     // touch keeps the idle under the threshold.
     const execPromise = rpc(app, '/execCommand', {
-      userKey: 'alice',
+      externalId: 'alice',
       command: 'sleep 1',
     });
     await new Promise((resolve) => setTimeout(resolve, 700));
@@ -528,17 +528,17 @@ describe('POST /execCommand', () => {
     // Reverse-verified: without the heartbeat's try/catch this crashes.
     const { app } = testApp();
     await acquire(app, {
-      userKey: 'alice',
+      externalId: 'alice',
       policy: { freezeAfterSeconds: 1 },
     });
 
     const execPromise = rpc(app, '/execCommand', {
-      userKey: 'alice',
+      externalId: 'alice',
       command: 'sleep 1',
     });
     await new Promise((resolve) => setTimeout(resolve, 100));
-    const releaseRes = await rpc(app, '/releaseSandbox', { userKey: 'alice' });
-    expect(releaseRes.json()).toEqual({ released: true });
+    const releaseRes = await rpc(app, '/destroySandbox', { externalId: 'alice' });
+    expect(releaseRes.json()).toEqual({ destroyed: true });
 
     // Both requests settle; ride out one more heartbeat interval on the
     // deleted row before declaring the daemon healthy.
@@ -552,15 +552,15 @@ describe('POST /execCommand', () => {
 
   it('rejects malformed requests with the protocol {message} shape', async () => {
     const { app } = testApp();
-    await acquire(app, { userKey: 'alice' });
+    await acquire(app, { externalId: 'alice' });
     const bad = [
-      { userKey: 'alice' }, // no command
-      { userKey: 'alice', command: '' },
-      { userKey: 'alice', command: 'echo hi', timeoutSeconds: 0 },
-      { userKey: 'alice', command: 'echo hi', timeoutSeconds: -5 },
-      { userKey: 'alice', command: 'echo hi', timeoutSeconds: 1.5 },
-      { userKey: 'alice', command: 'echo hi', timeoutSeconds: 86_401 },
-      { userKey: 'alice', command: 'echo hi', env: { PATH: 42 } },
+      { externalId: 'alice' }, // no command
+      { externalId: 'alice', command: '' },
+      { externalId: 'alice', command: 'echo hi', timeoutSeconds: 0 },
+      { externalId: 'alice', command: 'echo hi', timeoutSeconds: -5 },
+      { externalId: 'alice', command: 'echo hi', timeoutSeconds: 1.5 },
+      { externalId: 'alice', command: 'echo hi', timeoutSeconds: 86_401 },
+      { externalId: 'alice', command: 'echo hi', env: { PATH: 42 } },
     ];
     for (const payload of bad) {
       const res = await rpc(app, '/execCommand', payload);
@@ -573,13 +573,13 @@ describe('POST /execCommand', () => {
 describe('POST /writeFiles and /readFile', () => {
   it('round-trips content through base64, resolving paths to absolute', async () => {
     const { app } = testApp();
-    await acquire(app, { userKey: 'alice' });
+    await acquire(app, { externalId: 'alice' });
     // Every byte value: any utf8 coercion or base64 sloppiness breaks this.
     const bytes = Buffer.alloc(256);
     for (let i = 0; i < 256; i++) bytes[i] = i;
 
     const write = await rpc(app, '/writeFiles', {
-      userKey: 'alice',
+      externalId: 'alice',
       files: [
         {
           path: 'notes.txt',
@@ -600,7 +600,7 @@ describe('POST /writeFiles and /readFile', () => {
     });
 
     const read = await rpc(app, '/readFile', {
-      userKey: 'alice',
+      externalId: 'alice',
       path: 'blob.bin',
     });
     expect(read.statusCode).toBe(200);
@@ -613,18 +613,18 @@ describe('POST /writeFiles and /readFile', () => {
   it('answers an unknown key with a 404 on both verbs, never a silent create', async () => {
     const { app } = testApp();
     const write = await rpc(app, '/writeFiles', {
-      userKey: 'nobody',
+      externalId: 'nobody',
       files: [{ path: 'x', contentBase64: 'eA==' }],
     });
     expect(write.statusCode).toBe(404);
-    const read = await rpc(app, '/readFile', { userKey: 'nobody', path: 'x' });
+    const read = await rpc(app, '/readFile', { externalId: 'nobody', path: 'x' });
     expect(read.statusCode).toBe(404);
     expect(read.json().message).toMatch(/no sandbox for key/);
   });
 
   it('wakes a frozen sandbox before touching files', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
     await scanOnce(
       db,
       executor,
@@ -637,7 +637,7 @@ describe('POST /writeFiles and /readFile', () => {
     expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
 
     const res = await rpc(app, '/writeFiles', {
-      userKey: 'alice',
+      externalId: 'alice',
       files: [{ path: 'woke.txt', contentBase64: 'eA==' }],
     });
     expect(res.statusCode).toBe(200);
@@ -646,17 +646,17 @@ describe('POST /writeFiles and /readFile', () => {
 
   it('maps the typed file errors onto 404, 400 and 413', async () => {
     const { app, executor } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
 
     const missing = await rpc(app, '/readFile', {
-      userKey: 'alice',
+      externalId: 'alice',
       path: 'absent.txt',
     });
     expect(missing.statusCode).toBe(404);
     expect(missing.json().message).toBe('no such file: /home/user/absent.txt');
 
     const directory = await rpc(app, '/readFile', {
-      userKey: 'alice',
+      externalId: 'alice',
       path: '/home/user',
     });
     expect(directory.statusCode).toBe(400);
@@ -670,7 +670,7 @@ describe('POST /writeFiles and /readFile', () => {
       { path: 'big.bin', content: Buffer.alloc(size) },
     ]);
     const big = await rpc(app, '/readFile', {
-      userKey: 'alice',
+      externalId: 'alice',
       path: 'big.bin',
     });
     expect(big.statusCode).toBe(413);
@@ -684,9 +684,9 @@ describe('POST /writeFiles and /readFile', () => {
     // bodyLimit and failing the per-file refine proves both gates sit where
     // they should: total bytes at the body limit, per-file size in the schema.
     const { app } = testApp();
-    await acquire(app, { userKey: 'alice' });
+    await acquire(app, { externalId: 'alice' });
     const res = await rpc(app, '/writeFiles', {
-      userKey: 'alice',
+      externalId: 'alice',
       files: [
         {
           path: 'big.bin',
@@ -702,30 +702,30 @@ describe('POST /writeFiles and /readFile', () => {
 
   it('rejects malformed requests with the protocol {message} shape', async () => {
     const { app } = testApp();
-    await acquire(app, { userKey: 'alice' });
+    await acquire(app, { externalId: 'alice' });
     const bad = [
-      ['/writeFiles', { userKey: 'alice', files: [] }],
-      ['/writeFiles', { userKey: 'alice' }],
+      ['/writeFiles', { externalId: 'alice', files: [] }],
+      ['/writeFiles', { externalId: 'alice' }],
       [
         '/writeFiles',
-        { userKey: 'alice', files: [{ path: '', contentBase64: 'eA==' }] },
+        { externalId: 'alice', files: [{ path: '', contentBase64: 'eA==' }] },
       ],
       [
         '/writeFiles',
         {
-          userKey: 'alice',
+          externalId: 'alice',
           files: [{ path: 'a\0b', contentBase64: 'eA==' }],
         },
       ],
       [
         '/writeFiles',
         {
-          userKey: 'alice',
+          externalId: 'alice',
           files: [{ path: 'x', contentBase64: '!!not-b64' }],
         },
       ],
-      ['/readFile', { userKey: 'alice' }],
-      ['/readFile', { userKey: 'alice', path: '' }],
+      ['/readFile', { externalId: 'alice' }],
+      ['/readFile', { externalId: 'alice', path: '' }],
     ] as const;
     for (const [url, payload] of bad) {
       const res = await rpc(app, url, payload as Record<string, unknown>);
@@ -750,11 +750,11 @@ describe('POST /listSandboxes', () => {
     // Give alice a shorter freeze threshold so one sweep freezes only her.
     const alice = (
       await acquire(app, {
-        userKey: 'alice',
+        externalId: 'alice',
         policy: { freezeAfterSeconds: 60 },
       })
     ).json();
-    await acquire(app, { userKey: 'bob' });
+    await acquire(app, { externalId: 'bob' });
     await scanOnce(db, executor, locks, after(alice.sandbox.lastActiveAt, 60));
 
     const res = await rpc(app, '/listSandboxes');
@@ -762,8 +762,8 @@ describe('POST /listSandboxes', () => {
     const states = Object.fromEntries(
       res
         .json()
-        .sandboxes.map((s: { userKey: string; state: string }) => [
-          s.userKey,
+        .sandboxes.map((s: { externalId: string; state: string }) => [
+          s.externalId,
           s.state,
         ]),
     );
@@ -774,10 +774,10 @@ describe('POST /listSandboxes', () => {
 describe('POST /rebuildSandbox', () => {
   it('swaps the container, keeps the disk, and the same key wakes with its data', async () => {
     const { app, executor } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
     const id = created.sandbox.sandboxId;
     await rpc(app, '/writeFiles', {
-      userKey: 'alice',
+      externalId: 'alice',
       files: [
         {
           path: 'keep.txt',
@@ -786,7 +786,7 @@ describe('POST /rebuildSandbox', () => {
       ],
     });
 
-    const res = await rpc(app, '/rebuildSandbox', { userKey: 'alice' });
+    const res = await rpc(app, '/rebuildSandbox', { externalId: 'alice' });
     expect(res.statusCode).toBe(200);
     // The shell is gone, the row stays, the state says so honestly.
     expect(res.json().sandbox).toMatchObject({
@@ -796,10 +796,10 @@ describe('POST /rebuildSandbox', () => {
     expect(executor.stateOf(id)).toBeUndefined();
 
     // The same key comes back to the same sandbox — rebuilt shell, same body.
-    const again = (await acquire(app, { userKey: 'alice' })).json();
+    const again = (await acquire(app, { externalId: 'alice' })).json();
     expect(again.sandbox.sandboxId).toBe(id);
     const read = await rpc(app, '/readFile', {
-      userKey: 'alice',
+      externalId: 'alice',
       path: 'keep.txt',
     });
     expect(Buffer.from(read.json().contentBase64, 'base64').toString()).toBe(
@@ -809,7 +809,7 @@ describe('POST /rebuildSandbox', () => {
 
   it('rebuilds a frozen sandbox too, and again while already stopped', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
     await scanOnce(
       db,
       executor,
@@ -821,31 +821,31 @@ describe('POST /rebuildSandbox', () => {
     );
     expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
 
-    const res = await rpc(app, '/rebuildSandbox', { userKey: 'alice' });
+    const res = await rpc(app, '/rebuildSandbox', { externalId: 'alice' });
     expect(res.json().sandbox.state).toBe('stopped');
 
     // A second rebuild finds no container — the goal state, not an error.
-    const again = await rpc(app, '/rebuildSandbox', { userKey: 'alice' });
+    const again = await rpc(app, '/rebuildSandbox', { externalId: 'alice' });
     expect(again.statusCode).toBe(200);
     expect(again.json().sandbox.state).toBe('stopped');
   });
 
   it('answers 404 for an unknown key — rebuild is not a creator', async () => {
     const res = await rpc(testApp().app, '/rebuildSandbox', {
-      userKey: 'nobody',
+      externalId: 'nobody',
     });
     expect(res.statusCode).toBe(404);
     expect(res.json().message).toMatch(/acquire it first/);
   });
 });
 
-describe('POST /setPolicy', () => {
+describe('POST /updatePolicy', () => {
   it('patches one knob, keeps the rest, and does not refresh the idle clock', async () => {
     const { app } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
 
-    const res = await rpc(app, '/setPolicy', {
-      userKey: 'alice',
+    const res = await rpc(app, '/updatePolicy', {
+      externalId: 'alice',
       policy: { freezeAfterSeconds: 120 },
     });
     expect(res.statusCode).toBe(200);
@@ -859,14 +859,14 @@ describe('POST /setPolicy', () => {
     const events = (await rpc(app, '/listActivity')).json().events;
     expect(events[0]).toMatchObject({
       kind: 'policy-changed',
-      userKey: 'alice',
+      externalId: 'alice',
       detail: 'freeze 600s -> 120s',
     });
   });
 
   it('promotes a frozen sandbox to never-stop without waking it', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
     await scanOnce(
       db,
       executor,
@@ -878,8 +878,8 @@ describe('POST /setPolicy', () => {
     );
     expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
 
-    const res = await rpc(app, '/setPolicy', {
-      userKey: 'alice',
+    const res = await rpc(app, '/updatePolicy', {
+      externalId: 'alice',
       policy: { stopAfterSeconds: null },
     });
     expect(res.statusCode).toBe(200);
@@ -891,10 +891,10 @@ describe('POST /setPolicy', () => {
 
   it('rejects a patch whose merged result breaks the ordering rule', async () => {
     const { app } = testApp();
-    await acquire(app, { userKey: 'alice' });
+    await acquire(app, { externalId: 'alice' });
     // freeze pushed past the stored stop threshold.
-    const res = await rpc(app, '/setPolicy', {
-      userKey: 'alice',
+    const res = await rpc(app, '/updatePolicy', {
+      externalId: 'alice',
       policy: {
         freezeAfterSeconds:
           (DEFAULT_LIFECYCLE_POLICY.stopAfterSeconds ?? 0) + 1,
@@ -906,18 +906,18 @@ describe('POST /setPolicy', () => {
 
   it('refuses to promise archiving on a daemon without S3', async () => {
     const { app } = testApp();
-    await acquire(app, { userKey: 'alice' });
-    const res = await rpc(app, '/setPolicy', {
-      userKey: 'alice',
+    await acquire(app, { externalId: 'alice' });
+    const res = await rpc(app, '/updatePolicy', {
+      externalId: 'alice',
       policy: { archiveAfterSeconds: 30 * 24 * 60 * 60 },
     });
     expect(res.statusCode).toBe(400);
     expect(res.json().message).toMatch(/DORMICE_S3_/);
   });
 
-  it('answers 404 for an unknown key — setPolicy is not a creator', async () => {
-    const res = await rpc(testApp().app, '/setPolicy', {
-      userKey: 'nobody',
+  it('answers 404 for an unknown key — updatePolicy is not a creator', async () => {
+    const res = await rpc(testApp().app, '/updatePolicy', {
+      externalId: 'nobody',
       policy: { freezeAfterSeconds: 60 },
     });
     expect(res.statusCode).toBe(404);
@@ -926,9 +926,9 @@ describe('POST /setPolicy', () => {
 
   it('treats a no-change patch as the goal state and writes no history', async () => {
     const { app } = testApp();
-    await acquire(app, { userKey: 'alice' });
-    const res = await rpc(app, '/setPolicy', {
-      userKey: 'alice',
+    await acquire(app, { externalId: 'alice' });
+    const res = await rpc(app, '/updatePolicy', {
+      externalId: 'alice',
       policy: {
         freezeAfterSeconds: DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
       },
@@ -941,24 +941,24 @@ describe('POST /setPolicy', () => {
   });
 });
 
-describe('POST /releaseSandbox', () => {
+describe('POST /destroySandbox', () => {
   it('destroys the container and forgets the key', async () => {
     const { app, executor } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
     const id = created.sandbox.sandboxId;
 
-    const res = await rpc(app, '/releaseSandbox', { userKey: 'alice' });
-    expect(res.json()).toEqual({ released: true });
+    const res = await rpc(app, '/destroySandbox', { externalId: 'alice' });
+    expect(res.json()).toEqual({ destroyed: true });
     // Reality and ledger agree: container gone, key free again — the next
     // acquire builds a brand-new sandbox.
     expect(executor.stateOf(id)).toBeUndefined();
-    const again = (await acquire(app, { userKey: 'alice' })).json();
+    const again = (await acquire(app, { externalId: 'alice' })).json();
     expect(again.sandbox.sandboxId).not.toBe(id);
   });
 
   it('releases a cold sandbox too', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
     await scanOnce(
       db,
       executor,
@@ -970,17 +970,17 @@ describe('POST /releaseSandbox', () => {
     );
     expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
 
-    const res = await rpc(app, '/releaseSandbox', { userKey: 'alice' });
-    expect(res.json()).toEqual({ released: true });
+    const res = await rpc(app, '/destroySandbox', { externalId: 'alice' });
+    expect(res.json()).toEqual({ destroyed: true });
     expect(executor.stateOf(created.sandbox.sandboxId)).toBeUndefined();
   });
 
   it('is idempotent: a key with no sandbox reports released false', async () => {
-    const res = await rpc(testApp().app, '/releaseSandbox', {
-      userKey: 'nobody',
+    const res = await rpc(testApp().app, '/destroySandbox', {
+      externalId: 'nobody',
     });
     expect(res.statusCode).toBe(200);
-    expect(res.json()).toEqual({ released: false });
+    expect(res.json()).toEqual({ destroyed: false });
   });
 });
 
@@ -1017,11 +1017,11 @@ describe('the archiver through the app', () => {
   /** Polls acquire until the union flips to ready; the whole restore path. */
   async function acquireUntilReady(
     app: ReturnType<typeof testApp>['app'],
-    userKey: string,
+    externalId: string,
   ) {
     const deadline = Date.now() + 5_000;
     while (true) {
-      const body = (await acquire(app, { userKey })).json();
+      const body = (await acquire(app, { externalId })).json();
       if (body.status === 'ready') return body;
       expect(body.status).toBe('restoring');
       expect(body.progress.phase).toMatch(/downloading|extracting/);
@@ -1036,7 +1036,7 @@ describe('the archiver through the app', () => {
     const { app, db, executor, locks, store, archiver } = archiverTestApp();
     const created = (
       await acquire(app, {
-        userKey: 'alice',
+        externalId: 'alice',
         policy: {
           freezeAfterSeconds: 1,
           stopAfterSeconds: 2,
@@ -1046,7 +1046,7 @@ describe('the archiver through the app', () => {
     ).json();
     const id = created.sandbox.sandboxId;
     await rpc(app, '/writeFiles', {
-      userKey: 'alice',
+      externalId: 'alice',
       files: [
         {
           path: 'kept.txt',
@@ -1073,7 +1073,7 @@ describe('the archiver through the app', () => {
     expect(ready.sandbox.sandboxId).toBe(id);
     expect(ready.sandbox.state).toBe('active');
     const read = (
-      await rpc(app, '/readFile', { userKey: 'alice', path: 'kept.txt' })
+      await rpc(app, '/readFile', { externalId: 'alice', path: 'kept.txt' })
     ).json();
     expect(Buffer.from(read.contentBase64, 'base64').toString()).toBe(
       'through the archive',
@@ -1082,7 +1082,7 @@ describe('the archiver through the app', () => {
 
   it('stores the 7-day archive default when S3 is configured', async () => {
     const { app } = archiverTestApp();
-    const res = await acquire(app, { userKey: 'alice' });
+    const res = await acquire(app, { externalId: 'alice' });
     expect(res.json().sandbox.policy.archiveAfterSeconds).toBe(
       ARCHIVE_DEFAULT_SECONDS,
     );
@@ -1093,14 +1093,14 @@ describe('the archiver through the app', () => {
     // the rows are honest, the restore is impossible, the error names it.
     const executor = new FakeExecutor();
     const { app, db } = testApp(executor);
-    const created = (await acquire(app, { userKey: 'alice' })).json();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
     const id = created.sandbox.sandboxId;
     transition(db, id, 'frozen');
     transition(db, id, 'stopped');
     transition(db, id, 'archived');
     await executor.destroy(id);
 
-    const res = await acquire(app, { userKey: 'alice' });
+    const res = await acquire(app, { externalId: 'alice' });
     expect(res.statusCode).toBe(503);
     expect(res.json().message).toMatch(/no S3 configured \(DORMICE_S3_\*\)/);
   });
@@ -1109,7 +1109,7 @@ describe('the archiver through the app', () => {
     const { app, db, executor, locks, store, archiver } = archiverTestApp();
     const created = (
       await acquire(app, {
-        userKey: 'alice',
+        externalId: 'alice',
         policy: {
           freezeAfterSeconds: 1,
           stopAfterSeconds: 2,
@@ -1124,8 +1124,8 @@ describe('the archiver through the app', () => {
     await scanOnce(db, executor, locks, after(stamp, 3), archiver);
     expect(store.has(objectKey(id))).toBe(true);
 
-    const res = await rpc(app, '/releaseSandbox', { userKey: 'alice' });
-    expect(res.json()).toEqual({ released: true });
+    const res = await rpc(app, '/destroySandbox', { externalId: 'alice' });
+    expect(res.json()).toEqual({ destroyed: true });
     expect(store.has(objectKey(id))).toBe(false);
     expect((await rpc(app, '/listSandboxes')).json().sandboxes).toEqual([]);
   });
@@ -1134,7 +1134,7 @@ describe('the archiver through the app', () => {
     const { app, db, executor, locks, store, archiver } = archiverTestApp();
     const created = (
       await acquire(app, {
-        userKey: 'alice',
+        externalId: 'alice',
         policy: {
           freezeAfterSeconds: 1,
           stopAfterSeconds: 2,
@@ -1157,9 +1157,9 @@ describe('the archiver through the app', () => {
       return innerGet(key, dest, onProgress);
     };
 
-    const restoring = (await acquire(app, { userKey: 'alice' })).json();
+    const restoring = (await acquire(app, { externalId: 'alice' })).json();
     expect(restoring.status).toBe('restoring');
-    const res = await rpc(app, '/releaseSandbox', { userKey: 'alice' });
+    const res = await rpc(app, '/destroySandbox', { externalId: 'alice' });
     expect(res.statusCode).toBe(409);
     expect(res.json().message).toMatch(/restoring; retry/);
 
@@ -1171,7 +1171,7 @@ describe('the archiver through the app', () => {
     const { app, db, executor, locks, archiver } = archiverTestApp();
     const created = (
       await acquire(app, {
-        userKey: 'alice',
+        externalId: 'alice',
         policy: {
           freezeAfterSeconds: 1,
           stopAfterSeconds: 2,
@@ -1185,13 +1185,13 @@ describe('the archiver through the app', () => {
     await scanOnce(db, executor, locks, after(stamp, 3), archiver);
 
     const exec = await rpc(app, '/execCommand', {
-      userKey: 'alice',
+      externalId: 'alice',
       command: 'echo hi',
     });
     expect(exec.statusCode).toBe(409);
     expect(exec.json().message).toMatch(/call acquireSandbox and poll/);
     const read = await rpc(app, '/readFile', {
-      userKey: 'alice',
+      externalId: 'alice',
       path: 'kept.txt',
     });
     expect(read.statusCode).toBe(409);
@@ -1252,38 +1252,38 @@ describe('templates', () => {
   it('acquire with a template creates the sandbox from its image and records the name', async () => {
     const { app, executor } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' });
-    const res = await acquire(app, { userKey: 'alice', template: 'py' });
+    const res = await acquire(app, { externalId: 'alice', template: 'py' });
     expect(res.statusCode).toBe(200);
     const sandbox = res.json().sandbox;
     expect(sandbox.template).toBe('py');
     // The physical half: the shell was actually born from the template's image.
     expect(executor.imageOf(sandbox.sandboxId)).toBe('img-a');
     // A template-less acquire stays on the base image, template null.
-    const plain = (await acquire(app, { userKey: 'bob' })).json().sandbox;
+    const plain = (await acquire(app, { externalId: 'bob' })).json().sandbox;
     expect(plain.template).toBeNull();
   });
 
   it('rejects an unknown template with 400, on the wake path too', async () => {
     const { app } = testApp();
-    const res = await acquire(app, { userKey: 'alice', template: 'ghost' });
+    const res = await acquire(app, { externalId: 'alice', template: 'ghost' });
     expect(res.statusCode).toBe(400);
     expect(res.json().message).toBe(
       "unknown template 'ghost' — register it first",
     );
     // Same answer when the key already has a sandbox: the caller's mistake
     // deserves a 400 even when the value would not apply.
-    await acquire(app, { userKey: 'bob' });
-    const wake = await acquire(app, { userKey: 'bob', template: 'ghost' });
+    await acquire(app, { externalId: 'bob' });
+    const wake = await acquire(app, { externalId: 'bob', template: 'ghost' });
     expect(wake.statusCode).toBe(400);
   });
 
   it('a valid template on an existing key is not applied — creation-time only', async () => {
     const { app } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' });
-    const created = (await acquire(app, { userKey: 'alice' })).json().sandbox;
+    const created = (await acquire(app, { externalId: 'alice' })).json().sandbox;
     expect(created.template).toBeNull();
     const again = (
-      await acquire(app, { userKey: 'alice', template: 'py' })
+      await acquire(app, { externalId: 'alice', template: 'py' })
     ).json().sandbox;
     expect(again.sandboxId).toBe(created.sandboxId);
     expect(again.template).toBeNull();
@@ -1292,19 +1292,19 @@ describe('templates', () => {
   it('refuses to remove a template while sandboxes use it, naming the keys', async () => {
     const { app } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' });
-    await acquire(app, { userKey: 'alice', template: 'py' });
+    await acquire(app, { externalId: 'alice', template: 'py' });
 
     const refused = await rpc(app, '/removeTemplate', { name: 'py' });
     expect(refused.statusCode).toBe(409);
     expect(refused.json().message).toBe(
-      "template 'py' is used by 1 sandbox(es): alice — release them first",
+      "template 'py' is used by 1 sandbox(es): alice — destroy them first",
     );
 
-    await rpc(app, '/releaseSandbox', { userKey: 'alice' });
+    await rpc(app, '/destroySandbox', { externalId: 'alice' });
     expect((await rpc(app, '/removeTemplate', { name: 'py' })).json()).toEqual({
       removed: true,
     });
-    // Idempotent on an unknown name, like releaseSandbox.
+    // Idempotent on an unknown name, like destroySandbox.
     expect((await rpc(app, '/removeTemplate', { name: 'py' })).json()).toEqual({
       removed: false,
     });
@@ -1314,7 +1314,7 @@ describe('templates', () => {
     const { app, executor } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
     const created = (
-      await acquire(app, { userKey: 'alice', template: 'py' })
+      await acquire(app, { externalId: 'alice', template: 'py' })
     ).json().sandbox;
     expect(executor.imageOf(created.sandboxId)).toBe('img-v1');
 
@@ -1323,8 +1323,8 @@ describe('templates', () => {
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });
     expect(executor.imageOf(created.sandboxId)).toBe('img-v1');
 
-    await rpc(app, '/rebuildSandbox', { userKey: 'alice' });
-    const woken = (await acquire(app, { userKey: 'alice' })).json().sandbox;
+    await rpc(app, '/rebuildSandbox', { externalId: 'alice' });
+    const woken = (await acquire(app, { externalId: 'alice' })).json().sandbox;
     expect(woken.sandboxId).toBe(created.sandboxId);
     // The rebuilt shell was born from the template's *current* image.
     expect(executor.imageOf(created.sandboxId)).toBe('img-v2');
@@ -1381,11 +1381,11 @@ describe('POST /getHostMetrics', () => {
     // to alice+60 freezes exactly one of them.
     const created = (
       await acquire(app, {
-        userKey: 'alice',
+        externalId: 'alice',
         policy: { freezeAfterSeconds: 60 },
       })
     ).json();
-    await acquire(app, { userKey: 'bob' });
+    await acquire(app, { externalId: 'bob' });
 
     let body = (await rpc(app, '/getHostMetrics')).json();
     expect(body.sandboxes.total).toBe(2);
diff --git a/packages/server/src/archive/archiver.test.ts b/packages/server/src/archive/archiver.test.ts
index 783f2cc..66b3d71 100644
--- a/packages/server/src/archive/archiver.test.ts
+++ b/packages/server/src/archive/archiver.test.ts
@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { DEFAULT_LIFECYCLE_POLICY } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { type Db, migrateDb, openDb } from '../db/db';
-import { createSandbox, findByUserKey, transition } from '../db/ledger';
+import { createSandbox, findByExternalId, transition } from '../db/ledger';
 import type { SandboxRow } from '../db/schema';
 import { FakeExecutor } from '../executor/fake';
 import { KeyedQueue } from '../keyed-queue';
@@ -31,16 +31,16 @@ function setup() {
 async function seedStopped(
   db: Db,
   executor: FakeExecutor,
-  userKey: string,
+  externalId: string,
 ): Promise<SandboxRow> {
   const sandboxId = randomUUID();
   await executor.create(sandboxId);
   await executor.writeFiles(sandboxId, [
-    { path: 'kept.txt', content: Buffer.from(`data of ${userKey}`) },
+    { path: 'kept.txt', content: Buffer.from(`data of ${externalId}`) },
   ]);
   createSandbox(db, {
     sandboxId,
-    userKey,
+    externalId,
     nodeId: 'node-test',
     policy: DEFAULT_LIFECYCLE_POLICY,
   });
@@ -58,7 +58,7 @@ describe('Archiver.archive', () => {
     await archiver.archive(row);
 
     expect(store.has(objectKey(row.sandboxId))).toBe(true);
-    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
     // "Local copy freed" includes the shell: destroy, not just the disk.
     expect(executor.stateOf(row.sandboxId)).toBeUndefined();
     expect(await executor.listDisks()).not.toContain(row.sandboxId);
@@ -76,13 +76,13 @@ describe('Archiver.archive', () => {
     const events: string[] = [];
     const watchingStore = new (class extends MemStore {
       override async put(key: string, filePath: string): Promise<void> {
-        events.push(`put while ${findByUserKey(db, 'alice')?.state}`);
+        events.push(`put while ${findByExternalId(db, 'alice')?.state}`);
         await super.put(key, filePath);
       }
     })();
     const watchingExecutor = new (class extends FakeExecutor {
       override async destroy(sandboxId: string): Promise<void> {
-        events.push(`destroy while ${findByUserKey(db, 'alice')?.state}`);
+        events.push(`destroy while ${findByExternalId(db, 'alice')?.state}`);
         await super.destroy(sandboxId);
       }
     })();
@@ -119,7 +119,7 @@ describe('Archiver.archive', () => {
     await expect(archiver.archive(row)).rejects.toThrow('the bucket said no');
     // The invariant as behavior: disk still present <=> upload unconfirmed,
     // so the row stays stopped and the next sweep retries the whole thing.
-    expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
+    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
     expect(await executor.listDisks()).toContain(row.sandboxId);
     expect(readdirSync(tmpDir)).toEqual([]);
   });
@@ -130,7 +130,7 @@ describe('Archiver.archive', () => {
     await executor.create(sandboxId);
     const row = createSandbox(db, {
       sandboxId,
-      userKey: 'alice',
+      externalId: 'alice',
       nodeId: 'node-test',
       policy: DEFAULT_LIFECYCLE_POLICY,
     });
@@ -145,7 +145,7 @@ describe('Archiver.beginRestore', () => {
     const { db, executor, store, tmpDir, archiver } = setup();
     const row = await seedStopped(db, executor, 'alice');
     await archiver.archive(row);
-    const archived = findByUserKey(db, 'alice');
+    const archived = findByExternalId(db, 'alice');
     if (!archived) throw new Error('row vanished');
 
     let entry: ReturnType<Archiver['beginRestore']> | undefined;
@@ -153,13 +153,13 @@ describe('Archiver.beginRestore', () => {
       entry = archiver.beginRestore(archived);
     });
     // Non-blocking: the row is restoring the moment beginRestore returns.
-    expect(findByUserKey(db, 'alice')?.state).toBe('restoring');
+    expect(findByExternalId(db, 'alice')?.state).toBe('restoring');
     expect(archiver.hasLiveRestore(row.sandboxId)).toBe(true);
     expect(entry?.progress.phase).toBe('downloading');
 
     await archiver.restoreJoin(row.sandboxId);
 
-    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(findByExternalId(db, 'alice')?.state).toBe('active');
     expect(executor.stateOf(row.sandboxId)).toBe('running');
     expect(
       (await executor.readFile(row.sandboxId, 'kept.txt')).toString(),
@@ -176,7 +176,7 @@ describe('Archiver.beginRestore', () => {
     const row = await seedStopped(db, executor, 'alice');
     await archiver.archive(row);
     await store.delete(objectKey(row.sandboxId));
-    const archived = findByUserKey(db, 'alice');
+    const archived = findByExternalId(db, 'alice');
     if (!archived) throw new Error('row vanished');
 
     archiver.beginRestore(archived);
@@ -186,7 +186,7 @@ describe('Archiver.beginRestore', () => {
 
     // The S3 object is the only copy; with it gone the honest state is
     // archived-and-failing, retried on every acquire, loudly.
-    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
     expect(await executor.listDisks()).not.toContain(row.sandboxId);
     expect(archiver.hasLiveRestore(row.sandboxId)).toBe(false);
     expect(readdirSync(tmpDir)).toEqual([]);
@@ -196,16 +196,16 @@ describe('Archiver.beginRestore', () => {
     const { db, executor, archiver } = setup();
     const row = await seedStopped(db, executor, 'alice');
     await archiver.archive(row);
-    const archived = findByUserKey(db, 'alice');
+    const archived = findByExternalId(db, 'alice');
     if (!archived) throw new Error('row vanished');
 
     const first = archiver.beginRestore(archived);
     const again = archiver.beginRestore(
-      findByUserKey(db, 'alice') as SandboxRow,
+      findByExternalId(db, 'alice') as SandboxRow,
     );
     expect(again).toBe(first);
     await archiver.restoreJoin(row.sandboxId);
-    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(findByExternalId(db, 'alice')?.state).toBe('active');
   });
 });
 
@@ -216,12 +216,12 @@ describe('Archiver.restoreJoin', () => {
     await executor.create(sandboxId);
     createSandbox(db, {
       sandboxId,
-      userKey: 'alice',
+      externalId: 'alice',
       nodeId: 'node-test',
       policy: DEFAULT_LIFECYCLE_POLICY,
     });
     await archiver.restoreJoin(sandboxId);
-    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(findByExternalId(db, 'alice')?.state).toBe('active');
   });
 
   it('starts the restore itself when the row is archived', async () => {
@@ -231,7 +231,7 @@ describe('Archiver.restoreJoin', () => {
 
     await archiver.restoreJoin(row.sandboxId);
 
-    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(findByExternalId(db, 'alice')?.state).toBe('active');
     expect(executor.stateOf(row.sandboxId)).toBe('running');
   });
 });
diff --git a/packages/server/src/archive/archiver.ts b/packages/server/src/archive/archiver.ts
index 221945c..8edea98 100644
--- a/packages/server/src/archive/archiver.ts
+++ b/packages/server/src/archive/archiver.ts
@@ -113,7 +113,7 @@ export class Archiver {
     const seconds = ((Date.now() - startedAt) / 1000).toFixed(1);
     recordActivity(this.db, {
       kind: 'archived',
-      userKey: row.userKey,
+      externalId: row.externalId,
       sandboxId: row.sandboxId,
       detail: `disk shipped to S3 in ${seconds}s; local copy freed`,
     });
@@ -136,12 +136,12 @@ export class Archiver {
     transition(this.db, row.sandboxId, 'restoring');
     recordActivity(this.db, {
       kind: 'restore-started',
-      userKey: row.userKey,
+      externalId: row.externalId,
       sandboxId: row.sandboxId,
       detail: 'restore from S3 began',
     });
     const progress: RestoreProgress = { phase: 'downloading', percent: 0 };
-    const done = this.runRestore(row.sandboxId, row.userKey, progress).finally(
+    const done = this.runRestore(row.sandboxId, row.externalId, progress).finally(
       () => {
         this.restores.delete(row.sandboxId);
       },
@@ -178,7 +178,7 @@ export class Archiver {
     if (!row || (row.state !== 'archived' && row.state !== 'restoring')) {
       return;
     }
-    const entry = await this.locks.run(row.userKey, async () => {
+    const entry = await this.locks.run(row.externalId, async () => {
       const fresh = findBySandboxId(this.db, sandboxId);
       if (fresh?.state === 'archived') {
         return this.beginRestore(fresh) as RestoreEntry;
@@ -195,14 +195,14 @@ export class Archiver {
   /**
    * The restore task. Runs WITHOUT the key lock through the slow middle —
    * the restoring state is the guard (acquire polls answer progress,
-   * release answers 409, the scanner and reconciler skip) — and takes the
+   * destroy answers 409, the scanner and reconciler skip) — and takes the
    * slot only for the finish. On failure the half-built disk is removed and
    * the row reverts to archived: the S3 object is untouched, so the next
    * acquire is a clean retry.
    */
   private async runRestore(
     sandboxId: string,
-    userKey: string,
+    externalId: string,
     progress: RestoreProgress,
   ): Promise<void> {
     const tmp = path.join(this.tmpDir, `${sandboxId}.restore.tar.zst`);
@@ -215,14 +215,14 @@ export class Archiver {
       await this.executor.importDisk(sandboxId, tmp, (fraction) => {
         progress.percent = clampPercent(fraction);
       });
-      await this.locks.run(userKey, async () => {
+      await this.locks.run(externalId, async () => {
         const fresh = findBySandboxId(this.db, sandboxId);
         if (fresh?.state !== 'restoring') {
           // Nothing legal moves a restoring row but this task; hearing
           // otherwise is a bug report. The disk just built is task-owned.
           await this.executor.removeDisk(sandboxId);
           throw new Error(
-            `sandbox ${sandboxId} became ${fresh?.state ?? 'released'} mid-restore — the restoring state belongs to the restore task alone`,
+            `sandbox ${sandboxId} became ${fresh?.state ?? 'destroyed'} mid-restore — the restoring state belongs to the restore task alone`,
           );
         }
         await this.executor.start(sandboxId, {
@@ -238,13 +238,13 @@ export class Archiver {
         touch(this.db, sandboxId);
         recordActivity(this.db, {
           kind: 'restored',
-          userKey,
+          externalId,
           sandboxId,
           detail: 'disk back from S3, sandbox active; archive object deleted',
         });
       });
       // The object's job is done — the disk is local again, so from here
-      // "an object exists" means "the row is archived", and release never
+      // "an object exists" means "the row is archived", and destroy never
       // has to chase stale copies. Best effort: a leaked object costs
       // pennies, failing a finished restore over cleanup costs a wake.
       await this.store.delete(objectKey(sandboxId)).catch(() => {});
@@ -253,13 +253,13 @@ export class Archiver {
         `restore of ${sandboxId} failed: ${err instanceof Error ? err.message : String(err)}`,
       );
       await this.executor.removeDisk(sandboxId).catch(() => {});
-      await this.locks.run(userKey, async () => {
+      await this.locks.run(externalId, async () => {
         const fresh = findBySandboxId(this.db, sandboxId);
         if (fresh?.state === 'restoring') {
           transition(this.db, sandboxId, 'archived');
           recordActivity(this.db, {
             kind: 'restore-failed',
-            userKey,
+            externalId,
             sandboxId,
             detail: `back to archived, S3 object intact — ${
               err instanceof Error ? err.message : String(err)
diff --git a/packages/server/src/db/activity.ts b/packages/server/src/db/activity.ts
index d5985cd..a125d5f 100644
--- a/packages/server/src/db/activity.ts
+++ b/packages/server/src/db/activity.ts
@@ -13,7 +13,7 @@ export const ACTIVITY_KEEP = 1000;
 
 export interface ActivityInput {
   kind: ActivityKind;
-  userKey?: string | null;
+  externalId?: string | null;
   sandboxId?: string | null;
   detail: string;
 }
@@ -30,7 +30,7 @@ export function recordActivity(db: Db, input: ActivityInput): void {
     .values({
       at: new Date().toISOString(),
       kind: input.kind,
-      userKey: input.userKey ?? null,
+      externalId: input.externalId ?? null,
       sandboxId: input.sandboxId ?? null,
       detail: input.detail,
     })
diff --git a/packages/server/src/db/ledger.test.ts b/packages/server/src/db/ledger.test.ts
index e5d38aa..bf11633 100644
--- a/packages/server/src/db/ledger.test.ts
+++ b/packages/server/src/db/ledger.test.ts
@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { DEFAULT_LIFECYCLE_POLICY } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { type Db, migrateDb, openDb } from './db';
-import { createSandbox, findByUserKey, touch, transition } from './ledger';
+import { createSandbox, findByExternalId, touch, transition } from './ledger';
 
 const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
 
@@ -13,25 +13,25 @@ function testDb(): Db {
   return db;
 }
 
-function create(db: Db, userKey = 'user-1') {
+function create(db: Db, externalId = 'user-1') {
   return createSandbox(db, {
     sandboxId: randomUUID(),
-    userKey,
+    externalId,
     nodeId: 'node-1',
     policy: DEFAULT_LIFECYCLE_POLICY,
   });
 }
 
 describe('ledger', () => {
-  it('creates a sandbox in active state and finds it by user key', () => {
+  it('creates a sandbox in active state and finds it by external id', () => {
     const db = testDb();
     const created = create(db);
     expect(created.state).toBe('active');
-    expect(findByUserKey(db, 'user-1')).toEqual(created);
-    expect(findByUserKey(db, 'someone-else')).toBeUndefined();
+    expect(findByExternalId(db, 'user-1')).toEqual(created);
+    expect(findByExternalId(db, 'someone-else')).toBeUndefined();
   });
 
-  it('enforces one sandbox per user key at the database level', () => {
+  it('enforces one sandbox per external id at the database level', () => {
     const db = testDb();
     create(db);
     expect(() => create(db)).toThrow(/UNIQUE/);
@@ -49,7 +49,7 @@ describe('ledger', () => {
     ] as const) {
       expect(transition(db, sandboxId, to).state).toBe(to);
     }
-    expect(findByUserKey(db, 'user-1')?.state).toBe('active');
+    expect(findByExternalId(db, 'user-1')?.state).toBe('active');
   });
 
   it('wakes a frozen sandbox straight back to active', () => {
diff --git a/packages/server/src/db/ledger.ts b/packages/server/src/db/ledger.ts
index f2cdac8..f7a1f49 100644
--- a/packages/server/src/db/ledger.ts
+++ b/packages/server/src/db/ledger.ts
@@ -31,7 +31,7 @@ export interface CreateSandboxInput {
    * container is created under this id), then the ledger records it.
    */
   sandboxId: string;
-  userKey: string;
+  externalId: string;
   nodeId: string;
   policy: LifecyclePolicy;
   /** Template the sandbox is created from; absent/null means the base image. */
@@ -46,12 +46,12 @@ export interface CreateSandboxInput {
   };
 }
 
-/** Inserts a new sandbox row in `active` state. Throws if the user key is taken. */
+/** Inserts a new sandbox row in `active` state. Throws if the external id is taken. */
 export function createSandbox(db: Db, input: CreateSandboxInput): SandboxRow {
   const now = new Date().toISOString();
   const row: SandboxRow = {
     sandboxId: input.sandboxId,
-    userKey: input.userKey,
+    externalId: input.externalId,
     state: 'active',
     nodeId: input.nodeId,
     freezeAfterSeconds: input.policy.freezeAfterSeconds,
@@ -70,7 +70,7 @@ export function createSandbox(db: Db, input: CreateSandboxInput): SandboxRow {
   // The one place every creation passes through, whichever face asked.
   recordActivity(db, {
     kind: 'created',
-    userKey: row.userKey,
+    externalId: row.externalId,
     sandboxId: row.sandboxId,
     detail: `${input.e2b ? 'via E2B create' : 'via acquireSandbox'}${
       input.template ? `, template ${input.template}` : ''
@@ -160,7 +160,7 @@ export function setDeadline(
 
 /**
  * Rewrites the three lifecycle thresholds. Ledger-only: no container work,
- * no state change, and deliberately no touch — setPolicy is not activity,
+ * no state change, and deliberately no touch — updatePolicy is not activity,
  * the new thresholds judge the idle time already on the clock.
  */
 export function updatePolicy(
@@ -195,11 +195,11 @@ export function setPausedByUser(
     .run();
 }
 
-export function findByUserKey(db: Db, userKey: string): SandboxRow | undefined {
+export function findByExternalId(db: Db, externalId: string): SandboxRow | undefined {
   return db
     .select()
     .from(sandboxes)
-    .where(eq(sandboxes.userKey, userKey))
+    .where(eq(sandboxes.externalId, externalId))
     .get();
 }
 
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index e45df72..17ce4d0 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -12,8 +12,8 @@ import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
 export const sandboxes = sqliteTable('sandboxes', {
   /** UUID, never an autoincrement — ids must stay unique across machines. */
   sandboxId: text('sandbox_id').primaryKey(),
-  /** The key acquire() is idempotent on: one sandbox per user key. */
-  userKey: text('user_key').notNull().unique(),
+  /** The key acquire() is idempotent on: one sandbox per external id. */
+  externalId: text('external_id').notNull().unique(),
   state: text('state', { enum: SANDBOX_STATES }).notNull(),
   nodeId: text('node_id').notNull(),
   freezeAfterSeconds: integer('freeze_after_seconds').notNull(),
@@ -82,7 +82,7 @@ export const activity = sqliteTable('activity', {
   at: text('at').notNull(),
   kind: text('kind', { enum: ACTIVITY_KINDS }).notNull(),
   /** Null for events with no owning sandbox (orphan sweeps, daemon start). */
-  userKey: text('user_key'),
+  externalId: text('external_id'),
   sandboxId: text('sandbox_id'),
   detail: text('detail').notNull(),
 });
diff --git a/packages/server/src/db/templates.ts b/packages/server/src/db/templates.ts
index 7193314..6d9d658 100644
--- a/packages/server/src/db/templates.ts
+++ b/packages/server/src/db/templates.ts
@@ -48,16 +48,16 @@ export function removeTemplate(db: Db, name: string): boolean {
 }
 
 /**
- * User keys of sandboxes still created from this template — removal is
+ * External ids of sandboxes still created from this template — removal is
  * refused while this is non-empty, so wakes never resolve a dangling name.
  */
-export function sandboxKeysUsingTemplate(db: Db, name: string): string[] {
+export function externalIdsUsingTemplate(db: Db, name: string): string[] {
   return db
-    .select({ userKey: sandboxes.userKey })
+    .select({ externalId: sandboxes.externalId })
     .from(sandboxes)
     .where(eq(sandboxes.template, name))
     .all()
-    .map((row) => row.userKey);
+    .map((row) => row.externalId);
 }
 
 /**
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index c5b3931..33db5a2 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -216,10 +216,10 @@ describe('E2B control plane', () => {
     expect(t.executor.stateOf(first.sandboxID)).toBe('running');
   });
 
-  it('metadata.userKey is the Dormice extension: same key, same sandbox', async () => {
+  it('metadata.externalId is the Dormice extension: same key, same sandbox', async () => {
     const t = testApp();
-    const first = await createSandbox(t, { metadata: { userKey: 'agent-7' } });
-    const second = await createSandbox(t, { metadata: { userKey: 'agent-7' } });
+    const first = await createSandbox(t, { metadata: { externalId: 'agent-7' } });
+    const second = await createSandbox(t, { metadata: { externalId: 'agent-7' } });
     expect(second.sandboxID).toBe(first.sandboxID);
   });
 
@@ -227,13 +227,13 @@ describe('E2B control plane', () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t, {
       timeout: 600,
-      metadata: { userKey: 'meta-echo', team: 'blue' },
+      metadata: { externalId: 'meta-echo', team: 'blue' },
     });
     const res = await control(t, 'GET', `/sandboxes/${sandboxID}`);
     expect(res.statusCode).toBe(200);
     const info = res.json();
     expect(info.state).toBe('running');
-    expect(info.metadata).toEqual({ userKey: 'meta-echo', team: 'blue' });
+    expect(info.metadata).toEqual({ externalId: 'meta-echo', team: 'blue' });
     const endInMs = Date.parse(info.endAt) - Date.now();
     expect(endInMs).toBeGreaterThan(590_000);
     expect(endInMs).toBeLessThan(610_000);
@@ -513,7 +513,7 @@ describe('E2B control plane', () => {
       method: 'POST',
       url: '/acquireSandbox',
       headers: { authorization: `Bearer ${TOKEN}` },
-      payload: { userKey: 'native-immortal' },
+      payload: { externalId: 'native-immortal' },
     });
     const sandboxId = native.json().sandbox.sandboxId;
 
@@ -1689,20 +1689,20 @@ describe('E2B templates', () => {
     }
   });
 
-  it('userKey reuse keeps the original template; an unknown one still 404s first', async () => {
+  it('externalId reuse keeps the original template; an unknown one still 404s first', async () => {
     const t = testApp();
     await registerTemplate(t, 'tpl-a', 'img-a');
     await registerTemplate(t, 'tpl-b', 'img-b');
     const first = await createSandbox(t, {
       templateID: 'tpl-a',
-      metadata: { userKey: 'alice' },
+      metadata: { externalId: 'alice' },
     });
 
     // Same key, different template: the stored one stays — same principle
     // as metadata and envs on the reuse path.
     const again = await control(t, 'POST', '/sandboxes', {
       templateID: 'tpl-b',
-      metadata: { userKey: 'alice' },
+      metadata: { externalId: 'alice' },
     });
     expect(again.statusCode).toBe(201);
     expect(again.json().sandboxID).toBe(first.sandboxID);
@@ -1711,7 +1711,7 @@ describe('E2B templates', () => {
     // Validation happens before the reuse shortcut: a typo is a typo.
     const typo = await control(t, 'POST', '/sandboxes', {
       templateID: 'ghost',
-      metadata: { userKey: 'alice' },
+      metadata: { externalId: 'alice' },
     });
     expect(typo.statusCode).toBe(404);
   });
@@ -1721,7 +1721,7 @@ describe('E2B templates', () => {
     await registerTemplate(t, 'py311', 'img-py');
     await createSandbox(t, {
       templateID: 'py311',
-      metadata: { userKey: 'tpl-list' },
+      metadata: { externalId: 'tpl-list' },
     });
     const res = await control(t, 'GET', '/v2/sandboxes');
     const items = res.json() as Array<{ templateID: string; alias?: string }>;
@@ -1839,7 +1839,7 @@ describe('E2B surface vs the archiver', () => {
       url: '/acquireSandbox',
       headers: { authorization: `Bearer ${TOKEN}` },
       payload: {
-        userKey: 'native',
+        externalId: 'native',
         policy: {
           freezeAfterSeconds: 1,
           stopAfterSeconds: 2,
@@ -1864,16 +1864,16 @@ describe('E2B surface vs the archiver', () => {
     expect(findBySandboxId(t.db, sandboxID)?.state).toBe('active');
   });
 
-  it('create with metadata.userKey resumes its archived sandbox', async () => {
+  it('create with metadata.externalId resumes its archived sandbox', async () => {
     const t = archiverTestApp();
     const first = await createSandbox(t, {
       autoPause: true,
-      metadata: { userKey: 'alice' },
+      metadata: { externalId: 'alice' },
     });
     await walkToArchived(t, first.sandboxID);
 
     const res = await control(t, 'POST', '/sandboxes', {
-      metadata: { userKey: 'alice' },
+      metadata: { externalId: 'alice' },
     });
     expect(res.statusCode).toBe(201);
     expect(res.json().sandboxID).toBe(first.sandboxID);
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index 6e6b42b..d42653a 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -6,7 +6,7 @@ import {
   countSandboxes,
   createSandbox,
   findBySandboxId,
-  findByUserKey,
+  findByExternalId,
   listSandboxes,
   setDeadline,
   setPausedByUser,
@@ -16,7 +16,7 @@ import type { SandboxRow } from '../db/schema';
 import { findTemplate, resolveImage } from '../db/templates';
 import {
   freezeSandbox,
-  releaseSandbox,
+  destroySandbox,
   stopSandbox,
   wakeSandbox,
 } from '../lifecycle';
@@ -35,11 +35,11 @@ import { e2bView } from './view';
  * The E2B control plane: what the official SDK calls api.e2b.app for.
  * Mounted under /e2b/api; the SDK reaches it through its `apiUrl` option.
  * Faithful by default — timeouts kill, kill destroys; Dormice's immortality
- * is opt-in via metadata.userKey (idempotent create) or autoPause.
+ * is opt-in via metadata.externalId (idempotent create) or autoPause.
  */
 
-/** The Dormice extension key: metadata.userKey makes create idempotent. */
-const USER_KEY_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/;
+/** The Dormice extension key: metadata.externalId makes create idempotent. */
+const EXTERNAL_ID_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/;
 
 /** Seconds; E2B's default sandbox TTL. */
 const DEFAULT_TIMEOUT_SECONDS = 300;
@@ -243,19 +243,19 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     async (request, reply) => {
       const body = request.body;
       const timeoutSeconds = body.timeout ?? DEFAULT_TIMEOUT_SECONDS;
-      const requestedKey = body.metadata?.userKey;
-      if (requestedKey !== undefined && !USER_KEY_PATTERN.test(requestedKey)) {
+      const requestedKey = body.metadata?.externalId;
+      if (requestedKey !== undefined && !EXTERNAL_ID_PATTERN.test(requestedKey)) {
         throw apiError(
           400,
-          `invalid metadata.userKey "${requestedKey}": expected 1-64 chars of [a-zA-Z0-9._-]`,
+          `invalid metadata.externalId "${requestedKey}": expected 1-64 chars of [a-zA-Z0-9._-]`,
         );
       }
-      const userKey = requestedKey ?? `e2b-${randomUUID()}`;
+      const externalId = requestedKey ?? `e2b-${randomUUID()}`;
 
-      // The userKey reuse path may find an archived sandbox; the join
+      // The externalId reuse path may find an archived sandbox; the join
       // brings it back before the slot work below wakes it as usual.
       if (requestedKey !== undefined) {
-        await joinRestore(findByUserKey(db, requestedKey));
+        await joinRestore(findByExternalId(db, requestedKey));
       }
 
       // templateID resolution: a registered name wins; 'base', the base
@@ -275,8 +275,8 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         }
       }
 
-      const row = await locks.run(userKey, async () => {
-        const existing = findByUserKey(db, userKey);
+      const row = await locks.run(externalId, async () => {
+        const existing = findByExternalId(db, externalId);
         if (existing && e2bView(existing, new Date()) !== 'dead') {
           // The Dormice extension: same key, same sandbox — an acquire in
           // E2B clothes. Stored metadata/envs stay (same principle as the
@@ -289,13 +289,13 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         if (existing) {
           // Protocol-dead but not yet reaped: E2B semantics say it is gone,
           // so finish the job and build fresh under the same key.
-          await releaseSandbox(
+          await destroySandbox(
             db,
             executor,
             existing.sandboxId,
             archiver?.store ?? null,
             {
-              kind: 'released',
+              kind: 'destroyed',
               cause: 'protocol-dead row reaped by E2B create',
             },
           );
@@ -304,7 +304,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         if (countSandboxes(db) >= config.DORMICE_MAX_SANDBOXES) {
           throw apiError(
             429,
-            `sandbox limit reached (DORMICE_MAX_SANDBOXES=${config.DORMICE_MAX_SANDBOXES}) — release a sandbox or raise the limit`,
+            `sandbox limit reached (DORMICE_MAX_SANDBOXES=${config.DORMICE_MAX_SANDBOXES}) — destroy a sandbox or raise the limit`,
           );
         }
         const sandboxId = randomUUID();
@@ -313,7 +313,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         });
         return createSandbox(db, {
           sandboxId,
-          userKey,
+          externalId,
           nodeId: config.DORMICE_NODE_ID,
           policy: resolvePolicy(undefined, archiveDefaultSeconds),
           template,
@@ -346,7 +346,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       // then finds it active and the wake below is a no-op. Blocking is the
       // faithful behavior: E2B's connect returns a live sandbox, period.
       await joinRestore(before.row);
-      const row = await locks.run(before.row.userKey, async () => {
+      const row = await locks.run(before.row.externalId, async () => {
         const fresh = findBySandboxId(db, id);
         if (!fresh || e2bView(fresh, new Date()) === 'dead') {
           throw notFound(id);
@@ -403,26 +403,26 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
 
   app.delete('/sandboxes/:id', async (request, reply) => {
     const { id } = request.params as { id: string };
-    // kill = release, for real: container, disk and row gone. Persistence
-    // on the E2B surface is "don't kill" (autoPause / userKey), never a
+    // kill = destroy, for real: container, disk and row gone. Persistence
+    // on the E2B surface is "don't kill" (autoPause / externalId), never a
     // kill that secretly keeps data.
     const { row } = findLive(id);
     if (row.state === 'restoring') {
       // A mid-restore teardown would race the task over the half-built
       // disk; join it first. The outcome is irrelevant — we are deleting
       // either way, and a failed restore parks the row back on archived,
-      // whose release below deletes the S3 object.
+      // whose destroy below deletes the S3 object.
       await archiver?.restoreJoin(id).catch(() => {});
     }
-    await locks.run(row.userKey, async () => {
+    await locks.run(row.externalId, async () => {
       const fresh = findBySandboxId(db, id);
       if (!fresh) throw notFound(id);
-      await releaseSandbox(
+      await destroySandbox(
         db,
         executor,
         fresh.sandboxId,
         archiver?.store ?? null,
-        { kind: 'released', cause: 'via E2B kill' },
+        { kind: 'destroyed', cause: 'via E2B kill' },
       );
     });
     return reply.code(204).send();
@@ -458,7 +458,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         // The SDK reads a 409 as "already paused" and answers false.
         throw apiError(409, 'sandbox is already paused');
       }
-      await locks.run(before.row.userKey, async () => {
+      await locks.run(before.row.externalId, async () => {
         const fresh = findBySandboxId(db, id);
         if (!fresh) throw notFound(id);
         let current = fresh;
diff --git a/packages/server/src/e2b/envd/process.ts b/packages/server/src/e2b/envd/process.ts
index fa39ace..f4f7751 100644
--- a/packages/server/src/e2b/envd/process.ts
+++ b/packages/server/src/e2b/envd/process.ts
@@ -77,7 +77,7 @@ function streamSubscriber(write: (buf: Buffer) => Promise<void>): {
               envelope(FLAG_END_STREAM, {}),
             ]
           : [
-              // The container died under the process (a kill, a release):
+              // The container died under the process (a kill, a destroy):
               // an in-stream internal error, which the SDK triages via its
               // health check — the same feel as a killed E2B sandbox.
               envelope(FLAG_END_STREAM, {
diff --git a/packages/server/src/e2b/envd/shared.ts b/packages/server/src/e2b/envd/shared.ts
index 6417899..d3b89be 100644
--- a/packages/server/src/e2b/envd/shared.ts
+++ b/packages/server/src/e2b/envd/shared.ts
@@ -186,7 +186,7 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
 
   /**
    * Wake under the key's slot, like every native verb: physical wake-ups
-   * take seconds and must not race the scanner or a release.
+   * take seconds and must not race the scanner or a destroy.
    */
   async function wakeForUse(sandboxId: string): Promise<SandboxRow> {
     // The logical gate first: a paused-by-deadline sandbox answers 502
@@ -194,7 +194,7 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
     // will be refused anyway would waste a whole restore.
     const before = requireRunningRow(sandboxId);
     await joinRestore(sandboxId);
-    return locks.run(before.userKey, async () => {
+    return locks.run(before.externalId, async () => {
       const fresh = requireRunningRow(sandboxId);
       const awake = await wakeSandbox(db, executor, fresh);
       return touch(db, awake.sandboxId);
@@ -207,7 +207,7 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
   ): Promise<T> {
     const before = requireRunningRow(sandboxId);
     await joinRestore(sandboxId);
-    return locks.run(before.userKey, async () => {
+    return locks.run(before.externalId, async () => {
       const fresh = requireRunningRow(sandboxId);
       const awake = await wakeSandbox(db, executor, fresh);
       const row = touch(db, awake.sandboxId);
diff --git a/packages/server/src/e2b/view.test.ts b/packages/server/src/e2b/view.test.ts
index 91a98ae..208ed03 100644
--- a/packages/server/src/e2b/view.test.ts
+++ b/packages/server/src/e2b/view.test.ts
@@ -5,7 +5,7 @@ import { e2bView } from './view';
 function row(overrides: Partial<SandboxRow>): SandboxRow {
   return {
     sandboxId: 'sbx-1',
-    userKey: 'alice',
+    externalId: 'alice',
     state: 'active',
     nodeId: 'node-test',
     freezeAfterSeconds: 60,
diff --git a/packages/server/src/exec-heartbeat.ts b/packages/server/src/exec-heartbeat.ts
index 4fc82a9..54283e0 100644
--- a/packages/server/src/exec-heartbeat.ts
+++ b/packages/server/src/exec-heartbeat.ts
@@ -6,7 +6,7 @@ import { touch } from './db/ledger';
  * is in flight, so the scanner never freezes a container that is
  * mid-command. Half the freeze threshold (never above 10s) lands at least
  * one touch inside every scan window, down to the schema's minimum
- * freezeAfterSeconds of 1. A vanished row (released mid-exec) stops the
+ * freezeAfterSeconds of 1. A vanished row (destroyed mid-exec) stops the
  * timer — the exec itself will fail with its own honest error; an unhandled
  * throw inside setInterval would take the daemon down instead.
  */
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 32dd1d1..65749ea 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -389,7 +389,7 @@ export class DockerExecutor implements Executor {
       try {
         s = await stat(path.join(disksDir, name));
       } catch (err) {
-        // Torn down by a concurrent release between readdir and stat —
+        // Torn down by a concurrent destroy between readdir and stat —
         // a snapshot simply does not count what is no longer there.
         if ((err as NodeJS.ErrnoException).code === 'ENOENT') continue;
         throw err;
diff --git a/packages/server/src/keyed-queue.ts b/packages/server/src/keyed-queue.ts
index 87d2872..ec234b0 100644
--- a/packages/server/src/keyed-queue.ts
+++ b/packages/server/src/keyed-queue.ts
@@ -3,13 +3,13 @@ export const SKIPPED: unique symbol = Symbol('skipped');
 
 /**
  * The single serialization point for everything that operates on one
- * sandbox: acquire, release, the idle scanner's cooling moves and the
- * reconciler's repairs all take the sandbox's user-key slot before they
+ * sandbox: acquire, destroy, the idle scanner's cooling moves and the
+ * reconciler's repairs all take the sandbox's external-id slot before they
  * check-then-act. Each of those verbs has seconds of executor work between
  * its check and its act (create builds a disk, freeze can hold 45s in
  * memory.reclaim), and interleaving in that gap produced real corruption:
  * an acquire answering "ready" while the scanner was mid-freeze, two
- * releases racing one destroy into a 500.
+ * destroys racing one removal into a 500.
  *
  * One in-memory map suffices because the daemon is single-process by
  * design; different keys never wait on each other.
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index 7508030..1c02e39 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -38,7 +38,7 @@ export async function freezeSandbox(
   const row = transition(db, sandboxId, 'frozen');
   recordActivity(db, {
     kind: 'frozen',
-    userKey: row.userKey,
+    externalId: row.externalId,
     sandboxId,
     detail: cause ?? 'memory squeezed into swap',
   });
@@ -55,7 +55,7 @@ export async function stopSandbox(
   const row = transition(db, sandboxId, 'stopped');
   recordActivity(db, {
     kind: 'stopped',
-    userKey: row.userKey,
+    externalId: row.externalId,
     sandboxId,
     detail: cause ?? 'container torn down, disk kept',
   });
@@ -69,20 +69,20 @@ export async function stopSandbox(
  * of drift, not this caller's.
  *
  * An archived sandbox's body is its S3 object — nothing physical exists
- * locally, so release deletes the object instead of calling destroy (which
+ * locally, so destroy deletes the object instead of calling destroy (which
  * would honestly throw at the double absence). Every caller passes the
  * store explicitly (null = no archiver configured): releasing an archived
  * row without a store fails loudly and keeps the row, retryable once the
  * operator restores the DORMICE_S3_* configuration.
  */
-export async function releaseSandbox(
+export async function destroySandbox(
   db: Db,
   executor: Executor,
   sandboxId: string,
   store: ArchiveStore | null,
-  activity: { kind: 'released' | 'expired-killed'; cause: string } = {
-    kind: 'released',
-    cause: 'via releaseSandbox',
+  activity: { kind: 'destroyed' | 'expired-killed'; cause: string } = {
+    kind: 'destroyed',
+    cause: 'via destroySandbox',
   },
 ): Promise<void> {
   const row = findBySandboxId(db, sandboxId);
@@ -96,7 +96,7 @@ export async function releaseSandbox(
     deleteSandbox(db, sandboxId);
     recordActivity(db, {
       kind: activity.kind,
-      userKey: row.userKey,
+      externalId: row.externalId,
       sandboxId,
       detail: `${activity.cause}; archive object deleted`,
     });
@@ -107,7 +107,7 @@ export async function releaseSandbox(
   if (row) {
     recordActivity(db, {
       kind: activity.kind,
-      userKey: row.userKey,
+      externalId: row.externalId,
       sandboxId,
       detail: activity.cause,
     });
@@ -132,7 +132,7 @@ export async function rebuildSandbox(
   await executor.removeContainer(row.sandboxId);
   recordActivity(db, {
     kind: 'rebuilt',
-    userKey: row.userKey,
+    externalId: row.externalId,
     sandboxId: row.sandboxId,
     detail:
       'shell removed, disk kept — next wake builds from the current image',
@@ -185,7 +185,7 @@ function awaken(db: Db, row: SandboxRow, how: string): SandboxRow {
   const awake = transition(db, row.sandboxId, 'active');
   recordActivity(db, {
     kind: 'woken',
-    userKey: row.userKey,
+    externalId: row.externalId,
     sandboxId: row.sandboxId,
     detail: how,
   });
diff --git a/packages/server/src/reconciler.test.ts b/packages/server/src/reconciler.test.ts
index eeca470..3862bb5 100644
--- a/packages/server/src/reconciler.test.ts
+++ b/packages/server/src/reconciler.test.ts
@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { DEFAULT_LIFECYCLE_POLICY } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { type Db, migrateDb, openDb } from './db/db';
-import { createSandbox, findByUserKey, transition } from './db/ledger';
+import { createSandbox, findByExternalId, transition } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
@@ -34,13 +34,13 @@ function setup() {
 async function seed(
   db: Db,
   executor: FakeExecutor,
-  userKey: string,
+  externalId: string,
 ): Promise<SandboxRow> {
   const sandboxId = randomUUID();
   await executor.create(sandboxId);
   return createSandbox(db, {
     sandboxId,
-    userKey,
+    externalId,
     nodeId: 'node-test',
     policy: DEFAULT_LIFECYCLE_POLICY,
   });
@@ -51,7 +51,7 @@ describe('startup reconcile', () => {
     const { db, executor, locks } = setup();
     const row = await seed(db, executor, 'alice');
     expect(await reconcile(db, executor, locks)).toEqual(NONE);
-    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(findByExternalId(db, 'alice')?.state).toBe('active');
     expect(executor.stateOf(row.sandboxId)).toBe('running');
   });
 
@@ -63,7 +63,7 @@ describe('startup reconcile', () => {
 
     const result = await reconcile(db, executor, locks);
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByUserKey(db, 'alice')?.state).toBe('frozen');
+    expect(findByExternalId(db, 'alice')?.state).toBe('frozen');
   });
 
   it('repairs across rungs the transition table would forbid', async () => {
@@ -76,7 +76,7 @@ describe('startup reconcile', () => {
 
     const result = await reconcile(db, executor, locks);
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
+    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
   });
 
   it('keeps the row of a pruned container: the disk is the sandbox', async () => {
@@ -89,9 +89,9 @@ describe('startup reconcile', () => {
 
     const result = await reconcile(db, executor, locks);
     // Not a death: the sandbox is recorded as stopped, its row keeps the
-    // user key, and the next acquire rebuilds the container from the disk.
+    // external id, and the next acquire rebuilds the container from the disk.
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
+    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
     expect(await executor.listDisks()).toContain(row.sandboxId);
   });
 
@@ -105,13 +105,13 @@ describe('startup reconcile', () => {
 
     const result = await reconcile(db, executor, locks);
     expect(result).toEqual({ ...NONE, deletedRows: 1 });
-    expect(findByUserKey(db, 'alice')).toBeUndefined();
+    expect(findByExternalId(db, 'alice')).toBeUndefined();
   });
 
   it('destroys a container no row points at', async () => {
     const { db, executor, locks } = setup();
     // Crash between executor.create() and createSandbox(): a container was
-    // born but never entered the ledger, so no user key can ever reach it.
+    // born but never entered the ledger, so no external id can ever reach it.
     await executor.create('orphan');
 
     const result = await reconcile(db, executor, locks);
@@ -135,7 +135,7 @@ describe('startup reconcile', () => {
       ...NONE,
       archivedSwept: 1,
     });
-    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
     expect(executor.stateOf(row.sandboxId)).toBeUndefined();
     expect(await executor.listDisks()).not.toContain(row.sandboxId);
   });
@@ -154,7 +154,7 @@ describe('startup reconcile', () => {
       ...NONE,
       archivedSwept: 1,
     });
-    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
     expect(await executor.listDisks()).not.toContain(row.sandboxId);
   });
 
@@ -171,7 +171,7 @@ describe('startup reconcile', () => {
     // Nothing local, and crucially NOT deletedRows: an archived row with no
     // local remains is the normal state, not drift.
     expect(await reconcile(db, executor, locks)).toEqual(NONE);
-    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
   });
 
   it('reverts a restoring zombie with no live task to archived', async () => {
@@ -192,7 +192,7 @@ describe('startup reconcile', () => {
     // The disk is the task's garbage; the S3 object is intact, so archived
     // makes the next acquire a clean retry.
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
     expect(await executor.listDisks()).not.toContain(row.sandboxId);
   });
 
@@ -212,7 +212,7 @@ describe('startup reconcile', () => {
 
     const result = await reconcile(db, executor, locks);
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(findByExternalId(db, 'alice')?.state).toBe('active');
     expect(executor.stateOf(row.sandboxId)).toBe('running');
   });
 
@@ -233,7 +233,7 @@ describe('startup reconcile', () => {
       hasLiveRestore: () => true,
     });
     expect(result).toEqual(NONE);
-    expect(findByUserKey(db, 'alice')?.state).toBe('restoring');
+    expect(findByExternalId(db, 'alice')?.state).toBe('restoring');
     // The mid-flight disk also dodges the orphan pass: the row owns it.
     expect(await executor.listDisks()).toContain(row.sandboxId);
   });
@@ -259,10 +259,10 @@ describe('startup reconcile', () => {
       archivedSwept: 0,
       suspects: [],
     });
-    expect(findByUserKey(db, 'healthy')?.state).toBe('active');
-    expect(findByUserKey(db, 'drifted')?.state).toBe('frozen');
-    expect(findByUserKey(db, 'pruned')?.state).toBe('stopped');
-    expect(findByUserKey(db, 'dead')).toBeUndefined();
+    expect(findByExternalId(db, 'healthy')?.state).toBe('active');
+    expect(findByExternalId(db, 'drifted')?.state).toBe('frozen');
+    expect(findByExternalId(db, 'pruned')?.state).toBe('stopped');
+    expect(findByExternalId(db, 'dead')).toBeUndefined();
     expect(executor.stateOf(healthy.sandboxId)).toBe('running');
     expect(executor.stateOf('orphan')).toBeUndefined();
   });
@@ -300,7 +300,7 @@ describe('runtime reconcile (two-strike orphans)', () => {
     // The acquire finished: the row is in the ledger now.
     createSandbox(db, {
       sandboxId: 'in-flight',
-      userKey: 'alice',
+      externalId: 'alice',
       nodeId: 'node-test',
       policy: DEFAULT_LIFECYCLE_POLICY,
     });
@@ -313,7 +313,7 @@ describe('runtime reconcile (two-strike orphans)', () => {
     );
     expect(second).toEqual(NONE);
     expect(executor.stateOf('in-flight')).toBe('running');
-    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(findByExternalId(db, 'alice')?.state).toBe('active');
   });
 
   it('still repairs and buries on every runtime pass, not only at boot', async () => {
@@ -324,7 +324,7 @@ describe('runtime reconcile (two-strike orphans)', () => {
 
     const result = await reconcile(db, executor, locks, new Set());
     expect(result).toEqual({ ...NONE, deletedRows: 1 });
-    expect(findByUserKey(db, 'alice')).toBeUndefined();
+    expect(findByExternalId(db, 'alice')).toBeUndefined();
   });
 
   it('skips a row whose key is busy instead of repairing from a stale view', async () => {
@@ -345,14 +345,14 @@ describe('runtime reconcile (two-strike orphans)', () => {
 
     const result = await reconcile(db, executor, locks, new Set());
     expect(result.repairedStates).toBe(0);
-    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(findByExternalId(db, 'alice')?.state).toBe('active');
 
     release();
     await holder;
     // Next tick, with the key free, the repair lands.
     const next = await reconcile(db, executor, locks, new Set());
     expect(next).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByUserKey(db, 'alice')?.state).toBe('frozen');
+    expect(findByExternalId(db, 'alice')?.state).toBe('frozen');
   });
 });
 
diff --git a/packages/server/src/reconciler.ts b/packages/server/src/reconciler.ts
index 2361b39..7e1aeea 100644
--- a/packages/server/src/reconciler.ts
+++ b/packages/server/src/reconciler.ts
@@ -60,15 +60,15 @@ const LEDGER_STATE: Record<ContainerState, SandboxState> = {
  *                                a routine `docker container prune`
  *                                survivable instead of silent data loss.
  * - container and disk gone   -> the sandbox truly is gone (an interrupted
- *                                release, a wiped data dir): the row is
- *                                deleted and the user key is free again
+ *                                destroy, a wiped data dir): the row is
+ *                                deleted and the external id is free again
  * - container without a row   -> destroyed; without a row it has no user
  *                                key, so nothing could ever reach it
  * - disk owned by nothing     -> removed; leaked disks silently eat the host
  *
  * Every rowed repair happens inside the sandbox's per-key queue slot, and
  * only if the row still shows the state the snapshot decided on: an acquire
- * or release that moved the sandbox in between makes the observation stale,
+ * or destroy that moved the sandbox in between makes the observation stale,
  * and writing a stale repair would manufacture the very drift this function
  * exists to remove. A busy key is skipped outright — whatever holds it has
  * fresher knowledge — and the next tick sees the settled picture.
@@ -123,7 +123,7 @@ export async function reconcile(
     row: SandboxRow,
     apply: () => void | Promise<void>,
   ) =>
-    locks.tryRun(row.userKey, async () => {
+    locks.tryRun(row.externalId, async () => {
       const fresh = findBySandboxId(db, row.sandboxId);
       if (fresh && fresh.state === row.state) {
         await apply();
@@ -135,7 +135,7 @@ export async function reconcile(
   const note = (row: SandboxRow, detail: string) =>
     recordActivity(db, {
       kind: 'reconciled',
-      userKey: row.userKey,
+      externalId: row.externalId,
       sandboxId: row.sandboxId,
       detail,
     });
diff --git a/packages/server/src/routes/observability.test.ts b/packages/server/src/routes/observability.test.ts
index c12f2b2..3f15e76 100644
--- a/packages/server/src/routes/observability.test.ts
+++ b/packages/server/src/routes/observability.test.ts
@@ -157,7 +157,7 @@ describe('listActivity', () => {
   it('records create, wake, cooling and release, newest first', async () => {
     const { app, db, executor, locks } = testApp();
     const res = await rpc(app, '/acquireSandbox', {
-      userKey: 'story',
+      externalId: 'story',
       policy: { freezeAfterSeconds: 5, stopAfterSeconds: 10 },
     });
     expect(res.statusCode).toBe(200);
@@ -176,19 +176,19 @@ describe('listActivity', () => {
       locks,
       new Date(Date.parse(created.lastActiveAt) + 11_000),
     );
-    await rpc(app, '/acquireSandbox', { userKey: 'story' });
-    await rpc(app, '/releaseSandbox', { userKey: 'story' });
+    await rpc(app, '/acquireSandbox', { externalId: 'story' });
+    await rpc(app, '/destroySandbox', { externalId: 'story' });
 
     const log = await events(app);
     expect(log.map((e) => e.kind)).toEqual([
-      'released',
+      'destroyed',
       'woken',
       'stopped',
       'frozen',
       'created',
     ]);
     // Every event names its sandbox, and the scanner names its threshold.
-    expect(new Set(log.map((e) => e.userKey))).toEqual(new Set(['story']));
+    expect(new Set(log.map((e) => e.externalId))).toEqual(new Set(['story']));
     expect(log.find((e) => e.kind === 'frozen')?.detail).toContain('scanner');
     expect(log.find((e) => e.kind === 'created')?.detail).toContain(
       'acquireSandbox',
@@ -197,14 +197,14 @@ describe('listActivity', () => {
 
   it('records what reconciliation repaired', async () => {
     const { app, db, executor, locks } = testApp();
-    await rpc(app, '/acquireSandbox', { userKey: 'doomed' });
+    await rpc(app, '/acquireSandbox', { externalId: 'doomed' });
     const { sandboxes } = (await rpc(app, '/listSandboxes')).json();
     // Reality loses both container and disk behind the ledger's back.
     await executor.destroy(sandboxes[0].sandboxId);
     await reconcile(db, executor, locks);
 
     const log = await events(app);
-    expect(log[0]).toMatchObject({ kind: 'reconciled', userKey: 'doomed' });
+    expect(log[0]).toMatchObject({ kind: 'reconciled', externalId: 'doomed' });
     expect(log[0]?.detail).toContain('row deleted');
   });
 
@@ -242,8 +242,8 @@ describe('listActivity', () => {
 describe('getSandboxMetrics', () => {
   it('answers a single sample for a running sandbox', async () => {
     const { app } = testApp();
-    await rpc(app, '/acquireSandbox', { userKey: 'measured' });
-    const res = await rpc(app, '/getSandboxMetrics', { userKey: 'measured' });
+    await rpc(app, '/acquireSandbox', { externalId: 'measured' });
+    const res = await rpc(app, '/getSandboxMetrics', { externalId: 'measured' });
     expect(res.statusCode).toBe(200);
     const { sample } = getSandboxMetricsResponseSchema.parse(res.json());
     expect(sample).not.toBeNull();
@@ -253,12 +253,12 @@ describe('getSandboxMetrics', () => {
 
   it('answers null for a stopped sandbox instead of waking it', async () => {
     const { app, db, executor } = testApp();
-    const res = await rpc(app, '/acquireSandbox', { userKey: 'cold' });
+    const res = await rpc(app, '/acquireSandbox', { externalId: 'cold' });
     const { sandboxId } = res.json().sandbox;
     await freezeSandbox(db, executor, sandboxId);
     await stopSandbox(db, executor, sandboxId);
 
-    const metrics = await rpc(app, '/getSandboxMetrics', { userKey: 'cold' });
+    const metrics = await rpc(app, '/getSandboxMetrics', { externalId: 'cold' });
     expect(getSandboxMetricsResponseSchema.parse(metrics.json()).sample).toBe(
       null,
     );
@@ -269,7 +269,7 @@ describe('getSandboxMetrics', () => {
 
   it('404s an unknown key instead of inventing a sandbox', async () => {
     const { app } = testApp();
-    const res = await rpc(app, '/getSandboxMetrics', { userKey: 'nobody' });
+    const res = await rpc(app, '/getSandboxMetrics', { externalId: 'nobody' });
     expect(res.statusCode).toBe(404);
   });
 });
@@ -277,10 +277,10 @@ describe('getSandboxMetrics', () => {
 describe('listSandboxMetrics', () => {
   it('measures active and frozen sandboxes; colder states are absent', async () => {
     const { app, db, executor } = testApp();
-    await rpc(app, '/acquireSandbox', { userKey: 'hot' });
-    const frozen = await rpc(app, '/acquireSandbox', { userKey: 'napping' });
+    await rpc(app, '/acquireSandbox', { externalId: 'hot' });
+    const frozen = await rpc(app, '/acquireSandbox', { externalId: 'napping' });
     await freezeSandbox(db, executor, frozen.json().sandbox.sandboxId);
-    const cold = await rpc(app, '/acquireSandbox', { userKey: 'cold' });
+    const cold = await rpc(app, '/acquireSandbox', { externalId: 'cold' });
     const coldId = cold.json().sandbox.sandboxId;
     await freezeSandbox(db, executor, coldId);
     await stopSandbox(db, executor, coldId);
@@ -288,7 +288,7 @@ describe('listSandboxMetrics', () => {
     const res = await rpc(app, '/listSandboxMetrics', {});
     expect(res.statusCode).toBe(200);
     const { samples } = listSandboxMetricsResponseSchema.parse(res.json());
-    const keys = samples.map((s) => s.userKey).sort();
+    const keys = samples.map((s) => s.externalId).sort();
     // The frozen sandbox is measured as it sleeps; the stopped one has no
     // container to measure and is honestly absent, not null-stuffed.
     expect(keys).toEqual(['hot', 'napping']);
@@ -299,8 +299,8 @@ describe('listSandboxMetrics', () => {
     // Observation is not activity: nobody woke or cooled further.
     const { sandboxes } = (await rpc(app, '/listSandboxes')).json();
     const byKey = new Map<string, string>(
-      sandboxes.map((s: { userKey: string; state: string }) => [
-        s.userKey,
+      sandboxes.map((s: { externalId: string; state: string }) => [
+        s.externalId,
         s.state,
       ]),
     );
@@ -310,8 +310,8 @@ describe('listSandboxMetrics', () => {
 
   it('skips a sandbox whose container vanished instead of failing the sweep', async () => {
     const { app, executor } = testApp();
-    await rpc(app, '/acquireSandbox', { userKey: 'alive' });
-    const doomed = await rpc(app, '/acquireSandbox', { userKey: 'doomed' });
+    await rpc(app, '/acquireSandbox', { externalId: 'alive' });
+    const doomed = await rpc(app, '/acquireSandbox', { externalId: 'doomed' });
     // The container dies physically, past the ledger (gVisor OOM does this
     // for real) — the row still says active, the reading throws, the sweep
     // reports what it could see.
@@ -321,7 +321,7 @@ describe('listSandboxMetrics', () => {
 
     const res = await rpc(app, '/listSandboxMetrics', {});
     const { samples } = listSandboxMetricsResponseSchema.parse(res.json());
-    expect(samples.map((s) => s.userKey)).toEqual(['alive']);
+    expect(samples.map((s) => s.externalId)).toEqual(['alive']);
   });
 
   it('answers an empty list on an empty ledger', async () => {
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index 3ac58a5..ba58709 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -11,17 +11,22 @@ import {
   listSandboxesResponseSchema,
   listSandboxMetricsRequestSchema,
   listSandboxMetricsResponseSchema,
+  READ_FILES_TOTAL_LIMIT_BYTES,
   readFileRequestSchema,
   readFileResponseSchema,
+  readFilesRequestSchema,
+  readFilesResponseSchema,
   rebuildSandboxRequestSchema,
   rebuildSandboxResponseSchema,
-  releaseSandboxRequestSchema,
-  releaseSandboxResponseSchema,
+  destroySandboxRequestSchema,
+  destroySandboxResponseSchema,
   resolveSandboxPath,
   type Sandbox,
-  setPolicyRequestSchema,
-  setPolicyResponseSchema,
+  updatePolicyRequestSchema,
+  updatePolicyResponseSchema,
   WRITE_FILES_BODY_LIMIT_BYTES,
+  writeFileRequestSchema,
+  writeFileResponseSchema,
   writeFilesRequestSchema,
   writeFilesResponseSchema,
 } from '@dormice/shared';
@@ -34,7 +39,7 @@ import type { Db } from '../db/db';
 import {
   countSandboxes,
   createSandbox,
-  findByUserKey,
+  findByExternalId,
   listSandboxes,
   touch,
   updatePolicy,
@@ -50,7 +55,7 @@ import {
 } from '../executor/executor';
 import { httpError } from '../http-error';
 import type { KeyedQueue } from '../keyed-queue';
-import { rebuildSandbox, releaseSandbox, wakeSandbox } from '../lifecycle';
+import { rebuildSandbox, destroySandbox, wakeSandbox } from '../lifecycle';
 import { ArchiveDisabledError, resolvePolicy } from '../policy';
 
 export interface SandboxRoutesOptions {
@@ -73,7 +78,7 @@ type AcquireOutcome =
 function toSandbox(row: SandboxRow, endpoint: string): Sandbox {
   return {
     sandboxId: row.sandboxId,
-    userKey: row.userKey,
+    externalId: row.externalId,
     state: row.state,
     nodeId: row.nodeId,
     endpoint,
@@ -106,11 +111,11 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
   // request queues, finds the row the first one wrote, and comes back with
   // the same sandbox instead of racing a duplicate create.
   async function findOrCreate(
-    userKey: string,
+    externalId: string,
     policy: LifecyclePolicy,
     template: string | null,
   ): Promise<AcquireOutcome> {
-    const existing = findByUserKey(db, userKey);
+    const existing = findByExternalId(db, externalId);
     if (existing?.state === 'archived' || existing?.state === 'restoring') {
       // The protocol's promise: acquire never blocks on a slow wake-up. An
       // archived sandbox starts its restore and answers `restoring` with
@@ -118,15 +123,15 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       if (!archiver) {
         throw httpError(
           503,
-          `sandbox for key "${userKey}" is ${existing.state} but the daemon has no S3 configured (DORMICE_S3_*) — restore is impossible until it is`,
+          `sandbox for key "${externalId}" is ${existing.state} but the daemon has no S3 configured (DORMICE_S3_*) — restore is impossible until it is`,
         );
       }
       if (existing.state === 'archived') {
         archiver.beginRestore(existing);
       }
-      const restoring = findByUserKey(db, userKey);
+      const restoring = findByExternalId(db, externalId);
       if (!restoring) {
-        throw httpError(500, `sandbox for key "${userKey}" vanished mid-slot`);
+        throw httpError(500, `sandbox for key "${externalId}" vanished mid-slot`);
       }
       return {
         status: 'restoring',
@@ -156,7 +161,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     if (countSandboxes(db) >= config.DORMICE_MAX_SANDBOXES) {
       throw httpError(
         429,
-        `sandbox limit reached (DORMICE_MAX_SANDBOXES=${config.DORMICE_MAX_SANDBOXES}) — release a sandbox or raise the limit`,
+        `sandbox limit reached (DORMICE_MAX_SANDBOXES=${config.DORMICE_MAX_SANDBOXES}) — destroy a sandbox or raise the limit`,
       );
     }
 
@@ -173,7 +178,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       status: 'ready',
       row: createSandbox(db, {
         sandboxId,
-        userKey,
+        externalId,
         nodeId: config.DORMICE_NODE_ID,
         policy,
         template,
@@ -186,12 +191,12 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
   // is more likely a typo than an intent to build a sandbox as a side
   // effect — then wake whatever cold state the sandbox is in and refresh
   // its idle clock. Must be called while holding the key's queue slot.
-  async function wakeForUse(userKey: string): Promise<SandboxRow> {
-    const existing = findByUserKey(db, userKey);
+  async function wakeForUse(externalId: string): Promise<SandboxRow> {
+    const existing = findByExternalId(db, externalId);
     if (!existing) {
       throw httpError(
         404,
-        `no sandbox for key "${userKey}" — acquire it first`,
+        `no sandbox for key "${externalId}" — acquire it first`,
       );
     }
     if (existing.state === 'archived' || existing.state === 'restoring') {
@@ -199,7 +204,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       // blocks for minutes nor starts restores on the side.
       throw httpError(
         409,
-        `sandbox for key "${userKey}" is ${existing.state} — call acquireSandbox and poll until it is ready`,
+        `sandbox for key "${externalId}" is ${existing.state} — call acquireSandbox and poll until it is ready`,
       );
     }
     const awake = await wakeSandbox(db, executor, existing);
@@ -222,7 +227,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request, reply) => {
-      const { userKey, policy: override, template } = request.body;
+      const { externalId, policy: override, template } = request.body;
 
       // Validate the policy before taking the key's slot, so a queued
       // rejection can only come from the work itself, never from another
@@ -259,8 +264,8 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         });
       }
 
-      const outcome = await locks.run(userKey, () =>
-        findOrCreate(userKey, policy, template ?? null),
+      const outcome = await locks.run(externalId, () =>
+        findOrCreate(externalId, policy, template ?? null),
       );
       if (outcome.status === 'restoring') {
         return {
@@ -304,12 +309,12 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { userKey } = request.body;
-      const row = findByUserKey(db, userKey);
+      const { externalId } = request.body;
+      const row = findByExternalId(db, externalId);
       if (!row) {
         throw httpError(
           404,
-          `no sandbox for key "${userKey}" — acquire it first`,
+          `no sandbox for key "${externalId}" — acquire it first`,
         );
       }
       if (row.state !== 'active' && row.state !== 'frozen') {
@@ -343,7 +348,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
           try {
             const m = await executor.metrics(row.sandboxId);
             return {
-              userKey: row.userKey,
+              externalId: row.externalId,
               sandboxId: row.sandboxId,
               sample: { timestamp: new Date().toISOString(), ...m },
             };
@@ -365,16 +370,16 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { userKey, command, timeoutSeconds, cwd, env } = request.body;
+      const { externalId, command, timeoutSeconds, cwd, env } = request.body;
 
       // Only the wake takes the key's queue slot — seconds of executor
       // work, the same serialization story as acquire. The exec itself
       // runs OUTSIDE the slot: a command may legally run for hours, and
-      // holding the slot would block release and every other verb for its
+      // holding the slot would block destroy and every other verb for its
       // whole duration. The heartbeat keeps the scanner away; a concurrent
-      // release mid-exec destroys the container and this exec fails with
+      // destroy mid-exec removes the container and this exec fails with
       // the executor's honest error — accepted, not defended against.
-      const row = await locks.run(userKey, () => wakeForUse(userKey));
+      const row = await locks.run(externalId, () => wakeForUse(externalId));
 
       const stopHeartbeat = startExecHeartbeat(
         db,
@@ -409,12 +414,12 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     throw error;
   }
 
-  // Both file verbs run ENTIRELY inside the key's queue slot, unlike exec:
-  // a file operation's work is bounded (16 MiB against a local ext4 —
+  // The file verbs run ENTIRELY inside the key's queue slot, unlike exec:
+  // a file operation's work is bounded (48 MiB against a local ext4 —
   // seconds at worst), so holding the slot is cheap and buys the same
   // guarantees acquire enjoys — the scanner cannot freeze the sandbox
-  // mid-write and a concurrent release queues up behind us instead of
-  // destroying the container under our feet. No heartbeat needed.
+  // mid-write and a concurrent destroy queues up behind us instead of
+  // removing the container under our feet. No heartbeat needed.
   app.post(
     '/writeFiles',
     {
@@ -426,9 +431,9 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { userKey, files } = request.body;
-      return locks.run(userKey, async () => {
-        const row = await wakeForUse(userKey);
+      const { externalId, files } = request.body;
+      return locks.run(externalId, async () => {
+        const row = await wakeForUse(externalId);
         try {
           await executor.writeFiles(
             row.sandboxId,
@@ -448,6 +453,35 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     },
   );
 
+  // The single-file form of writeFiles: same slot, same executor call, no
+  // array ceremony. The transport gate is shared with the batch — the
+  // schema's per-file cap is the real limit.
+  app.post(
+    '/writeFile',
+    {
+      bodyLimit: WRITE_FILES_BODY_LIMIT_BYTES,
+      schema: {
+        body: writeFileRequestSchema,
+        response: { 200: writeFileResponseSchema },
+      },
+    },
+    async (request) => {
+      const { externalId, path, contentBase64 } = request.body;
+      return locks.run(externalId, async () => {
+        const row = await wakeForUse(externalId);
+        try {
+          await executor.writeFiles(row.sandboxId, [
+            { path, content: Buffer.from(contentBase64, 'base64') },
+          ]);
+        } catch (error) {
+          throwFileHttpError(error);
+        }
+        touch(db, row.sandboxId);
+        return { path: resolveSandboxPath(path) };
+      });
+    },
+  );
+
   app.post(
     '/readFile',
     {
@@ -457,9 +491,9 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { userKey, path } = request.body;
-      return locks.run(userKey, async () => {
-        const row = await wakeForUse(userKey);
+      const { externalId, path } = request.body;
+      return locks.run(externalId, async () => {
+        const row = await wakeForUse(externalId);
         let content: Buffer;
         try {
           content = await executor.readFile(row.sandboxId, path);
@@ -475,6 +509,48 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     },
   );
 
+  // Batch reads are all or nothing (see readFilesRequestSchema): the first
+  // failing path aborts the call through throwFileHttpError, and the running
+  // total is gated so a broad glob cannot buffer the daemon into the ground.
+  app.post(
+    '/readFiles',
+    {
+      schema: {
+        body: readFilesRequestSchema,
+        response: { 200: readFilesResponseSchema },
+      },
+    },
+    async (request) => {
+      const { externalId, paths } = request.body;
+      return locks.run(externalId, async () => {
+        const row = await wakeForUse(externalId);
+        const files: { path: string; contentBase64: string }[] = [];
+        let totalBytes = 0;
+        for (const path of paths) {
+          let content: Buffer;
+          try {
+            content = await executor.readFile(row.sandboxId, path);
+          } catch (error) {
+            throwFileHttpError(error);
+          }
+          totalBytes += content.length;
+          if (totalBytes > READ_FILES_TOTAL_LIMIT_BYTES) {
+            throw httpError(
+              413,
+              `readFiles batch exceeds the ${READ_FILES_TOTAL_LIMIT_BYTES}-byte total limit at "${resolveSandboxPath(path)}" — split it into smaller calls`,
+            );
+          }
+          files.push({
+            path: resolveSandboxPath(path),
+            contentBase64: content.toString('base64'),
+          });
+        }
+        touch(db, row.sandboxId);
+        return { files };
+      });
+    },
+  );
+
   app.post(
     '/rebuildSandbox',
     {
@@ -484,18 +560,18 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { userKey } = request.body;
+      const { externalId } = request.body;
       // The whole verb holds the key's slot, like the file verbs: seconds of
       // executor work at worst, and the slot keeps the scanner and a
-      // concurrent release from moving the sandbox under our feet.
-      return locks.run(userKey, async () => {
-        const existing = findByUserKey(db, userKey);
+      // concurrent destroy from moving the sandbox under our feet.
+      return locks.run(externalId, async () => {
+        const existing = findByExternalId(db, externalId);
         if (!existing) {
           // Not a creator and not a destroyer: an unknown key is a typo,
           // not a goal state — same manners as exec.
           throw httpError(
             404,
-            `no sandbox for key "${userKey}" — acquire it first`,
+            `no sandbox for key "${externalId}" — acquire it first`,
           );
         }
         if (existing.state === 'archived' || existing.state === 'restoring') {
@@ -503,7 +579,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
           // rebuild's promise (its next wake builds from the current image).
           throw httpError(
             409,
-            `sandbox for key "${userKey}" is ${existing.state} — it has no container to rebuild`,
+            `sandbox for key "${externalId}" is ${existing.state} — it has no container to rebuild`,
           );
         }
         const row = await rebuildSandbox(db, executor, existing);
@@ -513,30 +589,30 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
   );
 
   app.post(
-    '/setPolicy',
+    '/updatePolicy',
     {
       schema: {
-        body: setPolicyRequestSchema,
+        body: updatePolicyRequestSchema,
         response: {
-          200: setPolicyResponseSchema,
+          200: updatePolicyResponseSchema,
           400: z.object({ message: z.string() }),
         },
       },
     },
     async (request, reply) => {
-      const { userKey, policy: patch } = request.body;
+      const { externalId, policy: patch } = request.body;
       // Unlike acquire, the merge base is the STORED policy, so validation
       // must wait for the row — it runs inside the slot, which also keeps a
-      // concurrent release from deleting the row between check and write.
+      // concurrent destroy from deleting the row between check and write.
       const outcome = await locks.run<{ error: string } | { row: SandboxRow }>(
-        userKey,
+        externalId,
         async () => {
-          const existing = findByUserKey(db, userKey);
+          const existing = findByExternalId(db, externalId);
           if (!existing) {
             // Not a creator: an unknown key is a typo, same manners as rebuild.
             throw httpError(
               404,
-              `no sandbox for key "${userKey}" — acquire it first`,
+              `no sandbox for key "${externalId}" — acquire it first`,
             );
           }
           // Legal in every state: policy is a ledger attribute, not a container
@@ -590,7 +666,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
             seconds === null ? 'never' : `${seconds}s`;
           recordActivity(db, {
             kind: 'policy-changed',
-            userKey,
+            externalId,
             sandboxId: row.sandboxId,
             detail: changed
               .map(
@@ -610,39 +686,39 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
   );
 
   app.post(
-    '/releaseSandbox',
+    '/destroySandbox',
     {
       schema: {
-        body: releaseSandboxRequestSchema,
-        response: { 200: releaseSandboxResponseSchema },
+        body: destroySandboxRequestSchema,
+        response: { 200: destroySandboxResponseSchema },
       },
     },
     async (request) => {
-      const { userKey } = request.body;
-      // Same slot as acquire and the scanner: two parallel releases of one
+      const { externalId } = request.body;
+      // Same slot as acquire and the scanner: two parallel destroys of one
       // key queue up — the first destroys, the second re-checks and reports
       // the goal state honestly instead of tripping over a half-destroyed
       // sandbox.
-      return locks.run(userKey, async () => {
-        const existing = findByUserKey(db, userKey);
+      return locks.run(externalId, async () => {
+        const existing = findByExternalId(db, externalId);
         if (!existing) {
           // Idempotent like acquire: the desired end state — no sandbox
           // under this key — already holds.
-          return { released: false };
+          return { destroyed: false };
         }
         if (existing.state === 'restoring') {
-          // The one documented dent in release's idempotence: tearing the
+          // The one documented dent in destroy's idempotence: tearing the
           // half-built disk down would race the restore task over it. The
           // task finishes in seconds to minutes; retry then.
           throw httpError(409, 'sandbox is restoring; retry when it finishes');
         }
-        await releaseSandbox(
+        await destroySandbox(
           db,
           executor,
           existing.sandboxId,
           archiver?.store ?? null,
         );
-        return { released: true };
+        return { destroyed: true };
       });
     },
   );
diff --git a/packages/server/src/routes/templates.ts b/packages/server/src/routes/templates.ts
index 92c556b..6e7a281 100644
--- a/packages/server/src/routes/templates.ts
+++ b/packages/server/src/routes/templates.ts
@@ -11,7 +11,7 @@ import {
   listTemplates,
   registerTemplate,
   removeTemplate,
-  sandboxKeysUsingTemplate,
+  externalIdsUsingTemplate,
 } from '../db/templates';
 import { httpError } from '../http-error';
 
@@ -67,12 +67,12 @@ export const templateRoutes: FastifyPluginAsyncZod<
       const { name } = request.body;
       // Refused while referenced: a sandbox row pointing at a removed
       // template would wake onto a dangling name. Named keys, so the
-      // operator knows exactly what to release.
-      const users = sandboxKeysUsingTemplate(db, name);
+      // operator knows exactly what to destroy.
+      const users = externalIdsUsingTemplate(db, name);
       if (users.length > 0) {
         throw httpError(
           409,
-          `template '${name}' is used by ${users.length} sandbox(es): ${users.join(', ')} — release them first`,
+          `template '${name}' is used by ${users.length} sandbox(es): ${users.join(', ')} — destroy them first`,
         );
       }
       return { removed: removeTemplate(db, name) };
diff --git a/packages/server/src/sandbox-proxy.ts b/packages/server/src/sandbox-proxy.ts
index 15a478d..39d4404 100644
--- a/packages/server/src/sandbox-proxy.ts
+++ b/packages/server/src/sandbox-proxy.ts
@@ -87,7 +87,7 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
   /**
    * Host -> a dialable target, waking the sandbox under its key slot like
    * every other verb (physical wake-ups must not race the scanner or a
-   * release). Throws ProxyRefusal for everything that deserves a 502.
+   * destroy). Throws ProxyRefusal for everything that deserves a 502.
    */
   async function resolveTarget(req: http.IncomingMessage): Promise<{
     row: SandboxRow;
@@ -97,7 +97,7 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
     const parsed = parseSandboxHost(req.headers.host, domain);
     if (!parsed) throw new ProxyRefusal('not sandbox traffic');
     const before = liveRow(parsed.sandboxId);
-    const row = await locks.run(before.userKey, async () => {
+    const row = await locks.run(before.externalId, async () => {
       const fresh = liveRow(parsed.sandboxId);
       const awake = await wakeSandbox(db, executor, fresh);
       return touch(db, awake.sandboxId);
diff --git a/packages/server/src/scanner.test.ts b/packages/server/src/scanner.test.ts
index dbb412a..ee0c342 100644
--- a/packages/server/src/scanner.test.ts
+++ b/packages/server/src/scanner.test.ts
@@ -12,11 +12,11 @@ import { Archiver } from './archive/archiver';
 import { MemStore } from './archive/mem-store';
 import { objectKey } from './archive/store';
 import { type Db, migrateDb, openDb } from './db/db';
-import { createSandbox, findByUserKey, setDeadline, touch } from './db/ledger';
+import { createSandbox, findByExternalId, setDeadline, touch } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
-import { releaseSandbox } from './lifecycle';
+import { destroySandbox } from './lifecycle';
 import { scanOnce } from './scanner';
 
 const MIGRATIONS = fileURLToPath(new URL('../drizzle', import.meta.url));
@@ -42,12 +42,12 @@ function setupWithArchiver() {
 async function seed(
   db: Db,
   executor: FakeExecutor,
-  userKey: string,
+  externalId: string,
   policy: LifecyclePolicy = DEFAULT_LIFECYCLE_POLICY,
 ): Promise<SandboxRow> {
   const sandboxId = randomUUID();
   await executor.create(sandboxId);
-  return createSandbox(db, { sandboxId, userKey, nodeId: 'node-test', policy });
+  return createSandbox(db, { sandboxId, externalId, nodeId: 'node-test', policy });
 }
 
 /** Time travel: the instant `seconds` after the row's last activity. */
@@ -67,7 +67,7 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(findByExternalId(db, 'alice')?.state).toBe('active');
     expect(executor.stateOf(row.sandboxId)).toBe('running');
   });
 
@@ -87,7 +87,7 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'alice')?.state).toBe('frozen');
+    expect(findByExternalId(db, 'alice')?.state).toBe('frozen');
     expect(executor.stateOf(row.sandboxId)).toBe('paused');
   });
 
@@ -108,7 +108,7 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
+    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
     expect(executor.stateOf(row.sandboxId)).toBe('stopped');
   });
 
@@ -123,7 +123,7 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'alice')?.state).toBe('frozen');
+    expect(findByExternalId(db, 'alice')?.state).toBe('frozen');
     expect(await scanOnce(db, executor, locks, yearLater)).toEqual({
       frozen: 0,
       stopped: 1,
@@ -131,7 +131,7 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
+    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
   });
 
   it('applies each sandbox its own policy', async () => {
@@ -149,8 +149,8 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'quick')?.state).toBe('frozen');
-    expect(findByUserKey(db, 'slow')?.state).toBe('active');
+    expect(findByExternalId(db, 'quick')?.state).toBe('frozen');
+    expect(findByExternalId(db, 'slow')?.state).toBe('active');
     expect(executor.stateOf(slow.sandboxId)).toBe('running');
   });
 
@@ -163,7 +163,7 @@ describe('idle scanner', () => {
       archiveAfterSeconds: null,
     });
     await scanOnce(db, executor, locks, after(row, row.freezeAfterSeconds));
-    expect(findByUserKey(db, 'resident')?.state).toBe('frozen');
+    expect(findByExternalId(db, 'resident')?.state).toBe('frozen');
 
     const yearLater = await scanOnce(
       db,
@@ -178,7 +178,7 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'resident')?.state).toBe('frozen');
+    expect(findByExternalId(db, 'resident')?.state).toBe('frozen');
   });
 
   it('keeps sweeping past a sandbox whose container has vanished', async () => {
@@ -203,11 +203,11 @@ describe('idle scanner', () => {
       },
     ]);
     expect(result.frozen).toBe(1);
-    expect(findByUserKey(db, 'alive')?.state).toBe('frozen');
+    expect(findByExternalId(db, 'alive')?.state).toBe('frozen');
     expect(executor.stateOf(alive.sandboxId)).toBe('paused');
     // The dead row was not written: reality never moved. Repairing it is
     // reconciliation's job, not the scanner's.
-    expect(findByUserKey(db, 'dead')?.state).toBe('active');
+    expect(findByExternalId(db, 'dead')?.state).toBe('active');
   });
 });
 
@@ -241,7 +241,7 @@ describe('idle scanner vs the per-key queue', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(findByExternalId(db, 'alice')?.state).toBe('active');
 
     release();
     await holder;
@@ -286,7 +286,7 @@ describe('idle scanner vs the per-key queue', () => {
       after(first, first.freezeAfterSeconds),
     );
     const released = locks.run('doomed', () =>
-      releaseSandbox(db, executor, doomed.sandboxId, null),
+      destroySandbox(db, executor, doomed.sandboxId, null),
     );
     const [result] = await Promise.all([sweep, released]);
 
@@ -297,7 +297,7 @@ describe('idle scanner vs the per-key queue', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'doomed')).toBeUndefined();
+    expect(findByExternalId(db, 'doomed')).toBeUndefined();
   });
 });
 
@@ -317,7 +317,7 @@ describe('idle scanner: the archive rung', () => {
   ): Promise<void> {
     await scanOnce(db, executor, locks, after(row, 60));
     await scanOnce(db, executor, locks, after(row, 120));
-    expect(findByUserKey(db, row.userKey)?.state).toBe('stopped');
+    expect(findByExternalId(db, row.externalId)?.state).toBe('stopped');
   }
 
   it('archives a stopped sandbox idle past archiveAfterSeconds', async () => {
@@ -342,7 +342,7 @@ describe('idle scanner: the archive rung', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'alice')?.state).toBe('archived');
+    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
     expect(store.has(objectKey(row.sandboxId))).toBe(true);
     // Local copy freed: container and disk both gone.
     expect(executor.stateOf(row.sandboxId)).toBeUndefined();
@@ -357,7 +357,7 @@ describe('idle scanner: the archive rung', () => {
     // No archiver passed: the row keeps its recorded intent, untouched.
     const result = await scanOnce(db, executor, locks, after(row, 9999));
     expect(result.archived).toBe(0);
-    expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
+    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
     expect(await executor.listDisks()).toContain(row.sandboxId);
   });
 
@@ -377,7 +377,7 @@ describe('idle scanner: the archive rung', () => {
       archiver,
     );
     expect(yearLater.archived).toBe(0);
-    expect(findByUserKey(db, 'alice')?.state).toBe('stopped');
+    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
   });
 
   it('an archive failure lands in failures without blocking the sweep', async () => {
@@ -410,7 +410,7 @@ describe('idle scanner: the archive rung', () => {
       },
     ]);
     // Retryable: still stopped, disk still local.
-    expect(findByUserKey(db, 'doomed')?.state).toBe('stopped');
+    expect(findByExternalId(db, 'doomed')?.state).toBe('stopped');
     expect(await executor.listDisks()).toContain(doomed.sandboxId);
   });
 
@@ -433,7 +433,7 @@ describe('idle scanner: the archive rung', () => {
       archiver,
     );
     expect(result.expiredKilled).toBe(1);
-    expect(findByUserKey(db, 'alice')).toBeUndefined();
+    expect(findByExternalId(db, 'alice')).toBeUndefined();
     expect(store.has(objectKey(row.sandboxId))).toBe(false);
   });
 
@@ -453,10 +453,10 @@ describe('idle scanner: the archive rung', () => {
       await gate;
       return innerGet(key, dest, onProgress);
     };
-    const archived = findByUserKey(db, 'alice');
+    const archived = findByExternalId(db, 'alice');
     if (!archived) throw new Error('row vanished');
     archiver.beginRestore(archived);
-    expect(findByUserKey(db, 'alice')?.state).toBe('restoring');
+    expect(findByExternalId(db, 'alice')?.state).toBe('restoring');
     setDeadline(db, row.sandboxId, {
       deadlineAt: after(row, 200).toISOString(),
       onDeadline: 'kill',
@@ -471,11 +471,11 @@ describe('idle scanner: the archive rung', () => {
       archiver,
     );
     expect(during.expiredKilled).toBe(0);
-    expect(findByUserKey(db, 'alice')?.state).toBe('restoring');
+    expect(findByExternalId(db, 'alice')?.state).toBe('restoring');
 
     releaseDownload();
     await archiver.restoreJoin(row.sandboxId);
-    expect(findByUserKey(db, 'alice')?.state).toBe('active');
+    expect(findByExternalId(db, 'alice')?.state).toBe('active');
 
     // Next sweep, with the restore settled, the kill lands clean.
     const settled = await scanOnce(
@@ -486,7 +486,7 @@ describe('idle scanner: the archive rung', () => {
       archiver,
     );
     expect(settled.expiredKilled).toBe(1);
-    expect(findByUserKey(db, 'alice')).toBeUndefined();
+    expect(findByExternalId(db, 'alice')).toBeUndefined();
   });
 });
 
@@ -494,12 +494,12 @@ describe('E2B deadline rule', () => {
   async function seedWithDeadline(
     db: Db,
     executor: FakeExecutor,
-    userKey: string,
+    externalId: string,
     row: SandboxRow | null,
     afterSeconds: number,
     onDeadline: 'kill' | 'pause',
   ): Promise<SandboxRow> {
-    const seeded = row ?? (await seed(db, executor, userKey));
+    const seeded = row ?? (await seed(db, executor, externalId));
     setDeadline(db, seeded.sandboxId, {
       deadlineAt: after(seeded, afterSeconds).toISOString(),
       onDeadline,
@@ -536,7 +536,7 @@ describe('E2B deadline rule', () => {
       expiredKilled: 1,
       failures: [],
     });
-    expect(findByUserKey(db, 'doomed')).toBeUndefined();
+    expect(findByExternalId(db, 'doomed')).toBeUndefined();
     expect(executor.stateOf(row.sandboxId)).toBeUndefined();
     expect(await executor.listDisks()).not.toContain(row.sandboxId);
   });
@@ -558,7 +558,7 @@ describe('E2B deadline rule', () => {
       expiredKilled: 1,
       failures: [],
     });
-    expect(findByUserKey(db, 'both')).toBeUndefined();
+    expect(findByExternalId(db, 'both')).toBeUndefined();
   });
 
   it('activity does not extend a deadline — it is an absolute clock', async () => {
@@ -569,7 +569,7 @@ describe('E2B deadline rule', () => {
     touch(db, row.sandboxId, after(row, 99).toISOString());
     const result = await scanOnce(db, executor, locks, after(row, 101));
     expect(result.expiredKilled).toBe(1);
-    expect(findByUserKey(db, 'busy')).toBeUndefined();
+    expect(findByExternalId(db, 'busy')).toBeUndefined();
   });
 
   it('parks an expired pause-deadline sandbox frozen, once, and keeps the row', async () => {
@@ -591,7 +591,7 @@ describe('E2B deadline rule', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'parked')?.state).toBe('frozen');
+    expect(findByExternalId(db, 'parked')?.state).toBe('frozen');
     expect(executor.stateOf(row.sandboxId)).toBe('paused');
 
     // A second sweep finds no physical work left: frozen already satisfies
@@ -604,6 +604,6 @@ describe('E2B deadline rule', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByUserKey(db, 'parked')?.state).toBe('frozen');
+    expect(findByExternalId(db, 'parked')?.state).toBe('frozen');
   });
 });
diff --git a/packages/server/src/scanner.ts b/packages/server/src/scanner.ts
index b68fac6..e424f91 100644
--- a/packages/server/src/scanner.ts
+++ b/packages/server/src/scanner.ts
@@ -4,7 +4,7 @@ import { findBySandboxId, listSandboxes } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
-import { freezeSandbox, releaseSandbox, stopSandbox } from './lifecycle';
+import { freezeSandbox, destroySandbox, stopSandbox } from './lifecycle';
 
 export interface ScanResult {
   frozen: number;
@@ -21,7 +21,7 @@ export interface ScanResult {
  * The E2B deadline rule. Unlike the idle rules it is an absolute clock —
  * E2B kills a sandbox at its deadline even mid-command; activity does not
  * extend it, only create/connect/setTimeout do. `kill` applies from any
- * state (release handles them all); `pause` only has physical work while
+ * state (destroy handles them all); `pause` only has physical work while
  * the sandbox is still active — colder states already satisfy it, and the
  * logical view reads the expired deadline directly.
  */
@@ -86,7 +86,7 @@ function dueTransition(
  * slip into that gap, answer "ready", and leave the caller holding a paused
  * sandbox. A key that is already busy is skipped — whatever is running
  * there has fresher knowledge than this sweep's snapshot — and the re-read
- * catches rows that were released or woken between the snapshot and the
+ * catches rows that were destroyed or woken between the snapshot and the
  * slot.
  *
  * Two phases, fast then slow: an archive is minutes of tar and upload, and
@@ -128,7 +128,7 @@ export async function scanOnce(
       continue;
     }
     try {
-      await locks.tryRun(row.userKey, async () => {
+      await locks.tryRun(row.externalId, async () => {
         const fresh = findBySandboxId(db, row.sandboxId);
         if (!fresh) {
           return; // Released since the sweep's snapshot.
@@ -137,7 +137,7 @@ export async function scanOnce(
         // parks) by its deadline, not one rung colder.
         const deadline = dueDeadline(fresh, now);
         if (deadline === 'kill') {
-          await releaseSandbox(
+          await destroySandbox(
             db,
             executor,
             fresh.sandboxId,
@@ -187,10 +187,10 @@ export async function scanOnce(
   if (archiver === undefined) return result;
   for (const row of archiveDue) {
     try {
-      await locks.tryRun(row.userKey, async () => {
+      await locks.tryRun(row.externalId, async () => {
         const fresh = findBySandboxId(db, row.sandboxId);
         // Re-verified in the slot: phase one may have killed it by
-        // deadline, an acquire may have woken it, a release removed it —
+        // deadline, an acquire may have woken it, a destroy removed it —
         // the snapshot's opinion is void either way.
         if (
           !fresh ||
diff --git a/packages/shared/src/acquire.ts b/packages/shared/src/acquire.ts
index 6ee5c94..be07eb7 100644
--- a/packages/shared/src/acquire.ts
+++ b/packages/shared/src/acquire.ts
@@ -1,14 +1,14 @@
 import { z } from 'zod';
 import { lifecyclePolicyOverrideSchema } from './policy';
-import { sandboxSchema, userKeySchema } from './sandbox';
+import { sandboxSchema, externalIdSchema } from './sandbox';
 import { templateNameSchema } from './templates';
 
 /**
- * acquire(userKey) — the platform's single entry point. Idempotent:
+ * acquire(externalId) — the platform's single entry point. Idempotent:
  * no sandbox → create; frozen → wake; stopped → rebuild; archived → restore.
  */
 export const acquireRequestSchema = z.object({
-  userKey: userKeySchema,
+  externalId: externalIdSchema,
   /**
    * Lifecycle override applied when this acquire creates the sandbox;
    * omitted fields fall back to the daemon's global defaults. When the key
diff --git a/packages/shared/src/activity.ts b/packages/shared/src/activity.ts
index 1b7ddd6..c017686 100644
--- a/packages/shared/src/activity.ts
+++ b/packages/shared/src/activity.ts
@@ -15,7 +15,7 @@ export const ACTIVITY_KINDS = [
   'frozen',
   'stopped',
   'rebuilt',
-  'released',
+  'destroyed',
   /** An E2B deadline with the kill action passed: destroyed, disk and all. */
   'expired-killed',
   'archived',
@@ -24,7 +24,7 @@ export const ACTIVITY_KINDS = [
   'restore-failed',
   /** The reconciler corrected the ledger (or reality) to match the other. */
   'reconciled',
-  /** setPolicy rewrote a sandbox's lifecycle thresholds (ledger-only). */
+  /** updatePolicy rewrote a sandbox's lifecycle thresholds (ledger-only). */
   'policy-changed',
   'daemon-started',
   /** An operator bound or cleared the console domain through setIngress. */
@@ -41,7 +41,7 @@ export const activityEventSchema = z.object({
   at: z.string(),
   kind: activityKindSchema,
   /** Null for events with no owning sandbox (orphan sweeps, daemon start). */
-  userKey: z.string().nullable(),
+  externalId: z.string().nullable(),
   sandboxId: z.string().nullable(),
   /** One short line of context: which actor, which threshold, what was repaired. */
   detail: z.string(),
diff --git a/packages/shared/src/destroy.ts b/packages/shared/src/destroy.ts
new file mode 100644
index 0000000..b1ba8f2
--- /dev/null
+++ b/packages/shared/src/destroy.ts
@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { externalIdSchema } from './sandbox';
+
+/**
+ * destroySandbox(externalId) — the end of a sandbox's life: container and disk
+ * are destroyed for good. Idempotent like acquire, and on the same key: the
+ * desired end state is "no sandbox under this key", so destroying a key that
+ * has nothing is not an error.
+ */
+export const destroySandboxRequestSchema = z.object({
+  externalId: externalIdSchema,
+});
+
+export type DestroySandboxRequest = z.infer<typeof destroySandboxRequestSchema>;
+
+export const destroySandboxResponseSchema = z.object({
+  /** True when a sandbox existed and was destroyed; false when the key already had nothing. */
+  destroyed: z.boolean(),
+});
+
+export type DestroySandboxResponse = z.infer<
+  typeof destroySandboxResponseSchema
+>;
diff --git a/packages/shared/src/exec.ts b/packages/shared/src/exec.ts
index 93f3c2b..bcab7b4 100644
--- a/packages/shared/src/exec.ts
+++ b/packages/shared/src/exec.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { userKeySchema } from './sandbox';
+import { externalIdSchema } from './sandbox';
 
 /** In-container deadline applied when the caller does not set one. */
 export const DEFAULT_EXEC_TIMEOUT_SECONDS = 300;
@@ -16,13 +16,13 @@ export const MAX_EXEC_TIMEOUT_SECONDS = 86_400;
 export const EXEC_OUTPUT_LIMIT_BYTES = 1024 * 1024;
 
 /**
- * execCommand(userKey, command) — runs a shell command inside the sandbox
+ * execCommand(externalId, command) — runs a shell command inside the sandbox
  * behind the key and waits for it to finish. A cold (frozen/stopped) sandbox
  * is woken first; a running command counts as activity, so the idle scanner
  * never freezes a sandbox mid-command.
  */
 export const execCommandRequestSchema = z.object({
-  userKey: userKeySchema,
+  externalId: externalIdSchema,
   /** A shell string, executed as `bash -c <command>` inside the sandbox. */
   command: z.string().min(1),
   /**
diff --git a/packages/shared/src/files.ts b/packages/shared/src/files.ts
index d70d038..a21d3f2 100644
--- a/packages/shared/src/files.ts
+++ b/packages/shared/src/files.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { userKeySchema } from './sandbox';
+import { externalIdSchema } from './sandbox';
 
 /**
  * Per-file size cap, write and read alike. Content crosses the wire as
@@ -18,6 +18,14 @@ export const FILE_SIZE_LIMIT_BYTES = 16 * 1024 * 1024;
  */
 export const WRITE_FILES_BODY_LIMIT_BYTES = 48 * 1024 * 1024;
 
+/**
+ * Total decoded-bytes cap for a readFiles batch, the read-side twin of
+ * WRITE_FILES_BODY_LIMIT_BYTES: the whole response is buffered in daemon
+ * memory, so the sum of file sizes is gated, not just each file. A bigger
+ * haul splits into several calls.
+ */
+export const READ_FILES_TOTAL_LIMIT_BYTES = 48 * 1024 * 1024;
+
 /**
  * Exact decoded size of a canonical (padded) base64 string — zod's z.base64()
  * guarantees the canonical form, so length arithmetic is precise and the
@@ -67,14 +75,14 @@ const fileContentSchema = z
   });
 
 /**
- * writeFiles(userKey, files) — writes every file in the batch into the
+ * writeFiles(externalId, files) — writes every file in the batch into the
  * sandbox behind the key, waking it first if it is cold. Parent directories
  * are created as needed; an existing file is overwritten. Writes happen in
  * array order and fail fast: on error the earlier files are already written
  * — the batch is a round-trip saver, not a transaction.
  */
 export const writeFilesRequestSchema = z.object({
-  userKey: userKeySchema,
+  externalId: externalIdSchema,
   files: z
     .array(
       z.object({
@@ -96,14 +104,36 @@ export const writeFilesResponseSchema = z.object({
 export type WriteFilesResponse = z.infer<typeof writeFilesResponseSchema>;
 
 /**
- * readFile(userKey, path) — returns one file's bytes. A file over the size
+ * writeFile(externalId, path, content) — the single-file form of writeFiles:
+ * same rules (parents created, existing file overwritten, same size cap),
+ * one file, no array to wrap and unwrap. Kept as its own verb so the wire,
+ * the SDK and the docs stay one name per intent.
+ */
+export const writeFileRequestSchema = z.object({
+  externalId: externalIdSchema,
+  path: sandboxPathSchema,
+  /** The file's bytes, base64. Text is just UTF-8 bytes — the SDK encodes strings transparently. */
+  contentBase64: fileContentSchema,
+});
+
+export type WriteFileRequest = z.infer<typeof writeFileRequestSchema>;
+
+export const writeFileResponseSchema = z.object({
+  /** The path as resolved inside the sandbox, always absolute. */
+  path: z.string(),
+});
+
+export type WriteFileResponse = z.infer<typeof writeFileResponseSchema>;
+
+/**
+ * readFile(externalId, path) — returns one file's bytes. A file over the size
  * limit is refused outright (413 naming the actual size), never truncated:
  * unlike exec output, where a capped log still informs, a truncated file is
  * simply a corrupt file — an honest error beats delivering damaged goods.
  * Missing file: 404. Directory or other non-regular file: 400.
  */
 export const readFileRequestSchema = z.object({
-  userKey: userKeySchema,
+  externalId: externalIdSchema,
   path: sandboxPathSchema,
 });
 
@@ -116,3 +146,31 @@ export const readFileResponseSchema = z.object({
 });
 
 export type ReadFileResponse = z.infer<typeof readFileResponseSchema>;
+
+/**
+ * readFiles(externalId, paths) — the batch form of readFile, all or nothing:
+ * one missing path fails the whole call (404 naming it), same for a
+ * non-regular file (400) or a per-file size overrun (413). A partial result
+ * is not offered on purpose — a batch read that silently drops a file is a
+ * corrupt project checkout, and the caller who can tolerate absence can ask
+ * file by file. Files come back in request order; the batch total is gated
+ * by READ_FILES_TOTAL_LIMIT_BYTES (413 when the haul exceeds it).
+ */
+export const readFilesRequestSchema = z.object({
+  externalId: externalIdSchema,
+  paths: z.array(sandboxPathSchema).min(1),
+});
+
+export type ReadFilesRequest = z.infer<typeof readFilesRequestSchema>;
+
+export const readFilesResponseSchema = z.object({
+  /** In request order, every path resolved to its absolute form. */
+  files: z.array(
+    z.object({
+      path: z.string(),
+      contentBase64: z.base64(),
+    }),
+  ),
+});
+
+export type ReadFilesResponse = z.infer<typeof readFilesResponseSchema>;
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index fd1d656..66b0e64 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -1,6 +1,7 @@
 export * from './acquire';
 export * from './activity';
 export * from './config';
+export * from './destroy';
 export * from './exec';
 export * from './files';
 export * from './host';
@@ -9,8 +10,7 @@ export * from './list';
 export * from './metrics';
 export * from './policy';
 export * from './rebuild';
-export * from './release';
 export * from './sandbox';
-export * from './set-policy';
 export * from './states';
 export * from './templates';
+export * from './update-policy';
diff --git a/packages/shared/src/metrics.ts b/packages/shared/src/metrics.ts
index a0266dd..eb8b8e5 100644
--- a/packages/shared/src/metrics.ts
+++ b/packages/shared/src/metrics.ts
@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { userKeySchema } from './sandbox';
+import { externalIdSchema } from './sandbox';
 
 /**
- * getSandboxMetrics(userKey) — one sandbox's point-in-time resource
+ * getSandboxMetrics(externalId) — one sandbox's point-in-time resource
  * reading: the per-sandbox sibling of getHostMetrics, and the native twin
  * of the E2B surface's metrics endpoint (same executor reading, same
  * single-sample answer — the daemon keeps no metrics history). Observation
@@ -27,7 +27,7 @@ export const sandboxMetricsSampleSchema = z.object({
 export type SandboxMetricsSample = z.infer<typeof sandboxMetricsSampleSchema>;
 
 export const getSandboxMetricsRequestSchema = z.object({
-  userKey: userKeySchema,
+  externalId: externalIdSchema,
 });
 
 export type GetSandboxMetricsRequest = z.infer<
@@ -59,7 +59,7 @@ export type ListSandboxMetricsRequest = z.infer<
 export const listSandboxMetricsResponseSchema = z.object({
   samples: z.array(
     z.object({
-      userKey: z.string(),
+      externalId: z.string(),
       sandboxId: z.string(),
       sample: sandboxMetricsSampleSchema,
     }),
diff --git a/packages/shared/src/rebuild.ts b/packages/shared/src/rebuild.ts
index f75cb03..981a976 100644
--- a/packages/shared/src/rebuild.ts
+++ b/packages/shared/src/rebuild.ts
@@ -1,18 +1,18 @@
 import { z } from 'zod';
-import { sandboxSchema, userKeySchema } from './sandbox';
+import { sandboxSchema, externalIdSchema } from './sandbox';
 
 /**
- * rebuildSandbox(userKey) — swap the container, keep the disk. The disk is
+ * rebuildSandbox(externalId) — swap the container, keep the disk. The disk is
  * the sandbox's body; the container is a replaceable shell built from the
  * daemon's current base image. Removing the shell and letting the next wake
  * rebuild it is how an existing sandbox picks up a new base image without
  * losing a byte of /home/user.
  *
- * Not idempotent-forgiving like release: rebuilding a key that has no
+ * Not idempotent-forgiving like destroy: rebuilding a key that has no
  * sandbox is a caller's confusion (a typo, not a goal state) and answers 404.
  */
 export const rebuildSandboxRequestSchema = z.object({
-  userKey: userKeySchema,
+  externalId: externalIdSchema,
 });
 
 export type RebuildSandboxRequest = z.infer<typeof rebuildSandboxRequestSchema>;
diff --git a/packages/shared/src/release.ts b/packages/shared/src/release.ts
deleted file mode 100644
index dc9c3c6..0000000
--- a/packages/shared/src/release.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-import { z } from 'zod';
-import { userKeySchema } from './sandbox';
-
-/**
- * releaseSandbox(userKey) — the end of a sandbox's life: container and disk
- * are destroyed for good. Idempotent like acquire, and on the same key: the
- * desired end state is "no sandbox under this key", so releasing a key that
- * has nothing is not an error.
- */
-export const releaseSandboxRequestSchema = z.object({
-  userKey: userKeySchema,
-});
-
-export type ReleaseSandboxRequest = z.infer<typeof releaseSandboxRequestSchema>;
-
-export const releaseSandboxResponseSchema = z.object({
-  /** True when a sandbox existed and was destroyed; false when the key already had nothing. */
-  released: z.boolean(),
-});
-
-export type ReleaseSandboxResponse = z.infer<
-  typeof releaseSandboxResponseSchema
->;
diff --git a/packages/shared/src/sandbox.ts b/packages/shared/src/sandbox.ts
index d17858f..f35e8c6 100644
--- a/packages/shared/src/sandbox.ts
+++ b/packages/shared/src/sandbox.ts
@@ -4,11 +4,13 @@ import { SANDBOX_STATES } from './states';
 import { templateNameSchema } from './templates';
 
 /**
- * Caller-chosen key that acquire() is idempotent on: same key, same sandbox,
- * whatever state it was in. Opaque to the daemon; bounded so it can serve as
- * an indexed column.
+ * The caller's identifier from their own system — a user id, a session id,
+ * a CI job name — that acquire() is idempotent on: same external id, same
+ * sandbox, whatever state it was in. sandboxId is the daemon's internal
+ * identity; this is the external one, and it is the API's handle. Opaque to
+ * the daemon; bounded so it can serve as an indexed column.
  */
-export const userKeySchema = z.string().min(1).max(128);
+export const externalIdSchema = z.string().min(1).max(128);
 
 /**
  * A sandbox as reported by the daemon — the wire shape shared by the HTTP
@@ -17,7 +19,7 @@ export const userKeySchema = z.string().min(1).max(128);
 export const sandboxSchema = z.object({
   /** Generated by the daemon. UUID, never a DB autoincrement — ids must stay unique across machines. */
   sandboxId: z.string(),
-  userKey: userKeySchema,
+  externalId: externalIdSchema,
   state: z.enum(SANDBOX_STATES),
   /** Machine that owns this sandbox. Single-machine today; the field keeps the ledger shardable. */
   nodeId: z.string(),
diff --git a/packages/shared/src/templates.ts b/packages/shared/src/templates.ts
index 9715f99..0dbc3c5 100644
--- a/packages/shared/src/templates.ts
+++ b/packages/shared/src/templates.ts
@@ -67,7 +67,7 @@ export type ListTemplatesResponse = z.infer<typeof listTemplatesResponseSchema>;
 /**
  * removeTemplate(name) — refused with a 409 while any sandbox still uses the
  * template (the sandboxes would wake onto a dangling name); idempotent on an
- * unknown name, like releaseSandbox: "no template under this name" is the
+ * unknown name, like destroySandbox: "no template under this name" is the
  * desired end state.
  */
 export const removeTemplateRequestSchema = z.object({
diff --git a/packages/shared/src/set-policy.ts b/packages/shared/src/update-policy.ts
similarity index 58%
rename from packages/shared/src/set-policy.ts
rename to packages/shared/src/update-policy.ts
index c115ecc..e27269e 100644
--- a/packages/shared/src/set-policy.ts
+++ b/packages/shared/src/update-policy.ts
@@ -1,12 +1,12 @@
 import { z } from 'zod';
 import { lifecyclePolicyOverrideSchema } from './policy';
-import { sandboxSchema, userKeySchema } from './sandbox';
+import { sandboxSchema, externalIdSchema } from './sandbox';
 
 /**
- * setPolicy(userKey, policy) — the update verb acquire deliberately is not.
+ * updatePolicy(externalId, policy) — the update verb acquire deliberately is not.
  * Without it, changing a live sandbox's lifecycle (say, promoting it to a
- * never-stop resident agent) would require release + re-acquire, and release
- * destroys the disk — the one thing this platform promises to keep.
+ * never-stop resident agent) would require destroy + re-acquire, and destroy
+ * removes the disk — the one thing this platform promises to keep.
  *
  * Patch semantics over the STORED policy: omitted fields keep their current
  * values, `null` still means "never take that step". The merged result is
@@ -17,16 +17,16 @@ import { sandboxSchema, userKeySchema } from './sandbox';
  * is NOT refreshed — adjusting a knob is not sandbox activity, and the new
  * thresholds apply to the idle time already accumulated.
  */
-export const setPolicyRequestSchema = z.object({
-  userKey: userKeySchema,
+export const updatePolicyRequestSchema = z.object({
+  externalId: externalIdSchema,
   policy: lifecyclePolicyOverrideSchema,
 });
 
-export type SetPolicyRequest = z.infer<typeof setPolicyRequestSchema>;
+export type UpdatePolicyRequest = z.infer<typeof updatePolicyRequestSchema>;
 
 /** The sandbox as it stands after the update (state untouched). */
-export const setPolicyResponseSchema = z.object({
+export const updatePolicyResponseSchema = z.object({
   sandbox: sandboxSchema,
 });
 
-export type SetPolicyResponse = z.infer<typeof setPolicyResponseSchema>;
+export type UpdatePolicyResponse = z.infer<typeof updatePolicyResponseSchema>;
diff --git a/website/content/docs/cli.mdx b/website/content/docs/cli.mdx
index e83794e..f0e9149 100644
--- a/website/content/docs/cli.mdx
+++ b/website/content/docs/cli.mdx
@@ -39,7 +39,7 @@ characters: user keys are not restricted on the wire, and an ANSI escape
 inside one must not reach your terminal.)
 
 ```sh
-dor sandbox exec <userKey> '<command>' [-t <seconds>]
+dor sandbox exec <externalId> '<command>' [-t <seconds>]
 ```
 
 Runs a shell command in the sandbox behind the key, waking it first. The
@@ -51,8 +51,8 @@ it after that long ([enforced inside the container](/docs/commands)). An
 unknown key is a 404, never a sandbox created by accident.
 
 ```sh
-dor sandbox push <userKey> <localPath> [remotePath]
-dor sandbox pull <userKey> <remotePath> [localPath]
+dor sandbox push <externalId> <localPath> [remotePath]
+dor sandbox pull <externalId> <remotePath> [localPath]
 ```
 
 One file in, one file out. Relative remote paths land under `/home/user`;
@@ -61,7 +61,7 @@ local path writes the raw bytes to stdout — pipe it wherever. Both obey
 the [16 MiB single-file contract](/docs/files).
 
 ```sh
-dor sandbox rebuild <userKey>
+dor sandbox rebuild <externalId>
 ```
 
 Swaps the container, keeps `/home/user` — the sandbox's next use starts
@@ -70,7 +70,7 @@ on its template's *current* image (or the base image). This is how a
 [rebuild: new shell, same body](/docs/persistence#rebuild-new-shell-same-body).
 
 ```sh
-dor sandbox release <userKey>
+dor sandbox destroy <externalId>
 ```
 
 Destroys the sandbox — container, disk, and (if archived) the S3 object.
diff --git a/website/content/docs/commands.mdx b/website/content/docs/commands.mdx
index c68c383..6feb8bb 100644
--- a/website/content/docs/commands.mdx
+++ b/website/content/docs/commands.mdx
@@ -3,7 +3,7 @@ title: Running commands
 description: execCommand is a buffered shell round-trip — honest exit codes, timeouts enforced inside the container, output capped at 1 MiB per stream.
 ---
 
-The native surface has one command verb: `execCommand(userKey, command)`.
+The native surface has one command verb: `execCommand(externalId, command)`.
 It wakes the sandbox if it is cold, runs the command as `bash -c` inside
 the container (as the sandbox's non-root user, uid 1000), waits, and
 returns the whole result at once:
diff --git a/website/content/docs/e2b-differences.mdx b/website/content/docs/e2b-differences.mdx
index 3b499a4..1391805 100644
--- a/website/content/docs/e2b-differences.mdx
+++ b/website/content/docs/e2b-differences.mdx
@@ -33,7 +33,7 @@ daemon:
 - **Permanence stays the default.** Sandboxes created through the E2B
   surface get real deadlines, as E2B semantics demand; deadlines are
   never imposed on natively created sandboxes.
-- **`metadata.userKey`** turns `Sandbox.create` into Dormice's idempotent
+- **`metadata.externalId`** turns `Sandbox.create` into Dormice's idempotent
   acquire — see [Using the official E2B SDKs](/docs/e2b-sdks).
 - **One domain, not one subdomain per sandbox.** The SDK addresses
   sandboxes through a header on a single endpoint, so no wildcard DNS is
diff --git a/website/content/docs/e2b-sdks.mdx b/website/content/docs/e2b-sdks.mdx
index 6e86238..4128815 100644
--- a/website/content/docs/e2b-sdks.mdx
+++ b/website/content/docs/e2b-sdks.mdx
@@ -47,16 +47,16 @@ Python SDK validates its key against `e2b_[0-9a-f]+` client-side, before
 any request leaves the machine — a token with other characters fails in
 the SDK, not on the wire.
 
-## `metadata.userKey`: idempotent create
+## `metadata.externalId`: idempotent create
 
-A Dormice extension: pass `metadata: { userKey: '...' }` and
+A Dormice extension: pass `metadata: { externalId: '...' }` and
 `Sandbox.create` behaves like the native `acquireSandbox` — the same key
 always returns the same sandbox instead of a new one, whatever state it
 was in, with its files intact:
 
 ```ts
 const sbx = await Sandbox.create({
-  metadata: { userKey: 'my-project' },
+  metadata: { externalId: 'my-project' },
   // ...the two URLs and apiKey as above
 });
 ```
diff --git a/website/content/docs/files.mdx b/website/content/docs/files.mdx
index 4ac0bfd..e6e2c9c 100644
--- a/website/content/docs/files.mdx
+++ b/website/content/docs/files.mdx
@@ -1,19 +1,24 @@
 ---
 title: Moving files
-description: writeFiles and readFile move files through JSON — 16 MiB per file, honest refusals past that, and streaming alternatives when you need more.
+description: writeFile(s) and readFile(s) move files through JSON — 16 MiB per file, honest refusals past that, and streaming alternatives when you need more.
 ---
 
-Native file transfer is two verbs. Both wake a cold sandbox first; paths
-are absolute, or relative to `/home/user`:
+Native file transfer is four verbs — write and read, each in a single and
+a batch form. All wake a cold sandbox first; paths are absolute, or
+relative to `/home/user`:
 
 ```ts
 await client.writeFiles('my-agent', [
   { path: 'config.json', content: JSON.stringify(config) }, // string → UTF-8
   { path: 'data/input.bin', content: bytes },               // Uint8Array, as-is
 ]);
+await client.writeFile('my-agent', 'notes.md', '# one file, no array');
 
 const file = await client.readFile('my-agent', 'results/out.csv');
 const text = new TextDecoder().decode(file.content);
+
+// Batch read: request order, all or nothing.
+const files = await client.readFiles('my-agent', ['a.txt', 'b.txt']);
 ```
 
 Parent directories are created as needed; existing files are overwritten.
@@ -32,6 +37,12 @@ dor sandbox pull my-agent results/out.csv       # no local path: raw bytes to st
 earlier in the array are already written. Splitting a big upload into
 several calls loses nothing — writes are per-file independent.
 
+`readFiles` is the opposite on purpose: **all or nothing**. One missing
+path fails the whole call with a 404 naming it — a batch read that
+silently dropped a file would be a corrupt project checkout. A caller that
+can tolerate absence asks file by file; the batch total is capped at
+48 MiB (413 past it).
+
 ## The 16 MiB cap, and what to do past it
 
 Content crosses the wire as base64 inside JSON and is buffered in daemon
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
index c174391..c486854 100644
--- a/website/content/docs/http-api.mdx
+++ b/website/content/docs/http-api.mdx
@@ -12,7 +12,7 @@ can do that `curl` cannot.
 curl -X POST http://127.0.0.1:3676/acquireSandbox \
   -H "Authorization: Bearer $DORMICE_API_TOKEN" \
   -H "content-type: application/json" \
-  -d '{"userKey": "my-agent"}'
+  -d '{"externalId": "my-agent"}'
 ```
 
 Two rules cover the whole surface:
@@ -34,9 +34,11 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | `POST /listSandboxes` | every sandbox and its state; never wakes anything | — |
 | `POST /execCommand` | run a command, buffered | 404 unknown key, 409 archived/restoring |
 | `POST /writeFiles` | batch write, base64 in JSON | 404/409 as above; body over 48 MiB refused |
+| `POST /writeFile` | write one file — the single form of `writeFiles` | same refusals as `writeFiles` |
 | `POST /readFile` | read one file, base64 out | 404 no such file, 400 not a file, 413 over 16 MiB (names the real size) |
+| `POST /readFiles` | batch read, all or nothing, request order | first bad path fails the whole batch; 413 over 48 MiB total |
 | `POST /rebuildSandbox` | swap container, keep `/home/user` | 404 unknown key, 409 archived/restoring |
-| `POST /releaseSandbox` | destroy; idempotent | 409 mid-restore (the one dent — retry when it finishes) |
+| `POST /destroySandbox` | destroy; idempotent | 409 mid-restore (the one dent — retry when it finishes) |
 | `POST /registerTemplate` | upsert name → image | 400 `'base'` is reserved |
 | `POST /listTemplates` | every registered template | — |
 | `POST /removeTemplate` | unregister; idempotent | 409 while sandboxes still use it (names them) |
@@ -52,7 +54,7 @@ Everything that returns a sandbox returns this shape:
 
 ```json
 {
-  "sandboxId": "8b1e…-uuid", "userKey": "my-agent",
+  "sandboxId": "8b1e…-uuid", "externalId": "my-agent",
   "state": "active", "nodeId": "…", "endpoint": "http://127.0.0.1:3676",
   "policy": { "freezeAfterSeconds": 600, "stopAfterSeconds": 259200, "archiveAfterSeconds": null },
   "template": null, "createdAt": "…", "lastActiveAt": "…"
@@ -69,17 +71,19 @@ poll acquire until it flips to `ready`
 
 ## Commands and files on the wire
 
-`execCommand` takes `{ userKey, command, timeoutSeconds?, cwd?, env? }`
+`execCommand` takes `{ externalId, command, timeoutSeconds?, cwd?, env? }`
 and returns
 `{ exitCode, stdout, stderr, stdoutTruncated, stderrTruncated }` — a
 non-zero exit code is a result, not an HTTP error
 ([details](/docs/commands)).
 
 File content crosses the wire as base64 inside JSON: `writeFiles` takes
-`{ userKey, files: [{ path, contentBase64 }] }`, `readFile` takes
-`{ userKey, path }` and returns `{ path, contentBase64 }` with the path
-resolved absolute. Limits and refusal semantics:
-[moving files](/docs/files).
+`{ externalId, files: [{ path, contentBase64 }] }`, `readFile` takes
+`{ externalId, path }` and returns `{ path, contentBase64 }` with the path
+resolved absolute. Each has a twin for the other arity: `writeFile` writes
+one file without the array ceremony, `readFiles` reads a batch all or
+nothing — one missing path fails the whole call. Limits and refusal
+semantics: [moving files](/docs/files).
 
 ## Bring a patient HTTP client
 
diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdx
index f8566d9..a58a2fb 100644
--- a/website/content/docs/index.mdx
+++ b/website/content/docs/index.mdx
@@ -8,7 +8,7 @@ sandboxes are disposable. Dormice inverts that: you run it on a machine you
 already pay for, and sandboxes are **permanent** — they just get cheaper to
 keep the longer they sit idle.
 
-- **`acquireSandbox(userKey)` is the entire mental model.** Idempotent: the
+- **`acquireSandbox(externalId)` is the entire mental model.** Idempotent: the
   same key always comes back to the same sandbox, whatever state it was in.
   No sandbox → create; frozen → wake; stopped → start; archived → restore.
 - **Idle is free.** Sandboxes cool down on their own —
diff --git a/website/content/docs/persistence.mdx b/website/content/docs/persistence.mdx
index a718fd5..e22f60e 100644
--- a/website/content/docs/persistence.mdx
+++ b/website/content/docs/persistence.mdx
@@ -35,7 +35,7 @@ gVisor host:
 
 ## What does not
 
-- **`releaseSandbox`** — the only verb that loses data, by design.
+- **`destroySandbox`** — the only verb that loses data, by design.
 - **Everything outside `/home/user`** whenever the container is replaced
   (rebuild, prune, OOM): `/tmp`, packages installed at runtime outside the
   home directory, running processes. If it matters, keep it in
diff --git a/website/content/docs/quickstart.mdx b/website/content/docs/quickstart.mdx
index 078c47d..a7a3edd 100644
--- a/website/content/docs/quickstart.mdx
+++ b/website/content/docs/quickstart.mdx
@@ -26,7 +26,7 @@ await client.writeFiles('my-agent', [
   { path: 'notes.txt', content: 'survives freeze and stop' },
 ]);
 
-await client.releaseSandbox('my-agent'); // destroy — the only verb that loses data
+await client.destroySandbox('my-agent'); // destroy — the only verb that loses data
 ```
 
 ## The wire is plain HTTP
@@ -54,6 +54,6 @@ dor sandbox exec my-agent 'uname -r'  # run a command, exit code passes through
 dor sandbox push my-agent ./data.csv  # copy a file in…
 dor sandbox pull my-agent notes.txt   # …and out
 dor sandbox rebuild my-agent          # fresh container, /home/user kept
-dor sandbox release my-agent          # destroy
+dor sandbox destroy my-agent          # destroy
 dor doctor                            # can this machine run sandboxes?
 ```
diff --git a/website/content/docs/upgrading.mdx b/website/content/docs/upgrading.mdx
index 4b6ac78..6b36c44 100644
--- a/website/content/docs/upgrading.mdx
+++ b/website/content/docs/upgrading.mdx
@@ -49,7 +49,7 @@ whoever is using the sandbox and should happen on your schedule:
 docker build -t dormice-base:NEW -f images/Dockerfile images/
 # point DORMICE_BASE_IMAGE at the new tag in /etc/dormice/env, then:
 systemctl restart dormice
-dor sandbox rebuild <userKey>   # per sandbox, when it suits you
+dor sandbox rebuild <externalId>   # per sandbox, when it suits you
 ```
 
 [Rebuild](/docs/persistence#rebuild-new-shell-same-body) swaps the
diff --git a/website/src/components/sections/Features.tsx b/website/src/components/sections/Features.tsx
index e854e42..a969e89 100644
--- a/website/src/components/sections/Features.tsx
+++ b/website/src/components/sections/Features.tsx
@@ -11,7 +11,7 @@ const features: { title: string; body: ReactNode }[] = [
     title: 'Sandboxes are permanent',
     body: (
       <>
-        <code>acquireSandbox(userKey)</code> is the entire mental model — the
+        <code>acquireSandbox(externalId)</code> is the entire mental model — the
         same key always comes back to the same sandbox: created, woken or
         restarted as needed.
       </>

From bc66c7d9637599b9a5ae4fa24a5a4e41defb99cd Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Mon, 13 Jul 2026 13:38:30 +0800
Subject: [PATCH 066/133] The docs learn to speak to machines: the build emits
 llms.txt, llms-full.txt and a .md twin of every page, and an installable
 agent skill teaches the whole surface
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- website/scripts/generate-llms.mjs runs after next build: grouped index,
  full concatenation, per-page markdown — all from meta.json + frontmatter,
  with the same drift-fails-the-build assertions as docs.ts. Links are
  root-relative until SITE_URL is set; no hardcoded fallback origin.
- skills/dormice/SKILL.md (open Agent Skills format, `npx skills add
  BitMiracle-AI/Dormice`): connect, pick E2B SDK / native API / CLI, the
  core loop, policy knobs, gotchas — every sample lifted from the docs.
- New docs page (Reference › AI-readable docs) and a README section.
- README caught up with three renames it had slept through:
  releaseSandbox→destroySandbox, sandbox release→destroy,
  metadata.userKey→externalId.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md                         |  21 +++-
 skills/dormice/SKILL.md           | 192 ++++++++++++++++++++++++++++++
 website/content/docs/llms.mdx     |  37 ++++++
 website/content/docs/meta.json    |   2 +-
 website/package.json              |   2 +-
 website/scripts/generate-llms.mjs | 126 ++++++++++++++++++++
 website/src/lib/docs.ts           |   2 +
 7 files changed, 377 insertions(+), 5 deletions(-)
 create mode 100644 skills/dormice/SKILL.md
 create mode 100644 website/content/docs/llms.mdx
 create mode 100644 website/scripts/generate-llms.mjs

diff --git a/README.md b/README.md
index 8fd4937..4ea0e84 100644
--- a/README.md
+++ b/README.md
@@ -56,16 +56,31 @@ await client.writeFiles('my-agent', [
   { path: 'notes.txt', content: 'survives freeze and stop' },
 ]);
 
-await client.releaseSandbox('my-agent'); // destroy — the only verb that loses data
+await client.destroySandbox('my-agent'); // destroy — the only verb that loses data
 ```
 
 The wire is plain HTTP RPC (`POST /acquireSandbox`, `POST /execCommand`, …),
 so `curl` works where the SDK doesn't reach, and the `dor` CLI covers the
-operator side: `dor sandbox ls / exec / push / pull / rebuild / release`,
+operator side: `dor sandbox ls / exec / push / pull / rebuild / destroy`,
 plus `dor doctor`. The full native surface is documented in
 [`packages/sdk`](packages/sdk/README.md), and runnable versions of these
 flows live in [`examples/`](examples/).
 
+## Agent skill
+
+Dormice's users are agents, so the manual comes in a form an agent can
+install — a skill in the open [Agent Skills](https://skills.sh) format:
+
+```sh
+npx skills add BitMiracle-AI/Dormice
+```
+
+One file, [`skills/dormice/SKILL.md`](skills/dormice/SKILL.md), teaching a
+coding agent the whole surface: how to connect, pick between the E2B SDKs /
+native API / CLI, run commands, move files, and set lifecycle policy. The
+documentation site is AI-readable too — its build emits `/llms.txt`,
+`/llms-full.txt`, and a plain-markdown `.md` twin of every docs page.
+
 ## E2B compatibility
 
 The daemon speaks the E2B protocol on two prefixes (`/e2b/api`,
@@ -111,7 +126,7 @@ Deliberate deltas from the hosted product:
 - **Permanence stays the default.** Sandboxes created through the E2B
   surface get real deadlines, as E2B semantics demand; deadlines are never
   imposed on natively created sandboxes.
-- **`metadata.userKey`** turns `Sandbox.create` into Dormice's idempotent
+- **`metadata.externalId`** turns `Sandbox.create` into Dormice's idempotent
   acquire: the same key returns the same sandbox instead of a new one.
 - **Not implemented**, answered with an honest `unimplemented` on the
   wire: `Process/StreamInput` (the JS SDK never calls it) and xattr-based
diff --git a/skills/dormice/SKILL.md b/skills/dormice/SKILL.md
new file mode 100644
index 0000000..f066e75
--- /dev/null
+++ b/skills/dormice/SKILL.md
@@ -0,0 +1,192 @@
+---
+name: dormice
+description: Operate Dormice self-hosted agent sandboxes — acquire a sandbox, run commands, move files, tune lifecycle policy — through the official E2B SDKs, the native HTTP API and SDK, or the dor CLI. Use when connecting to a Dormice server, running untrusted or AI-generated code in a sandbox, giving an agent a persistent workspace, or migrating an application off E2B.
+---
+
+# Dormice
+
+Dormice is a self-hosted sandbox platform: one daemon on one machine, and
+sandboxes that are **permanent** — idle ones cool down
+(`active → frozen → stopped → archived`) instead of being destroyed, and any
+acquire brings them back. Two facts drive every workflow below:
+
+- **`acquireSandbox(externalId)` is the entire mental model.** Idempotent:
+  the same key always returns the same sandbox, whatever state it was in.
+  No sandbox → create; frozen → wake (~50 ms); stopped → start; archived →
+  restore. Only `acquireSandbox` creates — other verbs answer 404 for an
+  unknown key.
+- **The disk, not the container, is the sandbox's body.** Files survive
+  freezes, stops, daemon restarts, and host reboots. Only `destroySandbox`
+  loses data.
+
+## Connecting
+
+The daemon serves everything on one port and binds to `127.0.0.1:3676`
+only. On the server itself use that address directly; from another machine
+the operator has either an SSH tunnel
+(`ssh -L 3676:127.0.0.1:3676 root@host`, then use `http://127.0.0.1:3676`)
+or a reverse-proxy domain (then use `https://their-domain`). Auth is one
+API token (created by the installer, hex): ask the user for the endpoint
+and token, conventionally held in `DORMICE_ENDPOINT` / `DORMICE_API_TOKEN`.
+
+## Pick an entry path
+
+| Path | When |
+| --- | --- |
+| Official `e2b` SDK (npm / PyPI, unmodified) | Default for application code today, and for anything already written against E2B |
+| Native HTTP API (`curl`) | Shell scripts, quick checks, any language without an SDK |
+| `@dormice/sdk` (TypeScript) | Native semantics with types; first npm release is queued — inside the repo, `pnpm build` produces it |
+| `dor` CLI | Operator work in a terminal: list, exec, push/pull, rebuild, doctor |
+
+## Official E2B SDKs — change two URLs
+
+The daemon speaks the E2B protocol on `/e2b/api` (control plane) and
+`/e2b/envd` (in-sandbox). Prefix the token with `e2b_`:
+
+```ts
+import { Sandbox } from 'e2b';
+
+const sbx = await Sandbox.create({
+  apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`,
+  apiUrl: 'http://127.0.0.1:3676/e2b/api',
+  sandboxUrl: 'http://127.0.0.1:3676/e2b/envd',
+});
+await sbx.commands.run('echo hello');
+```
+
+```python
+import os
+from e2b import Sandbox
+
+sandbox = Sandbox.create(
+    api_key=f"e2b_{os.environ['DORMICE_API_TOKEN']}",
+    api_url="http://127.0.0.1:3676/e2b/api",
+    sandbox_url="http://127.0.0.1:3676/e2b/envd",
+)
+sandbox.commands.run("echo hello")
+```
+
+`Sandbox.create` makes a fresh sandbox each time (faithful E2B semantics).
+To get Dormice's idempotent acquire through the E2B surface, pass
+`metadata: { externalId: 'my-project' }` — the same key then always returns
+the same sandbox with its files intact. E2B `timeoutMs` deadlines are real:
+at the deadline the sandbox is killed, or parked with
+`lifecycle: { onTimeout: 'pause' }` and revived by `connect`.
+
+## Native API — one POST route per verb
+
+Every operation is `POST /<sdkMethodName>` with a JSON body and
+`Authorization: Bearer <token>`; every non-2xx body is
+`{ "message": "..." }`. Core loop with the SDK:
+
+```ts
+import { Dormice } from '@dormice/sdk';
+
+const client = new Dormice({
+  endpoint: 'http://127.0.0.1:3676',
+  token: process.env.DORMICE_API_TOKEN!,
+});
+
+await client.acquireSandbox('my-agent', { policy: { stopAfterSeconds: null } });
+
+const result = await client.execCommand('my-agent', 'python3 -c "print(6 * 7)"');
+console.log(result.exitCode, result.stdout); // 0 42
+
+await client.writeFiles('my-agent', [
+  { path: 'notes.txt', content: 'survives freeze and stop' },
+]);
+
+await client.destroySandbox('my-agent'); // the only verb that loses data
+```
+
+The same loop in curl:
+
+```sh
+curl -X POST http://127.0.0.1:3676/acquireSandbox \
+  -H "Authorization: Bearer $DORMICE_API_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"externalId": "my-agent"}'
+```
+
+Verbs: `acquireSandbox`, `listSandboxes`, `execCommand`, `writeFiles` /
+`writeFile`, `readFile` / `readFiles`, `rebuildSandbox` (fresh container,
+`/home/user` kept), `destroySandbox`, `registerTemplate` / `listTemplates` /
+`removeTemplate`, `getHostMetrics`. `execCommand` takes
+`{ externalId, command, timeoutSeconds?, cwd?, env? }` and returns
+`{ exitCode, stdout, stderr, ... }` — **a non-zero exit code is a result,
+not an HTTP error**. When a sandbox is coming back from S3, `acquireSandbox`
+returns `{ status: 'restoring', progress }` immediately; poll it until the
+status flips to `ready`.
+
+## CLI
+
+```sh
+dor sandbox ls                        # every sandbox, with lifecycle state
+dor sandbox exec my-agent 'uname -r'  # exit code passes through
+dor sandbox push my-agent ./data.csv  # → /home/user/data.csv
+dor sandbox pull my-agent notes.txt
+dor sandbox rebuild my-agent          # fresh container, /home/user kept
+dor sandbox destroy my-agent
+dor doctor                            # can this machine run sandboxes?
+```
+
+Connects via `DORMICE_ENDPOINT` and `DORMICE_API_TOKEN`.
+
+## Files
+
+Native file verbs move content as base64 inside JSON, capped at 16 MiB per
+file (batches 48 MiB) with honest refusals — never a truncated file. Paths
+are absolute or relative to `/home/user`; parent directories are created.
+Past the cap: download from *inside* the sandbox (`execCommand` with `curl`,
+in the stock image), or use the E2B files surface (`files.read/write`
+stream uncapped; `uploadUrl()` / `downloadUrl()` mint signed URLs).
+
+## Lifecycle policy — three knobs
+
+Set at **creation only** (overrides on an existing sandbox are not applied);
+all count seconds since last activity, ordering freeze ≤ stop ≤ archive:
+
+| Knob | Default | `null` means |
+| --- | --- | --- |
+| `freezeAfterSeconds` | 10 minutes | — (freezing is always on) |
+| `stopAfterSeconds` | 3 days | never stop |
+| `archiveAfterSeconds` | 7 days when S3 is configured, else never | never archive |
+
+The pattern Dormice was built for — one permanent sandbox per agent:
+
+```ts
+await client.acquireSandbox(`agent-${userId}`, {
+  policy: { stopAfterSeconds: null },
+});
+```
+
+It parks at frozen (~5 MiB resident) and wakes in ~50 ms — never a cold
+start; frozen processes suspend mid-flight and resume exactly where they
+were. Commands and file operations reset the idle clock; observation
+(`listSandboxes`, metrics) never wakes or warms anything. A background
+process does **not** keep its sandbox warm — a resident sandbox means
+"ready whenever the agent returns", not an unattended 24×7 workload.
+
+## Gotchas
+
+- **Keep the API token hexadecimal.** The Python E2B SDK validates
+  `e2b_[0-9a-f]+` client-side; other characters fail before any request.
+- **Bring a patient HTTP client.** `execCommand` sends response headers
+  only when the command finishes — legally hours later. Node's undici ships
+  a hidden ~5-minute header timeout; disable it (the native SDK already
+  does) or long commands die at exactly 300 s with an error that looks like
+  the server's fault.
+- **Sandboxes run untrusted code, contained.** Everything runs as a
+  non-root user (uid 1000) inside gVisor. The stock image ships Ubuntu
+  24.04, Python 3.12, Node 24, git, ripgrep, and a pinned Claude Code.
+
+## Learn more
+
+Docs (served as `/llms.txt`, `/llms-full.txt`, and per-page `.md` on the
+project site; sources on GitHub):
+[quickstart](https://github.com/BitMiracle-AI/Dormice/blob/main/website/content/docs/quickstart.mdx) ·
+[lifecycle](https://github.com/BitMiracle-AI/Dormice/blob/main/website/content/docs/lifecycle.mdx) ·
+[E2B SDKs](https://github.com/BitMiracle-AI/Dormice/blob/main/website/content/docs/e2b-sdks.mdx) ·
+[HTTP API](https://github.com/BitMiracle-AI/Dormice/blob/main/website/content/docs/http-api.mdx) ·
+[files](https://github.com/BitMiracle-AI/Dormice/blob/main/website/content/docs/files.mdx) ·
+[resident agents](https://github.com/BitMiracle-AI/Dormice/blob/main/website/content/docs/resident-agents.mdx)
diff --git a/website/content/docs/llms.mdx b/website/content/docs/llms.mdx
new file mode 100644
index 0000000..7508796
--- /dev/null
+++ b/website/content/docs/llms.mdx
@@ -0,0 +1,37 @@
+---
+title: AI-readable docs
+description: llms.txt, llms-full.txt and a markdown twin of every page — plus an installable skill that teaches a coding agent to drive Dormice.
+---
+
+Dormice's users are agents, so the documentation ships in forms an agent
+can consume directly — no HTML scraping.
+
+## llms.txt and markdown pages
+
+Following the [llms.txt convention](https://llmstxt.org), the site serves:
+
+- **`/llms.txt`** — an index of every docs page with its one-line
+  description, grouped exactly like the sidebar.
+- **`/llms-full.txt`** — the entire documentation concatenated into one
+  markdown file, for tools that prefer a single fetch.
+- **A `.md` twin of every page** — append `.md` to any docs path
+  (`/docs/quickstart` → `/docs/quickstart.md`; this page's index is
+  `/docs/index.md`) and get the page as plain markdown.
+
+All three are generated from the same sources as the pages you are
+reading, in the same build — they cannot drift.
+
+## The agent skill
+
+A skill in the open [Agent Skills](https://skills.sh) format teaches a
+coding agent the whole operating surface — connecting, choosing between
+the E2B SDKs, the native API and the CLI, running commands, moving files,
+setting lifecycle policy, and the gotchas:
+
+```sh
+npx skills add BitMiracle-AI/Dormice
+```
+
+It installs into your agent's skills directory (Claude Code, Codex,
+Cursor and others). The source is one reviewable file:
+[`skills/dormice/SKILL.md`](https://github.com/BitMiracle-AI/Dormice/blob/main/skills/dormice/SKILL.md).
diff --git a/website/content/docs/meta.json b/website/content/docs/meta.json
index ac651b3..4d5ddfb 100644
--- a/website/content/docs/meta.json
+++ b/website/content/docs/meta.json
@@ -26,7 +26,7 @@
     },
     {
       "title": "Reference",
-      "pages": ["configuration", "cli", "http-api", "console"]
+      "pages": ["configuration", "cli", "http-api", "console", "llms"]
     },
     {
       "title": "Operations",
diff --git a/website/package.json b/website/package.json
index 815c5e4..14b4f75 100644
--- a/website/package.json
+++ b/website/package.json
@@ -6,7 +6,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "build": "NEXT_TELEMETRY_DISABLED=1 next build",
+    "build": "NEXT_TELEMETRY_DISABLED=1 next build && node scripts/generate-llms.mjs",
     "dev": "NEXT_TELEMETRY_DISABLED=1 next dev",
     "typecheck": "tsc --noEmit"
   },
diff --git a/website/scripts/generate-llms.mjs b/website/scripts/generate-llms.mjs
new file mode 100644
index 0000000..4582ec0
--- /dev/null
+++ b/website/scripts/generate-llms.mjs
@@ -0,0 +1,126 @@
+// Emits the AI-readable docs layer into out/ after `next build`:
+//
+//   out/llms.txt         grouped index of every docs page (llms.txt convention)
+//   out/llms-full.txt    all pages concatenated, sidebar order
+//   out/docs/<slug>.md   one plain-markdown file per page
+//
+// content/docs/meta.json stays the single decision point for grouping and
+// order (same as src/lib/docs.ts); the assertions below fail the build when
+// the directory and meta.json drift. Links are root-relative so the output
+// works before the deployment domain is decided — set SITE_URL to make them
+// absolute. No fallback origin: a made-up domain in a published file is
+// worse than a relative link.
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const websiteDir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+);
+const contentDir = path.join(websiteDir, 'content/docs');
+const outDir = path.join(websiteDir, 'out');
+
+const siteUrl = (process.env.SITE_URL ?? '').replace(/\/+$/, '');
+
+/** Parse an .mdx file into { title, description, body } or throw naming the file. */
+async function parseDoc(name) {
+  const raw = await readFile(path.join(contentDir, `${name}.mdx`), 'utf8');
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!match)
+    throw new Error(`content/docs/${name}.mdx has no frontmatter block`);
+  const fields = {};
+  for (const line of match[1].split('\n')) {
+    const field = line.match(/^(title|description):\s*(.+)$/);
+    if (field) fields[field[1]] = field[2].trim();
+  }
+  for (const key of ['title', 'description']) {
+    if (!fields[key])
+      throw new Error(
+        `content/docs/${name}.mdx frontmatter is missing "${key}"`,
+      );
+  }
+  return {
+    title: fields.title,
+    description: fields.description,
+    body: raw.slice(match[0].length).trim(),
+  };
+}
+
+const meta = JSON.parse(
+  await readFile(path.join(contentDir, 'meta.json'), 'utf8'),
+);
+const listed = meta.groups.flatMap((group) => group.pages);
+
+// Both directions, mirroring src/lib/docs.ts: every listed page has a file,
+// every file is listed.
+const onDisk = (await readdir(contentDir))
+  .filter((f) => f.endsWith('.mdx'))
+  .map((f) => f.slice(0, -4));
+for (const name of listed) {
+  if (!onDisk.includes(name)) {
+    throw new Error(
+      `content/docs/meta.json lists "${name}" but content/docs/${name}.mdx does not exist`,
+    );
+  }
+}
+for (const name of onDisk) {
+  if (!listed.includes(name)) {
+    throw new Error(
+      `content/docs/${name}.mdx exists but content/docs/meta.json does not list it`,
+    );
+  }
+}
+
+// out/ must already exist — this script only decorates a finished export.
+try {
+  await readdir(outDir);
+} catch {
+  throw new Error(
+    `${outDir} not found — run \`next build\` first (the build script chains this)`,
+  );
+}
+
+const docs = new Map(
+  await Promise.all(listed.map(async (name) => [name, await parseDoc(name)])),
+);
+// The rendered page prepends the frontmatter title and description; the .md
+// rendition does the same so both say exactly the same thing.
+const asMarkdown = (doc) =>
+  `# ${doc.title}\n\n${doc.description}\n\n${doc.body}\n`;
+const mdPath = (name) => `${siteUrl}/docs/${name}.md`;
+
+const index = [
+  `# Dormice`,
+  ``,
+  `> ${docs.get('index').description}`,
+  ``,
+  `Every page below is served as plain markdown at the linked .md path;`,
+  `[/llms-full.txt](${siteUrl}/llms-full.txt) is all of them in one file.`,
+  ``,
+  ...meta.groups.flatMap((group) => [
+    `## ${group.title}`,
+    ``,
+    ...group.pages.map((name) => {
+      const doc = docs.get(name);
+      return `- [${doc.title}](${mdPath(name)}): ${doc.description}`;
+    }),
+    ``,
+  ]),
+].join('\n');
+
+const full = listed.map((name) => asMarkdown(docs.get(name))).join('\n---\n\n');
+
+await mkdir(path.join(outDir, 'docs'), { recursive: true });
+await writeFile(path.join(outDir, 'llms.txt'), index);
+await writeFile(path.join(outDir, 'llms-full.txt'), full);
+for (const name of listed) {
+  await writeFile(
+    path.join(outDir, 'docs', `${name}.md`),
+    asMarkdown(docs.get(name)),
+  );
+}
+
+console.log(
+  `llms.txt + llms-full.txt + ${listed.length} .md pages → ${path.relative(websiteDir, outDir)}/`,
+);
diff --git a/website/src/lib/docs.ts b/website/src/lib/docs.ts
index 820616d..3c77265 100644
--- a/website/src/lib/docs.ts
+++ b/website/src/lib/docs.ts
@@ -16,6 +16,7 @@ import * as httpApi from '../../content/docs/http-api.mdx';
 import * as indexDoc from '../../content/docs/index.mdx';
 import * as installation from '../../content/docs/installation.mdx';
 import * as lifecycle from '../../content/docs/lifecycle.mdx';
+import * as llms from '../../content/docs/llms.mdx';
 import meta from '../../content/docs/meta.json';
 import * as metrics from '../../content/docs/metrics.mdx';
 import * as persistence from '../../content/docs/persistence.mdx';
@@ -57,6 +58,7 @@ const modules: Record<string, DocModule> = {
   cli,
   'http-api': httpApi,
   console: consoleDoc,
+  llms,
   doctor,
   upgrading,
   troubleshooting,

From c99a920a625e43f8f9efbbdcb0fe383e53e6d44e Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Mon, 13 Jul 2026 13:51:27 +0800
Subject: [PATCH 067/133] The rename left the imports unsorted, and Biome said
 so: 24 files relearn their alphabet
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

externalId sorts before sandboxSchema where userKey sorted after, and the
longer name pushed a handful of lines past the width limit. The sweep
that renamed the field ran the tests and the type checker but not the
linter — CI ran it. Mechanical fixes only: import order and line wraps,
straight from biome check --write on exactly the files the rename
touched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/src/archive.test.ts                       |  4 +-
 e2e/src/native.test.ts                        |  6 +-
 packages/cli/src/commands.test.ts             |  2 +-
 packages/cli/src/main.ts                      | 56 ++++++++++---------
 .../features/activity/pages/ActivityPage.tsx  |  4 +-
 .../features/sandboxes/hooks/useSandboxes.ts  |  8 ++-
 .../sandboxes/pages/SandboxDetailPage.tsx     |  6 +-
 .../sandboxes/pages/SandboxesPage.tsx         |  4 +-
 packages/console/src/lib/api.ts               |  6 +-
 packages/sdk/src/client.test.ts               |  5 +-
 packages/sdk/src/client.ts                    | 10 ++--
 packages/server/src/app.test.ts               | 12 +++-
 packages/server/src/archive/archiver.ts       | 12 ++--
 packages/server/src/db/ledger.ts              |  5 +-
 packages/server/src/e2b/compat.test.ts        |  8 ++-
 packages/server/src/e2b/control.ts            |  9 ++-
 .../server/src/routes/observability.test.ts   |  8 ++-
 packages/server/src/routes/sandboxes.ts       | 11 ++--
 packages/server/src/routes/templates.ts       |  2 +-
 packages/server/src/scanner.test.ts           | 14 ++++-
 packages/server/src/scanner.ts                |  2 +-
 packages/shared/src/acquire.ts                |  2 +-
 packages/shared/src/rebuild.ts                |  2 +-
 packages/shared/src/update-policy.ts          |  2 +-
 24 files changed, 129 insertions(+), 71 deletions(-)

diff --git a/e2e/src/archive.test.ts b/e2e/src/archive.test.ts
index 0727c11..cc989b9 100644
--- a/e2e/src/archive.test.ts
+++ b/e2e/src/archive.test.ts
@@ -83,7 +83,9 @@ describe('the archive lifecycle over a real daemon', () => {
     const deadline = Date.now() + 15_000;
     for (;;) {
       const sandboxes = await dormice.listSandboxes();
-      const mine = sandboxes.find((s) => s.externalId === 'archive-destroy-key');
+      const mine = sandboxes.find(
+        (s) => s.externalId === 'archive-destroy-key',
+      );
       if (mine?.state === 'archived') break;
       if (Date.now() > deadline) {
         throw new Error(`never archived; last observed: ${mine?.state}`);
diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index b46a728..0f2841d 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -319,7 +319,11 @@ describe('native API over a real daemon', () => {
       { path: 'hello.txt', content: 'hello from e2e\n' },
     ]);
 
-    const one = await client().writeFile('files-key', 'single.txt', 'just me\n');
+    const one = await client().writeFile(
+      'files-key',
+      'single.txt',
+      'just me\n',
+    );
     expect(one).toEqual({ path: '/home/user/single.txt' });
 
     // Batch read comes back in request order, paths resolved.
diff --git a/packages/cli/src/commands.test.ts b/packages/cli/src/commands.test.ts
index 06f0dfc..f456ff5 100644
--- a/packages/cli/src/commands.test.ts
+++ b/packages/cli/src/commands.test.ts
@@ -12,12 +12,12 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import {
   clientFromEnv,
   pullSavedMessage,
+  sandboxDestroy,
   sandboxExec,
   sandboxLs,
   sandboxPull,
   sandboxPush,
   sandboxRebuild,
-  sandboxDestroy,
   templateAdd,
   templateLs,
   templateRm,
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index 16b5113..df20665 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -9,12 +9,12 @@ import { Command } from 'commander';
 import {
   clientFromEnv,
   pullSavedMessage,
+  sandboxDestroy,
   sandboxExec,
   sandboxLs,
   sandboxPull,
   sandboxPush,
   sandboxRebuild,
-  sandboxDestroy,
   templateAdd,
   templateLs,
   templateRm,
@@ -88,17 +88,19 @@ sandbox
     '[remotePath]',
     'destination inside the sandbox; relative paths land under /home/user (default: the local file name)',
   )
-  .action(async (externalId: string, localPath: string, remotePath?: string) => {
-    const content = await readFile(localPath);
-    console.log(
-      await sandboxPush(
-        clientFromEnv(process.env),
-        externalId,
-        content,
-        remotePath ?? path.basename(localPath),
-      ),
-    );
-  });
+  .action(
+    async (externalId: string, localPath: string, remotePath?: string) => {
+      const content = await readFile(localPath);
+      console.log(
+        await sandboxPush(
+          clientFromEnv(process.env),
+          externalId,
+          content,
+          remotePath ?? path.basename(localPath),
+        ),
+      );
+    },
+  );
 
 sandbox
   .command('pull')
@@ -106,20 +108,22 @@ sandbox
   .argument('<externalId>', 'the external id whose sandbox holds the file')
   .argument('<remotePath>', 'file inside the sandbox; relative to /home/user')
   .argument('[localPath]', 'where to save it; omitted = raw bytes to stdout')
-  .action(async (externalId: string, remotePath: string, localPath?: string) => {
-    const result = await sandboxPull(
-      clientFromEnv(process.env),
-      externalId,
-      remotePath,
-    );
-    if (localPath === undefined) {
-      // Raw on purpose, like exec output: the operator's own file's bytes.
-      process.stdout.write(result.content);
-      return;
-    }
-    await writeFile(localPath, result.content);
-    console.log(pullSavedMessage(result, localPath));
-  });
+  .action(
+    async (externalId: string, remotePath: string, localPath?: string) => {
+      const result = await sandboxPull(
+        clientFromEnv(process.env),
+        externalId,
+        remotePath,
+      );
+      if (localPath === undefined) {
+        // Raw on purpose, like exec output: the operator's own file's bytes.
+        process.stdout.write(result.content);
+        return;
+      }
+      await writeFile(localPath, result.content);
+      console.log(pullSavedMessage(result, localPath));
+    },
+  );
 
 sandbox
   .command('rebuild')
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index 21d54cb..e868a0f 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -51,7 +51,9 @@ export function ActivityPage() {
         (event) =>
           (kindFilter === 'all' || event.kind === kindFilter) &&
           (search === '' ||
-            (event.externalId ?? '').toLowerCase().includes(search.toLowerCase())),
+            (event.externalId ?? '')
+              .toLowerCase()
+              .includes(search.toLowerCase())),
       ),
     [events, kindFilter, search],
   );
diff --git a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
index 5296247..2399c00 100644
--- a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
+++ b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
@@ -2,11 +2,11 @@ import type { AcquireRequest, LifecyclePolicyOverride } from '@dormice/shared';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import {
   acquireSandbox,
+  destroySandbox,
   getSandboxMetrics,
   listSandboxes,
   listSandboxMetrics,
   rebuildSandbox,
-  destroySandbox,
   updatePolicy,
 } from '@/lib/api';
 
@@ -74,8 +74,10 @@ export function useAcquireSandbox() {
 export function useUpdatePolicy() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: (args: { externalId: string; policy: LifecyclePolicyOverride }) =>
-      updatePolicy(args.externalId, args.policy),
+    mutationFn: (args: {
+      externalId: string;
+      policy: LifecyclePolicyOverride;
+    }) => updatePolicy(args.externalId, args.policy),
     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
   });
 }
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index 4394816..fab4023 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -15,6 +15,7 @@ import {
   EmptyTitle,
 } from '@/components/ui/empty';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { DestroySandboxButton } from '../components/DestroySandboxButton';
 import { EditPolicyDialog } from '../components/EditPolicyDialog';
 import { FilesPanel } from '../components/FilesPanel';
 import { HistoryPanel } from '../components/HistoryPanel';
@@ -22,7 +23,6 @@ import { LifecycleCountdown } from '../components/LifecycleCountdown';
 import { MetricsPanel } from '../components/MetricsPanel';
 import { ProcessesPanel } from '../components/ProcessesPanel';
 import { RebuildSandboxButton } from '../components/RebuildSandboxButton';
-import { DestroySandboxButton } from '../components/DestroySandboxButton';
 import { RestoreCard } from '../components/RestoreCard';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
 import { SandboxTerminalCard } from '../components/SandboxTerminal';
@@ -87,7 +87,9 @@ export function SandboxDetailPage() {
     <>
       <div className="flex flex-wrap items-center justify-between gap-3">
         <div className="flex items-center gap-3">
-          <h1 className="font-mono text-lg font-semibold">{sandbox.externalId}</h1>
+          <h1 className="font-mono text-lg font-semibold">
+            {sandbox.externalId}
+          </h1>
           <SandboxStateBadge state={sandbox.state} />
           <LifecycleCountdown sandbox={sandbox} />
         </div>
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index aafab7b..f0af4ac 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -240,7 +240,9 @@ export function SandboxesPage() {
 
   const toggleAll = () => {
     setSelected(
-      allVisibleSelected ? new Set() : new Set(filtered.map((s) => s.externalId)),
+      allVisibleSelected
+        ? new Set()
+        : new Set(filtered.map((s) => s.externalId)),
     );
   };
   const toggleOne = (externalId: string) => {
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index b9c3586..75aaa52 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -169,8 +169,10 @@ export const rebuildSandbox = (externalId: string) =>
 
 // Patch the stored lifecycle policy in place — the update verb acquire is
 // not. Ledger-only: nothing wakes, the idle clock keeps running.
-export const updatePolicy = (externalId: string, policy: LifecyclePolicyOverride) =>
-  rpc<{ sandbox: Sandbox }>('/updatePolicy', { externalId, policy });
+export const updatePolicy = (
+  externalId: string,
+  policy: LifecyclePolicyOverride,
+) => rpc<{ sandbox: Sandbox }>('/updatePolicy', { externalId, policy });
 
 // The terminal's key: trades the session cookie for one sandbox's envd
 // access token, so the browser can speak to the envd surface directly.
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 26bd9cb..8e0cfbc 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -389,7 +389,10 @@ describe('the observability verbs over real HTTP', () => {
     await client.acquireSandbox('fleet-b');
     const samples = await client.listSandboxMetrics();
     const mine = samples.filter((s) => s.externalId.startsWith('fleet-'));
-    expect(mine.map((s) => s.externalId).sort()).toEqual(['fleet-a', 'fleet-b']);
+    expect(mine.map((s) => s.externalId).sort()).toEqual([
+      'fleet-a',
+      'fleet-b',
+    ]);
     for (const entry of mine) {
       expect(entry.sample.memTotalBytes).toBeGreaterThan(0);
     }
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 4c57a4b..405e889 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -3,6 +3,8 @@ import {
   type ActivityEvent,
   acquireResponseSchema,
   DEFAULT_EXEC_TIMEOUT_SECONDS,
+  type DestroySandboxResponse,
+  destroySandboxResponseSchema,
   type ExecCommandResponse,
   execCommandResponseSchema,
   type GetConfigResponse,
@@ -20,21 +22,19 @@ import {
   listTemplatesResponseSchema,
   type RebuildSandboxResponse,
   type RegisterTemplateResponse,
-  type DestroySandboxResponse,
   type RemoveTemplateResponse,
   readFileResponseSchema,
+  readFilesResponseSchema,
   rebuildSandboxResponseSchema,
   registerTemplateResponseSchema,
-  destroySandboxResponseSchema,
   removeTemplateResponseSchema,
-  readFilesResponseSchema,
   type Sandbox,
   type SandboxMetricsSample,
   type SetIngressResponse,
-  type UpdatePolicyResponse,
   setIngressResponseSchema,
-  updatePolicyResponseSchema,
   type Template,
+  type UpdatePolicyResponse,
+  updatePolicyResponseSchema,
   type WriteFileResponse,
   type WriteFilesResponse,
   writeFileResponseSchema,
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index 02307fa..f7db980 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -537,7 +537,9 @@ describe('POST /execCommand', () => {
       command: 'sleep 1',
     });
     await new Promise((resolve) => setTimeout(resolve, 100));
-    const releaseRes = await rpc(app, '/destroySandbox', { externalId: 'alice' });
+    const releaseRes = await rpc(app, '/destroySandbox', {
+      externalId: 'alice',
+    });
     expect(releaseRes.json()).toEqual({ destroyed: true });
 
     // Both requests settle; ride out one more heartbeat interval on the
@@ -617,7 +619,10 @@ describe('POST /writeFiles and /readFile', () => {
       files: [{ path: 'x', contentBase64: 'eA==' }],
     });
     expect(write.statusCode).toBe(404);
-    const read = await rpc(app, '/readFile', { externalId: 'nobody', path: 'x' });
+    const read = await rpc(app, '/readFile', {
+      externalId: 'nobody',
+      path: 'x',
+    });
     expect(read.statusCode).toBe(404);
     expect(read.json().message).toMatch(/no sandbox for key/);
   });
@@ -1280,7 +1285,8 @@ describe('templates', () => {
   it('a valid template on an existing key is not applied — creation-time only', async () => {
     const { app } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' });
-    const created = (await acquire(app, { externalId: 'alice' })).json().sandbox;
+    const created = (await acquire(app, { externalId: 'alice' })).json()
+      .sandbox;
     expect(created.template).toBeNull();
     const again = (
       await acquire(app, { externalId: 'alice', template: 'py' })
diff --git a/packages/server/src/archive/archiver.ts b/packages/server/src/archive/archiver.ts
index 8edea98..e4874c7 100644
--- a/packages/server/src/archive/archiver.ts
+++ b/packages/server/src/archive/archiver.ts
@@ -141,11 +141,13 @@ export class Archiver {
       detail: 'restore from S3 began',
     });
     const progress: RestoreProgress = { phase: 'downloading', percent: 0 };
-    const done = this.runRestore(row.sandboxId, row.externalId, progress).finally(
-      () => {
-        this.restores.delete(row.sandboxId);
-      },
-    );
+    const done = this.runRestore(
+      row.sandboxId,
+      row.externalId,
+      progress,
+    ).finally(() => {
+      this.restores.delete(row.sandboxId);
+    });
     // Native acquire never awaits this — a failure with no joiner must not
     // crash the daemon as an unhandled rejection. Joiners still observe the
     // rejection through the same promise.
diff --git a/packages/server/src/db/ledger.ts b/packages/server/src/db/ledger.ts
index f7a1f49..21fac0b 100644
--- a/packages/server/src/db/ledger.ts
+++ b/packages/server/src/db/ledger.ts
@@ -195,7 +195,10 @@ export function setPausedByUser(
     .run();
 }
 
-export function findByExternalId(db: Db, externalId: string): SandboxRow | undefined {
+export function findByExternalId(
+  db: Db,
+  externalId: string,
+): SandboxRow | undefined {
   return db
     .select()
     .from(sandboxes)
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 33db5a2..f4fa239 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -218,8 +218,12 @@ describe('E2B control plane', () => {
 
   it('metadata.externalId is the Dormice extension: same key, same sandbox', async () => {
     const t = testApp();
-    const first = await createSandbox(t, { metadata: { externalId: 'agent-7' } });
-    const second = await createSandbox(t, { metadata: { externalId: 'agent-7' } });
+    const first = await createSandbox(t, {
+      metadata: { externalId: 'agent-7' },
+    });
+    const second = await createSandbox(t, {
+      metadata: { externalId: 'agent-7' },
+    });
     expect(second.sandboxID).toBe(first.sandboxID);
   });
 
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index d42653a..cb8e8fb 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -5,8 +5,8 @@ import { z } from 'zod';
 import {
   countSandboxes,
   createSandbox,
-  findBySandboxId,
   findByExternalId,
+  findBySandboxId,
   listSandboxes,
   setDeadline,
   setPausedByUser,
@@ -15,8 +15,8 @@ import {
 import type { SandboxRow } from '../db/schema';
 import { findTemplate, resolveImage } from '../db/templates';
 import {
-  freezeSandbox,
   destroySandbox,
+  freezeSandbox,
   stopSandbox,
   wakeSandbox,
 } from '../lifecycle';
@@ -244,7 +244,10 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       const body = request.body;
       const timeoutSeconds = body.timeout ?? DEFAULT_TIMEOUT_SECONDS;
       const requestedKey = body.metadata?.externalId;
-      if (requestedKey !== undefined && !EXTERNAL_ID_PATTERN.test(requestedKey)) {
+      if (
+        requestedKey !== undefined &&
+        !EXTERNAL_ID_PATTERN.test(requestedKey)
+      ) {
         throw apiError(
           400,
           `invalid metadata.externalId "${requestedKey}": expected 1-64 chars of [a-zA-Z0-9._-]`,
diff --git a/packages/server/src/routes/observability.test.ts b/packages/server/src/routes/observability.test.ts
index 3f15e76..ae24231 100644
--- a/packages/server/src/routes/observability.test.ts
+++ b/packages/server/src/routes/observability.test.ts
@@ -243,7 +243,9 @@ describe('getSandboxMetrics', () => {
   it('answers a single sample for a running sandbox', async () => {
     const { app } = testApp();
     await rpc(app, '/acquireSandbox', { externalId: 'measured' });
-    const res = await rpc(app, '/getSandboxMetrics', { externalId: 'measured' });
+    const res = await rpc(app, '/getSandboxMetrics', {
+      externalId: 'measured',
+    });
     expect(res.statusCode).toBe(200);
     const { sample } = getSandboxMetricsResponseSchema.parse(res.json());
     expect(sample).not.toBeNull();
@@ -258,7 +260,9 @@ describe('getSandboxMetrics', () => {
     await freezeSandbox(db, executor, sandboxId);
     await stopSandbox(db, executor, sandboxId);
 
-    const metrics = await rpc(app, '/getSandboxMetrics', { externalId: 'cold' });
+    const metrics = await rpc(app, '/getSandboxMetrics', {
+      externalId: 'cold',
+    });
     expect(getSandboxMetricsResponseSchema.parse(metrics.json()).sample).toBe(
       null,
     );
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index ba58709..8c98638 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -2,6 +2,8 @@ import { randomUUID } from 'node:crypto';
 import {
   acquireRequestSchema,
   acquireResponseSchema,
+  destroySandboxRequestSchema,
+  destroySandboxResponseSchema,
   execCommandRequestSchema,
   execCommandResponseSchema,
   getSandboxMetricsRequestSchema,
@@ -18,8 +20,6 @@ import {
   readFilesResponseSchema,
   rebuildSandboxRequestSchema,
   rebuildSandboxResponseSchema,
-  destroySandboxRequestSchema,
-  destroySandboxResponseSchema,
   resolveSandboxPath,
   type Sandbox,
   updatePolicyRequestSchema,
@@ -55,7 +55,7 @@ import {
 } from '../executor/executor';
 import { httpError } from '../http-error';
 import type { KeyedQueue } from '../keyed-queue';
-import { rebuildSandbox, destroySandbox, wakeSandbox } from '../lifecycle';
+import { destroySandbox, rebuildSandbox, wakeSandbox } from '../lifecycle';
 import { ArchiveDisabledError, resolvePolicy } from '../policy';
 
 export interface SandboxRoutesOptions {
@@ -131,7 +131,10 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       }
       const restoring = findByExternalId(db, externalId);
       if (!restoring) {
-        throw httpError(500, `sandbox for key "${externalId}" vanished mid-slot`);
+        throw httpError(
+          500,
+          `sandbox for key "${externalId}" vanished mid-slot`,
+        );
       }
       return {
         status: 'restoring',
diff --git a/packages/server/src/routes/templates.ts b/packages/server/src/routes/templates.ts
index 6e7a281..0700e13 100644
--- a/packages/server/src/routes/templates.ts
+++ b/packages/server/src/routes/templates.ts
@@ -8,10 +8,10 @@ import {
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import type { Db } from '../db/db';
 import {
+  externalIdsUsingTemplate,
   listTemplates,
   registerTemplate,
   removeTemplate,
-  externalIdsUsingTemplate,
 } from '../db/templates';
 import { httpError } from '../http-error';
 
diff --git a/packages/server/src/scanner.test.ts b/packages/server/src/scanner.test.ts
index ee0c342..4f8abae 100644
--- a/packages/server/src/scanner.test.ts
+++ b/packages/server/src/scanner.test.ts
@@ -12,7 +12,12 @@ import { Archiver } from './archive/archiver';
 import { MemStore } from './archive/mem-store';
 import { objectKey } from './archive/store';
 import { type Db, migrateDb, openDb } from './db/db';
-import { createSandbox, findByExternalId, setDeadline, touch } from './db/ledger';
+import {
+  createSandbox,
+  findByExternalId,
+  setDeadline,
+  touch,
+} from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
@@ -47,7 +52,12 @@ async function seed(
 ): Promise<SandboxRow> {
   const sandboxId = randomUUID();
   await executor.create(sandboxId);
-  return createSandbox(db, { sandboxId, externalId, nodeId: 'node-test', policy });
+  return createSandbox(db, {
+    sandboxId,
+    externalId,
+    nodeId: 'node-test',
+    policy,
+  });
 }
 
 /** Time travel: the instant `seconds` after the row's last activity. */
diff --git a/packages/server/src/scanner.ts b/packages/server/src/scanner.ts
index e424f91..0c5b7f4 100644
--- a/packages/server/src/scanner.ts
+++ b/packages/server/src/scanner.ts
@@ -4,7 +4,7 @@ import { findBySandboxId, listSandboxes } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
-import { freezeSandbox, destroySandbox, stopSandbox } from './lifecycle';
+import { destroySandbox, freezeSandbox, stopSandbox } from './lifecycle';
 
 export interface ScanResult {
   frozen: number;
diff --git a/packages/shared/src/acquire.ts b/packages/shared/src/acquire.ts
index be07eb7..d222c1a 100644
--- a/packages/shared/src/acquire.ts
+++ b/packages/shared/src/acquire.ts
@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { lifecyclePolicyOverrideSchema } from './policy';
-import { sandboxSchema, externalIdSchema } from './sandbox';
+import { externalIdSchema, sandboxSchema } from './sandbox';
 import { templateNameSchema } from './templates';
 
 /**
diff --git a/packages/shared/src/rebuild.ts b/packages/shared/src/rebuild.ts
index 981a976..0933af6 100644
--- a/packages/shared/src/rebuild.ts
+++ b/packages/shared/src/rebuild.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { sandboxSchema, externalIdSchema } from './sandbox';
+import { externalIdSchema, sandboxSchema } from './sandbox';
 
 /**
  * rebuildSandbox(externalId) — swap the container, keep the disk. The disk is
diff --git a/packages/shared/src/update-policy.ts b/packages/shared/src/update-policy.ts
index e27269e..e313c63 100644
--- a/packages/shared/src/update-policy.ts
+++ b/packages/shared/src/update-policy.ts
@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { lifecyclePolicyOverrideSchema } from './policy';
-import { sandboxSchema, externalIdSchema } from './sandbox';
+import { externalIdSchema, sandboxSchema } from './sandbox';
 
 /**
  * updatePolicy(externalId, policy) — the update verb acquire deliberately is not.

From 7bb1d3ee5d661aba22aa377af2f872a20f224c4e Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Mon, 13 Jul 2026 15:29:45 +0800
Subject: [PATCH 068/133] =?UTF-8?q?The=20docs=20learn=20to=20speak=20to=20?=
 =?UTF-8?q?people:=20all=2023=20pages=20rebuilt=20on=20E2B's=20formula=20?=
 =?UTF-8?q?=E2=80=94=20task=20headings,=20you-sentences,=20code=20first,?=
 =?UTF-8?q?=20and=20the=20design=20essays=20sink=20to=20the=20footnotes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 website/content/docs/architecture.mdx    |  95 +++++++++--------
 website/content/docs/archiving.mdx       |  86 ++++++++-------
 website/content/docs/cli.mdx             |  96 +++++++++--------
 website/content/docs/commands.mdx        | 104 +++++++++---------
 website/content/docs/configuration.mdx   |  59 ++++++-----
 website/content/docs/console.mdx         |  39 ++++---
 website/content/docs/doctor.mdx          |  46 ++++----
 website/content/docs/e2b-differences.mdx |  28 ++---
 website/content/docs/e2b-sdks.mdx        |  49 +++++----
 website/content/docs/files.mdx           | 100 ++++++++++--------
 website/content/docs/http-api.mdx        |  58 +++++-----
 website/content/docs/index.mdx           |  87 +++++++++------
 website/content/docs/installation.mdx    | 128 +++++++++++++----------
 website/content/docs/lifecycle.mdx       | 115 ++++++++++----------
 website/content/docs/llms.mdx            |  13 +--
 website/content/docs/metrics.mdx         |  78 +++++++-------
 website/content/docs/persistence.mdx     |  95 +++++++++--------
 website/content/docs/ports.mdx           |  91 ++++++++--------
 website/content/docs/quickstart.mdx      |  53 +++++++---
 website/content/docs/resident-agents.mdx |  54 +++++-----
 website/content/docs/templates.mdx       |  75 +++++++------
 website/content/docs/troubleshooting.mdx |  80 +++++++-------
 website/content/docs/upgrading.mdx       |  55 +++++-----
 23 files changed, 922 insertions(+), 762 deletions(-)

diff --git a/website/content/docs/architecture.mdx b/website/content/docs/architecture.mdx
index fd482b1..cf7ac7d 100644
--- a/website/content/docs/architecture.mdx
+++ b/website/content/docs/architecture.mdx
@@ -1,67 +1,75 @@
 ---
 title: Architecture & security
-description: One daemon keeping a SQLite ledger and Docker reality in agreement — and what the sandbox boundary actually is.
+description: How the daemon works, what the sandbox isolation boundary actually is, and when Dormice is the wrong tool.
 ---
 
-## The ledger and reality
+This page is the deep end: how Dormice works underneath, and the
+security properties you are relying on. You don't need it to use
+Dormice — start with the [Quick start](/docs/quickstart) — but read it
+before you run untrusted code in production.
 
-The mental model behind the whole daemon: **SQLite is the ledger, Docker
-is reality, and the daemon's core job is keeping the two in agreement.**
+## One daemon, one database
 
-- Reality moves first, then the ledger records it — a crash between the
-  two leaves a container without a row, never a row without a container,
-  and the reconciler cleans up the former.
-- A **reconciler** runs before the daemon starts listening (a failure
-  refuses startup) and again on every heartbeat: a container that died
-  behind the daemon's back is recorded stopped — its disk, and therefore
-  its data, kept; ownerless leftovers are swept.
-- The design is **crash-only**: there is no graceful-shutdown path to get
-  wrong. Kill the daemon at any moment; it reconciles on the way up.
-- **One machine, one daemon**, enforced rather than assumed: an exclusive
-  lock next to the ledger makes a second daemon refuse to start, and a
-  startup guard refuses to boot when the ledger and the machine's reality
-  cannot belong together (an empty ledger facing live sandboxes means a
-  wrong database path — starting anyway would destroy them all).
+The daemon keeps a SQLite database of sandboxes and drives Docker to
+match it. **SQLite is the ledger, Docker is reality, and the daemon's
+core job is keeping the two in agreement.**
+
+- Reality moves first, then the ledger records it. A crash between the
+  two leaves a container without a record — never a record without a
+  container — and the reconciler cleans that up.
+- A **reconciler** runs before the daemon starts listening and again on
+  every heartbeat: a container that died behind the daemon's back is
+  recorded as stopped (its disk, and therefore its data, kept), and
+  ownerless leftovers are swept.
+- The design is **crash-only**: there is no graceful-shutdown path to
+  get wrong. You can kill the daemon at any moment; it reconciles on the
+  way up.
+- **One machine, one daemon**, enforced rather than assumed: an
+  exclusive lock next to the database makes a second daemon refuse to
+  start, and a startup guard refuses to boot when the database and the
+  machine's reality cannot belong together (an empty database facing
+  live sandboxes means a wrong database path — starting anyway would
+  destroy them all).
 
 There is deliberately no cluster mode, no external database, no queue.
-The ledger schema carries the fields sharding would need (node IDs,
-endpoints), but today the simplicity *is* the feature.
+The schema carries the fields sharding would need (node IDs, endpoints),
+but today the simplicity is the feature.
 
-## One sandbox = a gVisor container + a loop disk
+## What a sandbox is
 
 Each sandbox is a Docker container running under **gVisor** (`runsc`),
-with its `/home/user` on a dedicated loop-mounted disk image (see
-[The disk is the sandbox](/docs/persistence)). Every sandbox runs with
-the same non-negotiable parameters: non-root (uid 1000), `--init`,
+with its `/home/user` on a dedicated disk image (see
+[Sandbox persistence](/docs/persistence)). Every sandbox runs with the
+same non-negotiable parameters: non-root (uid 1000), `--init`,
 `no-new-privileges`, a pids limit, CPU and memory caps.
 
 Why gVisor and not VMs: freezing requires sandboxes to be **processes**
-(suspend them, squeeze their memory to swap), and "installs anywhere"
-rules out requiring KVM. Firecracker-class hardware virtualization is a
+(suspend them, push their memory to swap), and "installs anywhere" rules
+out requiring KVM. Firecracker-class hardware virtualization is a
 different trade — see the last section.
 
-## The security boundary, honestly
+## The security boundary
 
 - **gVisor's userspace kernel is the boundary.** Sandbox code — even
   running as `root` inside — talks to gVisor's reimplemented kernel, not
-  the host's. `uname -r` inside a sandbox reports a `-gvisor` kernel; the
-  host kernel is never exposed.
-- **Four red lines** hold everywhere:
-  1. The daemon binds to 127.0.0.1 only — by design without a knob.
-     Exposing anything is a reverse proxy's explicit job.
+  the host's. `uname -r` inside a sandbox reports a `-gvisor` kernel;
+  the host kernel is never exposed.
+- **Four rules hold everywhere:**
+  1. The daemon binds to 127.0.0.1 only — by design, without a setting
+     to change it. Exposing anything is a reverse proxy's explicit job.
   2. The Docker socket never enters a container.
-  3. Containers cannot reach the cloud metadata service (iptables) or
-     each other (`icc: false`).
+  3. Containers cannot reach the cloud metadata service (blocked by
+     iptables) or each other (`icc: false`).
   4. Containers may vanish at any time; only the disk is the sandbox.
 - **Credentials never downgrade.** The API token must be 32+ characters
-  and is compared in constant time; the E2B surface derives per-sandbox
-  access tokens from it (HMAC, stateless); the web console trades it once
-  for an httpOnly session cookie and never stores it anywhere page
+  and is compared in constant time. The E2B surface derives per-sandbox
+  access tokens from it (HMAC, stateless). The web console trades it
+  once for an httpOnly session cookie and never stores it anywhere page
   JavaScript can read.
 - **Sandbox preview URLs are deliberately unauthenticated** (the
-  `getHost()` port proxy, when `DORMICE_SANDBOX_DOMAIN` is set) — same as
-  E2B: they exist to be opened by humans and shared. Don't run a service
-  on a sandbox port unless you mean for the URL to work.
+  `getHost()` port proxy, when `DORMICE_SANDBOX_DOMAIN` is set) — same
+  as E2B: they exist to be opened by humans and shared. Don't run a
+  service on a sandbox port unless you mean for the URL to work.
 
 ## When Dormice is the wrong tool
 
@@ -74,8 +82,7 @@ Pick something else if:
 - **You want a managed service.** No hosted anything, no SLA. That is
   E2B's product, and it is good at it.
 - **Your threat model demands hardware virtualization.** Sandboxes are
-  Docker + gVisor — a userspace kernel, chosen deliberately: freezing
-  requires sandboxes to be processes, and "installs anywhere" rules out
-  requiring KVM. If only Firecracker-class VM isolation will do, this
-  trade is not for you.
+  Docker + gVisor — a userspace kernel, chosen deliberately, as above.
+  If only Firecracker-class VM isolation will do, this trade is not for
+  you.
 - **Your workloads aren't Linux.** Sandboxes are Linux containers.
diff --git a/website/content/docs/archiving.mdx b/website/content/docs/archiving.mdx
index 345adfa..17d066b 100644
--- a/website/content/docs/archiving.mdx
+++ b/website/content/docs/archiving.mdx
@@ -1,36 +1,40 @@
 ---
 title: Archiving to S3
-description: The last rung of the lifecycle — idle disks pack to tar.zst in any S3-compatible bucket, and acquire restores them with honest progress.
+description: Learn how to move long-idle sandboxes off the host into any S3-compatible bucket, and restore them with real progress reporting.
 ---
 
 Frozen costs a few MiB of RAM; stopped costs only disk. Archiving takes
-the last step: the sandbox's disk is packed with `tar` + `zstd` and
+the last step: the sandbox's disk is compressed (`tar` + `zstd`) and
 shipped to an S3-compatible bucket, and the host keeps **nothing**. A
 machine with a modest disk can hold a long tail of dormant sandboxes for
 the price of object storage.
 
+## Enable archiving
+
 Set the four `DORMICE_S3_*` variables
-([reference](/docs/configuration#archiver-s3)) — AWS, Cloudflare R2,
-MinIO, anything S3-compatible — and stopped sandboxes archive after 7
-more idle days by default, tunable per sandbox:
+([reference](/docs/configuration#archiver-s3)). Any S3-compatible store
+works: AWS, Cloudflare R2, MinIO, Alibaba OSS in S3-compat mode.
+
+With them set, stopped sandboxes archive after 7 more idle days by
+default. Tune it per sandbox with the policy:
 
 ```ts
 await client.acquireSandbox('user-42', {
   policy: {
-    stopAfterSeconds: 3600,         // an hour idle → cold storage
+    stopAfterSeconds: 3600,         // an hour idle → stopped
     archiveAfterSeconds: 7 * 86400, // a week idle → the bucket
   },
 });
 ```
 
-Without the S3 variables, archiving is honestly absent: sandboxes park at
-stopped forever, and a policy asking to archive is refused at acquire
-time — never stored as a promise the daemon cannot keep.
+Without the S3 variables, archiving is off: sandboxes park at stopped
+forever, and a policy asking to archive is rejected at acquire time —
+never stored as a promise the daemon cannot keep.
 
-## Restore: non-blocking, with real progress
+## Restore an archived sandbox
 
 `acquireSandbox` on an archived key starts the restore and answers
-immediately — a slow wake is honest, never a silent multi-minute hang:
+immediately with real progress — never a silent multi-minute hang:
 
 ```ts
 let res = await client.acquireSandbox('user-42');
@@ -44,39 +48,41 @@ while (res.status === 'restoring') {
 Progress is measured, not invented: download percent against the
 object's actual size, extraction percent against bytes fed to `tar`.
 While a restore runs, command and file verbs answer 409 pointing back at
-acquire, and release is refused too (the one exception to its
-idempotence — destroying a disk mid-rebuild would race the restore).
+acquire, and destroy is refused too — retry when the restore finishes.
 
-The E2B surface has no `restoring` concept, so there `connect` / `create`
-simply block until the sandbox is ready — faithful E2B semantics.
+The E2B surface has no `restoring` concept, so there `connect` /
+`create` simply block until the sandbox is ready — faithful E2B
+semantics.
 
-The whole loop is verified end to end against MinIO: sandbox idles down
-to archived, the bucket object appears and the local disk is freed;
-re-acquire reports `restoring { downloading }`, flips to `ready`, and the
-files come back byte-identical.
+The whole loop is verified end to end against MinIO: a sandbox idles
+down to archived, the bucket object appears and the local disk is freed;
+re-acquiring reports `restoring`, flips to `ready`, and the files come
+back byte-identical.
 
-## Crash-safe by ordering, not by ceremony
+## The trade-off
 
-The archiver holds one invariant: **the local disk is deleted only after
-the upload is confirmed and recorded.** A crash anywhere between the
-steps leaves either a stopped sandbox (the retry re-archives to the same
-object key, an idempotent overwrite) or an archived one — never a sandbox
-whose only copy is a half-written object. A failed restore deletes its
-half-built disk and returns the row to archived; the object was never
-touched, so the retry is clean.
+Archiving converts disk money into wake-up time: a stopped sandbox
+cold-starts in seconds, an archived one needs a download and an unpack
+first — proportional to how much the sandbox actually wrote. Raise
+`archiveAfterSeconds` to keep sandboxes on disk longer, or set it to
+`null` for sandboxes that must never wait.
 
-One object per sandbox (`disks/<sandboxId>.tar.zst`). A successful
-restore deletes the object; releasing an archived sandbox deletes it too
-— nothing leaks in the bucket. And if you unset the S3 variables while
-sandboxes sit archived, touching one answers a 503 naming the missing
-variables.
+As a bonus, a restore builds its disk at the *current* size setting and
+boots the *current* image —
+[restores upgrade too](/docs/persistence#restores-upgrade-too).
 
-## The trade, in plain terms
+## How archiving stays crash-safe
 
-Archiving converts disk money into wake-up time: a stopped sandbox
-cold-starts in seconds, an archived one needs a download and an unpack
-first — proportional to how much the sandbox actually wrote. Two knobs
-frame it: raise `archiveAfterSeconds` to keep sandboxes on disk longer,
-or set it `null` for sandboxes that must never wait. As a bonus, a
-restore builds its disk at the *current* size setting and boots the
-*current* image — [restore is also an upgrade](/docs/persistence#restore-is-also-an-upgrade).
+The archiver holds one invariant: **the local disk is deleted only after
+the upload is confirmed and recorded.** A crash anywhere in between
+leaves either a stopped sandbox (the retry re-archives to the same
+object key) or an archived one — never a sandbox whose only copy is a
+half-written object. A failed restore deletes its half-built disk and
+returns the sandbox to archived; the object was never touched, so the
+retry is clean.
+
+There is one object per sandbox (`disks/<sandboxId>.tar.zst`). A
+successful restore deletes the object, and destroying an archived
+sandbox deletes it too — nothing leaks in the bucket. If you unset the
+S3 variables while sandboxes sit archived, touching one answers a 503
+naming the missing variables.
diff --git a/website/content/docs/cli.mdx b/website/content/docs/cli.mdx
index f0e9149..3943c3f 100644
--- a/website/content/docs/cli.mdx
+++ b/website/content/docs/cli.mdx
@@ -1,42 +1,33 @@
 ---
 title: CLI reference
-description: Every dor command — sandboxes, templates, and the host doctor — with the exact flags and exit-code behavior.
+description: Every dor command — sandboxes, templates, and the host doctor — with flags and exit-code behavior.
 ---
 
-The CLI installs as two names for the same binary: `dormice` (the name you
-can guess) and `dor` (the name you actually type). It talks to a daemon
-over the [HTTP API](/docs/http-api) and connects with exactly two
-environment variables — missing one produces an error naming it:
+The CLI installs as two names for the same binary: `dormice` and `dor`
+(the one you actually type). It talks to a daemon over the
+[HTTP API](/docs/http-api) and connects with exactly two environment
+variables — missing one produces an error naming it:
 
 ```sh
 export DORMICE_ENDPOINT=http://127.0.0.1:3676
 export DORMICE_API_TOKEN=<token>   # on the daemon host: grep ^DORMICE_API_TOKEN /etc/dormice/env
 ```
 
-Errors print as one line on stderr (no stack traces at a shell prompt) and
-exit 1.
+Errors print as one line on stderr (no stack traces at a shell prompt)
+and exit 1.
 
-## dor doctor
-
-```sh
-dor doctor           # every check, including probes that start a real container
-dor doctor --quick   # skip the container probes
-```
-
-Read-only host checks: can this machine run the daemon? Exit 0 unless a
-check fails. Every check is documented one by one in
-[dor doctor](/docs/doctor).
-
-## dor sandbox
+## dor sandbox ls
 
 ```sh
 dor sandbox ls
 ```
 
-Every sandbox with its lifecycle state, as a table. Listing is
+Lists every sandbox with its lifecycle state, as a table. Listing is
 observation — it never wakes anything. (Table output strips control
-characters: user keys are not restricted on the wire, and an ANSI escape
-inside one must not reach your terminal.)
+characters, so an ANSI escape hidden in a sandbox key cannot reach your
+terminal.)
+
+## dor sandbox exec
 
 ```sh
 dor sandbox exec <externalId> '<command>' [-t <seconds>]
@@ -44,38 +35,46 @@ dor sandbox exec <externalId> '<command>' [-t <seconds>]
 
 Runs a shell command in the sandbox behind the key, waking it first. The
 command is one quoted argument, executed as `bash -c`. Its stdout and
-stderr pass through to yours, raw — this is your own command's output —
-and **its exit code becomes `dor`'s exit code**, so `dor sandbox exec` in
-a script behaves like the command itself. `-t, --timeout <seconds>` kills
-it after that long ([enforced inside the container](/docs/commands)). An
-unknown key is a 404, never a sandbox created by accident.
+stderr pass through to yours, and **its exit code becomes `dor`'s exit
+code** — so `dor sandbox exec` in a script behaves like the command
+itself.
+
+`-t, --timeout <seconds>` kills the command after that long
+([enforced inside the container](/docs/commands)). An unknown key is a
+404, never a sandbox created by accident.
+
+## dor sandbox push / pull
 
 ```sh
 dor sandbox push <externalId> <localPath> [remotePath]
 dor sandbox pull <externalId> <remotePath> [localPath]
 ```
 
-One file in, one file out. Relative remote paths land under `/home/user`;
-`push` without a remote path uses the local file's name. `pull` without a
-local path writes the raw bytes to stdout — pipe it wherever. Both obey
-the [16 MiB single-file contract](/docs/files).
+One file in, one file out. Relative remote paths land under
+`/home/user`; `push` without a remote path uses the local file's name.
+`pull` without a local path writes the raw bytes to stdout — pipe it
+wherever. Both obey the [16 MiB single-file limit](/docs/files).
+
+## dor sandbox rebuild
 
 ```sh
 dor sandbox rebuild <externalId>
 ```
 
-Swaps the container, keeps `/home/user` — the sandbox's next use starts
-on its template's *current* image (or the base image). This is how a
-[template upgrade](/docs/templates) reaches an existing sandbox. Details:
-[rebuild: new shell, same body](/docs/persistence#rebuild-new-shell-same-body).
+Swaps the container and keeps `/home/user` — the sandbox's next use
+starts on its template's *current* image (or the base image). This is
+how a [template upgrade](/docs/templates) reaches an existing sandbox.
+Details: [Rebuild a sandbox](/docs/persistence#rebuild-a-sandbox).
+
+## dor sandbox destroy
 
 ```sh
 dor sandbox destroy <externalId>
 ```
 
-Destroys the sandbox — container, disk, and (if archived) the S3 object.
-The only verb that loses data. Idempotent: releasing a key that has no
-sandbox reports so and exits 0.
+Destroys the sandbox — container, disk, and (if archived) the S3
+object. The only command that loses data. Idempotent: destroying a key
+that has no sandbox reports so and exits 0.
 
 ## dor template
 
@@ -85,8 +84,19 @@ dor template ls
 dor template rm <name>
 ```
 
-A template is a name for a Docker image already on the daemon's host —
-`add` on an existing name re-points it at the new image, which is the
-[upgrade front door](/docs/templates). `rm` is refused (with the sandboxes
-named) while any sandbox still uses the template, and never removes the
-image itself.
+A template is a name for a Docker image already on the daemon's host.
+`add` on an existing name re-points it at the new image — the
+[upgrade front door](/docs/templates). `rm` is refused (with the
+sandboxes named) while any sandbox still uses the template, and never
+removes the image itself.
+
+## dor doctor
+
+```sh
+dor doctor           # every check, including probes that start a real container
+dor doctor --quick   # skip the container probes
+```
+
+Read-only host checks: can this machine run the daemon? Exits 0 unless
+a check fails. Every check is documented one by one in
+[dor doctor](/docs/doctor).
diff --git a/website/content/docs/commands.mdx b/website/content/docs/commands.mdx
index 6feb8bb..4bcef08 100644
--- a/website/content/docs/commands.mdx
+++ b/website/content/docs/commands.mdx
@@ -1,68 +1,57 @@
 ---
 title: Running commands
-description: execCommand is a buffered shell round-trip — honest exit codes, timeouts enforced inside the container, output capped at 1 MiB per stream.
+description: Learn how to run shell commands inside a sandbox — timeouts, working directory, environment variables, and output limits.
 ---
 
-The native surface has one command verb: `execCommand(externalId, command)`.
-It wakes the sandbox if it is cold, runs the command as `bash -c` inside
-the container (as the sandbox's non-root user, uid 1000), waits, and
-returns the whole result at once:
+## Run a command
+
+You can run a shell command inside a sandbox with `execCommand`. It
+wakes the sandbox if needed, runs the command as `bash -c` (as the
+sandbox's non-root user), waits, and returns the whole result at once:
 
 ```ts
 const result = await client.execCommand('my-agent', 'python3 --version');
 result.exitCode;        // 0
 result.stdout;          // 'Python 3.12.…\n'
 result.stderr;          // ''
-result.stdoutTruncated; // false — see "Output is capped" below
+result.stdoutTruncated; // false — see "Output limits" below
 ```
 
-The same verb from the CLI, where stdout and stderr pass through to your
-own streams and the exit code becomes `dor`'s own:
+**A non-zero exit code is a result, not an error.** `execCommand`
+resolves with `exitCode: 1` — it does not throw. Errors are reserved for
+the protocol failing: 404 when no sandbox exists behind the key (one is
+never silently created), 409 while a sandbox is mid-restore.
+
+## Run a command from the CLI
+
+`dor sandbox exec` runs the same verb from a shell. The command's stdout
+and stderr pass through to yours, and its exit code becomes `dor`'s own —
+so it behaves like the command itself in scripts:
 
 ```sh
 dor sandbox exec my-agent 'uname -r'
 dor sandbox exec my-agent 'npm ci && npm test' -t 3600
 ```
 
-## A non-zero exit is a result, not an error
-
-`execCommand` resolves with `exitCode: 1` — it does not throw. Errors are
-reserved for the protocol failing (no sandbox behind the key: 404, never
-silently created; sandbox mid-restore: 409), not for your command doing
-what commands do.
-
-## Timeouts are enforced inside the container
+## Set a timeout
 
-`timeoutSeconds` (default 300, ceiling 86400) arms a
-`timeout --signal=KILL` around your command *inside* the sandbox; on
-expiry the command dies with exit 137 like any SIGKILLed process. Inside
-on purpose: dropping the HTTP request cannot reach a process on the other
-side of the container boundary, so a host-side deadline would report a
-kill without performing one.
+Pass `timeoutSeconds` (default 300, maximum 86400). On expiry the
+command is killed and returns exit code 137, like any SIGKILLed process:
 
-There is deliberately no `timedOut` flag in the response: 137 is also what
-an in-sandbox OOM kill looks like, and the daemon cannot tell the two
-apart — so it does not pretend to.
-
-The SDK derives its HTTP deadline from the same `timeoutSeconds` (plus
-slack for the wake and the round-trip), so a long-running command is never
-cut short by the client-wide `timeoutMs`.
-
-## A running command is activity
-
-While a command runs, the sandbox's idle clock keeps resetting — the idle
-scanner never freezes a sandbox mid-command, even one that legitimately
-runs for hours.
+```ts
+await client.execCommand('my-agent', 'npm ci && npm test', {
+  timeoutSeconds: 3600,
+});
+```
 
-## Output is capped at 1 MiB per stream
+The SDK derives its HTTP deadline from the same value, so a long-running
+command is never cut short by a client-side timeout.
 
-The buffered protocol holds the whole result in daemon memory, so stdout
-and stderr are each capped at 1 MiB. Truncation is reported
-(`stdoutTruncated` / `stderrTruncated`), never silent. A capped log still
-informs; for bulk output, write to a file and [read it out](/docs/files)
-instead of routing bytes through stdout.
+**Note:** there is no `timedOut` flag in the response — 137 is also what
+an out-of-memory kill inside the sandbox looks like, and the daemon
+cannot tell the two apart, so it does not pretend to.
 
-## Working directory and environment
+## Set the working directory and environment
 
 ```ts
 await client.execCommand('my-agent', 'env | sort', {
@@ -71,13 +60,34 @@ await client.execCommand('my-agent', 'env | sort', {
 });
 ```
 
-`cwd` defaults to `/home/user` — the same base relative file paths
+`cwd` defaults to `/home/user` — the same base that relative file paths
 resolve against.
 
-## When buffered is the wrong shape
+## Output limits
+
+stdout and stderr are each capped at 1 MiB. Truncation is always
+reported (`stdoutTruncated` / `stderrTruncated`), never silent. For bulk
+output, write to a file and [read it out](/docs/files) instead of
+routing everything through stdout.
+
+## A running command keeps the sandbox awake
+
+While a command runs, the sandbox's idle clock keeps resetting — the
+lifecycle engine never freezes a sandbox mid-command, even one that
+legitimately runs for hours.
+
+## Streaming, background processes, and terminals
 
 `execCommand` is deliberately simple: one request, one finished result.
 For live streaming output, processes that outlive the request, stdin, or
-an interactive terminal, use the E2B surface — `commands.run` streams,
-backgrounds, and reconnects, and `pty.*` is a real interactive bash. See
-[Using the official E2B SDKs](/docs/e2b-sdks).
+an interactive terminal, use the [E2B surface](/docs/e2b-sdks) —
+`commands.run` streams, backgrounds, and reconnects, and `pty.*` is a
+real interactive bash.
+
+## How timeouts are enforced
+
+The timeout runs *inside* the container (`timeout --signal=KILL` around
+your command), not as a host-side deadline. Dropping the HTTP request
+cannot reach a process on the other side of the container boundary — an
+in-container timeout actually kills the command instead of just
+reporting that it should die.
diff --git a/website/content/docs/configuration.mdx b/website/content/docs/configuration.mdx
index 43c7e93..85a5589 100644
--- a/website/content/docs/configuration.mdx
+++ b/website/content/docs/configuration.mdx
@@ -1,69 +1,74 @@
 ---
 title: Configuration
-description: Every environment variable the daemon reads, with defaults — validated once at startup, failing loudly.
+description: Every environment variable the daemon reads, with its default and what it does.
 ---
 
-All daemon configuration comes from `DORMICE_*` environment variables,
-validated once at startup: a bad value refuses to boot with a named error
-instead of surfacing later as confusing runtime behavior. Everything has
-a default except the API token and, in docker mode, the base image.
+All daemon configuration comes from `DORMICE_*` environment variables.
+They are validated once at startup: a bad value refuses to boot with a
+named error instead of surfacing later as confusing runtime behavior.
+Everything has a default except the API token and, in docker mode, the
+base image.
 
 On a host set up by `install.sh`, the variables live in
-`/etc/dormice/env` (loaded by the systemd unit); edit the file and
-`systemctl restart dormice`.
+`/etc/dormice/env`. Edit the file and restart:
+
+```sh
+systemctl restart dormice
+```
 
 ## Core
 
 | Variable | Default | What it does |
 | --- | --- | --- |
-| `DORMICE_API_TOKEN` | — **(required)** | Bearer token for the native API, and (with an `e2b_` prefix) the E2B API key. At least 32 characters; generate with `openssl rand -hex 32`. Keep it hex: the official Python e2b SDK validates `e2b_[0-9a-f]+` client-side before any request leaves the machine. |
-| `DORMICE_PORT` | `3676` | The one port everything is served on: native API, E2B surface, web console. Always bound to 127.0.0.1 — there is deliberately no host knob. |
-| `DORMICE_DB_PATH` | `data/dormice.db` | Where the SQLite ledger lives. Must be an **absolute path** in docker mode — a relative path depends on the start directory, and a wrong start directory means an empty ledger facing real sandboxes. |
-| `DORMICE_NODE_ID` | `node-1` | Identifies this machine in the ledger. Single-machine today; the field keeps the ledger shardable later. |
+| `DORMICE_API_TOKEN` | — **(required)** | Bearer token for the native API, and (with an `e2b_` prefix) the E2B API key. At least 32 characters; generate with `openssl rand -hex 32`. Keep it hex: the official Python e2b SDK validates `e2b_[0-9a-f]+` client-side. |
+| `DORMICE_PORT` | `3676` | The one port everything is served on: native API, E2B surface, web console. Always bound to 127.0.0.1 — there is deliberately no host setting. |
+| `DORMICE_DB_PATH` | `data/dormice.db` | Where the SQLite database lives. Must be an **absolute path** in docker mode — a relative path depends on the start directory, and a wrong start directory means an empty database facing real sandboxes. |
+| `DORMICE_NODE_ID` | `node-1` | Identifies this machine in the database. Single-machine today; the field keeps the schema shardable later. |
 
 ## Executor
 
 | Variable | Default | What it does |
 | --- | --- | --- |
-| `DORMICE_EXECUTOR` | `fake` | What drives reality: `fake` is an in-memory executor so a bare `pnpm dev` works on any machine (development, tests); `docker` runs real gVisor sandboxes and needs a prepared Linux host — see [Installation](/docs/installation). |
+| `DORMICE_EXECUTOR` | `fake` | What runs the sandboxes: `fake` is an in-memory executor so a bare checkout works on any machine (development, tests); `docker` runs real gVisor sandboxes and needs a prepared Linux host — see [Installation](/docs/installation). |
 | `DORMICE_BASE_IMAGE` | — | The image sandboxes boot from. **Required in docker mode**; `install.sh` builds one and records it here. |
 | `DORMICE_DATA_DIR` | `/var/lib/dormice` | Sandbox disk images and their mount points (docker mode). Must be an absolute path in docker mode. |
 
 ## Per-sandbox resources
 
-Applied when the container (or disk) is created, so existing sandboxes
-keep what they were born with. A rebuild replaces the container and picks
-up current CPU/memory/pids values — but keeps the disk, so a changed disk
-size only applies to new sandboxes and restores from archive.
+These apply when a container (or disk) is created, so existing sandboxes
+keep what they were born with. A [rebuild](/docs/persistence#rebuild-a-sandbox)
+picks up current CPU/memory/pids values — but keeps the disk, so a
+changed disk size only applies to new sandboxes and restores from
+archive.
 
 | Variable | Default | What it does |
 | --- | --- | --- |
-| `DORMICE_SANDBOX_DISK_GB` | `10` | Size of each sandbox's disk image. The quota is physical — the file is simply that big — and sparse, so unwritten space costs nothing. |
+| `DORMICE_SANDBOX_DISK_GB` | `10` | Size of each sandbox's disk. The quota is physical and the image is sparse — unwritten space costs nothing. |
 | `DORMICE_SANDBOX_CPUS` | `1` | CPU limit per sandbox. |
-| `DORMICE_SANDBOX_MEMORY_GB` | `2` | Memory cap per sandbox. A sandbox that hits it is killed as a whole by gVisor (exit 137) and parks at stopped — files intact, next acquire revives it. |
+| `DORMICE_SANDBOX_MEMORY_GB` | `2` | Memory cap per sandbox. A sandbox that hits it is killed by gVisor (exit 137) and parks at stopped — files intact, next acquire revives it. |
 | `DORMICE_SANDBOX_PIDS_LIMIT` | `512` | Fork-bomb ceiling per sandbox. |
 
 ## Lifecycle engine
 
 | Variable | Default | What it does |
 | --- | --- | --- |
-| `DORMICE_SCAN_INTERVAL_SECONDS` | `60` | How often the idle scanner sweeps the ledger. Each sweep demotes an idle sandbox at most one rung — see [Sandbox lifecycle](/docs/lifecycle). |
-| `DORMICE_MAX_SANDBOXES` | `100` | How many sandboxes may exist at once. Past the cap, *creation* answers an honest 429; wakes of existing sandboxes are never blocked. The binding resource is disk — a full host cannot even write its ledger. |
-| `DORMICE_RECLAIM_TIMEOUT_SECONDS` | `45` | Upper bound on the memory-reclaim step of a freeze. Hitting it is expected on stubborn tails, not a failure. |
+| `DORMICE_SCAN_INTERVAL_SECONDS` | `60` | How often the idle scanner runs. Each sweep moves an idle sandbox down at most one state — see [Sandbox lifecycle](/docs/lifecycle). |
+| `DORMICE_MAX_SANDBOXES` | `100` | How many sandboxes may exist at once. Past the cap, *creation* answers 429; wakes of existing sandboxes are never blocked. |
+| `DORMICE_RECLAIM_TIMEOUT_SECONDS` | `45` | Upper bound on the memory-reclaim step of a freeze. Hitting it is expected on stubborn workloads, not a failure. |
 
 ## Sandbox network
 
 | Variable | Default | What it does |
 | --- | --- | --- |
-| `DORMICE_SANDBOX_DOMAIN` | — | The wildcard domain behind the E2B SDK's `getHost(port)`: set it (a bare hostname like `sbx.example.com`) and responses carry it, the SDK builds `<port>-<sandboxId>.<domain>` URLs, and requests arriving with such a `Host` header are proxied into the sandbox — frozen sandboxes wake on traffic. You point `*.<domain>` DNS plus a TLS-terminating reverse proxy at the daemon. Unset, the feature is honestly absent. |
+| `DORMICE_SANDBOX_DOMAIN` | — | The wildcard domain behind the E2B SDK's `getHost(port)` — see [Exposing ports](/docs/ports). Set a bare hostname like `sbx.example.com`; you point `*.<domain>` DNS plus a TLS-terminating reverse proxy at the daemon. Unset, the feature is off. |
 
 ## Archiver (S3)
 
-The four core variables come as a set: with none of them, archiving is
-honestly absent — sandboxes park at stopped forever, and a policy asking
-to archive is refused. Set all four and stopped sandboxes take the last
-step down after 7 idle days (tunable per sandbox). A partial set refuses
-to boot, naming the missing variables.
+The four core variables come as a set. With none of them, archiving is
+off — sandboxes park at stopped forever, and a policy asking to archive
+is rejected. With all four, stopped sandboxes
+[archive](/docs/archiving) after 7 more idle days by default. A partial
+set refuses to boot, naming the missing variables.
 
 | Variable | Default | What it does |
 | --- | --- | --- |
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
index 5e57e0e..022a307 100644
--- a/website/content/docs/console.mdx
+++ b/website/content/docs/console.mdx
@@ -1,20 +1,20 @@
 ---
 title: Web console
-description: The daemon serves its own UI at /console — sign in once, watch everything, wake nothing by accident.
+description: The daemon serves its own web UI at /console — watch every sandbox live, open terminals, browse files, and manage templates.
 ---
 
 The daemon hosts a web console at `http://127.0.0.1:3676/console` — same
-process, same port, nothing extra to run. It is an observation window
-with hands: everything it shows comes from the same API documented in
-this section, and it follows the same rule the API does — **watching
-never wakes a sandbox; using does, and only behind an explicit click**.
+process, same port, nothing extra to run. Everything it shows comes from
+the same API documented in this section, and it follows the same rule:
+**watching never wakes a sandbox; using one does, and only behind an
+explicit click.**
 
 (The console UI is currently Chinese-language.)
 
 ## Signing in
 
-Paste the API token once. The browser trades it for an `httpOnly` session
-cookie (valid 7 days) and never stores the token anywhere page
+Paste the API token once. The browser trades it for an `httpOnly`
+session cookie (valid 7 days) and never stores the token anywhere page
 JavaScript can read — a script injected into the console cannot steal
 your long-term credential. Sessions are derived from the API token, so
 rotating the token signs every browser out at once.
@@ -23,8 +23,8 @@ rotating the token signs every browser out at once.
 
 The "is this machine healthy" page: CPU, memory, **swap** and the **data
 disk** as first-class cards — swap filling up means "idle is free" is
-ending, and a full data disk is the real capacity ceiling. Below them,
-sandbox counts by lifecycle state and the sandbox-disk overcommit figure
+ending, and a full data disk is the real capacity ceiling. Below them:
+sandbox counts by lifecycle state and the disk-overcommit figure
 (promised vs actually occupied — the same numbers as
 [`getHostMetrics`](/docs/metrics)). Usage bars turn amber at 75% and red
 at 90%; a host without swap gets an amber warning pointing at
@@ -32,23 +32,22 @@ at 90%; a host without swap gets an amber warning pointing at
 
 ## Sandboxes
 
-The live list — every sandbox with its state, polled every 2 seconds,
-with search, a state filter, and multi-select batch release. Creating a
-sandbox from here is exactly `acquireSandbox`: user key, the lifecycle
-knobs (including the never-stop [resident-agent
-switch](/docs/resident-agents)), and a template dropdown when templates
-are registered.
+The live list — every sandbox with its state, refreshed every 2 seconds,
+with search, a state filter, and multi-select batch destroy. Creating a
+sandbox from here is exactly `acquireSandbox`: a key, the lifecycle
+knobs (including the never-stop
+[resident-agent switch](/docs/resident-agents)), and a template dropdown
+when templates are registered.
 
 A sandbox's detail page is a workspace with four tabs:
 
-- **Overview** — identity, policy thresholds, last activity; release and
-  [rebuild](/docs/persistence#rebuild-new-shell-same-body) buttons, each
+- **Overview** — identity, policy thresholds, last activity; destroy
+  and [rebuild](/docs/persistence#rebuild-a-sandbox) buttons, each
   behind a confirmation dialog.
 - **Terminal** — a real interactive shell, kept behind an explicit
   "open" button because opening one *wakes* the sandbox. The browser
-  speaks the same wire the official E2B SDK does — the console did not
-  grow a second terminal protocol. Closing the terminal kills its shell
-  rather than leaving an orphan behind.
+  speaks the same wire the official E2B SDK does. Closing the terminal
+  kills its shell rather than leaving an orphan behind.
 - **Files** — browse, upload, download, rename, delete under
   `/home/user`. File operations wake the sandbox too, so a cold sandbox
   shows an explicit "open" gate first.
diff --git a/website/content/docs/doctor.mdx b/website/content/docs/doctor.mdx
index ce01d7d..a4ab42e 100644
--- a/website/content/docs/doctor.mdx
+++ b/website/content/docs/doctor.mdx
@@ -1,12 +1,18 @@
 ---
 title: dor doctor
-description: Read-only host checks, one by one — what each verifies, why it exists, and what fix it names.
+description: Read-only host checks, one by one — what each verifies and what fix it names.
 ---
 
 `dor doctor` answers one question: **can this host run the Dormice
 daemon?** Every check encodes a fact measured on real hardware — a pit
-someone actually fell into — not a hypothesis. Three disciplines shape
-it:
+someone actually fell into — not a hypothesis.
+
+```sh
+dor doctor           # every check, including probes that start a real container
+dor doctor --quick   # skip the container probes
+```
+
+Three rules shape it:
 
 - **Read-only.** Doctor names the fix but never applies it. Fixing is
   [the installer's](/docs/installation) job.
@@ -16,17 +22,17 @@ it:
 - **No silent downloads.** A missing image is reported with build
   instructions; doctor never runs `docker pull` behind your back.
 
-Checks are gated: when a prerequisite fails, dependents report *skip*
-with the blocker's name instead of piling on noise. Any failure exits 1;
-warnings don't affect the exit code. `--quick` skips the probes that
-start a real container.
+Checks are gated: when a prerequisite fails, dependent checks report
+*skip* with the blocker's name instead of piling on noise. Any failure
+exits 1; warnings don't affect the exit code.
 
 ## Platform
 
 - **operating system** — Linux, full stop: loop mounts, cgroups and
   gVisor exist nowhere else.
 - **Node.js version** — 22 or newer.
-- **running as root** — loop mounts, `mkfs` and cgroup writes need uid 0.
+- **running as root** — loop mounts, `mkfs` and cgroup writes need
+  uid 0.
 - **cgroup v2 memory controller** — freezing works by writing
   `memory.reclaim`, a cgroup v2 file (default on Ubuntu 22.04+).
 
@@ -45,14 +51,14 @@ start a real container.
 - **swap present** — freezing pushes sandbox memory to swap; measured
   without it: 0 bytes reclaimed.
 - **vm.swappiness = 100** — below 100 the kernel refuses to swap the
-  shmem-backed memory gVisor holds sandboxes in; measured at the default
-  60: 0 bytes reclaimed. This is the check that reads the live value.
+  kind of memory gVisor holds sandboxes in; measured at the default 60:
+  0 bytes reclaimed. This is the check that reads the live value.
 
 ## Network containment
 
 - **cloud metadata firewall** — `DROP` rules in the `DOCKER-USER` chain
-  for `169.254.0.0/16` and `100.100.100.200`; without them a sandbox can
-  steal cloud credentials from the metadata service.
+  for `169.254.0.0/16` and `100.100.100.200`; without them a sandbox
+  can steal cloud credentials from the metadata service.
 - **firewall rules persisted** — *warn*: rules living only in memory
   silently vanish on reboot.
 
@@ -60,20 +66,20 @@ start a real container.
 
 - **DORMICE_API_TOKEN** — set and at least 32 characters (the daemon
   refuses to start without it).
-- **S3 archive configuration** — three honest states: none set (skipped —
-  archiver off, sandboxes park at stopped), all four set (pass), or a
-  partial set (fail, naming the missing variables — the daemon refuses a
-  half-configured archiver anyway).
+- **S3 archive configuration** — three honest states: none set (skipped
+  — archiver off, sandboxes park at stopped), all four set (pass), or a
+  partial set (fail, naming the missing variables — the daemon refuses
+  a half-configured archiver anyway).
 - **zstd available** — the archiver shells out to `tar -I zstd` on the
   host at every archive and restore.
 - **base image available** — present locally; the fix names
   `images/Dockerfile`, and doctor never pulls.
 - **docker-mode paths absolute** — a relative `DORMICE_DB_PATH` depends
   on the start directory, and a wrong start directory opens an *empty
-  ledger next to real sandboxes* — the exact mismatch the daemon's
+  database next to real sandboxes* — the exact mismatch the daemon's
   startup guard exists to refuse.
-- **free disk space** — *warn* under 10 GiB for the data directory: past
-  full, even the ledger cannot write.
+- **free disk space** — *warn* under 10 GiB for the data directory:
+  past full, even the daemon's database cannot write.
 
 ## Probes (start a real sandbox container)
 
@@ -85,7 +91,7 @@ start a real container.
 - **image runs as uid 1000** — sandboxes must not run as root, even
   behind gVisor.
 - **image has inotify-tools** — *warn*: without `inotifywait`, E2B
-  directory watching honestly refuses to start; everything else works.
+  directory watching refuses to start; everything else works.
 
 When all of this passes, the machine can run the daemon — that is the
 installer's definition of success too: it ends by running doctor and
diff --git a/website/content/docs/e2b-differences.mdx b/website/content/docs/e2b-differences.mdx
index 1391805..3171f6c 100644
--- a/website/content/docs/e2b-differences.mdx
+++ b/website/content/docs/e2b-differences.mdx
@@ -1,9 +1,11 @@
 ---
 title: Capabilities & differences
-description: What of the E2B surface is implemented — verified through the official SDK — and where Dormice deliberately diverges.
+description: What of the E2B surface Dormice implements — verified through the official SDK — and where it deliberately differs from the hosted product.
 ---
 
-Everything below is exercised by the black-box e2e suite *through the
+## What works
+
+Everything below is exercised by the black-box test suite *through the
 official `e2b` package*, and has passed against a real Docker + gVisor
 daemon:
 
@@ -22,19 +24,21 @@ daemon:
 | `getMetrics()` | one live sample; observing never wakes a frozen sandbox |
 | Templates by name | `Sandbox.create('name')` resolves a registered template; an unregistered name is an honest 404 |
 
-## Deliberate deltas from the hosted product
+## Where Dormice deliberately differs
 
 - **No template builds.** Templates are named images: build one with
-  docker, register it with `dor template add`, and `Sandbox.create('name')`
-  resolves it. The hosted product's build pipeline (`e2b template build`)
-  is not implemented.
-- **Freezing keeps processes.** A frozen sandbox's processes suspend and
-  resume mid-flight — any touch wakes the sandbox in ~50 ms.
+  docker, register it with `dor template add`, and
+  `Sandbox.create('name')` resolves it. The hosted product's build
+  pipeline (`e2b template build`) is not implemented — see
+  [Templates](/docs/templates).
+- **Freezing keeps processes.** A frozen sandbox's processes suspend
+  and resume mid-flight — any touch wakes the sandbox in ~50 ms.
 - **Permanence stays the default.** Sandboxes created through the E2B
   surface get real deadlines, as E2B semantics demand; deadlines are
   never imposed on natively created sandboxes.
-- **`metadata.externalId`** turns `Sandbox.create` into Dormice's idempotent
-  acquire — see [Using the official E2B SDKs](/docs/e2b-sdks).
+- **`metadata.externalId`** turns `Sandbox.create` into Dormice's
+  idempotent acquire — see
+  [Using the official E2B SDKs](/docs/e2b-sdks).
 - **One domain, not one subdomain per sandbox.** The SDK addresses
   sandboxes through a header on a single endpoint, so no wildcard DNS is
   needed for the API itself — only `getHost()` preview URLs want a
@@ -49,5 +53,5 @@ swallowed:
   the real path)
 - xattr-based file metadata
 
-The daemon reports envd `0.6.1`, so the SDK gates these client-side
-before they ever reach the wire.
+The daemon reports envd `0.6.1`, so the SDK gates these on the client
+side before they ever reach the wire.
diff --git a/website/content/docs/e2b-sdks.mdx b/website/content/docs/e2b-sdks.mdx
index 4128815..ab44c40 100644
--- a/website/content/docs/e2b-sdks.mdx
+++ b/website/content/docs/e2b-sdks.mdx
@@ -1,14 +1,16 @@
 ---
 title: Using the official E2B SDKs
-description: The official e2b packages — JavaScript and Python, unmodified — run against Dormice by changing two URLs.
+description: Learn how to run the official e2b packages — JavaScript and Python, unmodified — against Dormice by changing two URLs.
 ---
 
-The daemon speaks the E2B protocol on two prefixes (`/e2b/api` for the
-control plane, `/e2b/envd` for the in-sandbox surface). Point the official
-SDK at them and prefix your token with `e2b_` — migrating an application
-is configuration, not code. Everything documented here is exercised by
-black-box test suites *through the official packages* (e2b 2.31.0,
-JavaScript and Python) against a real Docker + gVisor daemon.
+Dormice speaks the E2B protocol, so the official `e2b` SDKs work against
+it without modification. Migrating an application is configuration, not
+code: point the SDK at your daemon's two URL prefixes and prefix your
+API token with `e2b_`.
+
+Everything documented here is exercised by black-box test suites
+*through the official packages* (e2b 2.31.0, JavaScript and Python)
+against a real Docker + gVisor daemon.
 
 ## JavaScript
 
@@ -41,18 +43,18 @@ sandbox = Sandbox.create(
 sandbox.commands.run("echo hello")
 ```
 
-One constraint worth knowing: **keep the API token hexadecimal**
-(`openssl rand -hex 32`, which is also what `install.sh` generates). The
-Python SDK validates its key against `e2b_[0-9a-f]+` client-side, before
-any request leaves the machine — a token with other characters fails in
-the SDK, not on the wire.
+**Note: keep the API token hexadecimal** (`openssl rand -hex 32`, which
+is what `install.sh` generates). The Python SDK validates its key
+against `e2b_[0-9a-f]+` on the client side, before any request leaves
+the machine — a token with other characters fails in the SDK, not on the
+wire.
 
-## `metadata.externalId`: idempotent create
+## Reuse the same sandbox across creates
 
 A Dormice extension: pass `metadata: { externalId: '...' }` and
 `Sandbox.create` behaves like the native `acquireSandbox` — the same key
 always returns the same sandbox instead of a new one, whatever state it
-was in, with its files intact:
+was in, files intact:
 
 ```ts
 const sbx = await Sandbox.create({
@@ -64,17 +66,18 @@ const sbx = await Sandbox.create({
 Without it, `create` makes a fresh sandbox every time — faithful E2B
 semantics.
 
-## Timeouts are real
+## Timeouts work as E2B defines them
 
-`timeoutMs` and `setTimeout()` set an absolute deadline, exactly as E2B
-defines them: at the deadline the sandbox is killed, or — with
-`lifecycle: { onTimeout: 'pause' }` — parked, to be revived by `connect`.
-See [Sandbox lifecycle](/docs/lifecycle) for how deadlines interact with
+`timeoutMs` and `setTimeout()` set an absolute deadline: at the deadline
+the sandbox is killed, or — with `lifecycle: { onTimeout: 'pause' }` —
+paused, to be revived by `connect`. See
+[Sandbox lifecycle](/docs/lifecycle) for how deadlines interact with
 Dormice's own idle policy.
 
-## Version gating
+## What's implemented
 
 The daemon reports envd `0.6.1`, chosen so the SDK itself gates features
-client-side: everything at or below that version is implemented, and the
-few gaps above it are answered with an honest `unimplemented` on the wire
-— the full list is in [Capabilities & differences](/docs/e2b-differences).
+on the client side: everything at or below that version is implemented,
+and the few gaps above it are answered with an honest `unimplemented` on
+the wire. The full list is in
+[Capabilities & differences](/docs/e2b-differences).
diff --git a/website/content/docs/files.mdx b/website/content/docs/files.mdx
index e6e2c9c..b8519cc 100644
--- a/website/content/docs/files.mdx
+++ b/website/content/docs/files.mdx
@@ -1,28 +1,43 @@
 ---
 title: Moving files
-description: writeFile(s) and readFile(s) move files through JSON — 16 MiB per file, honest refusals past that, and streaming alternatives when you need more.
+description: Learn how to write and read files in a sandbox, from the SDK or the CLI — and what to do with files over the 16 MiB limit.
 ---
 
-Native file transfer is four verbs — write and read, each in a single and
-a batch form. All wake a cold sandbox first; paths are absolute, or
-relative to `/home/user`:
+## Write files
+
+You can write files into a sandbox with `writeFile` (one file) or
+`writeFiles` (a batch). Both wake a cold sandbox first; paths are
+absolute, or relative to `/home/user`:
 
 ```ts
 await client.writeFiles('my-agent', [
   { path: 'config.json', content: JSON.stringify(config) }, // string → UTF-8
   { path: 'data/input.bin', content: bytes },               // Uint8Array, as-is
 ]);
+
 await client.writeFile('my-agent', 'notes.md', '# one file, no array');
+```
+
+Parent directories are created as needed; existing files are
+overwritten.
 
+## Read files
+
+`readFile` reads one file; `readFiles` reads a batch, returned in
+request order:
+
+```ts
 const file = await client.readFile('my-agent', 'results/out.csv');
 const text = new TextDecoder().decode(file.content);
 
-// Batch read: request order, all or nothing.
 const files = await client.readFiles('my-agent', ['a.txt', 'b.txt']);
 ```
 
-Parent directories are created as needed; existing files are overwritten.
-The CLI moves single files:
+A missing file is a 404; a directory or other non-regular file is a 400.
+
+## Move files with the CLI
+
+`dor sandbox push` and `pull` move single files:
 
 ```sh
 dor sandbox push my-agent ./data.csv            # → /home/user/data.csv
@@ -31,47 +46,42 @@ dor sandbox pull my-agent results/out.csv out.csv
 dor sandbox pull my-agent results/out.csv       # no local path: raw bytes to stdout
 ```
 
-## A batch saves round-trips — it is not a transaction
-
-`writeFiles` writes in array order and fails fast: on an error, the files
-earlier in the array are already written. Splitting a big upload into
-several calls loses nothing — writes are per-file independent.
+## Size limits: 16 MiB per file
 
-`readFiles` is the opposite on purpose: **all or nothing**. One missing
-path fails the whole call with a 404 naming it — a batch read that
-silently dropped a file would be a corrupt project checkout. A caller that
-can tolerate absence asks file by file; the batch total is capped at
-48 MiB (413 past it).
+File content crosses the wire as base64 inside JSON, so each file is
+capped at 16 MiB, write and read alike. A `writeFiles` batch tops out at
+48 MiB of request body, and a `readFiles` batch at 48 MiB total.
 
-## The 16 MiB cap, and what to do past it
+Reading a file over the cap returns a **413 naming the file's actual
+size** — never a truncated file, which would just be a corrupt file.
 
-Content crosses the wire as base64 inside JSON and is buffered in daemon
-memory, so each file is capped at 16 MiB, write and read alike (a
-`writeFiles` batch tops out at 48 MiB of request body). The refusals are
-honest:
+For bigger files, use one of these instead:
 
-- Reading a file over the cap is a **413 naming the file's actual size** —
-  never a truncated file. Unlike exec output, where a capped log still
-  informs, a truncated file is simply a corrupt file.
-- Missing file: 404. A directory or other non-regular file: 400.
-
-Bigger files are not this protocol's job:
-
-- **Fetch from inside the sandbox.** `execCommand` with `curl` or `wget`
-  (both in the stock image) downloads at full speed without routing bytes
-  through the daemon's JSON layer.
-- **Use the E2B files surface.** `files.read` / `files.write` stream with
-  no artificial cap — the disk quota is the cap — and
-  `uploadUrl()` / `downloadUrl()` mint signed URLs a bare browser or curl
-  can use, no headers required. See
+- **Download from inside the sandbox.** Run `curl` or `wget` (both in
+  the stock image) with [`execCommand`](/docs/commands) — full speed, no
+  JSON layer in the path.
+- **Use the E2B files surface.** `files.read` / `files.write` stream
+  with no artificial cap — the disk quota is the cap — and
+  `uploadUrl()` / `downloadUrl()` mint signed URLs that a bare browser
+  or curl can use, no headers required. See
   [Using the official E2B SDKs](/docs/e2b-sdks).
 
-## Every byte moves through the container
-
-File verbs execute *inside* the sandbox, streamed through an in-container
-process — never as host-side writes into the disk image. The disk's
-contents belong to the sandbox, so a hostile symlink planted there must
-have nothing to escape to; resolved inside the container, it can only
-point at the container's own root. Ownership lands on the sandbox user
-(uid 1000) naturally. See [Architecture](/docs/architecture) for the
-boundary this preserves.
+## Batch behavior
+
+- **`writeFiles` fails fast, not atomically.** Files are written in
+  array order; on an error, the earlier files are already written.
+  Splitting a big upload into several calls loses nothing — writes are
+  independent per file.
+- **`readFiles` is all or nothing.** One missing path fails the whole
+  call with a 404 naming it — a batch read that silently dropped a file
+  would hand you a corrupt project checkout. If you can tolerate missing
+  files, read them one by one.
+
+## How file transfer works
+
+File operations execute *inside* the sandbox, streamed through an
+in-container process — never as host-side writes into the disk image.
+This means a hostile symlink planted in the sandbox can only point at
+the sandbox's own filesystem, and ownership lands on the sandbox user
+naturally. See [Architecture](/docs/architecture) for the boundary this
+preserves.
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
index c486854..3a9681a 100644
--- a/website/content/docs/http-api.mdx
+++ b/website/content/docs/http-api.mdx
@@ -3,10 +3,9 @@ title: HTTP API
 description: One RPC route per verb, plain JSON, Bearer auth — everything the SDK does, curl can do.
 ---
 
-The native API is deliberately boring: every operation is a `POST` to a
-camelCase verb route, input and output entirely in the JSON body, and the
-route name is identical to the SDK method name. There is nothing the SDK
-can do that `curl` cannot.
+Every operation is a `POST` to a camelCase verb route, with input and
+output entirely in the JSON body. The route name is identical to the SDK
+method name, so there is nothing the SDK can do that curl cannot:
 
 ```sh
 curl -X POST http://127.0.0.1:3676/acquireSandbox \
@@ -18,35 +17,37 @@ curl -X POST http://127.0.0.1:3676/acquireSandbox \
 Two rules cover the whole surface:
 
 - **Auth** is `Authorization: Bearer <token>` on every route except
-  `GET /healthz`, the open liveness probe (probes have no secrets — it
-  answers `{"status":"ok"}`).
+  `GET /healthz`, the open liveness probe (it answers
+  `{"status":"ok"}`).
 - **Every non-2xx body is `{ "message": "..." }`** — one error shape,
-  whoever produced the error. 4xx name your mistake; 5xx are the daemon's.
+  whoever produced the error. 4xx name your mistake; 5xx are the
+  daemon's.
 
 The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 `/e2b/*` with its own authentication — nothing below applies to it.
 
 ## The verbs
 
-| Route | Does | Refusals worth knowing |
+| Route | Does | Errors worth knowing |
 | --- | --- | --- |
 | `POST /acquireSandbox` | create, wake, or restore — idempotent per key | 400 invalid policy/unknown template, 429 at the sandbox limit |
 | `POST /listSandboxes` | every sandbox and its state; never wakes anything | — |
 | `POST /execCommand` | run a command, buffered | 404 unknown key, 409 archived/restoring |
 | `POST /writeFiles` | batch write, base64 in JSON | 404/409 as above; body over 48 MiB refused |
-| `POST /writeFile` | write one file — the single form of `writeFiles` | same refusals as `writeFiles` |
+| `POST /writeFile` | write one file — the single form of `writeFiles` | same as `writeFiles` |
 | `POST /readFile` | read one file, base64 out | 404 no such file, 400 not a file, 413 over 16 MiB (names the real size) |
 | `POST /readFiles` | batch read, all or nothing, request order | first bad path fails the whole batch; 413 over 48 MiB total |
 | `POST /rebuildSandbox` | swap container, keep `/home/user` | 404 unknown key, 409 archived/restoring |
-| `POST /destroySandbox` | destroy; idempotent | 409 mid-restore (the one dent — retry when it finishes) |
+| `POST /destroySandbox` | destroy; idempotent | 409 mid-restore — retry when it finishes |
 | `POST /registerTemplate` | upsert name → image | 400 `'base'` is reserved |
 | `POST /listTemplates` | every registered template | — |
 | `POST /removeTemplate` | unregister; idempotent | 409 while sandboxes still use it (names them) |
 | `POST /getHostMetrics` | host snapshot; never wakes anything | — |
 
-Use verbs (`execCommand`, files, `rebuildSandbox`) answer 404 for an
-unknown key rather than creating a sandbox as a side effect — an unknown
-key is more likely a typo than an intent. Only `acquireSandbox` creates.
+**Only `acquireSandbox` creates.** The use verbs (`execCommand`, files,
+`rebuildSandbox`) answer 404 for an unknown key rather than creating a
+sandbox as a side effect — an unknown key is more likely a typo than an
+intent.
 
 ## The sandbox object
 
@@ -61,13 +62,13 @@ Everything that returns a sandbox returns this shape:
 }
 ```
 
-`state` is one of `active | frozen | stopped | archived | restoring` (the
-[lifecycle ladder](/docs/lifecycle)). `acquireSandbox` wraps it in a
-union: `{ "status": "ready", "sandbox": … }`, or — when the sandbox is
+`state` is one of `active | frozen | stopped | archived | restoring`
+(the [lifecycle states](/docs/lifecycle)). `acquireSandbox` wraps it in
+a union: `{ "status": "ready", "sandbox": … }`, or — when the sandbox is
 coming back from S3 —
 `{ "status": "restoring", "sandbox": …, "progress": { "phase": "downloading" | "extracting", "percent": … } }`;
-poll acquire until it flips to `ready`
-([archiving](/docs/archiving)).
+poll acquire until it flips to `ready` (see
+[Archiving](/docs/archiving)).
 
 ## Commands and files on the wire
 
@@ -78,19 +79,18 @@ non-zero exit code is a result, not an HTTP error
 ([details](/docs/commands)).
 
 File content crosses the wire as base64 inside JSON: `writeFiles` takes
-`{ externalId, files: [{ path, contentBase64 }] }`, `readFile` takes
-`{ externalId, path }` and returns `{ path, contentBase64 }` with the path
-resolved absolute. Each has a twin for the other arity: `writeFile` writes
-one file without the array ceremony, `readFiles` reads a batch all or
-nothing — one missing path fails the whole call. Limits and refusal
-semantics: [moving files](/docs/files).
+`{ externalId, files: [{ path, contentBase64 }] }`; `readFile` takes
+`{ externalId, path }` and returns `{ path, contentBase64 }` with the
+path resolved absolute. Each has a twin for the other arity: `writeFile`
+writes one file without the array, `readFiles` reads a batch all or
+nothing. Limits and error semantics: [Moving files](/docs/files).
 
 ## Bring a patient HTTP client
 
 `execCommand`'s response headers arrive only when the command finishes —
 legally hours later. Many HTTP clients ship a hidden ~5-minute
-first-byte/header timeout (Node's undici does); the SDK disables it and
-enforces one deadline derived from `timeoutSeconds`. Rolling your own
-client, do the same, or a `sleep 310` dies at exactly 300 s with a
-connection error that looks like the daemon's fault. It isn't —
-measured, twice.
+wait-for-headers timeout (Node's undici does). The SDK disables it and
+enforces one deadline derived from `timeoutSeconds`; if you roll your
+own client, do the same — otherwise a `sleep 310` dies at exactly 300
+seconds with a connection error that looks like the daemon's fault. It
+isn't — measured, twice.
diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdx
index a58a2fb..9299718 100644
--- a/website/content/docs/index.mdx
+++ b/website/content/docs/index.mdx
@@ -1,45 +1,68 @@
 ---
 title: What is Dormice?
-description: A self-hosted sandbox platform for AI agents — one machine, sandboxes that live forever, idle costs nothing.
+description: Dormice is a self-hosted sandbox platform for AI agents — run it on your own machine and give every agent a secure, permanent sandbox.
 ---
 
-Cloud sandbox platforms charge for every second a sandbox exists, so their
-sandboxes are disposable. Dormice inverts that: you run it on a machine you
-already pay for, and sandboxes are **permanent** — they just get cheaper to
-keep the longer they sit idle.
-
-- **`acquireSandbox(externalId)` is the entire mental model.** Idempotent: the
-  same key always comes back to the same sandbox, whatever state it was in.
-  No sandbox → create; frozen → wake; stopped → start; archived → restore.
-- **Idle is free.** Sandboxes cool down on their own —
-  `active → frozen → stopped → archived` — one rung at a time, and any
-  acquire brings them back. Measured on real hardware: freezing takes an
-  idle sandbox holding 1 GiB down to ~5 MiB of resident memory, and waking
-  it takes ~50 ms.
-- **Deploys like a single binary.** One daemon, one SQLite ledger, one
+Dormice gives your AI agents isolated Linux sandboxes where they can
+safely run code, process data, and keep a long-lived workspace — on a
+machine you already own. You install one daemon; it manages the sandboxes
+for you.
+
+Start a sandbox and run a command in a few lines:
+
+```ts
+import { Dormice } from '@dormice/sdk';
+
+const client = new Dormice({
+  endpoint: 'http://127.0.0.1:3676',
+  token: process.env.DORMICE_API_TOKEN!,
+});
+
+await client.acquireSandbox('my-agent');
+const result = await client.execCommand('my-agent', 'echo "Hello from Dormice!"');
+console.log(result.stdout); // Hello from Dormice!
+```
+
+## Why Dormice
+
+- **Sandboxes are permanent.** Cloud sandbox platforms charge for every
+  second a sandbox exists, so their sandboxes are disposable. Dormice
+  inverts that: `acquireSandbox('my-agent')` always returns the same
+  sandbox for the same key — today, tomorrow, next month — with all its
+  files intact.
+- **Idle costs almost nothing.** Idle sandboxes cool down on their own
+  (`active → frozen → stopped → archived`), and any acquire brings them
+  back. Measured on real hardware: freezing takes an idle sandbox holding
+  1 GiB of memory down to ~5 MiB, and waking it takes ~50 ms.
+- **Deploys like a single binary.** One daemon, one SQLite database, one
   port. No Kubernetes, no external database.
-- **E2B compatible.** The official `e2b` SDKs — JavaScript and Python —
-  work against Dormice by changing two URLs — see
+- **Works with the official E2B SDKs.** The unmodified `e2b` packages
+  (JavaScript and Python) run against Dormice by changing two URLs — see
   [Using the official E2B SDKs](/docs/e2b-sdks).
 
 ## How it works
 
-The daemon keeps a SQLite ledger of sandboxes and drives Docker + gVisor to
-match it. Each sandbox is a gVisor container with its own disk-quota volume;
-freezing suspends its processes and squeezes their memory out to swap, so an
-idle sandbox costs a few megabytes of RAM and wakes in about 50 ms with all
-its processes still running.
-
-Because the disk — not the container — is the sandbox's body, a sandbox
-survives anything short of an explicit release: the daemon restarts, the
-host reboots, even `docker container prune` eating the container object.
+The daemon runs each sandbox as a Docker container under
+[gVisor](https://gvisor.dev), with its own disk. When a sandbox sits
+idle, the daemon suspends its processes and squeezes their memory out to
+swap — so it costs a few megabytes of RAM and wakes in about 50 ms,
+processes still running. The sandbox's data lives on its own disk, not in
+the container, so it survives daemon restarts, host reboots, and even the
+container being deleted. [Architecture](/docs/architecture) has the full
+picture.
 
 ## Status
 
-Early development. The daemon, its lifecycle engine, the SDK, the CLI, the
-web console, the real Docker + gVisor executor, and the E2B-compatible API
-work end to end and pass a black-box test suite against real
-infrastructure. Nothing here is ready for production yet.
+Early development. The daemon, SDK, CLI, web console, Docker + gVisor
+executor, and E2B-compatible API work end to end and pass a black-box
+test suite against real infrastructure. Nothing here is ready for
+production yet.
+
+## Next steps
 
-Next steps: [Installation](/docs/installation), then the
-[Quick start](/docs/quickstart).
+1. [Installation](/docs/installation) — set up the daemon on a Linux
+   host with one command.
+2. [Quick start](/docs/quickstart) — acquire your first sandbox and run
+   commands in it.
+3. [Using the official E2B SDKs](/docs/e2b-sdks) — if you already have
+   an E2B application, point it at Dormice.
diff --git a/website/content/docs/installation.mdx b/website/content/docs/installation.mdx
index 81a8ccb..7e0c149 100644
--- a/website/content/docs/installation.mdx
+++ b/website/content/docs/installation.mdx
@@ -1,68 +1,88 @@
 ---
 title: Installation
-description: One command on a bare Ubuntu/Debian x86_64 host.
+description: Install the Dormice daemon on a Linux host with one command.
 ---
 
-Run as root on a bare Ubuntu/Debian x86_64 host:
+## Install the daemon
+
+Run this as root on a bare Ubuntu/Debian x86_64 host:
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash
 ```
 
-Behind a slow connection to the usual sources, add `-s -- --mirror cn`.
+If your host has a slow connection to GitHub and the usual package
+sources, add `-s -- --mirror cn`.
+
+The installer sets up everything — Docker, gVisor, swap, the network
+hardening, the daemon as a systemd service — and finishes by running
+`dor doctor`, a battery of read-only checks that verifies the install
+actually works. You can re-run `dor doctor` at any time.
+
+**The installer is safe to re-run.** Running it again upgrades the code
+and repairs anything that drifted, and never rotates your API token.
+
+## Get your API token
+
+The installer generates an API token and stores it in the daemon's
+config file. You need it for every client — SDK, CLI, and console:
+
+```sh
+grep ^DORMICE_API_TOKEN /etc/dormice/env
+```
+
+## Connect from another machine
+
+The daemon listens on `127.0.0.1` only — reaching it from another
+machine is a choice you make explicitly, one of two ways.
+
+**Option 1: SSH tunnel** (private, zero setup):
+
+```sh
+ssh -L 3676:127.0.0.1:3676 root@your-host
+```
+
+Then use `http://127.0.0.1:3676` as your endpoint, as if the daemon were
+local.
 
-The installer is idempotent — re-running it upgrades the code and repairs
-drift, and never rotates your API token. It ends by running `dor doctor`, a
-battery of read-only checks — three of them boot a real gVisor container —
-that decides whether the install actually succeeded; `dor doctor` can be
-re-run on its own at any time.
+**Option 2: Reverse proxy** — serves the API, the E2B surface, and the
+web console at once. With Caddy, TLS certificates are automatic once you
+give it a domain:
+
+```text
+your-domain.example {
+	reverse_proxy 127.0.0.1:3676 {
+		flush_interval -1
+	}
+}
+```
+
+**Note:** `flush_interval -1` matters — streamed command output is
+written frame by frame, and a buffering proxy would hold it all back
+until the end. Use HTTPS for anything exposed beyond localhost: the API
+token and the session cookie travel in every request.
 
 ## What the host needs
 
-The daemon itself runs anywhere Node 22+ runs, with an in-memory fake
-executor for development. Running **real** sandboxes needs a Linux host —
-`install.sh` automates all of it and `dor doctor` verifies it, but these
-are the facts underneath:
-
-- **Docker + gVisor (`runsc`)**, and root (loop mounts, cgroup writes).
-- **Swap, and `vm.swappiness=100`.** Freezing squeezes an idle sandbox's
-  memory out to swap; gVisor holds sandbox memory as shared memory, which
-  the kernel refuses to swap at the default swappiness — measured on real
-  hardware: 0 bytes reclaimed at the default, 99.5% reclaimed at 100. Note
-  that some cloud images (Alibaba Cloud, for one) ship `vm.swappiness=0`;
-  check the *effective* value with `sysctl vm.swappiness`, not the config
-  files.
-- **Network hardening is not optional.** Sandboxes run untrusted code:
-  block the cloud metadata service from containers
+The installer handles all of this and `dor doctor` verifies it, but
+these are the requirements underneath:
+
+- **Docker + gVisor (`runsc`)**, and root — sandboxes are gVisor
+  containers, and the daemon needs loop mounts and cgroup writes.
+- **Swap, with `vm.swappiness=100`.** Freezing works by pushing idle
+  sandbox memory to swap. gVisor holds sandbox memory in a form the
+  kernel refuses to swap at the default setting — measured on real
+  hardware: 0 bytes reclaimed at the default, 99.5% reclaimed at 100.
+  Some cloud images (Alibaba Cloud, for one) ship `vm.swappiness=0`;
+  check the effective value with `sysctl vm.swappiness`.
+- **Network hardening.** Sandboxes run untrusted code, so the installer
+  blocks the cloud metadata service from containers
   (`iptables -I DOCKER-USER -d 169.254.0.0/16 -j DROP`, persisted) and
-  disable inter-container traffic (`"icc": false` in `daemon.json`). The
-  daemon binds to 127.0.0.1 only, by design without a knob; exposing it is
-  a reverse proxy's job.
-- **One machine, one daemon.** The daemon enforces this with a lock next
-  to its ledger and refuses to start when its ledger and the machine's
-  reality cannot belong together.
-
-## Reaching the daemon from outside
-
-The daemon listens on 127.0.0.1 only, so reaching it from another machine
-is a choice you make explicitly, one of two ways:
-
-- **SSH tunnel** (private, zero setup):
-  `ssh -L 3676:127.0.0.1:3676 root@host`, then use
-  `http://127.0.0.1:3676` as your endpoint.
-- **Reverse proxy** for the console, the API, and the E2B surface at once —
-  e.g. Caddy, which also handles TLS certificates automatically once you
-  give it a domain:
-
-  ```
-  your-domain.example {
-  	reverse_proxy 127.0.0.1:3676 {
-  		flush_interval -1
-  	}
-  }
-  ```
-
-  `flush_interval -1` matters: streamed command output is written frame by
-  frame, and a buffering proxy would turn it into one lump at the end.
-  Anything exposed beyond localhost should be HTTPS — the API token and
-  the session cookie travel in every request.
+  disables inter-container traffic (`"icc": false` in `daemon.json`).
+- **One machine, one daemon.** The daemon enforces this with a lock and
+  refuses to start when its database and the machine's reality don't
+  match.
+
+Without a prepared Linux host, the daemon still runs anywhere Node 22+
+runs using an in-memory fake executor — useful for development, not for
+real sandboxes.
diff --git a/website/content/docs/lifecycle.mdx b/website/content/docs/lifecycle.mdx
index d4796a6..746df8d 100644
--- a/website/content/docs/lifecycle.mdx
+++ b/website/content/docs/lifecycle.mdx
@@ -1,11 +1,11 @@
 ---
 title: Sandbox lifecycle
-description: Four states, three knobs — sandboxes cool down on their own, and any acquire brings them back.
+description: Idle sandboxes cool down through four states to save resources, and any acquire brings them back. Learn how to tune when that happens.
 ---
 
-A sandbox is always in one of four states. Idle time moves it down the
-ladder one rung at a time; `acquireSandbox` brings it back from any rung.
-The colder the state, the cheaper it is to keep — and the longer the wake.
+A sandbox is always in one of four states. The longer it sits idle, the
+colder — and cheaper — it gets, one step at a time. `acquireSandbox`
+brings it back from any state.
 
 ```text
 active ── idle ──▶ frozen ── idle ──▶ stopped ── idle ──▶ archived
@@ -13,71 +13,74 @@ active ── idle ──▶ frozen ── idle ──▶ stopped ── idle 
                     wakes in ~50 ms    cold start (seconds)  restore (download)
 ```
 
-- **active** — the container is running, normally.
-- **frozen** — every process is suspended mid-flight and its memory
-  squeezed out to swap. Measured on real hardware: an idle sandbox holding
-  1 GiB drops to about 5 MiB resident, and wakes in about 50 ms with all
-  its processes still running, exactly where they were.
-- **stopped** — the container is shut down; only the disk remains. Waking
-  is a cold start: a fresh boot from the surviving disk, seconds rather
-  than milliseconds. Processes do not survive this step — files do.
-- **archived** — the disk itself is packed with `tar` + `zstd` and shipped
-  to an S3-compatible bucket; nothing remains on the host. Only exists
-  when the archiver is configured (`DORMICE_S3_*`). Waking downloads and
-  unpacks; `acquireSandbox` reports `{ status: 'restoring', progress }`
-  immediately and flips to `ready` when the disk is back — a slow wake is
-  honest, never a silent hang.
-
-A background scanner sweeps the ledger every `DORMICE_SCAN_INTERVAL_SECONDS`
-(default 60) and demotes each idle sandbox at most one rung per sweep.
-
-## The three knobs
-
-Each sandbox carries a lifecycle policy — three thresholds, all counting
-seconds since the sandbox's last activity, all points on the same clock
-(hence the ordering rule freeze ≤ stop ≤ archive):
-
-| Knob | Default | `null` means |
-| --- | --- | --- |
-| `freezeAfterSeconds` | 10 minutes | — (freezing is always on) |
-| `stopAfterSeconds` | 3 days | never stop |
-| `archiveAfterSeconds` | 7 days when S3 is configured, otherwise never | never archive |
+## The four states
 
-Overrides are passed at acquire time and validated as a merged whole:
+- **active** — the container is running, normally.
+- **frozen** — every process is suspended and its memory pushed out to
+  swap. Measured on real hardware: an idle sandbox holding 1 GiB drops to
+  about 5 MiB of resident memory, and wakes in about 50 ms with all its
+  processes still running, exactly where they were.
+- **stopped** — the container is shut down; only the disk remains.
+  Waking is a cold start from the surviving disk — seconds rather than
+  milliseconds. Processes do not survive this step; files do.
+- **archived** — the disk is compressed and shipped to an S3-compatible
+  bucket; nothing remains on the host. This state only exists when you
+  [configure archiving](/docs/archiving). Waking downloads and unpacks
+  the disk, with real progress reporting.
+
+## Set the lifecycle policy
+
+Each sandbox carries three thresholds, all counting seconds since its
+last activity. Pass them when you create the sandbox:
 
 ```ts
 await client.acquireSandbox('my-agent', {
   policy: {
-    freezeAfterSeconds: 60,      // freeze aggressively
-    stopAfterSeconds: 7 * 86400, // a week to cold storage
+    freezeAfterSeconds: 60,      // freeze after 1 minute idle
+    stopAfterSeconds: 7 * 86400, // stop after a week idle
   },
 });
 ```
 
-Three rules worth knowing:
+| Knob | Default | `null` means |
+| --- | --- | --- |
+| `freezeAfterSeconds` | 10 minutes | — (freezing is always on) |
+| `stopAfterSeconds` | 3 days | never stop |
+| `archiveAfterSeconds` | 7 days when S3 is configured, otherwise never | never archive |
+
+Because all three count on the same clock, they must be ordered:
+freeze ≤ stop ≤ archive.
 
-- **Policy is fixed at creation.** An override sent while acquiring an
+**Good to know:**
+
+- **Policy is fixed at creation.** A policy sent while acquiring an
   *existing* sandbox is not applied — the sandbox keeps the policy it was
-  born with. (An invalid override is still rejected with a 400.)
-- **Archiving requires stopping.** Only a stopped sandbox can archive, so
-  `archiveAfterSeconds` needs a non-null `stopAfterSeconds` — and on a
-  daemon with no S3 configured, a policy asking to archive is refused
+  born with. (An invalid policy is still rejected with a 400.)
+- **Archiving requires stopping.** Only a stopped sandbox can archive,
+  so `archiveAfterSeconds` needs a non-null `stopAfterSeconds`. On a
+  daemon without S3 configured, a policy asking to archive is rejected
   outright rather than silently stored.
-- **Defaults yield to your explicit values.** Push `stopAfterSeconds`
-  past the 7-day archive default and the archive threshold follows it
-  instead of turning your legal override into an ordering error.
+- **Your explicit values win over defaults.** If you push
+  `stopAfterSeconds` past the 7-day archive default, the archive
+  threshold follows it instead of turning your valid setting into an
+  ordering error.
+
+A background scanner checks every `DORMICE_SCAN_INTERVAL_SECONDS`
+(default 60) and moves each idle sandbox down at most one state per
+sweep.
 
-## Resident agents: `stopAfterSeconds: null`
+## Keep a sandbox warm forever
 
-The setting for a long-lived agent's sandbox:
+For a long-lived agent's sandbox, set `stopAfterSeconds: null`:
 
 ```ts
 await client.acquireSandbox('my-agent', { policy: { stopAfterSeconds: null } });
 ```
 
-It parks at **frozen** forever — memory in swap, a few MiB of RAM, ~50 ms
-from any touch — and never decays to a cold boot. Its processes are never
-killed by idleness; they suspend and resume mid-flight, indefinitely.
+The sandbox parks at **frozen** when idle — a few MiB of RAM, ~50 ms to
+wake — and never decays to a cold start. Its processes are never killed
+by idleness; they suspend and resume mid-flight, indefinitely. See
+[Resident agents](/docs/resident-agents) for the full pattern.
 
 ## What counts as activity
 
@@ -85,15 +88,15 @@ Running commands, file operations, and `acquireSandbox` reset the idle
 clock. A long-running command keeps its sandbox alive for as long as it
 runs.
 
-Observation deliberately does not count: `listSandboxes`, sandbox metrics,
-and the console's list and detail views never wake a frozen sandbox and
-never reset its clock. Watching is free — using is what keeps a sandbox
-warm.
+Observation deliberately does not count: `listSandboxes`, sandbox
+metrics, and the console's list and detail views never wake a frozen
+sandbox and never reset its clock. You can watch a whole fleet from a
+dashboard without keeping anything warm.
 
-## E2B deadlines are a separate clock
+## E2B timeouts are a separate clock
 
 Sandboxes created through the [E2B surface](/docs/e2b-sdks) additionally
-carry an absolute deadline (`timeoutMs`), because E2B semantics demand
+carry an absolute deadline (`timeoutMs`), because E2B semantics require
 one: at the deadline the sandbox is killed — or parked, with
 `lifecycle: { onTimeout: 'pause' }`. Activity does not extend a deadline;
 only `create`, `connect`, and `setTimeout()` do. The deadline rule runs
diff --git a/website/content/docs/llms.mdx b/website/content/docs/llms.mdx
index 7508796..e3f11ee 100644
--- a/website/content/docs/llms.mdx
+++ b/website/content/docs/llms.mdx
@@ -1,6 +1,6 @@
 ---
 title: AI-readable docs
-description: llms.txt, llms-full.txt and a markdown twin of every page — plus an installable skill that teaches a coding agent to drive Dormice.
+description: Fetch these docs as plain markdown via llms.txt, or install an agent skill that teaches a coding agent to drive Dormice.
 ---
 
 Dormice's users are agents, so the documentation ships in forms an agent
@@ -8,10 +8,11 @@ can consume directly — no HTML scraping.
 
 ## llms.txt and markdown pages
 
-Following the [llms.txt convention](https://llmstxt.org), the site serves:
+Following the [llms.txt convention](https://llmstxt.org), the site
+serves:
 
 - **`/llms.txt`** — an index of every docs page with its one-line
-  description, grouped exactly like the sidebar.
+  description, grouped like the sidebar.
 - **`/llms-full.txt`** — the entire documentation concatenated into one
   markdown file, for tools that prefer a single fetch.
 - **A `.md` twin of every page** — append `.md` to any docs path
@@ -21,12 +22,12 @@ Following the [llms.txt convention](https://llmstxt.org), the site serves:
 All three are generated from the same sources as the pages you are
 reading, in the same build — they cannot drift.
 
-## The agent skill
+## Install the agent skill
 
 A skill in the open [Agent Skills](https://skills.sh) format teaches a
 coding agent the whole operating surface — connecting, choosing between
-the E2B SDKs, the native API and the CLI, running commands, moving files,
-setting lifecycle policy, and the gotchas:
+the E2B SDKs, the native API and the CLI, running commands, moving
+files, setting lifecycle policy, and the gotchas:
 
 ```sh
 npx skills add BitMiracle-AI/Dormice
diff --git a/website/content/docs/metrics.mdx b/website/content/docs/metrics.mdx
index ac71e2c..2d0cc55 100644
--- a/website/content/docs/metrics.mdx
+++ b/website/content/docs/metrics.mdx
@@ -1,22 +1,21 @@
 ---
 title: Metrics
-description: Two observation windows — one per sandbox, one for the host — and neither ever wakes anything.
+description: Learn how to read live metrics for a sandbox and for the host — without ever waking anything.
 ---
 
-Dormice ships observation windows, deliberately not a monitoring system:
-each call answers "how are things *right now*" with a single snapshot.
-For history, trends, and alerting, point a real monitoring stack at the
-box.
+Dormice answers "how are things *right now*" with single snapshots —
+deliberately not a monitoring system. For history, trends, and alerting,
+point a real monitoring stack at the box.
 
-One rule governs both windows: **observation never wakes a sandbox and
+One rule governs all metrics: **observation never wakes a sandbox and
 never resets its idle clock** — the same principle as listing
 ([what counts as activity](/docs/lifecycle#what-counts-as-activity)).
-Watching a fleet of frozen sandboxes from a dashboard keeps them exactly
-as cheap as ignoring them.
+You can watch a fleet of frozen sandboxes from a dashboard and they stay
+exactly as cheap as if you ignored them.
 
-## Per sandbox: `getMetrics()` (E2B surface)
+## Get metrics for one sandbox
 
-The official SDK's `getMetrics()` returns an array with one live sample —
+The E2B SDK's `getMetrics()` returns an array with one live sample —
 CPU count and usage, memory, and disk:
 
 ```ts
@@ -27,46 +26,41 @@ m.diskUsed; // real occupancy of the sandbox's disk
 m.diskTotal;
 ```
 
-- A **frozen** sandbox is readable without waking it — its resource
-  accounting is still there, and reading is not activity.
-- A **stopped** sandbox answers an empty array: no container, honestly no
-  sample — never zeros pretending to be measurements.
+- A **frozen** sandbox is readable without waking it.
+- A **stopped** sandbox answers an empty array: no container, honestly
+  no sample — never zeros pretending to be measurements.
 - The SDK's `start` / `end` range parameters are accepted and ignored —
-  there is no metrics history to query, only now.
+  there is no metrics history, only now.
 
-## The host: `getHostMetrics()` (native surface)
+## Get metrics for the host
 
-The operator's question — *is this machine okay, and what do the
-sandboxes collectively cost it?* — in one call:
+The native `getHostMetrics()` answers the operator's question — is this
+machine okay, and what do the sandboxes collectively cost it?
 
 ```ts
 const m = await client.getHostMetrics();
 ```
 
-Four sections:
+The snapshot has four sections:
 
-- **`host`** — CPU (computed as the delta between your calls, so the
-  first call after a daemon start honestly answers `null` rather than a
-  made-up zero), memory as `MemAvailable` (what could still be allocated
-  without swapping — the naive "free" number cries wolf on any healthy
-  Linux box), and **swap**, which is the freeze mechanism's fuel: frozen
-  sandboxes live there, and a full swap means "idle is free" stops being
-  true. `swap.totalBytes: 0` is a real reading of a machine with no swap
-  configured; `null` means the platform offers no reading at all.
-- **`dataDisk`** — the filesystem holding `DORMICE_DATA_DIR`, where
-  sandbox disks live. This is the real capacity ceiling: past it, even
-  the ledger cannot write.
-- **`sandboxes`** — ledger aggregates: total, the `DORMICE_MAX_SANDBOXES`
-  cap, and a count per lifecycle state.
-- **`sandboxDisks`** — what the sparse disk images *promise* (nominal)
-  versus what they *occupy* (actual). The gap is your disk overcommit,
-  and this number is its only cap — nothing else stops a hundred 10 GB
-  promises on a 200 GB disk, which is fine exactly as long as you watch
-  it. Measured on the test host: a sandbox promising 10 GiB actually
-  occupied 68 MiB.
+| Section | What it tells you |
+| --- | --- |
+| `host` | CPU usage, available memory, and **swap** — the freeze mechanism's fuel. Frozen sandboxes live in swap; a full swap means "idle is free" is ending. |
+| `dataDisk` | The filesystem holding sandbox disks (`DORMICE_DATA_DIR`). This is the real capacity ceiling: past full, even the daemon's database cannot write. |
+| `sandboxes` | Totals from the daemon's records: sandbox count, the `DORMICE_MAX_SANDBOXES` cap, and a count per lifecycle state. |
+| `sandboxDisks` | What the sparse disk images *promise* (nominal) versus what they *occupy* (actual). The gap is your disk overcommit — watch it, because nothing else caps it. Measured on the test host: a sandbox promising 10 GiB actually occupied 68 MiB. |
+
+**Readings are honest about their limits:**
+
+- CPU usage is computed as the delta between your calls, so the first
+  call after a daemon start answers `null` rather than a made-up zero.
+- Memory is reported as `MemAvailable` — what could still be allocated
+  without swapping. (The naive "free" number is misleadingly low on any
+  healthy Linux box.)
+- `swap.totalBytes: 0` is a real reading of a machine with no swap;
+  `null` means the platform offers no reading at all.
 
 The web console's Overview page renders exactly this snapshot — CPU,
-memory, swap, and the data disk side by side, sandbox states, and the
-overcommit meter — refreshed every few seconds. Readings a platform
-cannot produce come back `null`, never invented; the console shows an
-amber hint (pointing at `dor doctor`) instead of a fake number.
+memory, swap, the data disk, sandbox states, and the overcommit meter —
+refreshed every few seconds. Readings a platform cannot produce show as
+an amber hint pointing at `dor doctor`, never a fake number.
diff --git a/website/content/docs/persistence.mdx b/website/content/docs/persistence.mdx
index e22f60e..be806b6 100644
--- a/website/content/docs/persistence.mdx
+++ b/website/content/docs/persistence.mdx
@@ -1,16 +1,16 @@
 ---
-title: The disk is the sandbox
-description: /home/user lives on its own disk, and that disk — not the container — is what Dormice keeps alive.
+title: Sandbox persistence
+description: Everything under /home/user survives freezes, stops, restarts, and archiving. Learn what persists, what doesn't, and how rebuilds work.
 ---
 
-Every sandbox owns a disk: a sparse image file on the host
-(`DORMICE_SANDBOX_DISK_GB`, default 10 GB), formatted ext4 and mounted at
-`/home/user`. The container around it is a shell — replaceable machinery.
-That gives Dormice one contract worth memorizing:
+Every sandbox owns a disk: an image file on the host
+(`DORMICE_SANDBOX_DISK_GB`, default 10 GB) mounted at `/home/user`. The
+container around it is replaceable machinery. That gives you one rule to
+remember:
 
-> **What lives in `/home/user` survives everything short of an explicit
-> release. Everything outside it is container state, and containers may
-> vanish at any time.**
+> **What lives in `/home/user` survives everything short of destroying
+> the sandbox. Everything outside it is container state, and containers
+> may be replaced at any time.**
 
 ## What survives
 
@@ -19,52 +19,57 @@ gVisor host:
 
 - **Freeze / stop / wake cycles** — files ride through every lifecycle
   transition.
-- **The daemon restarting, the host rebooting** — the daemon reconciles
-  its ledger against reality at boot, and the next wake re-attaches the
-  disk (a reboot drops loop mounts; starting a sandbox repairs its own).
-- **`docker container prune`** eating the container object — a stopped
-  sandbox is an exited container plus a disk, and prune eats exited
-  containers. The next acquire rebuilds a container *from the surviving
-  disk*: same sandbox ID, `/home/user` intact.
+- **Daemon restarts and host reboots** — the daemon checks its records
+  against reality at boot, and the next wake re-attaches the disk.
+- **`docker container prune`** deleting the container — the next acquire
+  builds a fresh container from the surviving disk: same sandbox ID,
+  `/home/user` intact.
 - **Out-of-memory** — a sandbox that hits its memory cap
-  (`DORMICE_SANDBOX_MEMORY_GB`, default 2 GB) is killed as a whole by
-  gVisor, exit code 137. The reconciler records it stopped; the same key
-  acquires it right back, files intact.
-- **Archive → restore** — the disk round-trips through S3 as a
-  `tar.zst` and comes back byte-for-byte.
+  (`DORMICE_SANDBOX_MEMORY_GB`, default 2 GB) is killed by gVisor with
+  exit code 137 and recorded as stopped. The same key acquires it right
+  back, files intact.
+- **Archive → restore** — the disk round-trips through S3 and comes
+  back byte-for-byte.
 
 ## What does not
 
 - **`destroySandbox`** — the only verb that loses data, by design.
-- **Everything outside `/home/user`** whenever the container is replaced
-  (rebuild, prune, OOM): `/tmp`, packages installed at runtime outside the
-  home directory, running processes. If it matters, keep it in
-  `/home/user`.
+- **Everything outside `/home/user`**, whenever the container is
+  replaced (rebuild, prune, OOM): `/tmp`, packages installed at runtime
+  outside the home directory, running processes. If it matters, keep it
+  in `/home/user`.
 
-## The quota is physical
+## Rebuild a sandbox
 
-The disk file is simply that big. A sandbox that fills its disk gets
-`ENOSPC` from its own filesystem — there is no accounting layer to game,
-and the host's disk stays healthy. The image is sparse: a 10 GB promise
-occupies only what has actually been written, so disk is overcommitted by
-default and `getHostMetrics` reports both the promised and the real total.
+You can replace a sandbox's container while keeping its disk — with the
+SDK (`rebuildSandbox`), the CLI, or the console's Rebuild button:
 
-## Rebuild: new shell, same body
+```sh
+dor sandbox rebuild my-agent
+```
 
-`rebuildSandbox` (SDK), `dor sandbox rebuild` (CLI), or the Rebuild button
-in the console tears the container down — in any state — and keeps the
-disk. The next wake builds a fresh container from the daemon's *current*
-base image (or the sandbox's template's current image), with `/home/user`
+The next wake builds a fresh container from the daemon's *current* base
+image (or the sandbox's template's current image), with `/home/user`
 carried over untouched.
 
-That makes rebuild the upgrade path: update the image, re-register the
-template, rebuild the sandbox — its files never move. Rebuild deliberately
-does not wake the sandbox afterwards; the cold start bills to whoever
-actually comes back for it.
+This is the upgrade path: update the image, re-register the
+[template](/docs/templates), rebuild the sandbox — its files never move.
+Rebuild does not wake the sandbox afterwards; it starts cold on its next
+use.
 
-## Restore is also an upgrade
+## Restores upgrade too
 
-An archived sandbox's restore builds a **new** disk at the current
-`DORMICE_SANDBOX_DISK_GB` and unpacks into it, then boots from the current
-image. Grow the disk setting while a sandbox sits in the bucket and it
-comes back bigger — for free.
+When an [archived](/docs/archiving) sandbox is restored, Dormice builds
+a **new** disk at the current `DORMICE_SANDBOX_DISK_GB` setting, unpacks
+into it, and boots from the current image. Grow the disk setting while a
+sandbox sits in the bucket and it comes back bigger — for free.
+
+## How the disk quota works
+
+The quota is physical: the disk image file is simply that big. A sandbox
+that fills its disk gets `ENOSPC` from its own filesystem — there is no
+accounting layer to game, and the host's disk stays healthy. The image
+is sparse, so a 10 GB promise occupies only what has actually been
+written; disk is overcommitted by default, and
+[`getHostMetrics`](/docs/metrics) reports both the promised and the real
+total so you can watch it.
diff --git a/website/content/docs/ports.mdx b/website/content/docs/ports.mdx
index db72c98..2ddc593 100644
--- a/website/content/docs/ports.mdx
+++ b/website/content/docs/ports.mdx
@@ -1,47 +1,24 @@
 ---
 title: Exposing ports
-description: getHost(port) preview URLs — a transparent proxy with wake-on-traffic, behind one wildcard domain you control.
+description: Learn how to reach a server running inside a sandbox from the outside, through preview URLs that wake the sandbox on traffic.
 ---
 
-Anything listening on a port inside a sandbox — a dev server, a notebook,
-an agent's UI — can be reached from outside through the daemon's sandbox
-proxy. Switch it on with one variable:
+Anything listening on a port inside a sandbox — a dev server, a
+notebook, an agent's UI — can be reached from outside through the
+daemon's sandbox proxy.
 
-```sh
-DORMICE_SANDBOX_DOMAIN=sbx.example.com
-```
-
-and the E2B SDK's `getHost()` does the rest:
+## 1. Set the sandbox domain
 
-```ts
-const sbx = await Sandbox.create({ /* the two URLs + apiKey */ });
-await sbx.commands.run('python3 -m http.server 8000', { background: true });
+Pick a domain for sandbox traffic and tell the daemon about it:
 
-const host = sbx.getHost(8000); // '8000-<sandboxId>.sbx.example.com'
-await fetch(`https://${host}/`);
+```sh
+DORMICE_SANDBOX_DOMAIN=sbx.example.com
 ```
 
-Requests arriving with such a `Host` header are proxied straight into the
-sandbox — headers untouched, WebSocket upgrades passed through both ways.
-Verified on real hardware: a `python3 -m http.server` inside a gVisor
-sandbox answers 200 through the proxy. If nothing listens on the port,
-the proxy answers an honest **502 naming the port**, not a hang.
-
-Unset, the feature is honestly absent: responses carry no domain and the
-SDK has nothing to build URLs from.
-
-## Wake-on-traffic
-
-A frozen sandbox is woken by the first proxied request — ~50 ms,
-invisible to the caller — so a preview URL keeps working against a
-sandbox nobody has touched in days. While a proxied connection stays
-open, the sandbox counts as active; when the last one closes, the idle
-clock resumes.
-
-## The ops recipe
+## 2. Point DNS and a reverse proxy at the host
 
-The daemon itself only ever binds `127.0.0.1`. The internet-facing half
-is one wildcard DNS record plus a reverse proxy that terminates TLS:
+The daemon itself only binds `127.0.0.1`. The internet-facing half is
+one wildcard DNS record plus a reverse proxy that terminates TLS:
 
 ```text
 *.sbx.example.com → your host
@@ -54,16 +31,42 @@ is one wildcard DNS record plus a reverse proxy that terminates TLS:
 }
 ```
 
-`flush_interval -1` keeps streaming responses unbuffered — verified with
-a real terminal session through Caddy: output arrived while the stream
-was still open. (A wildcard certificate needs Caddy's DNS challenge; a
-plain HTTP setup works for a LAN.)
+**Note:** `flush_interval -1` keeps streaming responses unbuffered —
+verified with a real terminal session through Caddy. A wildcard
+certificate needs Caddy's DNS challenge; plain HTTP works for a LAN.
+
+## 3. Get the URL with `getHost()`
+
+The E2B SDK's `getHost(port)` builds the preview URL:
+
+```ts
+const sbx = await Sandbox.create({ /* the two URLs + apiKey */ });
+await sbx.commands.run('python3 -m http.server 8000', { background: true });
+
+const host = sbx.getHost(8000); // '8000-<sandboxId>.sbx.example.com'
+await fetch(`https://${host}/`);
+```
+
+Requests arriving with such a `Host` header are proxied straight into
+the sandbox — headers untouched, WebSocket upgrades passed through both
+ways. If nothing listens on the port, the proxy answers a 502 naming the
+port, not a hang.
+
+If `DORMICE_SANDBOX_DOMAIN` is unset, the feature is off: responses
+carry no domain and the SDK has nothing to build URLs from.
+
+## Frozen sandboxes wake on traffic
+
+The first proxied request wakes a frozen sandbox — ~50 ms, invisible to
+the caller — so a preview URL keeps working against a sandbox nobody has
+touched in days. While a proxied connection stays open, the sandbox
+counts as active; when the last one closes, the idle clock resumes.
 
-## No authentication, on purpose
+## Preview URLs are public
 
 Preview URLs are unauthenticated — the same call E2B made, because these
-URLs exist to be opened in browsers. The sandbox ID in the hostname is
-unguessable (a UUID), but that is obscurity, not access control: treat a
-preview URL as public while the port is open. Everything else on the
-daemon — native API, E2B API, console — stays authenticated; only sandbox
-port traffic passes free.
+URLs exist to be opened in browsers and shared. The sandbox ID in the
+hostname is unguessable (a UUID), but that is obscurity, not access
+control: **treat a preview URL as public while the port is open.**
+Everything else on the daemon — native API, E2B API, console — stays
+authenticated; only sandbox port traffic passes free.
diff --git a/website/content/docs/quickstart.mdx b/website/content/docs/quickstart.mdx
index a7a3edd..a774950 100644
--- a/website/content/docs/quickstart.mdx
+++ b/website/content/docs/quickstart.mdx
@@ -1,10 +1,26 @@
 ---
 title: Quick start
-description: Acquire a sandbox, run commands, move files — with the SDK, curl, or the CLI.
+description: This guide shows you how to acquire your first sandbox, run commands in it, and write files — with the SDK, curl, or the CLI.
 ---
 
-`@dormice/sdk` is the native TypeScript client. (Not on npm yet — the
-first release is queued; inside the repo, `pnpm build` produces it.)
+## 1. Set your environment variables
+
+You need the daemon's address and its API token
+(from [Installation](/docs/installation)):
+
+```sh
+export DORMICE_ENDPOINT=http://127.0.0.1:3676
+export DORMICE_API_TOKEN=<your token>  # on the daemon host: grep ^DORMICE_API_TOKEN /etc/dormice/env
+```
+
+## 2. Get the SDK
+
+`@dormice/sdk` is the native TypeScript client. It is not on npm yet —
+the first release is queued. Inside the repo, `pnpm build` produces it;
+or skip the SDK entirely and use [curl](#use-curl-instead) or the
+[CLI](#use-the-cli-instead) below.
+
+## 3. Acquire a sandbox and run commands
 
 ```ts
 import { Dormice } from '@dormice/sdk';
@@ -29,12 +45,15 @@ await client.writeFiles('my-agent', [
 await client.destroySandbox('my-agent'); // destroy — the only verb that loses data
 ```
 
-## The wire is plain HTTP
+That's the whole loop: `acquireSandbox` is idempotent (the same key
+always returns the same sandbox, whatever state it was in), commands run
+inside the sandbox, files persist until you destroy it.
+
+## Use curl instead
 
-Every operation is an RPC route named after the SDK method
-(`POST /acquireSandbox`, `POST /execCommand`, …), authenticated with
-`Authorization: Bearer` and your API token, so `curl` works where the SDK
-doesn't reach:
+Every operation is a plain HTTP RPC route named after the SDK method
+(`POST /acquireSandbox`, `POST /execCommand`, …), authenticated with a
+Bearer token — so curl works anywhere the SDK doesn't reach:
 
 ```sh
 curl -X POST http://127.0.0.1:3676/listSandboxes \
@@ -42,11 +61,12 @@ curl -X POST http://127.0.0.1:3676/listSandboxes \
   -H "content-type: application/json" -d '{}'
 ```
 
-## The CLI
+The full wire surface is in the [HTTP API reference](/docs/http-api).
+
+## Use the CLI instead
 
-The `dor` command (long form: `dormice`) covers the operator side. It
-connects with the `DORMICE_ENDPOINT` and `DORMICE_API_TOKEN` environment
-variables:
+The `dor` command (long form: `dormice`) covers the same ground from a
+shell. It connects with the two environment variables from step 1:
 
 ```sh
 dor sandbox ls                        # every sandbox, with lifecycle state
@@ -57,3 +77,12 @@ dor sandbox rebuild my-agent          # fresh container, /home/user kept
 dor sandbox destroy my-agent          # destroy
 dor doctor                            # can this machine run sandboxes?
 ```
+
+## Next steps
+
+- [Sandbox lifecycle](/docs/lifecycle) — how sandboxes cool down when
+  idle, and how to tune it.
+- [Running commands](/docs/commands) — timeouts, working directory,
+  environment variables.
+- [Moving files](/docs/files) — reading and writing files, and the
+  size limits.
diff --git a/website/content/docs/resident-agents.mdx b/website/content/docs/resident-agents.mdx
index cfaeba4..0dcf46e 100644
--- a/website/content/docs/resident-agents.mdx
+++ b/website/content/docs/resident-agents.mdx
@@ -1,11 +1,13 @@
 ---
 title: Resident agents
-description: One permanent sandbox per agent — frozen to a few MiB when idle, awake in ~50 ms, never a cold start.
+description: Give every agent a permanent sandbox that costs a few MiB while idle and wakes in ~50 ms — the pattern Dormice was built for.
 ---
 
-The pattern Dormice was built for: give every agent (or user, or project)
-a permanent sandbox keyed by its own ID, and let the lifecycle engine
-make the idle time free.
+The pattern Dormice was built for: give every agent (or user, or
+project) a permanent sandbox keyed by its own ID, and let the lifecycle
+engine make the idle time nearly free.
+
+## Give each agent a permanent sandbox
 
 ```ts
 const res = await client.acquireSandbox(`agent-${userId}`, {
@@ -13,13 +15,13 @@ const res = await client.acquireSandbox(`agent-${userId}`, {
 });
 ```
 
-`stopAfterSeconds: null` pins the sandbox to the top two rungs of the
-[lifecycle](/docs/lifecycle): idle, it freezes — measured on real
-hardware, ~1 GiB of resident memory squeezed to ~5 MiB — and any touch
+`stopAfterSeconds: null` keeps the sandbox in the top two states of the
+[lifecycle](/docs/lifecycle): when idle it freezes — measured on real
+hardware, ~1 GiB of resident memory drops to ~5 MiB — and any touch
 wakes it in about 50 ms. It never decays to a seconds-long cold start.
 
 Every later `acquireSandbox` with the same key — tomorrow, next month —
-comes back to the same sandbox: same files, same installed packages, same
+returns the same sandbox: same files, same installed packages, same
 processes. A runnable version of this pattern lives at
 [`examples/resident-agent.mjs`](https://github.com/BitMiracle-AI/Dormice/blob/main/examples/resident-agent.mjs).
 
@@ -30,31 +32,33 @@ they were: a REPL keeps its state, a dev server its sockets, an agent
 process its memory. Nothing running in a resident sandbox is ever killed
 by idleness.
 
-The flip side, stated honestly: a background process does not *keep* its
-sandbox warm. Once the streams watching it disconnect, the idle clock
-runs, the scanner freezes the sandbox, and the process suspends with it —
-to continue, mid-instruction, on the next touch. A resident sandbox is
-not a way to run an unattended 24×7 workload; it is a way to make "ready
-whenever the agent returns" cost a few MiB.
+**The flip side:** a background process does not *keep* its sandbox
+warm. Once nothing is watching it, the idle clock runs, the sandbox
+freezes, and the process suspends with it — to continue, mid-instruction,
+on the next touch. A resident sandbox is not a way to run an unattended
+24×7 workload; it is a way to make "ready whenever the agent returns"
+cost a few MiB.
+
+## What an idle sandbox costs
 
-## What a sandbox costs while frozen
+A frozen sandbox costs a few MiB of resident memory (the rest sits in
+swap), plus a sparse disk that occupies only what was actually written.
+That is the entire idle bill — which is why one modest machine can hold
+a long tail of dormant agents.
 
-A few MiB of resident memory (the rest sits in swap), plus a sparse disk
-that occupies only what was actually written. That is the entire idle
-bill — which is why one modest machine can hold a long tail of dormant
-agents. If even frozen is too warm, leave `stopAfterSeconds` set and let
+If even frozen is too warm, leave `stopAfterSeconds` set and let
 sandboxes fall to stopped (disk only, cold start in seconds) or
 [archived](/docs/archiving) (S3 only, nothing on the host).
 
-## What the stock image ships
+## What the default image ships
 
 Sandboxes boot from the image `install.sh` builds
 ([`images/Dockerfile`](https://github.com/BitMiracle-AI/Dormice/blob/main/images/Dockerfile)):
-Ubuntu 24.04 with Python 3.12 (`pip install` works — the PEP 668 guard is
-removed), Node.js 24 (sha256-pinned), git, ripgrep, jq, curl/wget, and a
-version-pinned [Claude Code](https://claude.com/claude-code) — so a coding
-agent can start working in its sandbox with zero setup. Everything runs
-as a non-root user (uid 1000) inside gVisor.
+Ubuntu 24.04 with Python 3.12 (`pip install` works out of the box),
+Node.js 24, git, ripgrep, jq, curl/wget, and a version-pinned
+[Claude Code](https://claude.com/claude-code) — so a coding agent can
+start working with zero setup. Everything runs as a non-root user inside
+gVisor.
 
 Need more? Bake it into a [template](/docs/templates) instead of
 reinstalling per sandbox — and remember that whatever an agent installs
diff --git a/website/content/docs/templates.mdx b/website/content/docs/templates.mdx
index ba72d71..00084d6 100644
--- a/website/content/docs/templates.mdx
+++ b/website/content/docs/templates.mdx
@@ -1,20 +1,25 @@
 ---
 title: Templates
-description: A template is a named Docker image — build it with docker, register the name, and both APIs create sandboxes from it.
+description: Learn how to create sandboxes from your own Docker images by registering them as templates.
 ---
 
-Dormice deliberately has no template build pipeline. The host's Docker
-daemon is already an image store and `docker build` is already the build
-tool — a template is just a **name pointing at an image**, recorded in
-the ledger:
+A template is a name pointing at a Docker image. Dormice deliberately
+has no build pipeline — the host's Docker daemon is already an image
+store, and `docker build` is already the build tool.
+
+## Create a template
+
+Build an image (any way you like) and register its name:
 
 ```sh
-docker build -t my-agent-env:v1 .        # any image, built anywhere
+docker build -t my-agent-env:v1 .
 dor template add my-agent-env my-agent-env:v1
 dor template ls
 ```
 
-Create sandboxes from it on either surface:
+## Create sandboxes from a template
+
+Both API surfaces accept a template name at creation:
 
 ```ts
 // Native: a creation-time option, like policy
@@ -27,47 +32,53 @@ const sbx = await Sandbox.create('my-agent-env', { /* the two URLs + apiKey */ }
 An unknown template name is refused — 400 natively, 404 through the E2B
 surface — never silently substituted with the base image.
 
-## Names resolve late — that is the upgrade mechanism
+## Update a template
 
-A sandbox's ledger row records the template *name*, not the image behind
-it. Every time a container is built — waking from stopped, a rebuild, a
-restore from archive — the name resolves to the template's **current**
-image. So upgrading is three commands:
+Re-registering a name points it at a new image. Sandboxes pick up the
+new image the next time their container is built — on a rebuild, a cold
+start, or a restore from archive:
 
 ```sh
 docker build -t my-agent-env:v2 .
 dor template add my-agent-env my-agent-env:v2  # re-registering re-points the name
-dor sandbox rebuild user-42                    # per sandbox: new shell, same /home/user
+dor sandbox rebuild user-42                    # per sandbox: new container, same /home/user
 ```
 
 Until rebuilt (or cold-started), existing sandboxes keep running the
 image they were born on. Through a rebuild, `/home/user` carries over
 untouched and everything outside it resets onto the new image — see
-[Rebuild: new shell, same body](/docs/persistence#rebuild-new-shell-same-body).
+[Rebuild a sandbox](/docs/persistence#rebuild-a-sandbox).
+
+## Remove a template
+
+```sh
+dor template rm my-agent-env
+```
+
+Removing a template that sandboxes still use is refused with a 409
+naming a sandbox. Removing an unknown name is a no-op, and removing a
+registration never removes the image itself.
+
+## Image requirements
+
+Sandboxes mount their own disk over `/home/user`, so a template must
+install its tools into image paths (`/opt`, `/usr/local`) — anything
+baked under `/home/user` is hidden at runtime. The stock image's
+[`Dockerfile`](https://github.com/BitMiracle-AI/Dormice/blob/main/images/Dockerfile)
+is the reference: layers ordered by change frequency, tools outside the
+home directory, non-root user at uid 1000.
 
-## Rules and edge cases
+## Good to know
 
 - **Registration is configuration.** The image is not checked for
-  existence — register first, build later, if you like. If it is still
-  missing when a sandbox needs it, creation fails with a named error
+  existence when you register — register first, build later, if you
+  like. If it is still missing when a sandbox needs it, creation fails
+  with a named error
   (`image X is not on this host — docker pull or build it, then retry`).
 - **`base` is reserved.** Through the E2B surface, `Sandbox.create()`
-  with no template argument sends the string `base`, which means the
-  daemon's base image; the name cannot be registered.
-- **A referenced template cannot be removed.** `dor template rm` answers
-  a 409 naming a sandbox that still uses the template. Removing an
-  unknown name is a no-op, and removing a registration never removes the
-  image itself.
+  with no template argument means the daemon's base image; the name
+  `base` cannot be registered.
 - **Templates apply at creation only.** An acquire with a `template` on
   a key that already has a sandbox keeps the sandbox it finds, template
   unchanged — but an unknown name is still refused, never silently
   ignored.
-
-## Keep the image rules in mind
-
-Sandboxes mount their own disk over `/home/user`, so a template must
-install into image paths (`/opt`, `/usr/local`) — anything baked under
-`/home/user` is shadowed at runtime. The stock image's
-[`Dockerfile`](https://github.com/BitMiracle-AI/Dormice/blob/main/images/Dockerfile)
-is the reference: layers ordered by change frequency, tools outside the
-home directory, non-root user at uid 1000.
diff --git a/website/content/docs/troubleshooting.mdx b/website/content/docs/troubleshooting.mdx
index 876ecbb..bd5986d 100644
--- a/website/content/docs/troubleshooting.mdx
+++ b/website/content/docs/troubleshooting.mdx
@@ -1,61 +1,65 @@
 ---
 title: Troubleshooting
-description: Symptoms, causes, and fixes — every entry was hit on real hardware before it was written down.
+description: Symptoms, causes, and fixes — every entry here was hit on real hardware before it was written down.
 ---
 
 Three places answer most questions before this page does: the daemon's
-log (`journalctl -u dormice -f` — refusals are written to be read),
-`dor doctor` (the environment, [check by check](/docs/doctor)), and the
-console's Overview or `getHostMetrics` (the machine's
-[capacity](/docs/metrics)).
+log (`journalctl -u dormice -f` — error messages are written to be
+read), `dor doctor` (the environment,
+[check by check](/docs/doctor)), and the console's Overview or
+`getHostMetrics` (the machine's [capacity](/docs/metrics)).
 
 ## Freezing frees almost no memory
 
-Idle sandboxes stay at full residency instead of dropping to a few MiB.
+**Symptom:** idle sandboxes stay at full memory instead of dropping to a
+few MiB.
+
 Freezing works by pushing sandbox memory to swap, and two host settings
 gate it: **swap must exist**, and **`vm.swappiness` must be 100** — at
-the default 60 the kernel refuses to swap the shmem-backed memory gVisor
+the default 60 the kernel refuses to swap the kind of memory gVisor
 holds sandboxes in. Measured: 0 bytes reclaimed at 60; the same sandbox
-went from ~1 GiB to ~5 MiB at 100. `dor doctor` checks both; note some
-clouds ship `swappiness=0` in their own sysctl.d file, which is why
-doctor reads the live value.
+went from ~1 GiB to ~5 MiB at 100.
+
+`dor doctor` checks both. Note that some clouds ship `swappiness=0` in
+their own sysctl.d file, which is why doctor reads the live value.
 
 ## The daemon refuses to start
 
 It refuses loudly and on purpose — each message names its situation:
 
-- **"another daemon holds the ledger"** — the ledger carries an
+- **"another daemon holds the ledger"** — the database carries an
   exclusive lock; one daemon per machine is enforced, not suggested.
-  The lock dies with the process, so no stale-pidfile cleanup exists.
-- **Empty ledger, but sandbox containers exist** — almost always a
-  wrong `DORMICE_DB_PATH` or a docker-mode daemon started from the
-  wrong directory. Starting anyway would make the reconciler destroy
-  every "orphan" — so it won't. Fix the path, or clean the leftovers
-  up by hand if they really are debris.
-- **Ledger has sandboxes, but Docker shows none** — the mirror image:
-  wrong machine or wrong data directory; starting would empty the
-  ledger.
+  The lock dies with the process, so there is no stale-lock cleanup.
+- **Empty database, but sandbox containers exist** — almost always a
+  wrong `DORMICE_DB_PATH`, or a daemon started from the wrong
+  directory. Starting anyway would make the reconciler destroy every
+  "orphan" container — so it won't. Fix the path, or clean the
+  leftovers up by hand if they really are debris.
+- **Database has sandboxes, but Docker shows none** — the mirror image:
+  wrong machine or wrong data directory; starting would wipe the
+  records.
 - **Relative paths in docker mode** — refused outright, because a
   relative DB path is how the first situation happens.
 
 ## `docker container prune` deleted my sandbox containers
 
-Not data loss. The **disk is the sandbox's body**; the container is a
-disposable shell. The reconciler records the pruned sandboxes as
-stopped, and the next `acquireSandbox` rebuilds a container from the
+Not data loss. The disk — not the container — is the sandbox; the
+container is a disposable shell. The daemon records the pruned sandboxes
+as stopped, and the next `acquireSandbox` rebuilds a container from the
 surviving disk — same sandbox ID, `/home/user` intact. Verified
-end-to-end on real hardware. ([Persistence](/docs/persistence) is the
-full contract.)
+end-to-end on real hardware.
+([Sandbox persistence](/docs/persistence) is the full contract.)
 
 ## Long commands die at exactly 5 minutes
 
-A command past ~300 s fails with a client-side connection error while
-the daemon shows nothing wrong. `execCommand` sends its response headers
-only when the command *finishes*, and many HTTP clients ship a hidden
-~5-minute wait-for-headers timeout — Node's undici does. The SDK
-disables those clocks and derives one honest deadline from
-`timeoutSeconds`; a hand-rolled client must do the same
-([details](/docs/http-api)).
+**Symptom:** a command past ~300 s fails with a client-side connection
+error while the daemon shows nothing wrong.
+
+`execCommand` sends its response headers only when the command
+*finishes*, and many HTTP clients ship a hidden ~5-minute
+wait-for-headers timeout — Node's undici does. The SDK disables those
+clocks and derives one deadline from `timeoutSeconds`; a hand-rolled
+client must do the same ([details](/docs/http-api)).
 
 ## Terminals or streams stall behind a reverse proxy
 
@@ -67,14 +71,14 @@ a live terminal session through Caddy.
 ## A sandbox turned up stopped with exit code 137
 
 Out-of-memory *inside* the sandbox takes down the whole gVisor container
-— that is the isolation working: the guest hit its
-`DORMICE_SANDBOX_MEMORY_GB` ceiling (default 2). The disk survives; the
+— that is the isolation working: the sandbox hit its
+`DORMICE_SANDBOX_MEMORY_GB` limit (default 2 GB). The disk survives; the
 next acquire revives the sandbox. Raise the limit if the workload
 honestly needs more.
 
 ## E2B `watchDir` refuses to start
 
-The sandbox image predates `inotify-tools`. Rebuild it from
+The sandbox image predates `inotify-tools`. Rebuild the image from
 `images/Dockerfile`, point `DORMICE_BASE_IMAGE` at the new tag, and
 [rebuild](/docs/upgrading) the sandboxes that need watching. Doctor's
 image probe warns about exactly this.
@@ -85,14 +89,14 @@ The sandbox limit (`DORMICE_MAX_SANDBOXES`, default 100) gates
 *creation* only — waking an existing sandbox is never blocked. Before
 raising it, look at the disk-overcommit figure in
 [`getHostMetrics`](/docs/metrics): disk is the real ceiling, and past
-full even the ledger cannot write.
+full even the daemon's database cannot write.
 
 ## Creating from a template fails: "image … is not on this host"
 
 By design: [registration is configuration](/docs/templates) — the image
 is not checked when a name is registered, so the error surfaces at
-create time, named. `docker pull` or build the image on the daemon
-host, then retry.
+create time, named. `docker pull` or build the image on the daemon host,
+then retry.
 
 ## A paused container won't `docker rm` by hand
 
diff --git a/website/content/docs/upgrading.mdx b/website/content/docs/upgrading.mdx
index 6b36c44..bf3eabc 100644
--- a/website/content/docs/upgrading.mdx
+++ b/website/content/docs/upgrading.mdx
@@ -1,11 +1,11 @@
 ---
 title: Upgrading
-description: Re-running the installer is the upgrade — what survives, what restarts, and how sandbox images move.
+description: Re-run the installer to upgrade the daemon — learn what survives, what restarts, and how sandbox images move separately.
 ---
 
-The installer is idempotent: every step checks before it acts, and a
-step whose outcome is already in place says `[skip]` and touches
-nothing. **Re-running it is the upgrade** — it pulls the latest code,
+## Upgrade the daemon
+
+Re-running the installer is the upgrade. It pulls the latest code,
 rebuilds the daemon, CLI and console, restarts the service, and proves
 the result by running `dor doctor` again:
 
@@ -13,33 +13,36 @@ the result by running `dor doctor` again:
 curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash
 ```
 
-Use the `curl | bash` form for upgrades. If you instead run a local copy
-(`bash /opt/dormice/deploy/install.sh`), know that its `git pull`
-updates the script file mid-run while bash keeps executing the *old*
-bytes — measured on a real upgrade. Run a local copy twice, or just
-pipe from the repo.
+Every step checks before it acts — a step whose outcome is already in
+place says `[skip]` and touches nothing.
+
+**Use the `curl | bash` form for upgrades.** If you instead run a local
+copy (`bash /opt/dormice/deploy/install.sh`), its `git pull` updates the
+script file mid-run while bash keeps executing the *old* bytes —
+measured on a real upgrade. Run a local copy twice, or just pipe from
+the repo.
 
 ## What survives an upgrade
 
 - **Your configuration.** `/etc/dormice/env` is never touched once it
   exists — the API token is never rotated, and the recorded
   `DORMICE_BASE_IMAGE` is kept (delete the file to regenerate).
-- **The ledger and every disk.** Everything under `/var/lib/dormice`
-  stays; schema migrations run forward automatically when the new
-  daemon boots — there is no manual migration step.
+- **The database and every disk.** Everything under `/var/lib/dormice`
+  stays; schema migrations run automatically when the new daemon boots —
+  there is no manual migration step.
 - **The sandboxes.** A daemon restart does not touch containers: active
-  ones keep running, frozen ones stay frozen. The daemon is crash-only
-  by design — before it starts listening it reconciles the ledger
-  against what Docker actually shows, so restarting it is always safe.
+  ones keep running, frozen ones stay frozen. Before the daemon starts
+  listening it reconciles its records against what Docker actually
+  shows, so restarting it is always safe.
 
-Two honest footnotes. The E2B process and watcher tables live in daemon
+Two footnotes. The E2B process and watcher tables live in daemon
 memory: processes started over that surface keep running inside their
 containers across a restart, but the fresh daemon no longer lists them
 ([details](/docs/e2b-differences)). And the pinned toolchain (Node,
 gVisor) is only *installed* when missing — an already-present gVisor is
 kept as-is, not upgraded.
 
-## Upgrading sandbox images
+## Upgrade sandbox images
 
 The daemon upgrade above changes no sandbox's image — images move on a
 separate, per-sandbox path, because a container swap is visible to
@@ -52,17 +55,17 @@ systemctl restart dormice
 dor sandbox rebuild <externalId>   # per sandbox, when it suits you
 ```
 
-[Rebuild](/docs/persistence#rebuild-new-shell-same-body) swaps the
-container and keeps `/home/user` — nothing under it is lost. Sandboxes
-created from a [template](/docs/templates) follow the same rhythm with
+[Rebuild](/docs/persistence#rebuild-a-sandbox) swaps the container and
+keeps `/home/user` — nothing under it is lost. Sandboxes created from a
+[template](/docs/templates) follow the same rhythm, with
 `dor template add` re-pointing the name first. Sandboxes you never
 rebuild simply keep running on the image they were born with.
 
-## When something looks wrong afterwards
+## If something looks wrong afterwards
 
 The installer refuses to call itself done until the daemon answers
-`/healthz` and `dor doctor` passes. If it stops early, the step that
-failed prints what it found; fix that and re-run — it continues from
-where it left off. The daemon's own story is in
-`journalctl -u dormice -f`, and [troubleshooting](/docs/troubleshooting)
-collects the failures that have actually happened.
+`/healthz` and `dor doctor` passes. If it stops early, the failed step
+prints what it found; fix that and re-run — it continues from where it
+left off. The daemon's own story is in `journalctl -u dormice -f`, and
+[Troubleshooting](/docs/troubleshooting) collects the failures that have
+actually happened.

From cf0de05e3c3a52efeee13a6251c136082ea53970 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Mon, 13 Jul 2026 17:43:12 +0800
Subject: [PATCH 069/133] The layers become visible: listSandboxImages pairs
 each shell's born image with its template's current one, the console marks
 stragglers upgradable, and the docs draw the sandbox's anatomy

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/src/native.test.ts                        | 54 +++++++++++++
 .../sandboxes/components/UpgradableBadge.tsx  | 23 ++++++
 .../features/sandboxes/hooks/useSandboxes.ts  | 21 ++++-
 .../sandboxes/pages/SandboxDetailPage.tsx     | 22 +++++-
 .../sandboxes/pages/SandboxesPage.tsx         | 20 ++++-
 .../templates/pages/TemplatesPage.tsx         |  2 +-
 packages/console/src/lib/api.ts               |  8 ++
 packages/sdk/src/client.test.ts               |  2 +-
 packages/sdk/src/client.ts                    | 14 ++++
 packages/server/src/app.test.ts               |  8 +-
 packages/server/src/e2b/compat.test.ts        |  4 +-
 .../server/src/executor/contract/image.ts     | 31 ++++++++
 packages/server/src/executor/docker.ts        | 18 +++++
 packages/server/src/executor/executor.ts      | 16 ++++
 packages/server/src/executor/fake.test.ts     |  4 +-
 packages/server/src/executor/fake.ts          | 11 ++-
 .../server/src/routes/observability.test.ts   | 77 ++++++++++++++++++-
 packages/server/src/routes/sandboxes.ts       | 50 ++++++++++++
 packages/shared/src/images.ts                 | 51 ++++++++++++
 packages/shared/src/index.ts                  |  1 +
 website/content/docs/architecture.mdx         | 40 ++++++++++
 website/content/docs/console.mdx              |  5 +-
 website/content/docs/http-api.mdx             |  1 +
 website/content/docs/persistence.mdx          |  3 +
 website/content/docs/templates.mdx            | 12 ++-
 25 files changed, 477 insertions(+), 21 deletions(-)
 create mode 100644 packages/console/src/features/sandboxes/components/UpgradableBadge.tsx
 create mode 100644 packages/shared/src/images.ts

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index 0f2841d..b6e4bc3 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -391,6 +391,60 @@ describe('native API over a real daemon', () => {
     });
   });
 
+  it('listSandboxImages tracks a template upgrade; rebuild closes the gap', async () => {
+    // The daemon's base image doubles as the template image (real in docker
+    // mode, an arbitrary string for the fake). The "upgrade" points the name
+    // at an unbuilt image on purpose: registration is config and observation
+    // never boots anything, so no engine ever has to pull it.
+    const image = process.env.DORMICE_BASE_IMAGE ?? 'img:lineage-v1';
+    await client().registerTemplate('lineage-tpl', image);
+    const created = await client().acquireSandbox('lineage-key', {
+      template: 'lineage-tpl',
+    });
+    const mine = async () =>
+      (await client().listSandboxImages()).find(
+        (e) => e.externalId === 'lineage-key',
+      );
+
+    // Fresh: born from the template's current image, nothing to upgrade.
+    expect(await mine()).toEqual({
+      externalId: 'lineage-key',
+      sandboxId: created.sandbox.sandboxId,
+      image,
+      nextImage: image,
+      upgradable: false,
+    });
+
+    // Re-registering moves nextImage; the live shell honestly stays behind.
+    await client().registerTemplate('lineage-tpl', 'img:lineage-v2');
+    expect(await mine()).toMatchObject({
+      image,
+      nextImage: 'img:lineage-v2',
+      upgradable: true,
+    });
+
+    // Point the name back and rebuild: no shell means no image and nothing
+    // to upgrade; the wake boots the template's current image, in sync.
+    await client().registerTemplate('lineage-tpl', image);
+    await client().rebuildSandbox('lineage-key');
+    expect(await mine()).toMatchObject({
+      image: null,
+      nextImage: image,
+      upgradable: false,
+    });
+    await client().acquireSandbox('lineage-key');
+    expect(await mine()).toMatchObject({
+      image,
+      nextImage: image,
+      upgradable: false,
+    });
+
+    await client().destroySandbox('lineage-key');
+    expect(await client().removeTemplate('lineage-tpl')).toEqual({
+      removed: true,
+    });
+  });
+
   // Registration never checks the image; only a real engine can show what
   // happens when the promise is broken at create time.
   it.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
diff --git a/packages/console/src/features/sandboxes/components/UpgradableBadge.tsx b/packages/console/src/features/sandboxes/components/UpgradableBadge.tsx
new file mode 100644
index 0000000..a6eff48
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/UpgradableBadge.tsx
@@ -0,0 +1,23 @@
+import type { ListSandboxImagesResponse } from '@dormice/shared';
+import { Badge } from '@/components/ui/badge';
+
+type ImageLineage = ListSandboxImagesResponse['images'][number];
+
+/**
+ * 「可升级」= 当前壳的出生镜像 ≠ 模板当前镜像,daemon 已经裁决好
+ * (upgradable 字段),这里只负责显示。Rebuild 是升级的正门:换壳保盘,
+ * 下一次使用跑在新镜像上——标记只指路,动作在详情页的 Rebuild 按钮。
+ * 文案只活在这一个组件里(单一翻译点,同 STATE_LABELS 的纪律)。
+ */
+export function UpgradableBadge({ lineage }: { lineage?: ImageLineage }) {
+  if (!lineage?.upgradable) return null;
+  return (
+    <Badge
+      variant="outline"
+      className="border-amber-500/40 bg-amber-500/10 font-medium text-amber-600 dark:text-amber-400"
+      title={`运行 ${lineage.image},模板当前 ${lineage.nextImage} — Rebuild 换新`}
+    >
+      可升级
+    </Badge>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
index 2399c00..a7b4ddd 100644
--- a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
+++ b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
@@ -5,6 +5,7 @@ import {
   destroySandbox,
   getSandboxMetrics,
   listSandboxes,
+  listSandboxImages,
   listSandboxMetrics,
   rebuildSandbox,
   updatePolicy,
@@ -63,6 +64,20 @@ export function useFleetMetrics() {
   });
 }
 
+/**
+ * 全舰队镜像血统:每行的出生镜像、下一次启动会用的镜像、是否可升级。
+ * upgradable 由 daemon 裁决(resolveImage 是唯一裁决点),前端只展示。
+ * 5 秒一拍与列表的 2 秒分开:读现实要逐容器 docker inspect,比读 SQLite 贵。
+ */
+export function useSandboxImages() {
+  return useQuery({
+    queryKey: ['sandbox-images'],
+    queryFn: listSandboxImages,
+    refetchInterval: 5000,
+    retry: false,
+  });
+}
+
 export function useAcquireSandbox() {
   const queryClient = useQueryClient();
   return useMutation({
@@ -86,7 +101,11 @@ export function useRebuildSandbox() {
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: (externalId: string) => rebuildSandbox(externalId),
-    onSettled: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['sandboxes'] });
+      // 换壳直接改变镜像血统(可升级标记要立即消失),不等下一拍。
+      queryClient.invalidateQueries({ queryKey: ['sandbox-images'] });
+    },
   });
 }
 
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index fab4023..713713f 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -26,8 +26,9 @@ import { RebuildSandboxButton } from '../components/RebuildSandboxButton';
 import { RestoreCard } from '../components/RestoreCard';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
 import { SandboxTerminalCard } from '../components/SandboxTerminal';
+import { UpgradableBadge } from '../components/UpgradableBadge';
 import { formatDuration, since } from '../format';
-import { useSandbox } from '../hooks/useSandboxes';
+import { useSandbox, useSandboxImages } from '../hooks/useSandboxes';
 
 export const DETAIL_TABS = [
   'overview',
@@ -58,6 +59,9 @@ export function SandboxDetailPage() {
   const { tab } = useSearch({ from: '/_app/sandboxes/$externalId' });
   const navigate = useNavigate({ from: '/sandboxes/$externalId' });
   const { sandbox, isSuccess } = useSandbox(externalId);
+  // 镜像血统与列表页同一份 5 秒缓存;拿不到就不显示,不挡页面。
+  const images = useSandboxImages();
+  const lineage = images.data?.images.find((e) => e.externalId === externalId);
 
   if (!sandbox) {
     return isSuccess ? (
@@ -130,7 +134,21 @@ export function SandboxDetailPage() {
             <CardContent>
               <dl>
                 <Row label="沙箱 ID">{sandbox.sandboxId}</Row>
-                <Row label="模板">{sandbox.template ?? '基础镜像'}</Row>
+                <Row label="模板">
+                  <span className="inline-flex items-center gap-1.5">
+                    {sandbox.template ?? '基础镜像'}
+                    <UpgradableBadge lineage={lineage} />
+                  </span>
+                </Row>
+                {lineage && (
+                  <Row label="镜像">
+                    {lineage.image === null
+                      ? `无容器 — 下次启动用 ${lineage.nextImage}`
+                      : lineage.upgradable
+                        ? `${lineage.image} → Rebuild 后 ${lineage.nextImage}`
+                        : lineage.image}
+                  </Row>
+                )}
                 <Row label="节点">{sandbox.nodeId}</Row>
                 <Row label="端点">{sandbox.endpoint}</Row>
                 <Row label="创建于">
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index f0af4ac..420af7b 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -55,8 +55,13 @@ import { cn } from '@/lib/utils';
 import { CreateSandboxDialog } from '../components/CreateSandboxDialog';
 import { DestroySandboxButton } from '../components/DestroySandboxButton';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
+import { UpgradableBadge } from '../components/UpgradableBadge';
 import { policyLine, STATE_LABELS, since } from '../format';
-import { useFleetMetrics, useSandboxes } from '../hooks/useSandboxes';
+import {
+  useFleetMetrics,
+  useSandboxes,
+  useSandboxImages,
+} from '../hooks/useSandboxes';
 
 const STATE_FILTERS: Array<SandboxState> = [
   'active',
@@ -208,6 +213,12 @@ export function SandboxesPage() {
       new Map((fleet.data?.samples ?? []).map((s) => [s.externalId, s.sample])),
     [fleet.data],
   );
+  // 镜像血统批量拉,同一口径:拉不到就不出标记,不挡列表。
+  const images = useSandboxImages();
+  const lineageOf = useMemo(
+    () => new Map((images.data?.images ?? []).map((e) => [e.externalId, e])),
+    [images.data],
+  );
   const [search, setSearch] = useState('');
   const [stateFilter, setStateFilter] = useState<'all' | SandboxState>('all');
   const [selected, setSelected] = useState<Set<string>>(new Set());
@@ -411,7 +422,12 @@ export function SandboxesPage() {
                     <SandboxStateBadge state={sandbox.state} />
                   </TableCell>
                   <TableCell className="text-muted-foreground">
-                    {sandbox.template ?? '基础镜像'}
+                    <span className="inline-flex items-center gap-1.5">
+                      {sandbox.template ?? '基础镜像'}
+                      <UpgradableBadge
+                        lineage={lineageOf.get(sandbox.externalId)}
+                      />
+                    </span>
                   </TableCell>
                   {(() => {
                     const m = metricsOf.get(sandbox.externalId);
diff --git a/packages/console/src/features/templates/pages/TemplatesPage.tsx b/packages/console/src/features/templates/pages/TemplatesPage.tsx
index 5b7c929..c3be251 100644
--- a/packages/console/src/features/templates/pages/TemplatesPage.tsx
+++ b/packages/console/src/features/templates/pages/TemplatesPage.tsx
@@ -107,7 +107,7 @@ function RegisterTemplateDialog({
                   toast.success(
                     `模板「${template.name}」→ ${template.image}` +
                       (initial
-                        ? ' — 存量沙箱要吃到新镜像,去详情页 Rebuild'
+                        ? ' — 还在旧镜像上的沙箱在列表里带「可升级」标记,逐个 Rebuild'
                         : ''),
                   );
                   setOpen(false);
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 75aaa52..6ac827e 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -7,6 +7,7 @@ import type {
   HostMetricsResponse,
   LifecyclePolicyOverride,
   ListActivityResponse,
+  ListSandboxImagesResponse,
   ListSandboxMetricsResponse,
   RegisterTemplateResponse,
   Sandbox,
@@ -123,6 +124,13 @@ export const getSandboxMetrics = (externalId: string) =>
 export const listSandboxMetrics = () =>
   rpc<ListSandboxMetricsResponse>('/listSandboxMetrics');
 
+// Every sandbox's image lineage: the born image of the current shell (null
+// when no shell exists), the image the next shell would boot, and whether a
+// rebuild would change anything — the window answering "who still runs an
+// old image?" after a template upgrade.
+export const listSandboxImages = () =>
+  rpc<ListSandboxImagesResponse>('/listSandboxImages');
+
 // The ledger's recent history, newest first — a bounded ring, not an audit
 // log. The daemon records at the moves themselves; this only reads.
 export const listActivity = (limit?: number) =>
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 8e0cfbc..46ec075 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -334,7 +334,7 @@ describe('templates over real HTTP', () => {
       template: 'tpl-sdk',
     });
     expect(res.sandbox.template).toBe('tpl-sdk');
-    expect(executor.imageOf(res.sandbox.sandboxId)).toBe('img-sdk');
+    expect(await executor.imageOf(res.sandbox.sandboxId)).toBe('img-sdk');
 
     // In use: removal is refused, naming the key that holds it.
     await expect(client.removeTemplate('tpl-sdk')).rejects.toMatchObject({
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 405e889..ff27525 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -15,9 +15,11 @@ import {
   type HostMetricsResponse,
   hostMetricsResponseSchema,
   type LifecyclePolicyOverride,
+  type ListSandboxImagesResponse,
   type ListSandboxMetricsResponse,
   listActivityResponseSchema,
   listSandboxesResponseSchema,
+  listSandboxImagesResponseSchema,
   listSandboxMetricsResponseSchema,
   listTemplatesResponseSchema,
   type RebuildSandboxResponse,
@@ -183,6 +185,18 @@ export class Dormice {
     return listSandboxMetricsResponseSchema.parse(data).samples;
   }
 
+  /**
+   * Every sandbox's image lineage in one answer: the image its current
+   * shell was born from (`image`, null when no shell exists), the image
+   * its next shell would boot (`nextImage`), and whether a rebuild would
+   * change anything (`upgradable`). The window answering "which sandboxes
+   * still run an old image?" after a template is re-registered.
+   */
+  async listSandboxImages(): Promise<ListSandboxImagesResponse['images']> {
+    const data = await this.rpc('listSandboxImages', {});
+    return listSandboxImagesResponseSchema.parse(data).images;
+  }
+
   /**
    * The daemon's recent history, newest first: who was created, cooled,
    * woken, destroyed, and what reconciliation repaired. A bounded ring —
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index f7db980..b16db3a 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -1262,7 +1262,7 @@ describe('templates', () => {
     const sandbox = res.json().sandbox;
     expect(sandbox.template).toBe('py');
     // The physical half: the shell was actually born from the template's image.
-    expect(executor.imageOf(sandbox.sandboxId)).toBe('img-a');
+    expect(await executor.imageOf(sandbox.sandboxId)).toBe('img-a');
     // A template-less acquire stays on the base image, template null.
     const plain = (await acquire(app, { externalId: 'bob' })).json().sandbox;
     expect(plain.template).toBeNull();
@@ -1322,18 +1322,18 @@ describe('templates', () => {
     const created = (
       await acquire(app, { externalId: 'alice', template: 'py' })
     ).json().sandbox;
-    expect(executor.imageOf(created.sandboxId)).toBe('img-v1');
+    expect(await executor.imageOf(created.sandboxId)).toBe('img-v1');
 
     // Operator builds a new image and re-points the name; the stock moves
     // per sandbox, on its own rebuild — never behind its back.
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });
-    expect(executor.imageOf(created.sandboxId)).toBe('img-v1');
+    expect(await executor.imageOf(created.sandboxId)).toBe('img-v1');
 
     await rpc(app, '/rebuildSandbox', { externalId: 'alice' });
     const woken = (await acquire(app, { externalId: 'alice' })).json().sandbox;
     expect(woken.sandboxId).toBe(created.sandboxId);
     // The rebuilt shell was born from the template's *current* image.
-    expect(executor.imageOf(created.sandboxId)).toBe('img-v2');
+    expect(await executor.imageOf(created.sandboxId)).toBe('img-v2');
   });
 });
 
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index f4fa239..1052a93 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -1653,7 +1653,7 @@ describe('E2B templates', () => {
     expect(body.templateID).toBe('py311');
     expect(body.alias).toBe('py311');
     // The physical half: the shell was born from the template's image.
-    expect(t.executor.imageOf(body.sandboxID)).toBe('img-py');
+    expect(await t.executor.imageOf(body.sandboxID)).toBe('img-py');
 
     const info = await control(t, 'GET', `/sandboxes/${body.sandboxID}`);
     // The SDK maps wire templateID -> SandboxInfo.templateId and a truthy
@@ -1689,7 +1689,7 @@ describe('E2B templates', () => {
       // Echo keeps the pre-templates shape: the base image name, no alias.
       expect(body.templateID).toBe('dormice-base:test');
       expect(body.alias).toBeUndefined();
-      expect(t.executor.imageOf(body.sandboxID)).toBe(FAKE_BASE_IMAGE);
+      expect(await t.executor.imageOf(body.sandboxID)).toBe(FAKE_BASE_IMAGE);
     }
   });
 
diff --git a/packages/server/src/executor/contract/image.ts b/packages/server/src/executor/contract/image.ts
index c85a457..c53e5fb 100644
--- a/packages/server/src/executor/contract/image.ts
+++ b/packages/server/src/executor/contract/image.ts
@@ -62,5 +62,36 @@ export function imageTests(ctx: ContractContext) {
       },
       timeoutMs,
     );
+
+    it(
+      'imageOf reads the born image in any state, stopped included',
+      async () => {
+        const id = await ctx.fresh({ image: ctx.subject.altImage });
+        expect(await ctx.executor.imageOf(id)).toBe(ctx.subject.altImage);
+        await ctx.executor.freeze(id);
+        expect(await ctx.executor.imageOf(id)).toBe(ctx.subject.altImage);
+        // The exited container is still the shell, and start would boot it
+        // as-is — so a stopped sandbox honestly reports the old image.
+        await ctx.executor.stop(id);
+        expect(await ctx.executor.imageOf(id)).toBe(ctx.subject.altImage);
+      },
+      timeoutMs,
+    );
+
+    it(
+      'imageOf answers null when no shell exists, never a guess',
+      async () => {
+        const id = await ctx.fresh();
+        await ctx.executor.freeze(id);
+        await ctx.executor.stop(id);
+        await ctx.subject.vanishContainer(id);
+        // The disk survives, but an image is a property of the shell — with
+        // no shell there is nothing to report; the next start decides.
+        expect(await ctx.executor.imageOf(id)).toBe(null);
+        // An observation verb: an unknown sandbox is null too, not a throw.
+        expect(await ctx.executor.imageOf('never-created')).toBe(null);
+      },
+      timeoutMs,
+    );
   });
 }
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 65749ea..e0cbde3 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -146,6 +146,10 @@ export class DockerExecutor implements Executor {
     this.docker = docker ?? new Docker({ socketPath: '/var/run/docker.sock' });
   }
 
+  get baseImage(): string {
+    return this.opts.baseImage;
+  }
+
   async create(sandboxId: string, opts?: ShellOptions): Promise<void> {
     if ((await this.inspect(sandboxId)) !== null) {
       throw new Error(`container ${sandboxId} already exists`);
@@ -421,6 +425,20 @@ export class DockerExecutor implements Executor {
     return { host: ip, port };
   }
 
+  async imageOf(sandboxId: string): Promise<string | null> {
+    try {
+      const info = await this.docker
+        .getContainer(containerName(sandboxId))
+        .inspect();
+      // Config.Image is the name the shell was created with — the same
+      // string launchContainer wrote, not a resolved digest.
+      return info.Config.Image;
+    } catch (err) {
+      if (isDockerApiError(err) && err.statusCode === 404) return null;
+      throw err;
+    }
+  }
+
   async metrics(sandboxId: string): Promise<SandboxMetrics> {
     const found = await this.inspect(sandboxId);
     const actual =
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index 8fe3508..cdbc989 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -241,6 +241,13 @@ export interface ShellOptions {
  * a container runtime.
  */
 export interface Executor {
+  /**
+   * The image shells boot from when create/start name none. The executor is
+   * the one authority on its own default — config knows it only in docker
+   * mode, and callers comparing born images against "what would boot next"
+   * must not guess.
+   */
+  readonly baseImage: string;
   /**
    * Brings a brand-new sandbox up to running. `image` picks what the shell
    * boots from (a template's current image); absent means the executor's
@@ -341,6 +348,15 @@ export interface Executor {
    * running to measure — the route above answers [] for those on its own.
    */
   metrics(sandboxId: string): Promise<SandboxMetrics>;
+  /**
+   * The image the sandbox's current shell was born from — an image is a
+   * property of the shell, fixed at its birth and gone with it. Returns
+   * null when no container object exists (stopped-and-pruned, archived):
+   * there is no shell to have an image, and the next start() decides one
+   * from the template's current image. A pure read on whatever state the
+   * container is in; never wakes anything — observation is not activity.
+   */
+  imageOf(sandboxId: string): Promise<string | null>;
   /**
    * Every sandbox disk on this host, summed: how many, what they were
    * promised, what they actually occupy. A snapshot like listDisks —
diff --git a/packages/server/src/executor/fake.test.ts b/packages/server/src/executor/fake.test.ts
index c2c00db..82f04d9 100644
--- a/packages/server/src/executor/fake.test.ts
+++ b/packages/server/src/executor/fake.test.ts
@@ -12,8 +12,8 @@ describeExecutorContract('FakeExecutor', () => {
     // Any string: the fake plays whatever image it is asked to.
     altImage: 'fake-alt-image',
     imageOf: async (sandboxId: string) => {
-      const image = executor.imageOf(sandboxId);
-      if (!image) {
+      const image = await executor.imageOf(sandboxId);
+      if (image === null) {
         throw new Error(`no shell for ${sandboxId}`);
       }
       return image;
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index 2c948f7..ceee8f9 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -197,6 +197,7 @@ class FakeProcessIO {
  * the fake too.
  */
 export class FakeExecutor implements Executor {
+  readonly baseImage = FAKE_BASE_IMAGE;
   private readonly containers = new Map<string, ContainerState>();
   private readonly disks = new Set<string>();
   /**
@@ -238,9 +239,13 @@ export class FakeExecutor implements Executor {
     return this.containers.get(sandboxId);
   }
 
-  /** Test hook: the image the sandbox's current shell was born from. */
-  imageOf(sandboxId: string): string | undefined {
-    return this.images.get(sandboxId);
+  /**
+   * The image the sandbox's current shell was born from; null when no
+   * shell exists. Reads the images map — keyed like containers, so a
+   * vanished or removed shell honestly has no image.
+   */
+  async imageOf(sandboxId: string): Promise<string | null> {
+    return this.images.get(sandboxId) ?? null;
   }
 
   /**
diff --git a/packages/server/src/routes/observability.test.ts b/packages/server/src/routes/observability.test.ts
index ae24231..02e4005 100644
--- a/packages/server/src/routes/observability.test.ts
+++ b/packages/server/src/routes/observability.test.ts
@@ -8,6 +8,7 @@ import {
   getConfigResponseSchema,
   getSandboxMetricsResponseSchema,
   listActivityResponseSchema,
+  listSandboxImagesResponseSchema,
   listSandboxMetricsResponseSchema,
 } from '@dormice/shared';
 import { count } from 'drizzle-orm';
@@ -19,7 +20,7 @@ import { CONFIG_KEYS, type ConfigSources, loadConfig } from '../config';
 import { ACTIVITY_KEEP, recordActivity } from '../db/activity';
 import { migrateDb, openDb } from '../db/db';
 import { activity } from '../db/schema';
-import { FakeExecutor } from '../executor/fake';
+import { FAKE_BASE_IMAGE, FakeExecutor } from '../executor/fake';
 import { KeyedQueue } from '../keyed-queue';
 import { freezeSandbox, stopSandbox } from '../lifecycle';
 import { ARCHIVE_DEFAULT_SECONDS } from '../policy';
@@ -336,3 +337,77 @@ describe('listSandboxMetrics', () => {
     );
   });
 });
+
+describe('listSandboxImages', () => {
+  async function images(app: Parameters<typeof rpc>[0]) {
+    const res = await rpc(app, '/listSandboxImages', {});
+    expect(res.statusCode).toBe(200);
+    return listSandboxImagesResponseSchema.parse(res.json()).images;
+  }
+
+  it('walks a template upgrade: in sync, left behind, rebuilt, in sync again', async () => {
+    const { app } = testApp();
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
+    const created = (
+      await rpc(app, '/acquireSandbox', { externalId: 'alice', template: 'py' })
+    ).json().sandbox;
+
+    // Fresh: the shell was born from the template's current image.
+    expect(await images(app)).toEqual([
+      {
+        externalId: 'alice',
+        sandboxId: created.sandboxId,
+        image: 'img-v1',
+        nextImage: 'img-v1',
+        upgradable: false,
+      },
+    ]);
+
+    // Re-registering moves nextImage; the live shell honestly stays behind.
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });
+    expect(await images(app)).toMatchObject([
+      { image: 'img-v1', nextImage: 'img-v2', upgradable: true },
+    ]);
+
+    // Rebuild removes the shell: no image to report, and nothing to upgrade
+    // — the next boot resolves the current image by itself.
+    await rpc(app, '/rebuildSandbox', { externalId: 'alice' });
+    expect(await images(app)).toMatchObject([
+      { image: null, nextImage: 'img-v2', upgradable: false },
+    ]);
+
+    // Woken: born from the template's current image, in sync again.
+    await rpc(app, '/acquireSandbox', { externalId: 'alice' });
+    expect(await images(app)).toMatchObject([
+      { image: 'img-v2', nextImage: 'img-v2', upgradable: false },
+    ]);
+  });
+
+  it('compares template-less sandboxes against the executor base image', async () => {
+    const { app } = testApp();
+    await rpc(app, '/acquireSandbox', { externalId: 'plain' });
+    expect(await images(app)).toMatchObject([
+      { image: FAKE_BASE_IMAGE, nextImage: FAKE_BASE_IMAGE, upgradable: false },
+    ]);
+  });
+
+  it('answers every row: a stopped shell keeps its old image, honestly upgradable', async () => {
+    const { app, db, executor } = testApp();
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
+    const created = (
+      await rpc(app, '/acquireSandbox', { externalId: 'cold', template: 'py' })
+    ).json().sandbox;
+    await freezeSandbox(db, executor, created.sandboxId);
+    await stopSandbox(db, executor, created.sandboxId);
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });
+
+    // The exited container is still the shell: waking it would boot the old
+    // image, so the row is honestly reported as upgradable.
+    expect(await images(app)).toMatchObject([
+      { image: 'img-v1', nextImage: 'img-v2', upgradable: true },
+    ]);
+    // Observation is not activity: still stopped afterwards.
+    const { sandboxes } = (await rpc(app, '/listSandboxes')).json();
+    expect(sandboxes[0].state).toBe('stopped');
+  });
+});
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index 8c98638..ea966d8 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -11,6 +11,8 @@ import {
   type LifecyclePolicy,
   lifecyclePolicySchema,
   listSandboxesResponseSchema,
+  listSandboxImagesRequestSchema,
+  listSandboxImagesResponseSchema,
   listSandboxMetricsRequestSchema,
   listSandboxMetricsResponseSchema,
   READ_FILES_TOTAL_LIMIT_BYTES,
@@ -364,6 +366,54 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     },
   );
 
+  // Every sandbox's image lineage in one answer: which image the current
+  // shell was born from, next to what the next shell would boot. The born
+  // image is a property of the shell and deliberately not a ledger column,
+  // so it is read from reality on demand — in parallel, like the metrics
+  // batch above. Rows that cannot have a container (archived, restoring)
+  // skip the executor call outright; for the rest a vanished container
+  // reads as null, not a guess. Observation never wakes anything.
+  app.post(
+    '/listSandboxImages',
+    {
+      schema: {
+        body: listSandboxImagesRequestSchema,
+        response: { 200: listSandboxImagesResponseSchema },
+      },
+    },
+    async () => {
+      const images = await Promise.all(
+        listSandboxes(db).map(async (row) => {
+          // resolveImage is the one arbiter of template -> image; undefined
+          // means "the executor's own base image", and the executor is the
+          // one authority on what that is (config only knows in docker mode).
+          const nextImage =
+            resolveImage(db, row.template) ?? executor.baseImage;
+          let image: string | null = null;
+          if (row.state !== 'archived' && row.state !== 'restoring') {
+            try {
+              image = await executor.imageOf(row.sandboxId);
+            } catch {
+              // Reading failed mid-vanish: no shell to report, same as null.
+              image = null;
+            }
+          }
+          return {
+            externalId: row.externalId,
+            sandboxId: row.sandboxId,
+            image,
+            nextImage,
+            // A row without a shell is not upgradable: its very next boot
+            // resolves the current image by itself. rebuildSandbox is the
+            // front door for the rest.
+            upgradable: image !== null && image !== nextImage,
+          };
+        }),
+      );
+      return { images };
+    },
+  );
+
   app.post(
     '/execCommand',
     {
diff --git a/packages/shared/src/images.ts b/packages/shared/src/images.ts
new file mode 100644
index 0000000..190c029
--- /dev/null
+++ b/packages/shared/src/images.ts
@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+/**
+ * listSandboxImages() — every sandbox's image lineage in one answer: which
+ * image its current shell was born from, next to the image its next shell
+ * would boot. The ledger deliberately records template names, not image
+ * strings, so the born image is read from reality (the container object)
+ * on demand — this verb is the one window answering "which sandboxes still
+ * run an old image?" after a template is re-registered. Observation never
+ * wakes a sandbox and never touches its lifecycle.
+ *
+ * The comparison is by image name, matching "a template is a named image":
+ * rebuilding the same tag in place is invisible here — upgrade templates by
+ * re-registering a new tag.
+ */
+export const listSandboxImagesRequestSchema = z.object({});
+
+export type ListSandboxImagesRequest = z.infer<
+  typeof listSandboxImagesRequestSchema
+>;
+
+export const listSandboxImagesResponseSchema = z.object({
+  images: z.array(
+    z.object({
+      externalId: z.string(),
+      sandboxId: z.string(),
+      /**
+       * The image the current shell was born from. Null when no shell
+       * exists (stopped-and-pruned, archived, restoring): there is nothing
+       * to report, and the next start decides — never a guess.
+       */
+      image: z.string().nullable(),
+      /**
+       * The image the next shell would boot: the template's current image,
+       * or the daemon's base image for template-less sandboxes. Answered
+       * for every row, shell or not.
+       */
+      nextImage: z.string(),
+      /**
+       * True when the current shell runs an image other than nextImage —
+       * rebuildSandbox is the front door to pick the new one up. A row
+       * without a shell is false: its next boot upgrades by itself.
+       */
+      upgradable: z.boolean(),
+    }),
+  ),
+});
+
+export type ListSandboxImagesResponse = z.infer<
+  typeof listSandboxImagesResponseSchema
+>;
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 66b0e64..0956e53 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -5,6 +5,7 @@ export * from './destroy';
 export * from './exec';
 export * from './files';
 export * from './host';
+export * from './images';
 export * from './ingress';
 export * from './list';
 export * from './metrics';
diff --git a/website/content/docs/architecture.mdx b/website/content/docs/architecture.mdx
index cf7ac7d..6a81a76 100644
--- a/website/content/docs/architecture.mdx
+++ b/website/content/docs/architecture.mdx
@@ -48,6 +48,46 @@ Why gVisor and not VMs: freezing requires sandboxes to be **processes**
 out requiring KVM. Firecracker-class hardware virtualization is a
 different trade — see the last section.
 
+## Anatomy of a sandbox
+
+A running sandbox is three layers stacked, each with its own lifetime:
+
+```text
+┌────────────────────────────────────────────┐
+│ your disk, mounted at /home/user           │  the sandbox itself:
+│                                            │  survives everything but destroy
+├────────────────────────────────────────────┤
+│ container writable layer (/tmp, processes) │  vanishes with the container
+├────────────────────────────────────────────┤
+│ image layers (base image or template)      │  read-only, shared by every
+│                                            │  sandbox on the same image
+└────────────────────────────────────────────┘
+```
+
+**Image layers** hold the tools. The stock base image ships Python,
+Node.js and Claude Code; a [template](/docs/templates) replaces it with
+your own image. These layers are read-only and Docker stores each one
+once per host, however many sandboxes boot from it. Composition happens
+at build time: a template image can `FROM` the base image, or another
+template's image, and stack as many layers as you need.
+
+**The container writable layer** is scratch space: `/tmp`, packages
+installed outside the home directory, running processes. The container
+is replaceable machinery, and this layer goes wherever it goes — a
+rebuild, a prune, an out-of-memory kill.
+
+**The disk at `/home/user`** is the sandbox's body: a dedicated disk
+image with a physical quota, and the only layer that persists. See
+[Sandbox persistence](/docs/persistence) for exactly what survives what.
+
+`rebuildSandbox` is the seam between the layers. It replaces the
+container and its writable layer while the disk stays put, so the next
+wake boots the template's *current* image with `/home/user` untouched —
+that is how an existing sandbox picks up new image layers. The
+`listSandboxImages` verb reports which sandboxes still run an image
+older than their template's current one; the console shows it as an
+"upgradable" marker next to the template name.
+
 ## The security boundary
 
 - **gVisor's userspace kernel is the boundary.** Sandbox code — even
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
index 022a307..69d52f2 100644
--- a/website/content/docs/console.mdx
+++ b/website/content/docs/console.mdx
@@ -37,7 +37,10 @@ with search, a state filter, and multi-select batch destroy. Creating a
 sandbox from here is exactly `acquireSandbox`: a key, the lifecycle
 knobs (including the never-stop
 [resident-agent switch](/docs/resident-agents)), and a template dropdown
-when templates are registered.
+when templates are registered. After a
+[template upgrade](/docs/templates#update-a-template), sandboxes still
+running the old image carry an "upgradable" marker next to their
+template name — rebuild them to move.
 
 A sandbox's detail page is a workspace with four tabs:
 
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
index 3a9681a..4b05db2 100644
--- a/website/content/docs/http-api.mdx
+++ b/website/content/docs/http-api.mdx
@@ -43,6 +43,7 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | `POST /listTemplates` | every registered template | — |
 | `POST /removeTemplate` | unregister; idempotent | 409 while sandboxes still use it (names them) |
 | `POST /getHostMetrics` | host snapshot; never wakes anything | — |
+| `POST /listSandboxImages` | each sandbox's born image vs its template's current one | — |
 
 **Only `acquireSandbox` creates.** The use verbs (`execCommand`, files,
 `rebuildSandbox`) answer 404 for an unknown key rather than creating a
diff --git a/website/content/docs/persistence.mdx b/website/content/docs/persistence.mdx
index be806b6..7022a51 100644
--- a/website/content/docs/persistence.mdx
+++ b/website/content/docs/persistence.mdx
@@ -12,6 +12,9 @@ remember:
 > the sandbox. Everything outside it is container state, and containers
 > may be replaced at any time.**
 
+See [Anatomy of a sandbox](/docs/architecture#anatomy-of-a-sandbox) for
+how the disk, the container, and the image layers stack.
+
 ## What survives
 
 All of these are exercised by the test suite against a real Docker +
diff --git a/website/content/docs/templates.mdx b/website/content/docs/templates.mdx
index 00084d6..befaf7b 100644
--- a/website/content/docs/templates.mdx
+++ b/website/content/docs/templates.mdx
@@ -49,6 +49,14 @@ image they were born on. Through a rebuild, `/home/user` carries over
 untouched and everything outside it resets onto the new image — see
 [Rebuild a sandbox](/docs/persistence#rebuild-a-sandbox).
 
+You can ask which sandboxes still run an old image with the
+`listSandboxImages` verb (SDK method of the same name), or look for the
+"upgradable" marker in the [console](/docs/console)'s sandbox list.
+
+**Note:** the comparison is by image name. Rebuilding the same tag in
+place is invisible to it — upgrade by registering a new tag
+(`my-agent-env:v2`), not by overwriting `v1`.
+
 ## Remove a template
 
 ```sh
@@ -61,7 +69,9 @@ registration never removes the image itself.
 
 ## Image requirements
 
-Sandboxes mount their own disk over `/home/user`, so a template must
+Sandboxes mount their own disk over `/home/user` (see
+[Anatomy of a sandbox](/docs/architecture#anatomy-of-a-sandbox)), so a
+template must
 install its tools into image paths (`/opt`, `/usr/local`) — anything
 baked under `/home/user` is hidden at runtime. The stock image's
 [`Dockerfile`](https://github.com/BitMiracle-AI/Dormice/blob/main/images/Dockerfile)

From e58a00c8e0669e802aad5d7d26b1aa7e913be5a0 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 02:46:49 +0800
Subject: [PATCH 070/133] The console learns its manners from the neighbors:
 crashes speak Chinese with a retry button, page titles gain weight, narrow
 tables come home to center, skeletons mirror the cards they stand in for,
 long tables pin their headers, filters wear dashed coats with badges, and the
 bulk-destroy toast remembers to count

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../console/src/components/CommandMenu.tsx    |  2 +-
 .../console/src/components/FilterMenu.tsx     | 78 +++++++++++++++++++
 .../src/components/RootErrorBoundary.tsx      | 40 ++++++++++
 .../features/activity/pages/ActivityPage.tsx  | 40 ++++------
 .../features/connect/pages/ConnectPage.tsx    |  2 +-
 .../src/features/doctor/pages/DoctorPage.tsx  |  2 +-
 .../features/ingress/pages/DomainsPage.tsx    |  9 ++-
 .../overview/components/OverviewCards.tsx     | 30 ++++---
 .../features/overview/pages/OverviewPage.tsx  |  2 +-
 .../components/FilePreviewDialog.tsx          |  2 +-
 .../sandboxes/components/HistoryPanel.tsx     |  2 +-
 .../sandboxes/components/MetricsPanel.tsx     |  2 +-
 .../sandboxes/components/SandboxTerminal.tsx  |  2 +-
 .../sandboxes/pages/SandboxDetailPage.tsx     |  2 +-
 .../sandboxes/pages/SandboxesPage.tsx         | 40 +++++-----
 .../features/settings/pages/SettingsPage.tsx  |  9 ++-
 .../templates/pages/TemplatesPage.tsx         |  7 +-
 packages/console/src/routes/__root.tsx        |  3 +
 18 files changed, 199 insertions(+), 75 deletions(-)
 create mode 100644 packages/console/src/components/FilterMenu.tsx
 create mode 100644 packages/console/src/components/RootErrorBoundary.tsx

diff --git a/packages/console/src/components/CommandMenu.tsx b/packages/console/src/components/CommandMenu.tsx
index b3ec778..4a0614b 100644
--- a/packages/console/src/components/CommandMenu.tsx
+++ b/packages/console/src/components/CommandMenu.tsx
@@ -100,7 +100,7 @@ export function CommandMenu() {
         title="命令面板"
         description="跳转到页面或沙箱"
       >
-        <CommandInput placeholder="搜页面、沙箱…" />
+        <CommandInput placeholder="搜页面、沙箱" />
         <CommandList>
           <CommandEmpty>没有匹配的结果。</CommandEmpty>
           <CommandGroup heading="页面">
diff --git a/packages/console/src/components/FilterMenu.tsx b/packages/console/src/components/FilterMenu.tsx
new file mode 100644
index 0000000..b3c9fbc
--- /dev/null
+++ b/packages/console/src/components/FilterMenu.tsx
@@ -0,0 +1,78 @@
+import { PlusSignCircleIcon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { Separator } from '@/components/ui/separator';
+
+export interface FilterOption {
+  /** '' 即「全部」(不筛)。 */
+  value: string;
+  label: string;
+}
+
+/**
+ * 工具栏筛选下拉(风格参考 clawsgo faceted-filter):虚线 outline 按钮 +
+ * 加号图标,选中后竖分隔 + secondary 徽章显示当前值 — 一眼看出"筛了
+ * 什么"。单选语义,选项少且固定,body 用 DropdownMenuRadioGroup,
+ * 不上 Command 那套搜索壳。
+ */
+export function FilterMenu({
+  label,
+  value,
+  options,
+  onChange,
+}: {
+  label: string;
+  value: string;
+  options: FilterOption[];
+  onChange: (value: string) => void;
+}) {
+  const selected = value
+    ? options.find((option) => option.value === value)
+    : undefined;
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        render={
+          <Button variant="outline" size="sm" className="border-dashed" />
+        }
+      >
+        <HugeiconsIcon
+          icon={PlusSignCircleIcon}
+          strokeWidth={2}
+          className="size-4"
+        />
+        {label}
+        {selected && (
+          <>
+            {/* 组件自带 data-vertical:self-stretch,限高后会钉上沿 — 压回居中。 */}
+            <Separator
+              orientation="vertical"
+              className="mx-0.5 !h-4 !self-center"
+            />
+            <Badge variant="secondary" className="rounded-sm px-1 font-normal">
+              {selected.label}
+            </Badge>
+          </>
+        )}
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start" className="min-w-36">
+        <DropdownMenuRadioGroup value={value} onValueChange={onChange}>
+          <DropdownMenuRadioItem value="">全部</DropdownMenuRadioItem>
+          {options.map((option) => (
+            <DropdownMenuRadioItem key={option.value} value={option.value}>
+              {option.label}
+            </DropdownMenuRadioItem>
+          ))}
+        </DropdownMenuRadioGroup>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
diff --git a/packages/console/src/components/RootErrorBoundary.tsx b/packages/console/src/components/RootErrorBoundary.tsx
new file mode 100644
index 0000000..8e7ed21
--- /dev/null
+++ b/packages/console/src/components/RootErrorBoundary.tsx
@@ -0,0 +1,40 @@
+import { useNavigate, useRouter } from '@tanstack/react-router';
+import { Button } from '@/components/ui/button';
+import { ApiError } from '@/lib/api';
+
+/**
+ * 全局错误兜底页(挂在 __root 的 errorComponent):会话失效已被
+ * lib/api.ts 的 401 拦截转成跳登录,不会走到这里。这里收的是真异常 —
+ * daemon 没起(fetch 直接 reject)、500、渲染崩溃。给一个能
+ * 「重试 / 回登录」的中文界面,取代 router 默认的英文报错页。
+ */
+export function RootErrorBoundary({ error }: { error: unknown }) {
+  const router = useRouter();
+  const navigate = useNavigate();
+
+  const message =
+    error instanceof ApiError || error instanceof Error
+      ? error.message
+      : '发生了未知错误';
+
+  // daemon 没起/网络不可达时 fetch 抛 TypeError('Failed to fetch'),
+  // 原文对用户毫无信息量,换成能行动的话。
+  const friendly = /failed to fetch|networkerror|load failed/i.test(message)
+    ? '无法连接 daemon — 确认它在运行后重试。'
+    : message;
+
+  return (
+    <div className="flex min-h-svh flex-col items-center justify-center gap-4 px-6 text-center">
+      <div className="space-y-2">
+        <h1 className="text-2xl font-semibold">出了点问题</h1>
+        <p className="max-w-md text-sm text-muted-foreground">{friendly}</p>
+      </div>
+      <div className="flex gap-3">
+        <Button onClick={() => router.invalidate()}>重试</Button>
+        <Button variant="outline" onClick={() => navigate({ to: '/login' })}>
+          返回登录
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index e868a0f..37ce55c 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -3,6 +3,7 @@ import { Search01Icon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
 import { Link } from '@tanstack/react-router';
 import { useMemo, useState } from 'react';
+import { FilterMenu } from '@/components/FilterMenu';
 import { Badge } from '@/components/ui/badge';
 import {
   Empty,
@@ -15,10 +16,6 @@ import {
   InputGroupAddon,
   InputGroupInput,
 } from '@/components/ui/input-group';
-import {
-  NativeSelect,
-  NativeSelectOption,
-} from '@/components/ui/native-select';
 import { Spinner } from '@/components/ui/spinner';
 import {
   Table,
@@ -61,7 +58,7 @@ export function ActivityPage() {
   return (
     <>
       <div>
-        <h1 className="text-lg font-semibold">活动</h1>
+        <h1 className="text-2xl font-semibold">活动</h1>
         <p className="text-sm text-muted-foreground">
           账本的历史:谁被创建、冻结、停止、销毁,对账修了什么。保留最近 1000
           条,更老的自然滚出。
@@ -82,24 +79,18 @@ export function ActivityPage() {
             placeholder="按 externalId 搜索"
           />
         </InputGroup>
-        <NativeSelect
-          aria-label="按事件类型筛选"
-          value={kindFilter}
-          onChange={(event) =>
-            setKindFilter(event.target.value as 'all' | ActivityKind)
-          }
-        >
-          <NativeSelectOption value="all">全部事件</NativeSelectOption>
-          {(
+        <FilterMenu
+          label="事件"
+          value={kindFilter === 'all' ? '' : kindFilter}
+          options={(
             Object.entries(ACTIVITY_KIND_LABELS) as Array<
               [ActivityKind, string]
             >
-          ).map(([kind, label]) => (
-            <NativeSelectOption key={kind} value={kind}>
-              {label}
-            </NativeSelectOption>
-          ))}
-        </NativeSelect>
+          ).map(([kind, label]) => ({ value: kind, label }))}
+          onChange={(value) =>
+            setKindFilter(value === '' ? 'all' : (value as ActivityKind))
+          }
+        />
         <span className="text-sm text-muted-foreground">
           {filtered.length} / {events.length} 条
         </span>
@@ -107,7 +98,7 @@ export function ActivityPage() {
 
       {isPending ? (
         <div className="flex items-center gap-2 text-sm text-muted-foreground">
-          <Spinner /> 读取活动…
+          <Spinner /> 读取活动
         </div>
       ) : isError ? (
         <Empty className="border border-dashed">
@@ -133,9 +124,10 @@ export function ActivityPage() {
           </EmptyHeader>
         </Empty>
       ) : (
-        <div className="overflow-x-auto rounded-lg border">
-          <Table>
-            <TableHeader>
+        // 环形记录上限 1000 条,是全站最长的表 — 限高框内滚,表头贴住。
+        <div className="max-h-[70vh] overflow-auto rounded-lg border">
+          <Table className="[&_tr]:transition-none">
+            <TableHeader className="sticky top-0 z-10 bg-background">
               <TableRow>
                 <TableHead className="w-28">时间</TableHead>
                 <TableHead className="w-28">事件</TableHead>
diff --git a/packages/console/src/features/connect/pages/ConnectPage.tsx b/packages/console/src/features/connect/pages/ConnectPage.tsx
index ab4ba46..e742235 100644
--- a/packages/console/src/features/connect/pages/ConnectPage.tsx
+++ b/packages/console/src/features/connect/pages/ConnectPage.tsx
@@ -76,7 +76,7 @@ dor sandbox exec my-project 'uname -r'`;
   return (
     <div className="mx-auto w-full max-w-3xl">
       <div className="mb-1">
-        <h1 className="text-lg font-semibold">连接</h1>
+        <h1 className="text-2xl font-semibold">连接</h1>
       </div>
       <p className="mb-6 text-sm text-muted-foreground">
         这个 daemon 的地址是 <code className="font-mono">{origin}</code> —
diff --git a/packages/console/src/features/doctor/pages/DoctorPage.tsx b/packages/console/src/features/doctor/pages/DoctorPage.tsx
index 4c54a5f..5904c3a 100644
--- a/packages/console/src/features/doctor/pages/DoctorPage.tsx
+++ b/packages/console/src/features/doctor/pages/DoctorPage.tsx
@@ -88,7 +88,7 @@ export function DoctorPage() {
     <>
       <div className="flex flex-wrap items-center justify-between gap-3">
         <div>
-          <h1 className="flex items-center gap-2 text-lg font-semibold">
+          <h1 className="flex items-center gap-2 text-2xl font-semibold">
             体检 <SampleDataBadge />
           </h1>
           <p className="text-sm text-muted-foreground">
diff --git a/packages/console/src/features/ingress/pages/DomainsPage.tsx b/packages/console/src/features/ingress/pages/DomainsPage.tsx
index 72d80a9..d46e119 100644
--- a/packages/console/src/features/ingress/pages/DomainsPage.tsx
+++ b/packages/console/src/features/ingress/pages/DomainsPage.tsx
@@ -247,10 +247,11 @@ export function DomainsPage() {
   };
 
   return (
-    <>
+    // 内容是竖排的域名条目与指引,同设置页限宽居中。
+    <div className="mx-auto flex w-full max-w-4xl flex-col gap-4">
       <div className="flex flex-wrap items-center justify-between gap-3">
         <div>
-          <h1 className="text-lg font-semibold">域名</h1>
+          <h1 className="text-2xl font-semibold">域名</h1>
           <p className="text-sm text-muted-foreground">
             给控制台(和 API)绑定域名,可以绑多个;HTTPS 证书自动申请与续期。
           </p>
@@ -262,7 +263,7 @@ export function DomainsPage() {
 
       {isPending ? (
         <div className="flex items-center gap-2 text-sm text-muted-foreground">
-          <Spinner /> 读取域名配置…
+          <Spinner /> 读取域名配置
         </div>
       ) : isError ? (
         <Empty className="border border-dashed">
@@ -321,6 +322,6 @@ export function DomainsPage() {
           </p>
         </>
       )}
-    </>
+    </div>
   );
 }
diff --git a/packages/console/src/features/overview/components/OverviewCards.tsx b/packages/console/src/features/overview/components/OverviewCards.tsx
index 747eb30..6bdff1d 100644
--- a/packages/console/src/features/overview/components/OverviewCards.tsx
+++ b/packages/console/src/features/overview/components/OverviewCards.tsx
@@ -139,16 +139,28 @@ export function OverviewCards() {
   }
 
   if (!query.data) {
-    // One placeholder per card in the top row, keyed by what will load there.
+    // Skeletons mirror the real card anatomy (label / value / hint / meter)
+    // and both rows, block heights matched to the text line heights — the
+    // loading and loaded states are the same height, so nothing jumps.
+    const bones = (slot: string) => (
+      <Card key={slot} size="sm">
+        <CardContent className="flex flex-col gap-2">
+          <Skeleton className="h-5 w-16" />
+          <Skeleton className="h-8 w-24" />
+          <Skeleton className="h-4 w-32" />
+          <Skeleton className="h-1.5 w-full rounded-full" />
+        </CardContent>
+      </Card>
+    );
     return (
-      <div className="grid gap-4 sm:grid-cols-2 xl:grid-cols-4">
-        {['cpu', 'memory', 'swap', 'data-disk'].map((slot) => (
-          <Skeleton
-            key={slot}
-            className="h-28 rounded-[min(var(--radius-4xl),24px)]"
-          />
-        ))}
-      </div>
+      <section className="flex flex-col gap-4">
+        <div className="grid gap-4 sm:grid-cols-2 xl:grid-cols-4">
+          {['cpu', 'memory', 'swap', 'data-disk'].map(bones)}
+        </div>
+        <div className="grid gap-4 md:grid-cols-2">
+          {['sandboxes', 'sandbox-disks'].map(bones)}
+        </div>
+      </section>
     );
   }
 
diff --git a/packages/console/src/features/overview/pages/OverviewPage.tsx b/packages/console/src/features/overview/pages/OverviewPage.tsx
index ff26a2f..764fa74 100644
--- a/packages/console/src/features/overview/pages/OverviewPage.tsx
+++ b/packages/console/src/features/overview/pages/OverviewPage.tsx
@@ -8,7 +8,7 @@ export function OverviewPage() {
   return (
     <>
       <div>
-        <h1 className="text-lg font-semibold">总览</h1>
+        <h1 className="text-2xl font-semibold">总览</h1>
         <p className="text-sm text-muted-foreground">
           这台机器的健康状况,与沙箱群花掉的资源。
         </p>
diff --git a/packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx b/packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx
index 4cde883..5a5a633 100644
--- a/packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx
+++ b/packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx
@@ -158,7 +158,7 @@ export function FilePreviewDialog({
           </Empty>
         ) : content.isPending ? (
           <div className="flex items-center gap-2 text-sm text-muted-foreground">
-            <Spinner /> 读取文件…
+            <Spinner /> 读取文件
           </div>
         ) : (
           <Textarea
diff --git a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
index 1a374cd..d42b780 100644
--- a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
@@ -39,7 +39,7 @@ export function HistoryPanel({ externalId }: { externalId: string }) {
   if (isPending) {
     return (
       <div className="flex items-center gap-2 text-sm text-muted-foreground">
-        <Spinner /> 读取历史…
+        <Spinner /> 读取历史
       </div>
     );
   }
diff --git a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
index d24f311..d835609 100644
--- a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
@@ -191,7 +191,7 @@ export function MetricsPanel({ sandbox }: { sandbox: Sandbox }) {
   if (isPending) {
     return (
       <div className="flex items-center gap-2 text-sm text-muted-foreground">
-        <Spinner /> 读取指标…
+        <Spinner /> 读取指标
       </div>
     );
   }
diff --git a/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx b/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
index 7492599..2f32ca6 100644
--- a/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
+++ b/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
@@ -35,7 +35,7 @@ function LiveTerminal({ sandboxId }: { sandboxId: string }) {
     fit.fit();
     // Waking a stopped sandbox is a cold start — seconds, not ms. Say so
     // in the terminal itself instead of leaving a dead black box.
-    term.writeln('\x1b[2m连接中 — 沉睡的沙箱会先被唤醒…\x1b[0m');
+    term.writeln('\x1b[2m连接中 — 沉睡的沙箱会先被唤醒\x1b[0m');
 
     let session: PtySession | undefined;
     let cancelled = false;
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index 713713f..a73404b 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -91,7 +91,7 @@ export function SandboxDetailPage() {
     <>
       <div className="flex flex-wrap items-center justify-between gap-3">
         <div className="flex items-center gap-3">
-          <h1 className="font-mono text-lg font-semibold">
+          <h1 className="font-mono text-2xl font-semibold">
             {sandbox.externalId}
           </h1>
           <SandboxStateBadge state={sandbox.state} />
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index 420af7b..3b864e3 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -9,6 +9,7 @@ import { HugeiconsIcon } from '@hugeicons/react';
 import { Link } from '@tanstack/react-router';
 import { useMemo, useState } from 'react';
 import { toast } from 'sonner';
+import { FilterMenu } from '@/components/FilterMenu';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import {
   AlertDialog,
@@ -35,10 +36,6 @@ import {
   InputGroupAddon,
   InputGroupInput,
 } from '@/components/ui/input-group';
-import {
-  NativeSelect,
-  NativeSelectOption,
-} from '@/components/ui/native-select';
 import { Spinner } from '@/components/ui/spinner';
 import {
   Table,
@@ -167,7 +164,7 @@ function BulkDestroyButton({
     setPending(false);
     void queryClient.invalidateQueries({ queryKey: ['sandboxes'] });
     if (failures.length === 0) {
-      toast.success(`已销毁  个沙箱`);
+      toast.success(`已销毁 ${externalIds.length} 个沙箱`);
     } else {
       toast.error(`${failures.length} 个销毁失败:${failures.join('、')}`);
     }
@@ -269,7 +266,7 @@ export function SandboxesPage() {
     <>
       <div className="flex flex-wrap items-center justify-between gap-3">
         <div>
-          <h1 className="text-lg font-semibold">沙箱</h1>
+          <h1 className="text-2xl font-semibold">沙箱</h1>
           <p className="text-sm text-muted-foreground">
             账本里的全部沙箱,每 2 秒刷新 — 看着不会吵醒任何一个。
           </p>
@@ -291,20 +288,17 @@ export function SandboxesPage() {
             placeholder="按 externalId 搜索"
           />
         </InputGroup>
-        <NativeSelect
-          aria-label="按状态筛选"
-          value={stateFilter}
-          onChange={(event) =>
-            setStateFilter(event.target.value as 'all' | SandboxState)
+        <FilterMenu
+          label="状态"
+          value={stateFilter === 'all' ? '' : stateFilter}
+          options={STATE_FILTERS.map((state) => ({
+            value: state,
+            label: STATE_LABELS[state],
+          }))}
+          onChange={(value) =>
+            setStateFilter(value === '' ? 'all' : (value as SandboxState))
           }
-        >
-          <NativeSelectOption value="all">全部状态</NativeSelectOption>
-          {STATE_FILTERS.map((state) => (
-            <NativeSelectOption key={state} value={state}>
-              {STATE_LABELS[state]}
-            </NativeSelectOption>
-          ))}
-        </NativeSelect>
+        />
         <span className="text-sm text-muted-foreground">
           {filtered.length} / {sandboxes.length} 个
         </span>
@@ -348,9 +342,11 @@ export function SandboxesPage() {
       )}
 
       {filtered.length > 0 && (
-        <div className="overflow-x-auto rounded-lg border">
-          <Table>
-            <TableHeader>
+        // 限高让长列表在框内滚,表头 sticky 才有得贴 — 列名滚不丢。
+        <div className="max-h-[70vh] overflow-auto rounded-lg border">
+          {/* 行上的 transition-colors 在 2 秒轮询重渲下会微闪 — 关掉。 */}
+          <Table className="[&_tr]:transition-none">
+            <TableHeader className="sticky top-0 z-10 bg-background">
               <TableRow>
                 <TableHead className="w-10">
                   <Checkbox
diff --git a/packages/console/src/features/settings/pages/SettingsPage.tsx b/packages/console/src/features/settings/pages/SettingsPage.tsx
index 0e078d3..b149147 100644
--- a/packages/console/src/features/settings/pages/SettingsPage.tsx
+++ b/packages/console/src/features/settings/pages/SettingsPage.tsx
@@ -74,7 +74,7 @@ export function SettingsPage() {
   if (isPending) {
     return (
       <div className="flex items-center gap-2 text-sm text-muted-foreground">
-        <Spinner /> 读取生效配置…
+        <Spinner /> 读取生效配置
       </div>
     );
   }
@@ -90,9 +90,10 @@ export function SettingsPage() {
   }
 
   return (
-    <>
+    // 四列窄表,铺满宽屏一行字拉太长 — 限宽居中,读起来是一页文档。
+    <div className="mx-auto flex w-full max-w-4xl flex-col gap-4">
       <div>
-        <h1 className="text-lg font-semibold">设置</h1>
+        <h1 className="text-2xl font-semibold">设置</h1>
         <p className="text-sm text-muted-foreground">
           daemon 的生效配置,只读。改配置在主机的{' '}
           <code className="font-mono">/etc/dormice/env</code>,改完{' '}
@@ -138,6 +139,6 @@ export function SettingsPage() {
           </TableBody>
         </Table>
       </div>
-    </>
+    </div>
   );
 }
diff --git a/packages/console/src/features/templates/pages/TemplatesPage.tsx b/packages/console/src/features/templates/pages/TemplatesPage.tsx
index c3be251..ac32036 100644
--- a/packages/console/src/features/templates/pages/TemplatesPage.tsx
+++ b/packages/console/src/features/templates/pages/TemplatesPage.tsx
@@ -218,10 +218,11 @@ export function TemplatesPage() {
     sandboxes.filter((sandbox) => sandbox.template === name).length;
 
   return (
-    <>
+    // 五列窄表,同设置页限宽居中 — 宽屏上不摊大饼。
+    <div className="mx-auto flex w-full max-w-4xl flex-col gap-4">
       <div className="flex flex-wrap items-center justify-between gap-3">
         <div>
-          <h1 className="text-lg font-semibold">模板</h1>
+          <h1 className="text-2xl font-semibold">模板</h1>
           <p className="text-sm text-muted-foreground">
             模板 = 命名的 Docker 镜像。名字即 E2B 的 templateID,重新注册
             即升级。
@@ -316,6 +317,6 @@ export function TemplatesPage() {
           </Table>
         </div>
       )}
-    </>
+    </div>
   );
 }
diff --git a/packages/console/src/routes/__root.tsx b/packages/console/src/routes/__root.tsx
index cccb3c1..06d3abf 100644
--- a/packages/console/src/routes/__root.tsx
+++ b/packages/console/src/routes/__root.tsx
@@ -1,4 +1,5 @@
 import { createRootRoute, Outlet } from '@tanstack/react-router';
+import { RootErrorBoundary } from '@/components/RootErrorBoundary';
 import { Toaster } from '@/components/ui/sonner';
 
 export const Route = createRootRoute({
@@ -8,4 +9,6 @@ export const Route = createRootRoute({
       <Toaster />
     </>
   ),
+  // 漏网真异常(daemon 没起/500/渲染崩溃)的兜底,取代默认英文报错页。
+  errorComponent: RootErrorBoundary,
 });

From 2404eb28a5c1e0751d5c03bc61d0c87f163cf519 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 02:50:33 +0800
Subject: [PATCH 071/133] The console stops squinting at macOS: grayscale
 antialiasing joins the base layer, and medium finally weighs what Inter drew

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/console/src/index.css | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/packages/console/src/index.css b/packages/console/src/index.css
index c01d53b..5a98c4f 100644
--- a/packages/console/src/index.css
+++ b/packages/console/src/index.css
@@ -2,3 +2,11 @@
    owned by the shadcn CLI (rewritten wholesale by `shadcn apply`) — custom
    styles live here, never there. */
 @import "./shadcn.css";
+
+@layer base {
+  body {
+    /* macOS 浏览器默认亚像素渲染把字形描粗,medium/semibold 都显臃肿;
+       灰度平滑(antialiased)才是 Inter 设计稿上的粗细。 */
+    @apply antialiased;
+  }
+}

From 7424fb15ed647492c7d0bcf8afb73ade01fb5e9d Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 11:49:35 +0800
Subject: [PATCH 072/133] The wordmark drops its subtitle and dresses up:
 Dormice stands alone in Google Sans, one latin-600 subset deep

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/console/package.json                  | 1 +
 packages/console/src/components/AppSidebar.tsx | 7 ++++---
 packages/console/src/index.css                 | 4 ++++
 pnpm-lock.yaml                                 | 8 ++++++++
 4 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/packages/console/package.json b/packages/console/package.json
index 595d375..7f3fd27 100644
--- a/packages/console/package.json
+++ b/packages/console/package.json
@@ -14,6 +14,7 @@
   "dependencies": {
     "@base-ui/react": "^1.6.0",
     "@fontsource-variable/inter": "^5.2.8",
+    "@fontsource/google-sans": "^5.2.1",
     "@hugeicons/core-free-icons": "^4.2.2",
     "@hugeicons/react": "^1.1.9",
     "@shadcn/react": "^0.2.1",
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index 11c7008..2d75721 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -90,9 +90,10 @@ export function AppSidebar() {
     <Sidebar variant="inset" className="px-1">
       <SidebarHeader>
         {/* 纯文字 wordmark:侧栏融在页面底色里,不需要图标方块撑品牌。 */}
-        <Link to="/" className="flex items-baseline gap-1.5 px-2.5 pt-2 pb-1.5">
-          <span className="text-lg font-semibold leading-none">Dormice</span>
-          <span className="text-xs text-muted-foreground">控制台</span>
+        <Link to="/" className="flex items-center px-2.5 pt-2 pb-1.5">
+          <span className="text-lg font-semibold leading-none [font-family:'Google_Sans',sans-serif]">
+            Dormice
+          </span>
         </Link>
       </SidebarHeader>
 
diff --git a/packages/console/src/index.css b/packages/console/src/index.css
index 5a98c4f..61ca628 100644
--- a/packages/console/src/index.css
+++ b/packages/console/src/index.css
@@ -3,6 +3,10 @@
    styles live here, never there. */
 @import "./shadcn.css";
 
+/* Google Sans 只给品牌 wordmark(Dormice)用,只引 latin 600 子集控体积;
+   正文照旧 Inter(shadcn.css 里)。 */
+@import "@fontsource/google-sans/latin-600.css";
+
 @layer base {
   body {
     /* macOS 浏览器默认亚像素渲染把字形描粗,medium/semibold 都显臃肿;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6e88801..d704809 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -70,6 +70,9 @@ importers:
       '@fontsource-variable/inter':
         specifier: ^5.2.8
         version: 5.2.8
+      '@fontsource/google-sans':
+        specifier: ^5.2.1
+        version: 5.2.1
       '@hugeicons/core-free-icons':
         specifier: ^4.2.2
         version: 4.2.2
@@ -1399,6 +1402,9 @@ packages:
   '@fontsource-variable/inter@5.2.8':
     resolution: {integrity: sha512-kOfP2D+ykbcX/P3IFnokOhVRNoTozo5/JxhAIVYLpea/UBmCQ/YWPBfWIDuBImXX/15KH+eKh4xpEUyS2sQQGQ==}
 
+  '@fontsource/google-sans@5.2.1':
+    resolution: {integrity: sha512-FteXH18YS0288Bcrjefwyyp7hLwxd8yQBEcmjU/P0BED9c8n8kxwgna3gtMtYyFQx/wIkpyrzj8RaYQyl/4quw==}
+
   '@grpc/grpc-js@1.14.4':
     resolution: {integrity: sha512-k9Dj3DV/itK9D06Y8f190Qgop7/Ui+D0njFV3LHMPwPT75DpXLQohE9Wmz0QElrJnzsjB7KPWiKJbOl7IPDArQ==}
     engines: {node: '>=12.10.0'}
@@ -6527,6 +6533,8 @@ snapshots:
 
   '@fontsource-variable/inter@5.2.8': {}
 
+  '@fontsource/google-sans@5.2.1': {}
+
   '@grpc/grpc-js@1.14.4':
     dependencies:
       '@grpc/proto-loader': 0.8.1

From 6963adb061b4c1b7e5bee834ae1810373e93314b Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 11:53:12 +0800
Subject: [PATCH 073/133] =?UTF-8?q?The=20sidebar=20keeps=20its=20hands=20s?=
 =?UTF-8?q?till=20and=20the=20overview=20takes=20a=20new=20title:=20chrome?=
 =?UTF-8?q?=20cursors=20stop=20pointing,=20and=20=E6=80=BB=E8=A7=88=20beco?=
 =?UTF-8?q?mes=20=E4=BB=AA=E8=A1=A8=E7=9B=98=20in=20menu,=20breadcrumb,=20?=
 =?UTF-8?q?and=20heading=20alike?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/console/src/components/AppShell.tsx          |  2 +-
 packages/console/src/components/AppSidebar.tsx        | 11 ++++++++---
 .../src/features/overview/pages/OverviewPage.tsx      |  2 +-
 3 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/packages/console/src/components/AppShell.tsx b/packages/console/src/components/AppShell.tsx
index 99d6f95..b843d95 100644
--- a/packages/console/src/components/AppShell.tsx
+++ b/packages/console/src/components/AppShell.tsx
@@ -29,7 +29,7 @@ const SEGMENT_LABELS: Record<string, string> = {
 
 function crumbsOf(pathname: string): string[] {
   const segments = pathname.split('/').filter(Boolean);
-  if (segments.length === 0) return ['总览'];
+  if (segments.length === 0) return ['仪表盘'];
   return segments.map(
     (segment) => SEGMENT_LABELS[segment] ?? decodeURIComponent(segment),
   );
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index 2d75721..324c4b2 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -45,7 +45,7 @@ export const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
   {
     label: '平台',
     items: [
-      { to: '/', label: '总览', icon: DashboardSquare01Icon },
+      { to: '/', label: '仪表盘', icon: DashboardSquare01Icon },
       { to: '/sandboxes', label: '沙箱', icon: PackageIcon },
       { to: '/templates', label: '模板', icon: Layers01Icon },
     ],
@@ -73,7 +73,9 @@ async function signOut() {
 }
 
 // 侧栏按钮统一药丸形 + medium 字重(风格参考 openasi 侧栏,2026-07-12)。
-const menuButtonClass = 'rounded-full font-medium';
+// cursor-default 抹平 Link(手型)与 button(箭头)的光标分裂 — 侧栏是
+// 应用 chrome,不是网页链接。
+const menuButtonClass = 'rounded-full font-medium cursor-default';
 
 function isActivePath(pathname: string, to: string): boolean {
   if (to === '/') return pathname === '/';
@@ -90,7 +92,10 @@ export function AppSidebar() {
     <Sidebar variant="inset" className="px-1">
       <SidebarHeader>
         {/* 纯文字 wordmark:侧栏融在页面底色里,不需要图标方块撑品牌。 */}
-        <Link to="/" className="flex items-center px-2.5 pt-2 pb-1.5">
+        <Link
+          to="/"
+          className="flex cursor-default items-center px-2.5 pt-2 pb-1.5"
+        >
           <span className="text-lg font-semibold leading-none [font-family:'Google_Sans',sans-serif]">
             Dormice
           </span>
diff --git a/packages/console/src/features/overview/pages/OverviewPage.tsx b/packages/console/src/features/overview/pages/OverviewPage.tsx
index 764fa74..0916046 100644
--- a/packages/console/src/features/overview/pages/OverviewPage.tsx
+++ b/packages/console/src/features/overview/pages/OverviewPage.tsx
@@ -8,7 +8,7 @@ export function OverviewPage() {
   return (
     <>
       <div>
-        <h1 className="text-2xl font-semibold">总览</h1>
+        <h1 className="text-2xl font-semibold">仪表盘</h1>
         <p className="text-sm text-muted-foreground">
           这台机器的健康状况,与沙箱群花掉的资源。
         </p>

From 2a71b29d7ddafe8e142761f63b36d92a964afab1 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 11:54:43 +0800
Subject: [PATCH 074/133] The sidebar icons firm up their line: strokeWidth 2
 across nav, theme toggle, and logout

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/console/src/components/AppSidebar.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index 324c4b2..7abf696 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -120,7 +120,7 @@ export function AppSidebar() {
                         isActive={isActivePath(pathname, item.to)}
                         render={<Link to={item.to} />}
                       >
-                        <HugeiconsIcon icon={item.icon} strokeWidth={1.8} />
+                        <HugeiconsIcon icon={item.icon} strokeWidth={2} />
                         <span>{item.label}</span>
                       </SidebarMenuButton>
                       {item.mock && <SidebarMenuBadge>预览</SidebarMenuBadge>}
@@ -144,14 +144,14 @@ export function AppSidebar() {
             >
               <HugeiconsIcon
                 icon={resolvedTheme === 'dark' ? Sun02Icon : Moon02Icon}
-                strokeWidth={1.8}
+                strokeWidth={2}
               />
               <span>{resolvedTheme === 'dark' ? '浅色模式' : '深色模式'}</span>
             </SidebarMenuButton>
           </SidebarMenuItem>
           <SidebarMenuItem>
             <SidebarMenuButton className={menuButtonClass} onClick={signOut}>
-              <HugeiconsIcon icon={Logout01Icon} strokeWidth={1.8} />
+              <HugeiconsIcon icon={Logout01Icon} strokeWidth={2} />
               <span>退出登录</span>
             </SidebarMenuButton>
           </SidebarMenuItem>

From 629752aa13c69a8531e6a7c1c3eae8d3b0ffe66e Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 12:17:56 +0800
Subject: [PATCH 075/133] The tables learn one shared skin: every list sits on
 a card with room to breathe, numbers align right, and row actions fold into a
 quiet menu

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/console/src/components/DataTable.tsx |  38 ++
 .../features/activity/pages/ActivityPage.tsx  | 104 +++---
 .../components/DestroySandboxButton.tsx       |  48 ++-
 .../sandboxes/components/FilesPanel.tsx       | 204 ++++++-----
 .../sandboxes/components/HistoryPanel.tsx     |  72 ++--
 .../sandboxes/components/ProcessesPanel.tsx   |  88 +++--
 .../sandboxes/pages/SandboxesPage.tsx         | 326 +++++++++++-------
 .../features/settings/pages/SettingsPage.tsx  |  66 ++--
 .../templates/pages/TemplatesPage.tsx         | 222 +++++++-----
 9 files changed, 675 insertions(+), 493 deletions(-)
 create mode 100644 packages/console/src/components/DataTable.tsx

diff --git a/packages/console/src/components/DataTable.tsx b/packages/console/src/components/DataTable.tsx
new file mode 100644
index 0000000..dfa7f6d
--- /dev/null
+++ b/packages/console/src/components/DataTable.tsx
@@ -0,0 +1,38 @@
+import type * as React from 'react';
+import { Card } from '@/components/ui/card';
+import { Table } from '@/components/ui/table';
+import { cn } from '@/lib/utils';
+
+// 表格皮的唯一定义(参考 openasi 表格,2026-07-15 用户拍板):
+// - 表头 h-12、单元格 px-4 py-2.5,首末列 24px 边距 — 内容离卡面圆角有喘息
+// - 吸顶表头 bg-card 与卡面同色,滚动不穿帮;短表贴不到顶,无害
+// - 行动画一律关闭:2 秒轮询重渲下 transition-colors 会微闪
+const TABLE_CHROME =
+  '[&_tr]:transition-none [&_th]:h-12 [&_th]:px-4 [&_td]:px-4 [&_td]:py-2.5 [&_th:first-child]:pl-6 [&_td:first-child]:pl-6 [&_th:last-child]:pr-6 [&_td:last-child]:pr-6 [&_thead]:sticky [&_thead]:top-0 [&_thead]:z-10 [&_thead]:bg-card';
+
+/**
+ * 数据表外壳:卡面(bg-card + 大圆角 + ring)包一层滚动容器,再套统一
+ * 密度的 Table — 密度与边距只在这里定一次,全站表格共用,漂移无从发生。
+ * 长表传 containerClassName="max-h-[70vh]" 限高框内滚,吸顶表头才有得贴。
+ * vendored table.tsx 不动,覆写全在这一侧。
+ */
+export function DataTable({
+  containerClassName,
+  className,
+  ...props
+}: React.ComponentProps<typeof Table> & { containerClassName?: string }) {
+  return (
+    <Card className="p-0">
+      {/* vendored Table 自带 overflow-x-auto 内容器 — 把它放开,让这层
+          成为唯一滚动口:竖向吸顶与横向滚动发生在同一个容器上。 */}
+      <div
+        className={cn(
+          'overflow-auto [&_[data-slot=table-container]]:overflow-visible',
+          containerClassName,
+        )}
+      >
+        <Table className={cn(TABLE_CHROME, className)} {...props} />
+      </div>
+    </Card>
+  );
+}
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index 37ce55c..1c1ab1c 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -3,6 +3,7 @@ import { Search01Icon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
 import { Link } from '@tanstack/react-router';
 import { useMemo, useState } from 'react';
+import { DataTable } from '@/components/DataTable';
 import { FilterMenu } from '@/components/FilterMenu';
 import { Badge } from '@/components/ui/badge';
 import {
@@ -18,7 +19,6 @@ import {
 } from '@/components/ui/input-group';
 import { Spinner } from '@/components/ui/spinner';
 import {
-  Table,
   TableBody,
   TableCell,
   TableHead,
@@ -124,60 +124,58 @@ export function ActivityPage() {
           </EmptyHeader>
         </Empty>
       ) : (
-        // 环形记录上限 1000 条,是全站最长的表 — 限高框内滚,表头贴住。
-        <div className="max-h-[70vh] overflow-auto rounded-lg border">
-          <Table className="[&_tr]:transition-none">
-            <TableHeader className="sticky top-0 z-10 bg-background">
-              <TableRow>
-                <TableHead className="w-28">时间</TableHead>
-                <TableHead className="w-28">事件</TableHead>
-                <TableHead className="w-40">externalId</TableHead>
-                <TableHead>详情</TableHead>
-              </TableRow>
-            </TableHeader>
-            <TableBody>
-              {filtered.map((event) => (
-                <TableRow key={event.id}>
-                  <TableCell
-                    className="tabular-nums text-muted-foreground"
-                    // 相对时间好扫读,绝对时间才对得上日志 — hover 给后者。
-                    title={new Date(event.at).toLocaleString()}
+        // 环形记录上限 1000 条,是全站最长的表 — 限高框内滚,表头吸顶。
+        <DataTable containerClassName="max-h-[70vh]">
+          <TableHeader>
+            <TableRow>
+              <TableHead className="w-28">时间</TableHead>
+              <TableHead className="w-28">事件</TableHead>
+              <TableHead className="w-40">externalId</TableHead>
+              <TableHead>详情</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {filtered.map((event) => (
+              <TableRow key={event.id}>
+                <TableCell
+                  className="tabular-nums text-muted-foreground"
+                  // 相对时间好扫读,绝对时间才对得上日志 — hover 给后者。
+                  title={new Date(event.at).toLocaleString()}
+                >
+                  {since(event.at)}前
+                </TableCell>
+                <TableCell>
+                  <Badge
+                    variant="outline"
+                    className={cn(
+                      'font-medium',
+                      ACTIVITY_KIND_STYLES[event.kind],
+                    )}
                   >
-                    {since(event.at)}前
-                  </TableCell>
-                  <TableCell>
-                    <Badge
-                      variant="outline"
-                      className={cn(
-                        'font-medium',
-                        ACTIVITY_KIND_STYLES[event.kind],
-                      )}
+                    {ACTIVITY_KIND_LABELS[event.kind]}
+                  </Badge>
+                </TableCell>
+                <TableCell>
+                  {event.externalId ? (
+                    <Link
+                      to="/sandboxes/$externalId"
+                      params={{ externalId: event.externalId }}
+                      search={{ tab: 'overview' as const }}
+                      className="font-mono hover:underline"
                     >
-                      {ACTIVITY_KIND_LABELS[event.kind]}
-                    </Badge>
-                  </TableCell>
-                  <TableCell>
-                    {event.externalId ? (
-                      <Link
-                        to="/sandboxes/$externalId"
-                        params={{ externalId: event.externalId }}
-                        search={{ tab: 'overview' as const }}
-                        className="font-mono hover:underline"
-                      >
-                        {event.externalId}
-                      </Link>
-                    ) : (
-                      <span className="text-muted-foreground">—</span>
-                    )}
-                  </TableCell>
-                  <TableCell className="text-muted-foreground">
-                    {event.detail}
-                  </TableCell>
-                </TableRow>
-              ))}
-            </TableBody>
-          </Table>
-        </div>
+                      {event.externalId}
+                    </Link>
+                  ) : (
+                    <span className="text-muted-foreground">—</span>
+                  )}
+                </TableCell>
+                <TableCell className="text-muted-foreground">
+                  {event.detail}
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </DataTable>
       )}
     </>
   );
diff --git a/packages/console/src/features/sandboxes/components/DestroySandboxButton.tsx b/packages/console/src/features/sandboxes/components/DestroySandboxButton.tsx
index fd73f3b..5f9835e 100644
--- a/packages/console/src/features/sandboxes/components/DestroySandboxButton.tsx
+++ b/packages/console/src/features/sandboxes/components/DestroySandboxButton.tsx
@@ -1,3 +1,4 @@
+import { useState } from 'react';
 import { toast } from 'sonner';
 import {
   AlertDialog,
@@ -8,21 +9,26 @@ import {
   AlertDialogFooter,
   AlertDialogHeader,
   AlertDialogTitle,
-  AlertDialogTrigger,
 } from '@/components/ui/alert-dialog';
 import { Button } from '@/components/ui/button';
-import { Spinner } from '@/components/ui/spinner';
 import { useDestroySandbox } from '../hooks/useSandboxes';
 
 /**
  * Destroy removes the sandbox AND its disk — the one irreversible action in
- * the console, so it is the one action behind a confirmation dialog.
+ * the console, so it is the one action behind a confirmation dialog. The
+ * dialog is controlled: the detail page composes it with a red button below,
+ * table rows open it from a dropdown menu item (the menu unmounts on close,
+ * so the dialog must live outside it — a trigger inside would vanish).
  */
-export function DestroySandboxButton({
+export function DestroySandboxDialog({
   externalId,
+  open,
+  onOpenChange,
   onDestroyed,
 }: {
   externalId: string;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
   onDestroyed?: () => void;
 }) {
   const mutation = useDestroySandbox();
@@ -39,15 +45,7 @@ export function DestroySandboxButton({
     });
 
   return (
-    <AlertDialog>
-      <AlertDialogTrigger
-        render={
-          <Button variant="destructive" size="sm" disabled={mutation.isPending}>
-            {mutation.isPending && <Spinner />}
-            销毁
-          </Button>
-        }
-      />
+    <AlertDialog open={open} onOpenChange={onOpenChange}>
       <AlertDialogContent>
         <AlertDialogHeader>
           <AlertDialogTitle>销毁「{externalId}」?</AlertDialogTitle>
@@ -66,3 +64,27 @@ export function DestroySandboxButton({
     </AlertDialog>
   );
 }
+
+export function DestroySandboxButton({
+  externalId,
+  onDestroyed,
+}: {
+  externalId: string;
+  onDestroyed?: () => void;
+}) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button variant="destructive" size="sm" onClick={() => setOpen(true)}>
+        销毁
+      </Button>
+      <DestroySandboxDialog
+        externalId={externalId}
+        open={open}
+        onOpenChange={setOpen}
+        onDestroyed={onDestroyed}
+      />
+    </>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/components/FilesPanel.tsx b/packages/console/src/features/sandboxes/components/FilesPanel.tsx
index f3eafbd..7970560 100644
--- a/packages/console/src/features/sandboxes/components/FilesPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/FilesPanel.tsx
@@ -13,6 +13,7 @@ import {
 import { HugeiconsIcon } from '@hugeicons/react';
 import { Fragment, useRef, useState } from 'react';
 import { toast } from 'sonner';
+import { DataTable } from '@/components/DataTable';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import {
   AlertDialog,
@@ -55,7 +56,6 @@ import {
 import { Input } from '@/components/ui/input';
 import { Spinner } from '@/components/ui/spinner';
 import {
-  Table,
   TableBody,
   TableCell,
   TableHead,
@@ -290,113 +290,111 @@ export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
       )}
 
       {entries.length > 0 && (
-        <div className="overflow-x-auto rounded-lg border">
-          <Table>
-            <TableHeader>
-              <TableRow>
-                <TableHead>名称</TableHead>
-                <TableHead>大小</TableHead>
-                <TableHead>权限</TableHead>
-                <TableHead>修改时间</TableHead>
-                <TableHead className="w-12" />
-              </TableRow>
-            </TableHeader>
-            <TableBody>
-              {entries.map((entry) => {
-                const isDir = entry.type === 'FILE_TYPE_DIRECTORY';
-                return (
-                  <TableRow key={entry.path}>
-                    <TableCell>
-                      {isDir ? (
-                        <button
-                          type="button"
-                          className="inline-flex items-center gap-2 font-medium hover:underline"
-                          onClick={() => setPath(entry.path)}
-                        >
-                          <HugeiconsIcon
-                            icon={Folder01Icon}
-                            className="size-4 text-sky-500"
-                          />
-                          {entry.name}
-                        </button>
-                      ) : (
-                        <button
-                          type="button"
-                          className="inline-flex items-center gap-2 hover:underline"
-                          onClick={() => setViewing(entry)}
-                        >
-                          <HugeiconsIcon
-                            icon={File01Icon}
-                            className="size-4 text-muted-foreground"
-                          />
-                          {entry.name}
-                        </button>
-                      )}
-                    </TableCell>
-                    <TableCell className="tabular-nums text-muted-foreground">
-                      {isDir ? '—' : formatBytes(Number(entry.size))}
-                    </TableCell>
-                    <TableCell className="font-mono text-xs text-muted-foreground">
-                      {entry.permissions}
-                    </TableCell>
-                    <TableCell className="text-muted-foreground">
-                      {new Date(entry.modifiedTime).toLocaleString()}
-                    </TableCell>
-                    <TableCell>
-                      <DropdownMenu>
-                        <DropdownMenuTrigger
-                          render={
-                            <Button
-                              variant="ghost"
-                              size="icon-sm"
-                              aria-label={`${entry.name} 的操作`}
-                            >
-                              <HugeiconsIcon icon={MoreVerticalIcon} />
-                            </Button>
-                          }
+        <DataTable>
+          <TableHeader>
+            <TableRow>
+              <TableHead>名称</TableHead>
+              <TableHead className="text-right">大小</TableHead>
+              <TableHead>权限</TableHead>
+              <TableHead>修改时间</TableHead>
+              <TableHead className="w-12" />
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {entries.map((entry) => {
+              const isDir = entry.type === 'FILE_TYPE_DIRECTORY';
+              return (
+                <TableRow key={entry.path}>
+                  <TableCell>
+                    {isDir ? (
+                      <button
+                        type="button"
+                        className="inline-flex items-center gap-2 font-medium hover:underline"
+                        onClick={() => setPath(entry.path)}
+                      >
+                        <HugeiconsIcon
+                          icon={Folder01Icon}
+                          className="size-4 text-sky-500"
                         />
-                        <DropdownMenuContent align="end">
-                          {!isDir && (
-                            <DropdownMenuItem
-                              onClick={() =>
-                                mutations.download.mutate(
-                                  { path: entry.path, name: entry.name },
-                                  {
-                                    onError: (error) =>
-                                      toast.error(error.message),
-                                  },
-                                )
-                              }
-                            >
-                              <HugeiconsIcon icon={Download01Icon} />
-                              下载
-                            </DropdownMenuItem>
-                          )}
-                          <DropdownMenuItem
-                            onClick={() => {
-                              setRenaming(entry);
-                              setRenameTo(entry.name);
-                            }}
+                        {entry.name}
+                      </button>
+                    ) : (
+                      <button
+                        type="button"
+                        className="inline-flex items-center gap-2 hover:underline"
+                        onClick={() => setViewing(entry)}
+                      >
+                        <HugeiconsIcon
+                          icon={File01Icon}
+                          className="size-4 text-muted-foreground"
+                        />
+                        {entry.name}
+                      </button>
+                    )}
+                  </TableCell>
+                  <TableCell className="text-right tabular-nums text-muted-foreground">
+                    {isDir ? '—' : formatBytes(Number(entry.size))}
+                  </TableCell>
+                  <TableCell className="font-mono text-xs text-muted-foreground">
+                    {entry.permissions}
+                  </TableCell>
+                  <TableCell className="text-muted-foreground">
+                    {new Date(entry.modifiedTime).toLocaleString()}
+                  </TableCell>
+                  <TableCell>
+                    <DropdownMenu>
+                      <DropdownMenuTrigger
+                        render={
+                          <Button
+                            variant="ghost"
+                            size="icon-sm"
+                            aria-label={`${entry.name} 的操作`}
                           >
-                            <HugeiconsIcon icon={Edit02Icon} />
-                            重命名
-                          </DropdownMenuItem>
+                            <HugeiconsIcon icon={MoreVerticalIcon} />
+                          </Button>
+                        }
+                      />
+                      <DropdownMenuContent align="end">
+                        {!isDir && (
                           <DropdownMenuItem
-                            variant="destructive"
-                            onClick={() => setDeleting(entry)}
+                            onClick={() =>
+                              mutations.download.mutate(
+                                { path: entry.path, name: entry.name },
+                                {
+                                  onError: (error) =>
+                                    toast.error(error.message),
+                                },
+                              )
+                            }
                           >
-                            <HugeiconsIcon icon={Delete02Icon} />
-                            删除
+                            <HugeiconsIcon icon={Download01Icon} />
+                            下载
                           </DropdownMenuItem>
-                        </DropdownMenuContent>
-                      </DropdownMenu>
-                    </TableCell>
-                  </TableRow>
-                );
-              })}
-            </TableBody>
-          </Table>
-        </div>
+                        )}
+                        <DropdownMenuItem
+                          onClick={() => {
+                            setRenaming(entry);
+                            setRenameTo(entry.name);
+                          }}
+                        >
+                          <HugeiconsIcon icon={Edit02Icon} />
+                          重命名
+                        </DropdownMenuItem>
+                        <DropdownMenuItem
+                          variant="destructive"
+                          onClick={() => setDeleting(entry)}
+                        >
+                          <HugeiconsIcon icon={Delete02Icon} />
+                          删除
+                        </DropdownMenuItem>
+                      </DropdownMenuContent>
+                    </DropdownMenu>
+                  </TableCell>
+                </TableRow>
+              );
+            })}
+          </TableBody>
+        </DataTable>
       )}
 
       {/* 预览/编辑 */}
diff --git a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
index d42b780..a810025 100644
--- a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
@@ -1,5 +1,6 @@
 import { Clock01Icon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
+import { DataTable } from '@/components/DataTable';
 import { Badge } from '@/components/ui/badge';
 import {
   Empty,
@@ -10,7 +11,6 @@ import {
 } from '@/components/ui/empty';
 import { Spinner } from '@/components/ui/spinner';
 import {
-  Table,
   TableBody,
   TableCell,
   TableHead,
@@ -71,43 +71,41 @@ export function HistoryPanel({ externalId }: { externalId: string }) {
 
   return (
     <div className="flex flex-col gap-3">
-      <div className="overflow-x-auto rounded-lg border">
-        <Table>
-          <TableHeader>
-            <TableRow>
-              <TableHead className="w-28">时间</TableHead>
-              <TableHead className="w-28">事件</TableHead>
-              <TableHead>详情</TableHead>
-            </TableRow>
-          </TableHeader>
-          <TableBody>
-            {events.map((event) => (
-              <TableRow key={event.id}>
-                <TableCell
-                  className="tabular-nums text-muted-foreground"
-                  title={new Date(event.at).toLocaleString()}
+      <DataTable>
+        <TableHeader>
+          <TableRow>
+            <TableHead className="w-28">时间</TableHead>
+            <TableHead className="w-28">事件</TableHead>
+            <TableHead>详情</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {events.map((event) => (
+            <TableRow key={event.id}>
+              <TableCell
+                className="tabular-nums text-muted-foreground"
+                title={new Date(event.at).toLocaleString()}
+              >
+                {since(event.at)}前
+              </TableCell>
+              <TableCell>
+                <Badge
+                  variant="outline"
+                  className={cn(
+                    'font-medium',
+                    ACTIVITY_KIND_STYLES[event.kind],
+                  )}
                 >
-                  {since(event.at)}前
-                </TableCell>
-                <TableCell>
-                  <Badge
-                    variant="outline"
-                    className={cn(
-                      'font-medium',
-                      ACTIVITY_KIND_STYLES[event.kind],
-                    )}
-                  >
-                    {ACTIVITY_KIND_LABELS[event.kind]}
-                  </Badge>
-                </TableCell>
-                <TableCell className="text-muted-foreground">
-                  {event.detail}
-                </TableCell>
-              </TableRow>
-            ))}
-          </TableBody>
-        </Table>
-      </div>
+                  {ACTIVITY_KIND_LABELS[event.kind]}
+                </Badge>
+              </TableCell>
+              <TableCell className="text-muted-foreground">
+                {event.detail}
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </DataTable>
       <p className="text-sm text-muted-foreground">
         销毁沙箱后 key 会重新可用 — 这里可能同时看到新旧两代沙箱的事件。
       </p>
diff --git a/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx b/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
index 02f9ddf..2cf791c 100644
--- a/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
@@ -1,9 +1,16 @@
 import type { Sandbox } from '@dormice/shared';
-import { ListViewIcon } from '@hugeicons/core-free-icons';
+import { ListViewIcon, MoreVerticalIcon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
 import { toast } from 'sonner';
+import { DataTable } from '@/components/DataTable';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
 import {
   Empty,
   EmptyDescription,
@@ -12,7 +19,6 @@ import {
   EmptyTitle,
 } from '@/components/ui/empty';
 import {
-  Table,
   TableBody,
   TableCell,
   TableHead,
@@ -100,51 +106,61 @@ export function ProcessesPanel({ sandbox }: { sandbox: Sandbox }) {
       )}
 
       {list.length > 0 && (
-        <div className="overflow-x-auto rounded-lg border">
-          <Table>
-            <TableHeader>
-              <TableRow>
-                <TableHead className="w-20">PID</TableHead>
-                <TableHead>命令</TableHead>
-                <TableHead className="text-right">操作</TableHead>
-              </TableRow>
-            </TableHeader>
-            <TableBody>
-              {list.map((process) => (
-                <TableRow key={process.pid}>
-                  <TableCell className="tabular-nums">{process.pid}</TableCell>
-                  <TableCell className="max-w-md truncate font-mono text-xs">
-                    {[process.config.cmd, ...process.config.args].join(' ')}
-                  </TableCell>
-                  <TableCell className="text-right">
-                    <div className="inline-flex gap-1">
-                      <Button
-                        variant="outline"
-                        size="sm"
+        <DataTable>
+          <TableHeader>
+            <TableRow>
+              <TableHead className="w-20">PID</TableHead>
+              <TableHead>命令</TableHead>
+              <TableHead className="text-right">操作</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {list.map((process) => (
+              <TableRow key={process.pid}>
+                <TableCell className="tabular-nums">{process.pid}</TableCell>
+                <TableCell className="max-w-md truncate font-mono text-xs">
+                  {[process.config.cmd, ...process.config.args].join(' ')}
+                </TableCell>
+                <TableCell className="text-right">
+                  {/* 两个信号收进「⋯」菜单:SIGTERM 是常规请求,
+                        SIGKILL 不可拒绝 — 才配 destructive 红。 */}
+                  <DropdownMenu>
+                    <DropdownMenuTrigger
+                      render={
+                        <Button
+                          variant="ghost"
+                          size="icon-sm"
+                          aria-label={`进程 ${process.pid} 的操作`}
+                        >
+                          <HugeiconsIcon icon={MoreVerticalIcon} />
+                        </Button>
+                      }
+                    />
+                    <DropdownMenuContent align="end">
+                      <DropdownMenuItem
                         disabled={kill.isPending}
                         onClick={() =>
                           sendSignal(process.pid, 'SIGNAL_SIGTERM')
                         }
                       >
-                        SIGTERM
-                      </Button>
-                      <Button
+                        发送 SIGTERM
+                      </DropdownMenuItem>
+                      <DropdownMenuItem
                         variant="destructive"
-                        size="sm"
                         disabled={kill.isPending}
                         onClick={() =>
                           sendSignal(process.pid, 'SIGNAL_SIGKILL')
                         }
                       >
-                        SIGKILL
-                      </Button>
-                    </div>
-                  </TableCell>
-                </TableRow>
-              ))}
-            </TableBody>
-          </Table>
-        </div>
+                        发送 SIGKILL
+                      </DropdownMenuItem>
+                    </DropdownMenuContent>
+                  </DropdownMenu>
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </DataTable>
       )}
     </div>
   );
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index 3b864e3..f5625e3 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -2,6 +2,9 @@ import type { Sandbox, SandboxState } from '@dormice/shared';
 import {
   ArrowDown01Icon,
   ArrowUp01Icon,
+  Copy01Icon,
+  Delete02Icon,
+  MoreVerticalIcon,
   PackageIcon,
   Search01Icon,
 } from '@hugeicons/core-free-icons';
@@ -9,6 +12,7 @@ import { HugeiconsIcon } from '@hugeicons/react';
 import { Link } from '@tanstack/react-router';
 import { useMemo, useState } from 'react';
 import { toast } from 'sonner';
+import { DataTable } from '@/components/DataTable';
 import { FilterMenu } from '@/components/FilterMenu';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import {
@@ -24,6 +28,12 @@ import {
 } from '@/components/ui/alert-dialog';
 import { Button } from '@/components/ui/button';
 import { Checkbox } from '@/components/ui/checkbox';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
 import {
   Empty,
   EmptyDescription,
@@ -38,7 +48,6 @@ import {
 } from '@/components/ui/input-group';
 import { Spinner } from '@/components/ui/spinner';
 import {
-  Table,
   TableBody,
   TableCell,
   TableHead,
@@ -50,7 +59,7 @@ import { formatBytes, pctOf } from '@/lib/format';
 import { queryClient } from '@/lib/queryClient';
 import { cn } from '@/lib/utils';
 import { CreateSandboxDialog } from '../components/CreateSandboxDialog';
-import { DestroySandboxButton } from '../components/DestroySandboxButton';
+import { DestroySandboxDialog } from '../components/DestroySandboxButton';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
 import { UpgradableBadge } from '../components/UpgradableBadge';
 import { policyLine, STATE_LABELS, since } from '../format';
@@ -86,12 +95,14 @@ function UsageCell({
   title?: string;
 }) {
   if (value === null) {
-    return <TableCell className="text-muted-foreground">—</TableCell>;
+    return (
+      <TableCell className="text-right text-muted-foreground">—</TableCell>
+    );
   }
   return (
     <TableCell
       className={cn(
-        'tabular-nums',
+        'text-right tabular-nums',
         pct >= 90
           ? 'text-red-600 dark:text-red-400'
           : pct >= 75
@@ -138,6 +149,56 @@ function SortableHead({
   );
 }
 
+/**
+ * 行操作收进「⋯」菜单(风格参考 openasi 表格,2026-07-15):每行一个
+ * 安静的 ghost 图标,不是一排常驻按钮。销毁的确认弹窗挂在菜单外 —
+ * 菜单关闭即卸载,弹窗放里面会跟着消失。
+ */
+function SandboxRowMenu({ externalId }: { externalId: string }) {
+  const [confirmOpen, setConfirmOpen] = useState(false);
+
+  return (
+    <>
+      <DropdownMenu>
+        <DropdownMenuTrigger
+          render={
+            <Button
+              variant="ghost"
+              size="icon-sm"
+              aria-label={`${externalId} 的操作`}
+            >
+              <HugeiconsIcon icon={MoreVerticalIcon} />
+            </Button>
+          }
+        />
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem
+            onClick={async () => {
+              await navigator.clipboard.writeText(externalId);
+              toast.success('externalId 已复制');
+            }}
+          >
+            <HugeiconsIcon icon={Copy01Icon} />
+            复制 externalId
+          </DropdownMenuItem>
+          <DropdownMenuItem
+            variant="destructive"
+            onClick={() => setConfirmOpen(true)}
+          >
+            <HugeiconsIcon icon={Delete02Icon} />
+            销毁
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      <DestroySandboxDialog
+        externalId={externalId}
+        open={confirmOpen}
+        onOpenChange={setConfirmOpen}
+      />
+    </>
+  );
+}
+
 /**
  * 批量销毁:逐个调用 destroySandbox(daemon 的 per-key 锁本来就是逐个
  * 裁决的,并发只是把失败搅在一起),结束后一次性汇报成败。
@@ -342,143 +403,140 @@ export function SandboxesPage() {
       )}
 
       {filtered.length > 0 && (
-        // 限高让长列表在框内滚,表头 sticky 才有得贴 — 列名滚不丢。
-        <div className="max-h-[70vh] overflow-auto rounded-lg border">
-          {/* 行上的 transition-colors 在 2 秒轮询重渲下会微闪 — 关掉。 */}
-          <Table className="[&_tr]:transition-none">
-            <TableHeader className="sticky top-0 z-10 bg-background">
-              <TableRow>
-                <TableHead className="w-10">
+        // 限高让长列表在框内滚,表头吸顶 — 列名滚不丢。
+        <DataTable containerClassName="max-h-[70vh]">
+          <TableHeader>
+            <TableRow>
+              <TableHead className="w-0">
+                <Checkbox
+                  aria-label="全选"
+                  checked={allVisibleSelected}
+                  onCheckedChange={toggleAll}
+                />
+              </TableHead>
+              <TableHead>
+                <SortableHead
+                  label="externalId"
+                  sortKey="externalId"
+                  sort={sort}
+                  onSort={toggleSort}
+                />
+              </TableHead>
+              <TableHead>状态</TableHead>
+              <TableHead>模板</TableHead>
+              <TableHead className="text-right">CPU</TableHead>
+              <TableHead className="text-right">内存</TableHead>
+              <TableHead className="text-right">磁盘</TableHead>
+              <TableHead>
+                {/* 升序 = 最久没动的排最前:回收磁盘时先看这里。 */}
+                <SortableHead
+                  label="空闲"
+                  sortKey="lastActiveAt"
+                  sort={sort}
+                  onSort={toggleSort}
+                />
+              </TableHead>
+              <TableHead>生命周期策略</TableHead>
+              <TableHead>
+                <SortableHead
+                  label="存活"
+                  sortKey="createdAt"
+                  sort={sort}
+                  onSort={toggleSort}
+                />
+              </TableHead>
+              <TableHead className="text-right">操作</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {filtered.map((sandbox: Sandbox) => (
+              <TableRow
+                key={sandbox.sandboxId}
+                data-state={
+                  selected.has(sandbox.externalId) ? 'selected' : undefined
+                }
+              >
+                <TableCell>
                   <Checkbox
-                    aria-label="全选"
-                    checked={allVisibleSelected}
-                    onCheckedChange={toggleAll}
-                  />
-                </TableHead>
-                <TableHead>
-                  <SortableHead
-                    label="externalId"
-                    sortKey="externalId"
-                    sort={sort}
-                    onSort={toggleSort}
-                  />
-                </TableHead>
-                <TableHead>状态</TableHead>
-                <TableHead>模板</TableHead>
-                <TableHead>CPU</TableHead>
-                <TableHead>内存</TableHead>
-                <TableHead>磁盘</TableHead>
-                <TableHead>
-                  {/* 升序 = 最久没动的排最前:回收磁盘时先看这里。 */}
-                  <SortableHead
-                    label="空闲"
-                    sortKey="lastActiveAt"
-                    sort={sort}
-                    onSort={toggleSort}
+                    aria-label={`选中 ${sandbox.externalId}`}
+                    checked={selected.has(sandbox.externalId)}
+                    onCheckedChange={() => toggleOne(sandbox.externalId)}
                   />
-                </TableHead>
-                <TableHead>生命周期策略</TableHead>
-                <TableHead>
-                  <SortableHead
-                    label="存活"
-                    sortKey="createdAt"
-                    sort={sort}
-                    onSort={toggleSort}
-                  />
-                </TableHead>
-                <TableHead className="text-right">操作</TableHead>
-              </TableRow>
-            </TableHeader>
-            <TableBody>
-              {filtered.map((sandbox: Sandbox) => (
-                <TableRow
-                  key={sandbox.sandboxId}
-                  data-state={
-                    selected.has(sandbox.externalId) ? 'selected' : undefined
-                  }
-                >
-                  <TableCell>
-                    <Checkbox
-                      aria-label={`选中 ${sandbox.externalId}`}
-                      checked={selected.has(sandbox.externalId)}
-                      onCheckedChange={() => toggleOne(sandbox.externalId)}
+                </TableCell>
+                <TableCell>
+                  <Link
+                    to="/sandboxes/$externalId"
+                    params={{ externalId: sandbox.externalId }}
+                    search={{ tab: 'overview' }}
+                    className="font-mono font-medium hover:underline"
+                  >
+                    {sandbox.externalId}
+                  </Link>
+                </TableCell>
+                <TableCell>
+                  <SandboxStateBadge state={sandbox.state} />
+                </TableCell>
+                <TableCell className="text-muted-foreground">
+                  <span className="inline-flex items-center gap-1.5">
+                    {sandbox.template ?? '基础镜像'}
+                    <UpgradableBadge
+                      lineage={lineageOf.get(sandbox.externalId)}
                     />
-                  </TableCell>
-                  <TableCell>
-                    <Link
-                      to="/sandboxes/$externalId"
-                      params={{ externalId: sandbox.externalId }}
-                      search={{ tab: 'overview' }}
-                      className="font-mono font-medium hover:underline"
-                    >
-                      {sandbox.externalId}
-                    </Link>
-                  </TableCell>
-                  <TableCell>
-                    <SandboxStateBadge state={sandbox.state} />
-                  </TableCell>
-                  <TableCell className="text-muted-foreground">
-                    <span className="inline-flex items-center gap-1.5">
-                      {sandbox.template ?? '基础镜像'}
-                      <UpgradableBadge
-                        lineage={lineageOf.get(sandbox.externalId)}
-                      />
-                    </span>
-                  </TableCell>
-                  {(() => {
-                    const m = metricsOf.get(sandbox.externalId);
-                    if (!m) {
-                      return (
-                        <>
-                          <UsageCell value={null} pct={0} />
-                          <UsageCell value={null} pct={0} />
-                          <UsageCell value={null} pct={0} />
-                        </>
-                      );
-                    }
+                  </span>
+                </TableCell>
+                {(() => {
+                  const m = metricsOf.get(sandbox.externalId);
+                  if (!m) {
                     return (
                       <>
-                        <UsageCell
-                          value={`${Math.round(m.cpuUsedPct)}%`}
-                          pct={m.cpuUsedPct / m.cpuCount}
-                          title={`${m.cpuCount} 核 · 百分比按单核计`}
-                        />
-                        <UsageCell
-                          value={formatBytes(m.memUsedBytes)}
-                          pct={pctOf(m.memUsedBytes, m.memTotalBytes)}
-                          title={`共 ${formatBytes(m.memTotalBytes)}`}
-                        />
-                        <UsageCell
-                          value={formatBytes(m.diskUsedBytes)}
-                          pct={pctOf(m.diskUsedBytes, m.diskTotalBytes)}
-                          title={`名义 ${formatBytes(m.diskTotalBytes)}`}
-                        />
+                        <UsageCell value={null} pct={0} />
+                        <UsageCell value={null} pct={0} />
+                        <UsageCell value={null} pct={0} />
                       </>
                     );
-                  })()}
-                  <TableCell
-                    className="tabular-nums text-muted-foreground"
-                    title={`最近活动:${new Date(sandbox.lastActiveAt).toLocaleString()}`}
-                  >
-                    {since(sandbox.lastActiveAt)}
-                  </TableCell>
-                  <TableCell className="text-xs text-muted-foreground">
-                    {policyLine(sandbox.policy)}
-                  </TableCell>
-                  <TableCell
-                    className="tabular-nums text-muted-foreground"
-                    title={`创建于:${new Date(sandbox.createdAt).toLocaleString()}`}
-                  >
-                    {since(sandbox.createdAt)}
-                  </TableCell>
-                  <TableCell className="text-right">
-                    <DestroySandboxButton externalId={sandbox.externalId} />
-                  </TableCell>
-                </TableRow>
-              ))}
-            </TableBody>
-          </Table>
-        </div>
+                  }
+                  return (
+                    <>
+                      <UsageCell
+                        value={`${Math.round(m.cpuUsedPct)}%`}
+                        pct={m.cpuUsedPct / m.cpuCount}
+                        title={`${m.cpuCount} 核 · 百分比按单核计`}
+                      />
+                      <UsageCell
+                        value={formatBytes(m.memUsedBytes)}
+                        pct={pctOf(m.memUsedBytes, m.memTotalBytes)}
+                        title={`共 ${formatBytes(m.memTotalBytes)}`}
+                      />
+                      <UsageCell
+                        value={formatBytes(m.diskUsedBytes)}
+                        pct={pctOf(m.diskUsedBytes, m.diskTotalBytes)}
+                        title={`名义 ${formatBytes(m.diskTotalBytes)}`}
+                      />
+                    </>
+                  );
+                })()}
+                <TableCell
+                  className="tabular-nums text-muted-foreground"
+                  title={`最近活动:${new Date(sandbox.lastActiveAt).toLocaleString()}`}
+                >
+                  {since(sandbox.lastActiveAt)}
+                </TableCell>
+                <TableCell className="text-xs text-muted-foreground">
+                  {policyLine(sandbox.policy)}
+                </TableCell>
+                <TableCell
+                  className="tabular-nums text-muted-foreground"
+                  title={`创建于:${new Date(sandbox.createdAt).toLocaleString()}`}
+                >
+                  {since(sandbox.createdAt)}
+                </TableCell>
+                <TableCell className="text-right">
+                  <SandboxRowMenu externalId={sandbox.externalId} />
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </DataTable>
       )}
     </>
   );
diff --git a/packages/console/src/features/settings/pages/SettingsPage.tsx b/packages/console/src/features/settings/pages/SettingsPage.tsx
index b149147..340e999 100644
--- a/packages/console/src/features/settings/pages/SettingsPage.tsx
+++ b/packages/console/src/features/settings/pages/SettingsPage.tsx
@@ -1,4 +1,5 @@
 import type { ConfigEntry } from '@dormice/shared';
+import { DataTable } from '@/components/DataTable';
 import { Badge } from '@/components/ui/badge';
 import {
   Empty,
@@ -8,7 +9,6 @@ import {
 } from '@/components/ui/empty';
 import { Spinner } from '@/components/ui/spinner';
 import {
-  Table,
   TableBody,
   TableCell,
   TableHead,
@@ -105,40 +105,38 @@ export function SettingsPage() {
         </p>
       </div>
 
-      <div className="overflow-x-auto rounded-lg border">
-        <Table>
-          <TableHeader>
-            <TableRow>
-              <TableHead>旋钮</TableHead>
-              <TableHead>生效值</TableHead>
-              <TableHead>来源</TableHead>
-              <TableHead>说明</TableHead>
+      <DataTable>
+        <TableHeader>
+          <TableRow>
+            <TableHead>旋钮</TableHead>
+            <TableHead>生效值</TableHead>
+            <TableHead>来源</TableHead>
+            <TableHead>说明</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {data.entries.map((entry) => (
+            <TableRow key={entry.key}>
+              <TableCell className="font-mono text-xs font-medium">
+                {entry.key}
+              </TableCell>
+              <TableCell className="font-mono text-xs">
+                <ValueCell entry={entry} />
+              </TableCell>
+              <TableCell>
+                <Badge
+                  variant={entry.source === 'env' ? 'outline' : 'secondary'}
+                >
+                  {entry.source === 'env' ? '环境变量' : '默认值'}
+                </Badge>
+              </TableCell>
+              <TableCell className="text-sm text-muted-foreground">
+                {KEY_HINTS[entry.key] ?? ''}
+              </TableCell>
             </TableRow>
-          </TableHeader>
-          <TableBody>
-            {data.entries.map((entry) => (
-              <TableRow key={entry.key}>
-                <TableCell className="font-mono text-xs font-medium">
-                  {entry.key}
-                </TableCell>
-                <TableCell className="font-mono text-xs">
-                  <ValueCell entry={entry} />
-                </TableCell>
-                <TableCell>
-                  <Badge
-                    variant={entry.source === 'env' ? 'outline' : 'secondary'}
-                  >
-                    {entry.source === 'env' ? '环境变量' : '默认值'}
-                  </Badge>
-                </TableCell>
-                <TableCell className="text-sm text-muted-foreground">
-                  {KEY_HINTS[entry.key] ?? ''}
-                </TableCell>
-              </TableRow>
-            ))}
-          </TableBody>
-        </Table>
-      </div>
+          ))}
+        </TableBody>
+      </DataTable>
     </div>
   );
 }
diff --git a/packages/console/src/features/templates/pages/TemplatesPage.tsx b/packages/console/src/features/templates/pages/TemplatesPage.tsx
index ac32036..aa9750f 100644
--- a/packages/console/src/features/templates/pages/TemplatesPage.tsx
+++ b/packages/console/src/features/templates/pages/TemplatesPage.tsx
@@ -1,9 +1,16 @@
 import type { Template } from '@dormice/shared';
-import { Add01Icon, Layers01Icon } from '@hugeicons/core-free-icons';
+import {
+  Add01Icon,
+  Delete02Icon,
+  Edit02Icon,
+  Layers01Icon,
+  MoreVerticalIcon,
+} from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
 import { Link } from '@tanstack/react-router';
 import { useState } from 'react';
 import { toast } from 'sonner';
+import { DataTable } from '@/components/DataTable';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import {
   AlertDialog,
@@ -14,7 +21,6 @@ import {
   AlertDialogFooter,
   AlertDialogHeader,
   AlertDialogTitle,
-  AlertDialogTrigger,
 } from '@/components/ui/alert-dialog';
 import { Button } from '@/components/ui/button';
 import {
@@ -26,6 +32,12 @@ import {
   DialogTitle,
   DialogTrigger,
 } from '@/components/ui/dialog';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
 import {
   Empty,
   EmptyDescription,
@@ -43,7 +55,6 @@ import {
 import { Input } from '@/components/ui/input';
 import { Spinner } from '@/components/ui/spinner';
 import {
-  Table,
   TableBody,
   TableCell,
   TableHead,
@@ -61,32 +72,39 @@ import {
 /**
  * 注册/升级共用一个对话框:模板是 upsert,对已有名字注册就是把它指向
  * 新镜像 — 那正是升级的正门(升级完对引用它的沙箱逐个 rebuild)。
+ * 页头用 trigger 形态;表格行从「⋯」菜单打开,传受控 open — 菜单关闭
+ * 即卸载,trigger 放里面会跟着消失。
  */
 function RegisterTemplateDialog({
   trigger,
   initial,
+  open: controlledOpen,
+  onOpenChange,
 }: {
-  trigger: React.ReactElement;
+  trigger?: React.ReactElement;
   initial?: Template;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
 }) {
-  const [open, setOpen] = useState(false);
+  const [internalOpen, setInternalOpen] = useState(false);
+  const open = controlledOpen ?? internalOpen;
   const [name, setName] = useState(initial?.name ?? '');
   const [image, setImage] = useState(initial?.image ?? '');
   const mutation = useRegisterTemplate();
 
+  const setOpen = (next: boolean) => {
+    if (controlledOpen === undefined) setInternalOpen(next);
+    onOpenChange?.(next);
+    if (next) {
+      setName(initial?.name ?? '');
+      setImage(initial?.image ?? '');
+      mutation.reset();
+    }
+  };
+
   return (
-    <Dialog
-      open={open}
-      onOpenChange={(next) => {
-        setOpen(next);
-        if (next) {
-          setName(initial?.name ?? '');
-          setImage(initial?.image ?? '');
-          mutation.reset();
-        }
-      }}
-    >
-      <DialogTrigger render={trigger} />
+    <Dialog open={open} onOpenChange={setOpen}>
+      {trigger && <DialogTrigger render={trigger} />}
       <DialogContent className="sm:max-w-md">
         <DialogHeader>
           <DialogTitle>
@@ -164,7 +182,15 @@ function RegisterTemplateDialog({
   );
 }
 
-function RemoveTemplateButton({ name }: { name: string }) {
+function RemoveTemplateDialog({
+  name,
+  open,
+  onOpenChange,
+}: {
+  name: string;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
   const mutation = useRemoveTemplate();
 
   const remove = () =>
@@ -178,15 +204,7 @@ function RemoveTemplateButton({ name }: { name: string }) {
     });
 
   return (
-    <AlertDialog>
-      <AlertDialogTrigger
-        render={
-          <Button variant="destructive" size="sm" disabled={mutation.isPending}>
-            {mutation.isPending && <Spinner />}
-            删除
-          </Button>
-        }
-      />
+    <AlertDialog open={open} onOpenChange={onOpenChange}>
       <AlertDialogContent>
         <AlertDialogHeader>
           <AlertDialogTitle>删除模板「{name}」?</AlertDialogTitle>
@@ -205,6 +223,56 @@ function RemoveTemplateButton({ name }: { name: string }) {
   );
 }
 
+/**
+ * 行操作收进「⋯」菜单(风格参考 openasi 表格,2026-07-15):两个弹窗都
+ * 挂在菜单外受控 — 菜单关闭即卸载,放里面会跟着消失。
+ */
+function TemplateRowMenu({ template }: { template: Template }) {
+  const [editOpen, setEditOpen] = useState(false);
+  const [removeOpen, setRemoveOpen] = useState(false);
+
+  return (
+    <>
+      <DropdownMenu>
+        <DropdownMenuTrigger
+          render={
+            <Button
+              variant="ghost"
+              size="icon-sm"
+              aria-label={`${template.name} 的操作`}
+            >
+              <HugeiconsIcon icon={MoreVerticalIcon} />
+            </Button>
+          }
+        />
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem onClick={() => setEditOpen(true)}>
+            <HugeiconsIcon icon={Edit02Icon} />
+            更新镜像
+          </DropdownMenuItem>
+          <DropdownMenuItem
+            variant="destructive"
+            onClick={() => setRemoveOpen(true)}
+          >
+            <HugeiconsIcon icon={Delete02Icon} />
+            删除
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      <RegisterTemplateDialog
+        initial={template}
+        open={editOpen}
+        onOpenChange={setEditOpen}
+      />
+      <RemoveTemplateDialog
+        name={template.name}
+        open={removeOpen}
+        onOpenChange={setRemoveOpen}
+      />
+    </>
+  );
+}
+
 /**
  * 模板注册表:名字 → 镜像的账本行。宿主机的 Docker daemon 就是镜像库,
  * 这一页管的只是指向;引用数从 2 秒轮询的沙箱列表现算,不发明新端点。
@@ -260,62 +328,50 @@ export function TemplatesPage() {
       )}
 
       {list.length > 0 && (
-        <div className="overflow-x-auto rounded-lg border">
-          <Table>
-            <TableHeader>
-              <TableRow>
-                <TableHead>名字</TableHead>
-                <TableHead>镜像</TableHead>
-                <TableHead>引用沙箱</TableHead>
-                <TableHead>注册于</TableHead>
-                <TableHead className="text-right">操作</TableHead>
-              </TableRow>
-            </TableHeader>
-            <TableBody>
-              {list.map((template) => {
-                const references = referenceCount(template.name);
-                return (
-                  <TableRow key={template.name}>
-                    <TableCell className="font-mono font-medium">
-                      {template.name}
-                    </TableCell>
-                    <TableCell className="font-mono text-muted-foreground">
-                      {template.image}
-                    </TableCell>
-                    <TableCell className="tabular-nums">
-                      {references > 0 ? (
-                        <Link
-                          to="/sandboxes"
-                          className="text-foreground hover:underline"
-                        >
-                          {references} 个
-                        </Link>
-                      ) : (
-                        <span className="text-muted-foreground">0 个</span>
-                      )}
-                    </TableCell>
-                    <TableCell className="tabular-nums text-muted-foreground">
-                      {since(template.createdAt)}前
-                    </TableCell>
-                    <TableCell className="text-right">
-                      <div className="inline-flex gap-2">
-                        <RegisterTemplateDialog
-                          initial={template}
-                          trigger={
-                            <Button variant="outline" size="sm">
-                              更新镜像
-                            </Button>
-                          }
-                        />
-                        <RemoveTemplateButton name={template.name} />
-                      </div>
-                    </TableCell>
-                  </TableRow>
-                );
-              })}
-            </TableBody>
-          </Table>
-        </div>
+        <DataTable>
+          <TableHeader>
+            <TableRow>
+              <TableHead>名字</TableHead>
+              <TableHead>镜像</TableHead>
+              <TableHead className="text-right">引用沙箱</TableHead>
+              <TableHead>注册于</TableHead>
+              <TableHead className="text-right">操作</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {list.map((template) => {
+              const references = referenceCount(template.name);
+              return (
+                <TableRow key={template.name}>
+                  <TableCell className="font-mono font-medium">
+                    {template.name}
+                  </TableCell>
+                  <TableCell className="font-mono text-muted-foreground">
+                    {template.image}
+                  </TableCell>
+                  <TableCell className="text-right tabular-nums">
+                    {references > 0 ? (
+                      <Link
+                        to="/sandboxes"
+                        className="text-foreground hover:underline"
+                      >
+                        {references} 个
+                      </Link>
+                    ) : (
+                      <span className="text-muted-foreground">0 个</span>
+                    )}
+                  </TableCell>
+                  <TableCell className="tabular-nums text-muted-foreground">
+                    {since(template.createdAt)}前
+                  </TableCell>
+                  <TableCell className="text-right">
+                    <TemplateRowMenu template={template} />
+                  </TableCell>
+                </TableRow>
+              );
+            })}
+          </TableBody>
+        </DataTable>
       )}
     </div>
   );

From a36faec24ff15a54273bf171f8023c9dae8f5e5f Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 17:32:07 +0800
Subject: [PATCH 076/133] The daemon learns to answer who it is and what main
 has that it lacks: tsup bakes the build commit into dist, checkUpgrade
 fetches through the checkout's own origin and adjudicates upgradable
 server-side, and the settings page grows a version card with the changelog
 preview

---
 .../settings/components/VersionCard.tsx       | 153 ++++++++++++++++++
 .../src/features/settings/hooks/useUpgrade.ts |  25 +++
 .../features/settings/pages/SettingsPage.tsx  |   3 +
 packages/console/src/lib/api.ts               |   7 +
 packages/console/vite.config.ts               |   1 +
 packages/sdk/src/client.ts                    |  20 +++
 packages/server/package.json                  |   2 +-
 packages/server/src/app.ts                    |  13 ++
 packages/server/src/main.ts                   |  20 +++
 packages/server/src/routes/upgrade.ts         |  32 ++++
 packages/server/src/updater.test.ts           | 146 +++++++++++++++++
 packages/server/src/updater.ts                | 141 ++++++++++++++++
 packages/server/src/version.ts                |  23 +++
 packages/server/tsup.config.ts                |  40 +++++
 packages/shared/src/index.ts                  |   1 +
 packages/shared/src/upgrade.ts                |  78 +++++++++
 16 files changed, 704 insertions(+), 1 deletion(-)
 create mode 100644 packages/console/src/features/settings/components/VersionCard.tsx
 create mode 100644 packages/console/src/features/settings/hooks/useUpgrade.ts
 create mode 100644 packages/server/src/routes/upgrade.ts
 create mode 100644 packages/server/src/updater.test.ts
 create mode 100644 packages/server/src/updater.ts
 create mode 100644 packages/server/src/version.ts
 create mode 100644 packages/server/tsup.config.ts
 create mode 100644 packages/shared/src/upgrade.ts

diff --git a/packages/console/src/features/settings/components/VersionCard.tsx b/packages/console/src/features/settings/components/VersionCard.tsx
new file mode 100644
index 0000000..c8241f8
--- /dev/null
+++ b/packages/console/src/features/settings/components/VersionCard.tsx
@@ -0,0 +1,153 @@
+import type { CheckUpgradeResponse } from '@dormice/shared';
+import { RefreshIcon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import { Spinner } from '@/components/ui/spinner';
+import { useCheckUpgrade, useForceCheckUpgrade } from '../hooks/useUpgrade';
+
+/**
+ * daemon 自己的版本与升级窗口。「版本」= 构建进 dist 的 git commit
+ * (还没有发版 tag,main 上每个提交都过验收链);比较由 daemon 服务端
+ * 裁决(upgradable 字段),这里只负责显示 — 与沙箱「可升级」徽章同一
+ * 纪律。检查失败如实显示 checkError,绝不把失败装成「已是最新」。
+ */
+export function VersionCard() {
+  const { data, isPending, isError, error } = useCheckUpgrade();
+  const force = useForceCheckUpgrade();
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>版本</CardTitle>
+        <CardDescription>
+          daemon 当前运行的构建,以及远端 main 上有没有更新的版本
+        </CardDescription>
+        <CardAction>
+          <Button
+            variant="outline"
+            size="sm"
+            disabled={isPending || force.isPending}
+            onClick={() => force.mutate()}
+          >
+            {force.isPending ? (
+              <Spinner />
+            ) : (
+              <HugeiconsIcon icon={RefreshIcon} />
+            )}
+            检查更新
+          </Button>
+        </CardAction>
+      </CardHeader>
+      <CardContent className="flex flex-col gap-3">
+        {isPending ? (
+          <div className="flex items-center gap-2 text-sm text-muted-foreground">
+            <Spinner /> 检查版本
+          </div>
+        ) : isError ? (
+          <p className="text-sm text-destructive">检查失败:{error.message}</p>
+        ) : (
+          <VersionBody data={data} />
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+
+function VersionBody({ data }: { data: CheckUpgradeResponse }) {
+  const { current, check, checkError } = data;
+  return (
+    <>
+      <div className="flex flex-wrap items-baseline gap-x-3 gap-y-1 text-sm">
+        <span className="text-muted-foreground">当前版本</span>
+        {current ? (
+          <>
+            <code className="font-mono font-medium">{current.commit}</code>
+            <span
+              className="min-w-0 truncate text-muted-foreground"
+              title={new Date(current.committedAt).toLocaleString()}
+            >
+              {current.title}
+            </span>
+          </>
+        ) : (
+          <span className="text-muted-foreground">
+            未知 — 此构建不在 git 检出里完成,没有版本身份
+          </span>
+        )}
+      </div>
+
+      {checkError !== null && (
+        <p className="text-sm text-destructive">无法检查更新:{checkError}</p>
+      )}
+
+      {check &&
+        (check.upgradable ? (
+          <UpgradePreview check={check} />
+        ) : check.aheadBy > 0 ? (
+          <p className="text-sm text-amber-600 dark:text-amber-400">
+            本地比远端 main 多 {check.aheadBy} 个提交(代码有分叉)
+            ,升级前先处理本地改动 — install.sh 只接受快进更新。
+          </p>
+        ) : (
+          <p
+            className="text-sm text-muted-foreground"
+            title={new Date(check.checkedAt).toLocaleString()}
+          >
+            已是最新{check.cached ? '(缓存结果,点「检查更新」重测)' : ''}
+          </p>
+        ))}
+    </>
+  );
+}
+
+function UpgradePreview({
+  check,
+}: {
+  check: NonNullable<CheckUpgradeResponse['check']>;
+}) {
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center gap-2 text-sm">
+        <Badge
+          variant="outline"
+          className="border-amber-500/40 bg-amber-500/10 font-medium text-amber-600 dark:text-amber-400"
+        >
+          可升级
+        </Badge>
+        <span>
+          落后 {check.behindBy} 个提交,最新{' '}
+          <code className="font-mono">{check.latest.commit}</code>
+        </span>
+      </div>
+      <ul className="max-h-48 overflow-y-auto rounded-md border bg-muted/30 p-3 font-mono text-xs leading-relaxed">
+        {check.commits.map((entry) => (
+          <li key={entry.commit} className="flex gap-2">
+            <span className="shrink-0 text-muted-foreground">
+              {entry.commit}
+            </span>
+            <span className="min-w-0 truncate" title={entry.title}>
+              {entry.title}
+            </span>
+          </li>
+        ))}
+        {check.behindBy > check.commits.length && (
+          <li className="text-muted-foreground">
+            还有 {check.behindBy - check.commits.length} 个更早的提交未列出
+          </li>
+        )}
+      </ul>
+      <p className="text-sm text-muted-foreground">
+        升级方式:在服务器上重跑 install.sh(重跑即升级,不轮换 API token)。
+      </p>
+    </div>
+  );
+}
diff --git a/packages/console/src/features/settings/hooks/useUpgrade.ts b/packages/console/src/features/settings/hooks/useUpgrade.ts
new file mode 100644
index 0000000..c44fbab
--- /dev/null
+++ b/packages/console/src/features/settings/hooks/useUpgrade.ts
@@ -0,0 +1,25 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { checkUpgrade } from '@/lib/api';
+
+/**
+ * 版本检查只在打开设置页与点按钮时发生 — 刻意不做后台轮询(检查会打
+ * 远端仓库,后台跑等于 phone home);daemon 侧另有一小时缓存,反复进
+ * 页面不重复走网络。检查失败是数据(checkError)不是异常,卡片如实显示。
+ */
+export function useCheckUpgrade() {
+  return useQuery({
+    queryKey: ['checkUpgrade'],
+    queryFn: () => checkUpgrade(),
+    staleTime: 3600_000,
+    retry: false,
+  });
+}
+
+/** 「检查更新」按钮:force 穿透 daemon 缓存,结果写回同一份查询缓存。 */
+export function useForceCheckUpgrade() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: () => checkUpgrade(true),
+    onSuccess: (data) => queryClient.setQueryData(['checkUpgrade'], data),
+  });
+}
diff --git a/packages/console/src/features/settings/pages/SettingsPage.tsx b/packages/console/src/features/settings/pages/SettingsPage.tsx
index 340e999..228d1ff 100644
--- a/packages/console/src/features/settings/pages/SettingsPage.tsx
+++ b/packages/console/src/features/settings/pages/SettingsPage.tsx
@@ -16,6 +16,7 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { formatDuration } from '@/features/sandboxes/format';
+import { VersionCard } from '../components/VersionCard';
 import { useConfig } from '../hooks/useConfig';
 
 /**
@@ -105,6 +106,8 @@ export function SettingsPage() {
         </p>
       </div>
 
+      <VersionCard />
+
       <DataTable>
         <TableHeader>
           <TableRow>
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 6ac827e..608c5c7 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -1,6 +1,7 @@
 import type {
   AcquireRequest,
   AcquireResponse,
+  CheckUpgradeResponse,
   GetConfigResponse,
   GetIngressResponse,
   GetSandboxMetricsResponse,
@@ -140,6 +141,12 @@ export const listActivity = (limit?: number) =>
 // their value; archive.enabled is the daemon's own adjudication.
 export const getConfig = () => rpc<GetConfigResponse>('/getConfig');
 
+// Is a newer Dormice available? The daemon compares its built commit
+// against the origin's main and caches the answer for an hour; force is
+// the "check now" button. A failed check is data (checkError), not a 500.
+export const checkUpgrade = (force = false) =>
+  rpc<CheckUpgradeResponse>('/checkUpgrade', { force });
+
 // The daemon's front door: whether it manages a reverse proxy config, and
 // every bound domain with live probes (DNS record, certificate served).
 export const getIngress = () => rpc<GetIngressResponse>('/getIngress');
diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index 7672c3c..2184d38 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -37,6 +37,7 @@ export default defineConfig({
       '/listSandboxMetrics': 'http://127.0.0.1:3676',
       '/listActivity': 'http://127.0.0.1:3676',
       '/getConfig': 'http://127.0.0.1:3676',
+      '/checkUpgrade': 'http://127.0.0.1:3676',
       '/getIngress': 'http://127.0.0.1:3676',
       '/setIngress': 'http://127.0.0.1:3676',
       // The terminal speaks the envd surface directly, like the e2b SDK.
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index ff27525..ce123c2 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -2,6 +2,8 @@ import {
   type AcquireResponse,
   type ActivityEvent,
   acquireResponseSchema,
+  type CheckUpgradeResponse,
+  checkUpgradeResponseSchema,
   DEFAULT_EXEC_TIMEOUT_SECONDS,
   type DestroySandboxResponse,
   destroySandboxResponseSchema,
@@ -220,6 +222,24 @@ export class Dormice {
     return getConfigResponseSchema.parse(data);
   }
 
+  /**
+   * Is a newer Dormice available for this daemon? Versions are git
+   * commits (trunk-based, no tags yet): the commit baked into the running
+   * build is compared against the origin's main, fetched through the
+   * checkout's own remote. The answer is served from a short-lived
+   * server-side cache; `force: true` is the "check now" button. A failed
+   * check comes back as `checkError` with `check: null` — never invented
+   * freshness.
+   */
+  async checkUpgrade(options?: {
+    force?: boolean;
+  }): Promise<CheckUpgradeResponse> {
+    const data = await this.rpc('checkUpgrade', {
+      force: options?.force,
+    });
+    return checkUpgradeResponseSchema.parse(data);
+  }
+
   /**
    * The daemon's managed front door (the reverse proxy in front of it):
    * whether one is managed at all, and every bound domain with live probes
diff --git a/packages/server/package.json b/packages/server/package.json
index 2937f9e..4596500 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -20,7 +20,7 @@
     "drizzle"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/main.ts src/archive/mini-s3.ts --format esm --dts --clean",
+    "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index d8b691f..68c979f 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -27,7 +27,10 @@ import { hostRoutes } from './routes/host';
 import { ingressRoutes } from './routes/ingress';
 import { sandboxRoutes } from './routes/sandboxes';
 import { templateRoutes } from './routes/templates';
+import { upgradeRoutes } from './routes/upgrade';
 import { createSandboxProxy } from './sandbox-proxy';
+import { Updater } from './updater';
+import { readBuildInfo } from './version';
 
 export interface AppDeps {
   config: Config;
@@ -71,6 +74,14 @@ export interface AppDeps {
    * assert on sources inject a fixed map instead of trusting the shell.
    */
   sources?: ConfigSources;
+  /**
+   * The daemon's own upgrade window. main.ts injects one that knows the
+   * checkout the daemon runs from; the default knows no checkout, so
+   * checkUpgrade answers an honest checkError instead of comparing (or
+   * fetching over) whatever repository the process happens to sit in —
+   * tests must never reach the network by accident.
+   */
+  updater?: Updater;
 }
 
 /**
@@ -92,6 +103,7 @@ export function buildApp({
   archiver,
   ingress,
   sources = configSources(),
+  updater = new Updater({ repoDir: null, build: readBuildInfo() }),
 }: AppDeps) {
   // The archive default is adjudicated once, here, by the archiver's
   // presence: with one, new sandboxes archive after a week of idleness;
@@ -194,6 +206,7 @@ export function buildApp({
       sources,
       archiveDefaultSeconds,
     });
+    await api.register(upgradeRoutes, { updater });
   });
 
   // The web console: account + session endpoints (open — setup and login
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 2eb3e0d..53fa84f 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -18,6 +18,8 @@ import { KeyedQueue } from './keyed-queue';
 import { reconcile } from './reconciler';
 import { scanOnce } from './scanner';
 import { locallyClaimedCount, startupGuard } from './startup-guard';
+import { Updater } from './updater';
+import { readBuildInfo } from './version';
 
 // One logger, created before everything that needs it: the executor logs
 // through it directly and Fastify adopts it as its own.
@@ -121,6 +123,23 @@ if (!existsSync(consoleDistDir)) {
   log.warn(`web console not found at ${consoleDistDir} — /console disabled`);
 }
 
+// The daemon's own upgrade window compares the commit baked into this
+// build against the checkout it runs from — main.js sits at
+// packages/server/dist (src/main.ts at packages/server/src: same depth),
+// so three hops up is the repo root either way. No checkout (a dist
+// copied elsewhere) means checking is honestly unavailable, not guessed.
+const repoRoot = fileURLToPath(new URL('../../..', import.meta.url));
+const build = readBuildInfo();
+const updater = new Updater({
+  repoDir: existsSync(path.join(repoRoot, '.git')) ? repoRoot : null,
+  build,
+});
+log.info(
+  build
+    ? `dormice build ${build.commit} (${build.title})`
+    : 'dormice build: no version identity (built outside a git checkout)',
+);
+
 const app = buildApp({
   config,
   db,
@@ -130,6 +149,7 @@ const app = buildApp({
   consoleDistDir: existsSync(consoleDistDir) ? consoleDistDir : undefined,
   archiver,
   ingress,
+  updater,
 });
 
 // Before trusting the pairing of this ledger and this reality, check it:
diff --git a/packages/server/src/routes/upgrade.ts b/packages/server/src/routes/upgrade.ts
new file mode 100644
index 0000000..6fbe5c3
--- /dev/null
+++ b/packages/server/src/routes/upgrade.ts
@@ -0,0 +1,32 @@
+import {
+  checkUpgradeRequestSchema,
+  checkUpgradeResponseSchema,
+} from '@dormice/shared';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import type { Updater } from '../updater';
+
+export interface UpgradeRoutesOptions {
+  updater: Updater;
+}
+
+/**
+ * The daemon's own upgrade window: what commit am I, what does origin's
+ * main have that I lack. Checking reaches the network exactly when asked
+ * (no background phone-home — the check runs on an operator's click, and
+ * a server-side cache keeps repeats cheap); failures are honest data in
+ * checkError, not invented freshness.
+ */
+export const upgradeRoutes: FastifyPluginAsyncZod<
+  UpgradeRoutesOptions
+> = async (app, { updater }) => {
+  app.post(
+    '/checkUpgrade',
+    {
+      schema: {
+        body: checkUpgradeRequestSchema,
+        response: { 200: checkUpgradeResponseSchema },
+      },
+    },
+    async (request) => updater.check(request.body.force),
+  );
+};
diff --git a/packages/server/src/updater.test.ts b/packages/server/src/updater.test.ts
new file mode 100644
index 0000000..431517e
--- /dev/null
+++ b/packages/server/src/updater.test.ts
@@ -0,0 +1,146 @@
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { checkUpgradeResponseSchema } from '@dormice/shared';
+import { execaSync } from 'execa';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { Updater } from './updater';
+import type { BuildInfo } from './version';
+
+// The updater against real git: a fixture origin, a clone that plays the
+// installed daemon, and builds pinned to specific commits. Everything is
+// local paths — the network is never touched.
+
+function git(cwd: string, ...args: string[]): string {
+  return execaSync('git', args, { cwd }).stdout.trim();
+}
+
+function commit(cwd: string, title: string): { commit: string; title: string } {
+  execaSync(
+    'git',
+    [
+      '-c',
+      'user.email=test@example.com',
+      '-c',
+      'user.name=test',
+      'commit',
+      '--allow-empty',
+      '-m',
+      title,
+    ],
+    { cwd },
+  );
+  return { commit: git(cwd, 'rev-parse', '--short', 'HEAD'), title };
+}
+
+function buildAt(repo: string): BuildInfo {
+  return {
+    commit: git(repo, 'rev-parse', '--short', 'HEAD'),
+    title: git(repo, 'log', '-1', '--format=%s'),
+    committedAt: new Date(git(repo, 'log', '-1', '--format=%cI')).toISOString(),
+  };
+}
+
+let origin: string;
+let clone: string;
+/** The identity of the clone's HEAD at "install time". */
+let installedBuild: BuildInfo;
+
+beforeAll(() => {
+  const root = mkdtempSync(path.join(tmpdir(), 'dormice-updater-'));
+  origin = path.join(root, 'origin');
+  clone = path.join(root, 'clone');
+  execaSync('git', ['init', '-q', '-b', 'main', origin]);
+  commit(origin, 'first');
+  commit(origin, 'second');
+  execaSync('git', ['clone', '-q', origin, clone]);
+  installedBuild = buildAt(clone);
+});
+
+describe('Updater.check', () => {
+  it('reports up to date when the build matches origin main', async () => {
+    const updater = new Updater({ repoDir: clone, build: installedBuild });
+    const answer = await updater.check();
+    const parsed = checkUpgradeResponseSchema.parse(answer);
+    expect(parsed.checkError).toBeNull();
+    expect(parsed.current).toEqual(installedBuild);
+    expect(parsed.check).toMatchObject({
+      behindBy: 0,
+      aheadBy: 0,
+      upgradable: false,
+      cached: false,
+      commits: [],
+    });
+    expect(parsed.check?.latest.commit).toBe(installedBuild.commit);
+  });
+
+  it('reports behind commits newest first and adjudicates upgradable', async () => {
+    const third = commit(origin, 'third');
+    const fourth = commit(origin, 'fourth');
+    const updater = new Updater({ repoDir: clone, build: installedBuild });
+    const answer = await updater.check();
+    expect(answer.checkError).toBeNull();
+    expect(answer.check).toMatchObject({
+      behindBy: 2,
+      aheadBy: 0,
+      upgradable: true,
+      latest: fourth,
+    });
+    expect(answer.check?.commits).toEqual([fourth, third]);
+  });
+
+  it('serves the second answer from cache and refetches on force', async () => {
+    const updater = new Updater({ repoDir: clone, build: installedBuild });
+    const first = await updater.check();
+    expect(first.check?.cached).toBe(false);
+    const behindThen = first.check?.behindBy ?? 0;
+
+    commit(origin, 'landed after the first check');
+    const second = await updater.check();
+    expect(second.check?.cached).toBe(true);
+    expect(second.check?.behindBy).toBe(behindThen);
+
+    const forced = await updater.check(true);
+    expect(forced.check?.cached).toBe(false);
+    expect(forced.check?.behindBy).toBe(behindThen + 1);
+  });
+
+  it('reports divergence as not upgradable', async () => {
+    // A local commit origin lacks: install.sh pulls --ff-only and would
+    // refuse, so the check must say diverged instead of promising an
+    // upgrade that cannot apply.
+    commit(clone, 'local only');
+    try {
+      const updater = new Updater({ repoDir: clone, build: buildAt(clone) });
+      const answer = await updater.check();
+      expect(answer.checkError).toBeNull();
+      expect(answer.check?.aheadBy).toBe(1);
+      expect(answer.check?.upgradable).toBe(false);
+    } finally {
+      execaSync('git', ['reset', '-q', '--hard', 'HEAD~1'], { cwd: clone });
+    }
+  });
+
+  it('is honest without a checkout, without a build identity, and on a dead remote', async () => {
+    const noRepo = new Updater({ repoDir: null, build: installedBuild });
+    expect((await noRepo.check()).checkError).toMatch(/git checkout/);
+
+    const noBuild = new Updater({ repoDir: clone, build: null });
+    const answer = await noBuild.check();
+    expect(answer.current).toBeNull();
+    expect(answer.checkError).toMatch(/version identity/);
+
+    const broken = mkdtempSync(path.join(tmpdir(), 'dormice-broken-'));
+    execaSync('git', ['init', '-q', '-b', 'main', broken]);
+    commit(broken, 'orphan');
+    execaSync(
+      'git',
+      ['remote', 'add', 'origin', path.join(broken, 'does-not-exist')],
+      { cwd: broken },
+    );
+    const deadRemote = new Updater({ repoDir: broken, build: buildAt(broken) });
+    const dead = await deadRemote.check();
+    expect(dead.check).toBeNull();
+    expect(dead.checkError).toMatch(/fetch failed/);
+  });
+});
diff --git a/packages/server/src/updater.ts b/packages/server/src/updater.ts
new file mode 100644
index 0000000..f6ca99e
--- /dev/null
+++ b/packages/server/src/updater.ts
@@ -0,0 +1,141 @@
+import type { CheckUpgradeResponse } from '@dormice/shared';
+import { execa } from 'execa';
+import type { BuildInfo } from './version';
+
+/**
+ * The daemon's own upgrade window. Versions are git commits (trunk-based,
+ * no release tags yet), and the question "is a newer Dormice available?"
+ * is answered by comparing the commit baked into this build against the
+ * origin's main — fetched through the checkout's own `origin` remote, so
+ * an install done with `--mirror cn` (whose clone URL carries the mirror
+ * prefix) checks through the same mirror for free.
+ *
+ * `git fetch` updates .git only and never touches the working tree or the
+ * running process — checking is always safe. The result is cached so a
+ * console session does not hammer the network; `force` is the "check now"
+ * button. Failures come back as data (checkError), never invented.
+ */
+
+const CHECK_CACHE_MS = 3600_000;
+/** Changelog preview cap — the wire is a preview, not the full history. */
+const CHANGELOG_LIMIT = 50;
+const FETCH_TIMEOUT_MS = 30_000;
+
+export interface UpdaterOptions {
+  /**
+   * Root of the git checkout the daemon runs from; null when there is
+   * none (a dist copied around, tests) — checking is then honestly
+   * impossible instead of quietly comparing the wrong repository.
+   */
+  repoDir: string | null;
+  /** The identity baked into this build (version.ts). */
+  build: BuildInfo | null;
+}
+
+type Check = NonNullable<CheckUpgradeResponse['check']>;
+
+export class Updater {
+  private readonly repoDir: string | null;
+  private readonly build: BuildInfo | null;
+  private cache: { at: number; check: Check } | null = null;
+
+  constructor(options: UpdaterOptions) {
+    this.repoDir = options.repoDir;
+    this.build = options.build;
+  }
+
+  async check(force = false): Promise<CheckUpgradeResponse> {
+    if (this.repoDir === null) {
+      return {
+        current: this.build,
+        check: null,
+        checkError:
+          'the daemon does not run from a git checkout — nothing to compare against',
+      };
+    }
+    if (this.build === null) {
+      return {
+        current: null,
+        check: null,
+        checkError:
+          'this build carries no version identity (built outside a git checkout) — nothing to compare',
+      };
+    }
+    if (!force && this.cache && Date.now() - this.cache.at < CHECK_CACHE_MS) {
+      return {
+        current: this.build,
+        check: { ...this.cache.check, cached: true },
+        checkError: null,
+      };
+    }
+    try {
+      const check = await this.compare(this.build.commit);
+      this.cache = { at: Date.now(), check };
+      return { current: this.build, check, checkError: null };
+    } catch (error) {
+      return {
+        current: this.build,
+        check: null,
+        checkError: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  private async compare(currentCommit: string): Promise<Check> {
+    // FETCH_HEAD instead of origin/main: it is written by every fetch
+    // regardless of the clone's refspec configuration.
+    await this.git(['fetch', '--quiet', 'origin', 'main'], FETCH_TIMEOUT_MS);
+    const behindBy = Number(
+      await this.git(['rev-list', '--count', `${currentCommit}..FETCH_HEAD`]),
+    );
+    const aheadBy = Number(
+      await this.git(['rev-list', '--count', `FETCH_HEAD..${currentCommit}`]),
+    );
+    const latest = parseCommitLine(
+      await this.git(['log', '-1', '--format=%h%x09%s', 'FETCH_HEAD']),
+    );
+    const changelog = await this.git([
+      'log',
+      '--format=%h%x09%s',
+      '-n',
+      String(CHANGELOG_LIMIT),
+      `${currentCommit}..FETCH_HEAD`,
+    ]);
+    return {
+      checkedAt: new Date().toISOString(),
+      cached: false,
+      latest,
+      behindBy,
+      aheadBy,
+      // Diverged (local commits the origin lacks) is not upgradable:
+      // install.sh pulls --ff-only and would refuse — say so up front.
+      upgradable: behindBy > 0 && aheadBy === 0,
+      commits: changelog
+        ? changelog.split('\n').map((line) => parseCommitLine(line))
+        : [],
+    };
+  }
+
+  private async git(args: string[], timeout = 10_000): Promise<string> {
+    const result = await execa('git', args, {
+      cwd: this.repoDir ?? undefined,
+      timeout,
+      reject: false,
+    });
+    if (result.exitCode !== 0) {
+      const stderr = (result.stderr ?? '').trim();
+      throw new Error(
+        `git ${args[0]} failed: ${stderr.slice(0, 300) || `exit ${result.exitCode ?? 'unknown'}`}`,
+      );
+    }
+    return result.stdout.trim();
+  }
+}
+
+function parseCommitLine(line: string): { commit: string; title: string } {
+  const tab = line.indexOf('\t');
+  // A title containing a tab keeps its tail; a missing tab (never happens
+  // with %h%x09%s) degrades to an empty title rather than a crash.
+  if (tab === -1) return { commit: line, title: '' };
+  return { commit: line.slice(0, tab), title: line.slice(tab + 1) };
+}
diff --git a/packages/server/src/version.ts b/packages/server/src/version.ts
new file mode 100644
index 0000000..62ed433
--- /dev/null
+++ b/packages/server/src/version.ts
@@ -0,0 +1,23 @@
+/**
+ * The identity tsup baked into this build (tsup.config.ts): the commit the
+ * dist was built from. In the built daemon these `process.env` reads are
+ * compile-time literals; running from source (tests, tsx) they fall
+ * through to the real environment and come back empty — an unbuilt tree
+ * has no build identity, and null says so honestly.
+ */
+export interface BuildInfo {
+  /** Short hash. */
+  commit: string;
+  /** The commit's subject line. */
+  title: string;
+  /** ISO 8601 UTC — the commit's time, not the build's. */
+  committedAt: string;
+}
+
+export function readBuildInfo(): BuildInfo | null {
+  const commit = process.env.DORMICE_BUILD_COMMIT;
+  const title = process.env.DORMICE_BUILD_COMMIT_TITLE;
+  const committedAt = process.env.DORMICE_BUILD_COMMIT_AT;
+  if (!commit || !title || !committedAt) return null;
+  return { commit, title, committedAt };
+}
diff --git a/packages/server/tsup.config.ts b/packages/server/tsup.config.ts
new file mode 100644
index 0000000..e004f51
--- /dev/null
+++ b/packages/server/tsup.config.ts
@@ -0,0 +1,40 @@
+import { execSync } from 'node:child_process';
+import { defineConfig } from 'tsup';
+
+/**
+ * The build stamps its own identity: the commit the dist was built from,
+ * baked in as literals (src/version.ts reads them back). Deliberately
+ * build-time, not runtime — after a `git pull` the checkout's HEAD moves
+ * while the running process does not, and the daemon must report what it
+ * IS, not what the directory says. Built outside a git checkout, the
+ * values are empty and version.ts honestly answers null.
+ */
+function git(args: string): string {
+  try {
+    return execSync(`git ${args}`, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .toString()
+      .trim();
+  } catch {
+    return '';
+  }
+}
+
+const commitTime = git('log -1 --format=%cI');
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/main.ts', 'src/archive/mini-s3.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  env: {
+    DORMICE_BUILD_COMMIT: git('rev-parse --short HEAD'),
+    DORMICE_BUILD_COMMIT_TITLE: git('log -1 --format=%s'),
+    // Normalized to UTC here so the wire schema keeps its one timestamp
+    // shape (ISO 8601 UTC) — %cI carries the author's local offset.
+    DORMICE_BUILD_COMMIT_AT: commitTime
+      ? new Date(commitTime).toISOString()
+      : '',
+  },
+});
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 0956e53..d96a96d 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -15,3 +15,4 @@ export * from './sandbox';
 export * from './states';
 export * from './templates';
 export * from './update-policy';
+export * from './upgrade';
diff --git a/packages/shared/src/upgrade.ts b/packages/shared/src/upgrade.ts
new file mode 100644
index 0000000..cdf6601
--- /dev/null
+++ b/packages/shared/src/upgrade.ts
@@ -0,0 +1,78 @@
+import { z } from 'zod';
+
+/**
+ * checkUpgrade() — is a newer Dormice available for this daemon?
+ *
+ * There are no release tags yet: main is trunk-based and every commit
+ * passes the acceptance chain, so "a version" is honestly a git commit.
+ * The daemon's identity is the commit baked into its dist at build time —
+ * deliberately not the checkout's HEAD, which moves on `git pull` while
+ * the running process does not. The comparison is that built commit
+ * against the origin's main (`git fetch` touches .git only, never the
+ * working tree), so "pulled but not rebuilt" still honestly reads behind.
+ *
+ * The check reaches the network, so failures are data, not surprises:
+ * `check` is null and `checkError` says why (the getIngress probe
+ * precedent — the observation succeeded, the probe inside it did not).
+ * Nothing checks in the background; this verb runs when asked, with a
+ * short-lived server-side cache to keep a busy console polite.
+ */
+export const checkUpgradeRequestSchema = z.object({
+  /** Bypass the server-side cache — the "check now" button. */
+  force: z.boolean().default(false),
+});
+
+export type CheckUpgradeRequest = z.input<typeof checkUpgradeRequestSchema>;
+
+export const upgradeCommitSchema = z.object({
+  /** Short hash. */
+  commit: z.string(),
+  /** The commit's subject line — trunk commit titles are the changelog. */
+  title: z.string(),
+});
+
+export const checkUpgradeResponseSchema = z.object({
+  /**
+   * The identity baked into the running build. Null when the dist was
+   * built outside a git checkout — an honest "I don't know who I am",
+   * never a guess.
+   */
+  current: z
+    .object({
+      commit: z.string(),
+      title: z.string(),
+      /** ISO 8601 UTC — the commit's time, not the build machine's clock. */
+      committedAt: z.iso.datetime(),
+    })
+    .nullable(),
+  /** The comparison against origin's main. Null exactly when checkError says why. */
+  check: z
+    .object({
+      /** ISO 8601 UTC — when the fetch actually ran (may predate this response: see cached). */
+      checkedAt: z.iso.datetime(),
+      /** True when this answer came from the server-side cache instead of a fresh fetch. */
+      cached: z.boolean(),
+      latest: upgradeCommitSchema,
+      /** Commits on origin/main that this build lacks. */
+      behindBy: z.number().int().min(0),
+      /**
+       * Commits this build has that origin/main lacks. Non-zero means the
+       * checkout diverged (local commits, force-push upstream) — install.sh
+       * pulls --ff-only, so a one-click upgrade would refuse anyway; the
+       * daemon says so up front.
+       */
+      aheadBy: z.number().int().min(0),
+      /** Server-adjudicated: behind and not diverged. Clients never re-derive. */
+      upgradable: z.boolean(),
+      /** What the upgrade would bring, newest first, capped — the changelog preview. */
+      commits: z.array(upgradeCommitSchema),
+    })
+    .nullable(),
+  /**
+   * Why check is null: no git checkout under the daemon, no baked
+   * identity to compare, or the fetch itself failed (network, mirror).
+   */
+  checkError: z.string().nullable(),
+});
+
+export type CheckUpgradeResponse = z.infer<typeof checkUpgradeResponseSchema>;

From 4b8a9b3d70d1b1a9a5367da06d798e9e322fe194 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 17:42:20 +0800
Subject: [PATCH 077/133] install.sh learns to fall back on its feet: a failed
 build after git pull resets to the commit that was running and rebuilds it
 (the daemon is crash-only and must stay restartable), and --status-dir
 reports the outcome as JSON for the one-click upgrade to read back

---
 deploy/install.sh | 117 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 102 insertions(+), 15 deletions(-)

diff --git a/deploy/install.sh b/deploy/install.sh
index d3a2be5..04ac240 100644
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -8,14 +8,21 @@
 #   --mirror cn     use mainland-China mirrors for every download
 #   --swap-gb N     size of the swapfile to create when the host has no swap
 #                   (default 16 — the configuration freezing was measured on)
+#   --status-dir D  write status.json into D as the run progresses — how the
+#                   daemon's one-click upgrade reads the outcome back; a
+#                   manual run doesn't need it
 #
-# Three promises, mirroring `dor doctor`:
+# Four promises, mirroring `dor doctor`:
 #   - Idempotent. Every step checks before it acts; a step whose outcome is
 #     already in place says [skip] and touches nothing. Re-running upgrades
 #     the code and repairs drift, and never rotates your API token.
 #   - Loud. Every step prints what it found and what it did.
 #   - Verified. The install has not succeeded until `dor doctor` says so —
 #     the same battery of checks, including the real-container probes.
+#   - Restartable. On a re-run, if the build fails after `git pull` moved
+#     the tree, the code is put back and rebuilt at the commit that was
+#     running — the daemon in memory survives a failed upgrade anyway, but
+#     it is crash-only and must stay able to restart at any moment.
 set -euo pipefail
 export DEBIAN_FRONTEND=noninteractive
 
@@ -42,13 +49,16 @@ PORT=3676
 # ---- flags -----------------------------------------------------------------
 MIRROR=''
 SWAP_GB=16
+STATUS_DIR=''
 while [ $# -gt 0 ]; do
   case "$1" in
     --mirror) MIRROR="${2:?--mirror needs a value}"; shift 2 ;;
     --mirror=*) MIRROR="${1#*=}"; shift ;;
     --swap-gb) SWAP_GB="${2:?--swap-gb needs a value}"; shift 2 ;;
     --swap-gb=*) SWAP_GB="${1#*=}"; shift ;;
-    *) echo "install.sh: unknown flag $1 (known: --mirror cn, --swap-gb N)" >&2; exit 1 ;;
+    --status-dir) STATUS_DIR="${2:?--status-dir needs a value}"; shift 2 ;;
+    --status-dir=*) STATUS_DIR="${1#*=}"; shift ;;
+    *) echo "install.sh: unknown flag $1 (known: --mirror cn, --swap-gb N, --status-dir D)" >&2; exit 1 ;;
   esac
 done
 if [ -n "$MIRROR" ] && [ "$MIRROR" != cn ]; then
@@ -56,9 +66,69 @@ if [ -n "$MIRROR" ] && [ "$MIRROR" != cn ]; then
   exit 1
 fi
 
-log()  { printf '\n==> %s\n' "$*"; }
+# log() doubles as the phase tracker: when something fails under `set -e`
+# there is no message to report, but "which step" is always known.
+PHASE='startup'
+log()  { PHASE="$*"; printf '\n==> %s\n' "$*"; }
 note() { printf '    %s\n' "$*"; }
-die()  { printf '\ninstall.sh: %s\n' "$*" >&2; exit 1; }
+DIE_MSG=''
+die()  { DIE_MSG="$*"; printf '\ninstall.sh: %s\n' "$*" >&2; exit 1; }
+
+# ---- outcome reporting and the build rollback --------------------------------
+# status.json is the one file the daemon's one-click upgrade reads back;
+# without --status-dir every write is a no-op and a manual run behaves as
+# always. Written to a temp name and moved so a reader never sees a torn
+# file. Error text is flattened (JSON has no raw newlines) and truncated —
+# the full story is always the log.
+STARTED_AT=$(date -u +%FT%TZ)
+OLD_SHA=''
+NEW_SHA=''
+status_write() { # <state> [error]
+  [ -n "$STATUS_DIR" ] || return 0
+  mkdir -p "$STATUS_DIR"
+  local finished=null from=null to=null err=null safe
+  [ "$1" != running ] && finished="\"$(date -u +%FT%TZ)\""
+  [ -n "$OLD_SHA" ] && from="\"$OLD_SHA\""
+  [ -n "$NEW_SHA" ] && to="\"$NEW_SHA\""
+  if [ -n "${2:-}" ]; then
+    safe=$(printf '%s' "$2" | tr '\n\t' '  ' | sed 's/[\\"]//g' | cut -c1-500)
+    err="\"$safe\""
+  fi
+  printf '{"state":"%s","startedAt":"%s","finishedAt":%s,"fromCommit":%s,"toCommit":%s,"error":%s}\n' \
+    "$1" "$STARTED_AT" "$finished" "$from" "$to" "$err" >"$STATUS_DIR/status.json.tmp"
+  mv "$STATUS_DIR/status.json.tmp" "$STATUS_DIR/status.json"
+}
+
+# The window where a failure leaves the install broken: after `git pull`
+# moved the tree (PULLED) and before the build completed (BUILT), the dist
+# on disk is part new, part old — the running daemon still serves from
+# memory, but being crash-only it must stay restartable. The exit trap puts
+# the code back at the commit that was running and rebuilds it; the daemon
+# is deliberately NOT restarted on any failure path. A fresh clone has no
+# rollback target — a broken first install is honestly broken.
+PULLED=''
+BUILT=''
+on_exit() {
+  local code=$?
+  [ "$code" -eq 0 ] && return 0
+  local msg="${DIE_MSG:-failed during: $PHASE}"
+  if [ -n "$PULLED" ] && [ -z "$BUILT" ] && [ -n "$OLD_SHA" ]; then
+    log "build failed — rolling back to $OLD_SHA"
+    # The rollback rebuild may itself hit the same cause (it does reuse the
+    # pnpm store, so a network hiccup usually does not repeat); both
+    # outcomes are reported honestly and neither restarts the daemon.
+    if git -C "$INSTALL_DIR" reset --hard -q "$OLD_SHA" && build_repo; then
+      note "rolled back and rebuilt at $OLD_SHA — the daemon was not restarted; fix the cause and re-run"
+      status_write rolled-back "$msg"
+    else
+      status_write failed "$msg — and the rollback rebuild failed too: the daemon keeps running but must not restart until install.sh succeeds; fix the cause and re-run"
+    fi
+  else
+    status_write failed "$msg"
+  fi
+}
+trap on_exit EXIT
+status_write running
 
 # ---- preflight: the facts install.sh cannot fix ----------------------------
 log 'preflight'
@@ -236,16 +306,37 @@ else
 fi
 
 # ---- Dormice code -----------------------------------------------------------
+# Defined before the pull so the rollback in on_exit can always call it.
+# Deps then build, from a clean tree at whatever commit is checked out —
+# the same path for the fresh install, the upgrade, and the rollback.
+build_repo() {
+  cd "$INSTALL_DIR"
+  if [ "$MIRROR" = cn ]; then
+    npm_config_registry=https://registry.npmmirror.com pnpm install --frozen-lockfile
+  else
+    pnpm install --frozen-lockfile
+  fi
+  # Build only what a daemon host runs: the server (plus its workspace deps),
+  # the CLI, and the console SPA. The website package is the project's Next.js
+  # marketing site — building it here would cost minutes and import a frontend
+  # toolchain's failure modes into an installer whose job is the daemon.
+  pnpm --filter "@dormice/server..." --filter "@dormice/cli..." --filter "@dormice/console" build
+}
+
 log "Dormice code ($INSTALL_DIR)"
 clone_url=$REPO_URL
 [ "$MIRROR" = cn ] && clone_url="https://ghfast.top/$REPO_URL"
 if [ -d "$INSTALL_DIR/.git" ]; then
+  OLD_SHA=$(git -C "$INSTALL_DIR" rev-parse --short HEAD)
   git -C "$INSTALL_DIR" pull --ff-only -q
+  PULLED=1
   note "updated to $(git -C "$INSTALL_DIR" log --oneline -1)"
 else
   git clone -q "$clone_url" "$INSTALL_DIR"
   note "cloned $(git -C "$INSTALL_DIR" log --oneline -1)"
 fi
+NEW_SHA=$(git -C "$INSTALL_DIR" rev-parse --short HEAD)
+status_write running
 
 log 'build'
 pnpm_version=$(node -p "require('$INSTALL_DIR/package.json').packageManager.split('@')[1]")
@@ -261,17 +352,8 @@ if ! command -v pnpm >/dev/null || [ "$(pnpm --version)" != "$pnpm_version" ]; t
     ln -sf "/opt/node-$NODE_VERSION-linux-x64/bin/pnpm" /usr/local/bin/pnpm
   fi
 fi
-cd "$INSTALL_DIR"
-if [ "$MIRROR" = cn ]; then
-  npm_config_registry=https://registry.npmmirror.com pnpm install --frozen-lockfile
-else
-  pnpm install --frozen-lockfile
-fi
-# Build only what a daemon host runs: the server (plus its workspace deps),
-# the CLI, and the console SPA. The website package is the project's Next.js
-# marketing site — building it here would cost minutes and import a frontend
-# toolchain's failure modes into an installer whose job is the daemon.
-pnpm --filter "@dormice/server..." --filter "@dormice/cli..." --filter "@dormice/console" build
+build_repo
+BUILT=1
 ln -sf "$INSTALL_DIR/packages/cli/dist/main.js" /usr/local/bin/dormice
 ln -sf "$INSTALL_DIR/packages/cli/dist/main.js" /usr/local/bin/dor
 note "built; \`dormice\` and \`dor\` linked into /usr/local/bin"
@@ -453,6 +535,11 @@ set -a
 set +a
 dor doctor
 
+# Written only now: succeeded means what it says — the daemon restarted on
+# the new code AND doctor proved the install whole, not merely "the script
+# reached the end".
+status_write succeeded
+
 printf '\nDormice is installed.\n'
 printf '  API token:   grep ^DORMICE_API_TOKEN %s\n' "$ENV_FILE"
 printf '  daemon logs: journalctl -u dormice -f\n'

From d5262fc47f56c20b2276a86d996b3dbf3c9d3642 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 17:47:17 +0800
Subject: [PATCH 078/133] =?UTF-8?q?The=20docs=20stop=20assuming=20you've?=
 =?UTF-8?q?=20met=20Docker:=20a=20Core=20concepts=20page=20defines=20every?=
 =?UTF-8?q?=20term=20once,=20each=20page=20opens=20by=20saying=20why=20it?=
 =?UTF-8?q?=20exists,=20and=20jargon=20gets=20a=20plain-words=20clause=20a?=
 =?UTF-8?q?t=20first=20sight=20=E2=80=94=20while=20updatePolicy,=20the=20o?=
 =?UTF-8?q?bservation=20verbs,=20ingress,=20and=20the=20console's=20passwo?=
 =?UTF-8?q?rd=20login=20finally=20make=20it=20into=20print?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 skills/dormice/SKILL.md                  |  21 +++-
 website/content/docs/architecture.mdx    |   7 +-
 website/content/docs/archiving.mdx       |  10 +-
 website/content/docs/commands.mdx        |   7 +-
 website/content/docs/configuration.mdx   |   9 +-
 website/content/docs/console.mdx         |  74 ++++++++---
 website/content/docs/core-concepts.mdx   | 149 +++++++++++++++++++++++
 website/content/docs/doctor.mdx          |   6 +
 website/content/docs/e2b-differences.mdx |   6 +
 website/content/docs/e2b-sdks.mdx        |  14 ++-
 website/content/docs/files.mdx           |  15 ++-
 website/content/docs/http-api.mdx        |   7 ++
 website/content/docs/index.mdx           |  53 +++++---
 website/content/docs/installation.mdx    | 130 +++++++++++++-------
 website/content/docs/lifecycle.mdx       |  47 +++++--
 website/content/docs/meta.json           |   2 +-
 website/content/docs/metrics.mdx         |  43 +++++--
 website/content/docs/persistence.mdx     |  36 +++---
 website/content/docs/ports.mdx           |  20 ++-
 website/content/docs/quickstart.mdx      |  18 ++-
 website/content/docs/resident-agents.mdx |  11 +-
 website/content/docs/templates.mdx       |  18 ++-
 website/content/docs/upgrading.mdx       |   8 +-
 website/src/lib/docs.ts                  |   2 +
 24 files changed, 552 insertions(+), 161 deletions(-)
 create mode 100644 website/content/docs/core-concepts.mdx

diff --git a/skills/dormice/SKILL.md b/skills/dormice/SKILL.md
index f066e75..ae8c938 100644
--- a/skills/dormice/SKILL.md
+++ b/skills/dormice/SKILL.md
@@ -108,10 +108,17 @@ curl -X POST http://127.0.0.1:3676/acquireSandbox \
   -d '{"externalId": "my-agent"}'
 ```
 
-Verbs: `acquireSandbox`, `listSandboxes`, `execCommand`, `writeFiles` /
-`writeFile`, `readFile` / `readFiles`, `rebuildSandbox` (fresh container,
-`/home/user` kept), `destroySandbox`, `registerTemplate` / `listTemplates` /
-`removeTemplate`, `getHostMetrics`. `execCommand` takes
+Verbs: `acquireSandbox`, `updatePolicy` (patch an existing sandbox's
+lifecycle policy in place — no wake, no destroy), `listSandboxes`,
+`execCommand`, `writeFiles` / `writeFile`, `readFile` / `readFiles`,
+`rebuildSandbox` (fresh container, `/home/user` kept), `destroySandbox`,
+`registerTemplate` / `listTemplates` / `removeTemplate`,
+`getHostMetrics`, `getSandboxMetrics` / `listSandboxMetrics` (live
+resource samples; never wake anything), `listSandboxImages` (who still
+runs an old template image), `listActivity` (recent daemon history),
+`getConfig` (effective config, secrets redacted), `getIngress` /
+`setIngress` (bind domains on the daemon's managed reverse proxy).
+`execCommand` takes
 `{ externalId, command, timeoutSeconds?, cwd?, env? }` and returns
 `{ exitCode, stdout, stderr, ... }` — **a non-zero exit code is a result,
 not an HTTP error**. When a sandbox is coming back from S3, `acquireSandbox`
@@ -143,8 +150,10 @@ stream uncapped; `uploadUrl()` / `downloadUrl()` mint signed URLs).
 
 ## Lifecycle policy — three knobs
 
-Set at **creation only** (overrides on an existing sandbox are not applied);
-all count seconds since last activity, ordering freeze ≤ stop ≤ archive:
+Set at creation (overrides while acquiring an existing sandbox are not
+applied — change an existing sandbox's policy with `updatePolicy`, a
+patch that never wakes and never resets the idle clock); all count
+seconds since last activity, ordering freeze ≤ stop ≤ archive:
 
 | Knob | Default | `null` means |
 | --- | --- | --- |
diff --git a/website/content/docs/architecture.mdx b/website/content/docs/architecture.mdx
index 6a81a76..8fd7a10 100644
--- a/website/content/docs/architecture.mdx
+++ b/website/content/docs/architecture.mdx
@@ -6,7 +6,9 @@ description: How the daemon works, what the sandbox isolation boundary actually
 This page is the deep end: how Dormice works underneath, and the
 security properties you are relying on. You don't need it to use
 Dormice — start with the [Quick start](/docs/quickstart) — but read it
-before you run untrusted code in production.
+before you run untrusted code in production. It assumes the vocabulary
+from [Core concepts](/docs/core-concepts); unfamiliar terms are
+explained there.
 
 ## One daemon, one database
 
@@ -37,7 +39,8 @@ but today the simplicity is the feature.
 
 ## What a sandbox is
 
-Each sandbox is a Docker container running under **gVisor** (`runsc`),
+Each sandbox is a Docker container running under
+**[gVisor](/docs/core-concepts#gvisor)** (`runsc`),
 with its `/home/user` on a dedicated disk image (see
 [Sandbox persistence](/docs/persistence)). Every sandbox runs with the
 same non-negotiable parameters: non-root (uid 1000), `--init`,
diff --git a/website/content/docs/archiving.mdx b/website/content/docs/archiving.mdx
index 17d066b..ff065a5 100644
--- a/website/content/docs/archiving.mdx
+++ b/website/content/docs/archiving.mdx
@@ -4,10 +4,12 @@ description: Learn how to move long-idle sandboxes off the host into any S3-comp
 ---
 
 Frozen costs a few MiB of RAM; stopped costs only disk. Archiving takes
-the last step: the sandbox's disk is compressed (`tar` + `zstd`) and
-shipped to an S3-compatible bucket, and the host keeps **nothing**. A
-machine with a modest disk can hold a long tail of dormant sandboxes for
-the price of object storage.
+the last step: the sandbox's disk is packed into one compressed file
+(with `tar` + `zstd`) and shipped to an [S3-compatible
+bucket](/docs/core-concepts#object-storage-s3) — rented internet
+storage — and the host keeps **nothing**. A machine with a modest disk
+can hold a long tail of dormant sandboxes for the price of object
+storage.
 
 ## Enable archiving
 
diff --git a/website/content/docs/commands.mdx b/website/content/docs/commands.mdx
index 4bcef08..51ee472 100644
--- a/website/content/docs/commands.mdx
+++ b/website/content/docs/commands.mdx
@@ -3,6 +3,10 @@ title: Running commands
 description: Learn how to run shell commands inside a sandbox — timeouts, working directory, environment variables, and output limits.
 ---
 
+Running commands is how your code (or your agent) actually does things
+inside a sandbox — install packages, run scripts, execute whatever the
+agent wrote. This page covers the native `execCommand` verb end to end.
+
 ## Run a command
 
 You can run a shell command inside a sandbox with `execCommand`. It
@@ -36,7 +40,8 @@ dor sandbox exec my-agent 'npm ci && npm test' -t 3600
 ## Set a timeout
 
 Pass `timeoutSeconds` (default 300, maximum 86400). On expiry the
-command is killed and returns exit code 137, like any SIGKILLed process:
+command is forcibly killed and returns exit code 137 — the Linux
+convention for a process that was killed rather than allowed to finish:
 
 ```ts
 await client.execCommand('my-agent', 'npm ci && npm test', {
diff --git a/website/content/docs/configuration.mdx b/website/content/docs/configuration.mdx
index 85a5589..203e1e4 100644
--- a/website/content/docs/configuration.mdx
+++ b/website/content/docs/configuration.mdx
@@ -10,12 +10,19 @@ Everything has a default except the API token and, in docker mode, the
 base image.
 
 On a host set up by `install.sh`, the variables live in
-`/etc/dormice/env`. Edit the file and restart:
+`/etc/dormice/env`. Edit the file and restart the daemon:
 
 ```sh
 systemctl restart dormice
 ```
 
+To see the values actually in force, use the
+[console](/docs/console)'s settings page or the `getConfig` verb — both
+report every knob with its effective value and whether it came from the
+environment or a default (secrets are reported present-or-absent only).
+Unfamiliar terms in the tables below are covered in
+[Core concepts](/docs/core-concepts).
+
 ## Core
 
 | Variable | Default | What it does |
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
index 69d52f2..e25834b 100644
--- a/website/content/docs/console.mdx
+++ b/website/content/docs/console.mdx
@@ -13,11 +13,19 @@ explicit click.**
 
 ## Signing in
 
-Paste the API token once. The browser trades it for an `httpOnly`
-session cookie (valid 7 days) and never stores the token anywhere page
-JavaScript can read — a script injected into the console cannot steal
-your long-term credential. Sessions are derived from the API token, so
-rotating the token signs every browser out at once.
+The console has one account with a username and password. On first
+visit it walks you through creating it — you prove you are the operator
+by pasting the API token once, then choose the credentials you will
+actually sign in with. Forgot the password? Present the token again and
+set a new one; repeated wrong guesses are slowed down with increasing
+delays.
+
+Signing in sets an `httpOnly` session cookie (valid 7 days) — a cookie
+page JavaScript cannot read, so a script injected into the console
+cannot steal your credential. The API token and the console password
+rotate independently: changing the password does not break SDK clients,
+and rotating the token does not sign browsers out. Resetting the
+account (via the token) invalidates every existing session.
 
 ## Overview
 
@@ -32,30 +40,38 @@ at 90%; a host without swap gets an amber warning pointing at
 
 ## Sandboxes
 
-The live list — every sandbox with its state, refreshed every 2 seconds,
-with search, a state filter, and multi-select batch destroy. Creating a
-sandbox from here is exactly `acquireSandbox`: a key, the lifecycle
-knobs (including the never-stop
-[resident-agent switch](/docs/resident-agents)), and a template dropdown
-when templates are registered. After a
+The live list — every sandbox with its state and live CPU, memory, and
+disk columns, refreshed every few seconds, with search, a state filter,
+sorting, and multi-select batch destroy. Creating a sandbox from here
+is exactly `acquireSandbox`: a key, the lifecycle knobs (including the
+never-stop [resident-agent switch](/docs/resident-agents)), and a
+template dropdown when templates are registered. After a
 [template upgrade](/docs/templates#update-a-template), sandboxes still
 running the old image carry an "upgradable" marker next to their
 template name — rebuild them to move.
 
-A sandbox's detail page is a workspace with four tabs:
+A sandbox's detail page is a workspace:
 
-- **Overview** — identity, policy thresholds, last activity; destroy
-  and [rebuild](/docs/persistence#rebuild-a-sandbox) buttons, each
-  behind a confirmation dialog.
+- **Overview** — identity, policy thresholds with a countdown to the
+  next lifecycle step, last activity; an adjust-policy dialog (the
+  console's face of
+  [`updatePolicy`](/docs/lifecycle#change-the-policy-later)), plus
+  destroy and [rebuild](/docs/persistence#rebuild-a-sandbox) buttons,
+  each behind a confirmation dialog.
 - **Terminal** — a real interactive shell, kept behind an explicit
   "open" button because opening one *wakes* the sandbox. The browser
   speaks the same wire the official E2B SDK does. Closing the terminal
   kills its shell rather than leaving an orphan behind.
-- **Files** — browse, upload, download, rename, delete under
-  `/home/user`. File operations wake the sandbox too, so a cold sandbox
-  shows an explicit "open" gate first.
+- **Files** — browse, preview, edit, upload (drag and drop works),
+  download, rename, delete under `/home/user`, refreshing live while
+  the sandbox runs. File operations wake the sandbox too, so a cold
+  sandbox shows an explicit "open" gate first.
 - **Processes** — the E2B process table, polled without waking (a
   stopped sandbox honestly shows none).
+- **Metrics** — the sandbox's live resource snapshot, with an
+  in-session trend chart (the browser accumulates it — the daemon
+  [keeps no history](/docs/metrics)).
+- **History** — this sandbox's recent lifecycle events.
 
 ## Templates
 
@@ -64,12 +80,30 @@ form is the same [upgrade front door](/docs/templates) as
 `dor template add`. Deleting a template a sandbox still uses is refused
 with the daemon's own message naming the sandboxes.
 
+## Activity, domains, and settings
+
+Three more pages round out the operator view:
+
+- **Activity** — the daemon's recent history (who was created, frozen,
+  destroyed, what the reconciler repaired), filterable by event kind
+  and sandbox key. A bounded window, not an audit log.
+- **Domains** — bind domains to the daemon's front door (the managed
+  reverse proxy), with a copyable DNS record guide and a live per-domain
+  probe that shows DNS and certificate progress until each one turns
+  green. See
+  [Installation](/docs/installation#connect-from-another-machine).
+- **Settings** — the daemon's effective configuration, read-only, with
+  secrets shown as present-or-absent only. Changing configuration
+  happens in `/etc/dormice/env` plus a restart, never from the browser.
+
+A command palette (⌘K) jumps to any page or sandbox.
+
 ## Connect
 
 Copy-paste snippets for the SDK, the official E2B packages, and curl,
 pre-filled with the endpoint the browser itself is using. The API token
-is never displayed — the console traded it for a cookie at sign-in and
-cannot read it back; fetch it from the daemon host
+is never displayed — the console does not hold it and cannot read it
+back; fetch it from the daemon host
 (`grep ^DORMICE_API_TOKEN /etc/dormice/env`).
 
 ## What you will not find
diff --git a/website/content/docs/core-concepts.mdx b/website/content/docs/core-concepts.mdx
new file mode 100644
index 0000000..329ae6d
--- /dev/null
+++ b/website/content/docs/core-concepts.mdx
@@ -0,0 +1,149 @@
+---
+title: Core concepts
+description: Learn what the recurring terms in these docs mean — servers, containers, images, swap, object storage, reverse proxies, and E2B — with no Docker or Linux background assumed.
+---
+
+These docs use a handful of infrastructure terms without stopping to
+re-explain them on every page. This page is the one place they are all
+explained in plain language. You do not need to memorize it — other pages
+link back here the first time a term appears, so you can also just read
+on and return when a word is unfamiliar.
+
+## The host
+
+The host is the Linux server Dormice runs on — typically a machine you
+rent from a cloud provider and reach over the network. Everything in
+these docs lives on that one machine: the sandboxes, their data, and the
+program that manages them. When a page says "on the host", it means "on
+that server, as opposed to inside a sandbox or on your laptop".
+
+## Containers and images
+
+A container is a lightweight, isolated computer running inside the host.
+It has its own files, its own processes, and its own network — programs
+inside it cannot see the rest of the machine. Unlike a full virtual
+machine it shares the host's Linux kernel, which is what makes it cheap:
+starting one takes about a second, and an idle one costs almost nothing.
+Containers are treated as disposable — deleted and recreated freely.
+
+An image is the template a container starts from: a read-only snapshot
+of a filesystem with an operating system and preinstalled tools. Think
+of the image as an install disk and the container as a computer freshly
+booted from it. One image can start any number of containers, and the
+containers never modify the image.
+
+Docker is the standard tool that stores images and runs containers. The
+Dormice [installer](/docs/installation) sets it up for you; you only
+need to touch Docker directly if you build your own images for
+[templates](/docs/templates).
+
+## gVisor
+
+Containers alone are not a strong enough wall for running untrusted or
+AI-generated code, because every container talks to the host's real
+Linux kernel — and kernel bugs are how programs escape. gVisor is an
+extra isolation layer that puts a fake, userspace kernel between each
+sandbox and the real one. Malicious code attacks the decoy instead of
+your machine. Every Dormice sandbox runs under gVisor; the installer
+sets this up too. [Architecture & security](/docs/architecture) covers
+the full boundary.
+
+## Sandboxes
+
+A Dormice sandbox is a container plus one thing containers do not
+normally have: **a permanent disk of its own**. The disk is a file on
+the host that appears inside the sandbox as `/home/user`, and it is the
+sandbox's real body — the container around it can be deleted, upgraded,
+or lost to a crash, and the sandbox's files survive every time. Only
+`destroySandbox` deletes the disk. [Sandbox
+persistence](/docs/persistence) is the full story.
+
+## The daemon
+
+A daemon is a program that runs in the background forever rather than
+doing one job and exiting. The Dormice daemon is the single program that
+manages everything: it creates sandboxes, runs your commands in them,
+cools idle ones down, and serves the API, the E2B surface, and the web
+console — all on one port. The installer registers it with systemd, the
+Linux service manager, so it starts on boot and restarts if it crashes.
+
+The daemon keeps its records in SQLite, a database that lives in a
+single ordinary file — no database server to install or operate.
+
+## Swap and freezing
+
+Swap is disk space the operating system uses as overflow memory: when
+RAM runs short, memory that has not been touched recently is written out
+to disk, and read back the moment it is needed.
+
+Dormice's signature trick is built on it. When a sandbox sits idle, the
+daemon suspends its processes mid-flight and pushes their memory out to
+swap. Measured on real hardware, an idle sandbox holding 1 GiB of memory
+drops to about 5 MiB of RAM — and wakes in about 50 ms with every
+process exactly where it was. That is a **frozen** sandbox, and it is
+why keeping sandboxes forever is affordable. [Sandbox
+lifecycle](/docs/lifecycle) explains the full cool-down ladder.
+
+## Object storage (S3)
+
+Object storage is rented internet disk space: you upload files ("objects")
+into a named bucket and pay only for what is stored. S3 is Amazon's
+object storage service, and its API became the industry standard — many
+providers (Cloudflare R2, MinIO, Alibaba Cloud OSS, and others) speak
+the same protocol, so tools say "S3-compatible" to mean "works with any
+of them".
+
+Dormice uses object storage for exactly one optional feature:
+[archiving](/docs/archiving), which packs a long-idle sandbox's disk into a single
+compressed file, ships it to your bucket, and frees the host's disk. If
+you never configure S3, archiving simply stays off.
+
+## Reverse proxies, domains, and HTTPS
+
+The daemon only accepts connections from the host itself — that is a
+security default, not a limitation. To reach it from elsewhere you put a
+reverse proxy in front: a small program that stands at the machine's
+public door, receives requests from the internet, and forwards them to a
+program inside. The installer sets up [Caddy](https://caddyserver.com)
+for this role.
+
+Two related terms appear wherever proxies do:
+
+- **A DNS record** is the public phonebook entry that points a domain
+  name (like `dormice.example.com`) at your server's IP address. You
+  create it in the dashboard of whoever sold you the domain.
+- **TLS (the padlock behind `https://`)** encrypts traffic so tokens
+  and session cookies cannot be read in transit. It requires a
+  certificate per domain; Caddy obtains and renews certificates
+  automatically once the DNS record points at your server.
+
+## What is E2B
+
+[E2B](https://e2b.dev) is a popular commercial cloud service for running
+AI-generated code in sandboxes, with official SDKs (`e2b` on npm and
+PyPI) that many agent frameworks already use. Dormice speaks the E2B
+protocol: the unmodified official SDKs work against your own server by
+changing two URLs, which makes Dormice a drop-in, self-hosted
+alternative — see [Using the official E2B SDKs](/docs/e2b-sdks). If you
+have never used E2B, you can ignore every E2B mention in these docs and
+use the native API instead; nothing is behind it.
+
+## Tokens, SDKs, and the CLI
+
+The API token is a long random string the installer generates — a
+password for programs. Every client presents it with every request;
+anyone holding it controls your sandboxes, so it belongs in environment
+variables and secret stores, never in code.
+
+There are three ways to talk to the daemon, all equivalent:
+
+- **The native API** — plain HTTP requests; works from any language,
+  even `curl` in a shell. See the [HTTP API](/docs/http-api).
+- **An SDK** (software development kit) — a library that wraps the API
+  in ready-made functions for your programming language:
+  `@dormice/sdk` for TypeScript, or the official `e2b` packages.
+- **The CLI** (command-line interface) — the `dor` command you type in
+  a terminal, for looking around and one-off operations. See the [CLI
+  reference](/docs/cli).
+
+[Quick start](/docs/quickstart) walks all three.
diff --git a/website/content/docs/doctor.mdx b/website/content/docs/doctor.mdx
index a4ab42e..95aa26c 100644
--- a/website/content/docs/doctor.mdx
+++ b/website/content/docs/doctor.mdx
@@ -26,6 +26,12 @@ Checks are gated: when a prerequisite fails, dependent checks report
 *skip* with the blocker's name instead of piling on noise. Any failure
 exits 1; warnings don't affect the exit code.
 
+**You don't need to understand the checks to act on them.** A failed
+check prints the exact fix to run — copy it, re-run doctor, done. The
+list below explains what each check is protecting, for when you want to
+know why; the Linux terms in it are covered in
+[Core concepts](/docs/core-concepts).
+
 ## Platform
 
 - **operating system** — Linux, full stop: loop mounts, cgroups and
diff --git a/website/content/docs/e2b-differences.mdx b/website/content/docs/e2b-differences.mdx
index 3171f6c..8d3d745 100644
--- a/website/content/docs/e2b-differences.mdx
+++ b/website/content/docs/e2b-differences.mdx
@@ -3,6 +3,12 @@ title: Capabilities & differences
 description: What of the E2B surface Dormice implements — verified through the official SDK — and where it deliberately differs from the hosted product.
 ---
 
+This page is the compatibility contract for applications written
+against [E2B](/docs/core-concepts#what-is-e2b): which parts of the E2B
+surface Dormice implements, where it deliberately behaves differently,
+and what is honestly missing. If you are not migrating from E2B, you
+can skip it.
+
 ## What works
 
 Everything below is exercised by the black-box test suite *through the
diff --git a/website/content/docs/e2b-sdks.mdx b/website/content/docs/e2b-sdks.mdx
index ab44c40..bdd7868 100644
--- a/website/content/docs/e2b-sdks.mdx
+++ b/website/content/docs/e2b-sdks.mdx
@@ -3,10 +3,16 @@ title: Using the official E2B SDKs
 description: Learn how to run the official e2b packages — JavaScript and Python, unmodified — against Dormice by changing two URLs.
 ---
 
-Dormice speaks the E2B protocol, so the official `e2b` SDKs work against
-it without modification. Migrating an application is configuration, not
-code: point the SDK at your daemon's two URL prefixes and prefix your
-API token with `e2b_`.
+[E2B](https://e2b.dev) is a popular commercial sandbox cloud, and its
+official `e2b` SDKs (JavaScript and Python) are what many agent
+frameworks already build on ([what is
+E2B?](/docs/core-concepts#what-is-e2b)). Dormice speaks the E2B
+protocol, so those SDKs work against it without modification.
+Migrating an application is configuration, not code: point the SDK at
+your daemon's two URL prefixes and prefix your API token with `e2b_`.
+
+If you have never used E2B, you don't need this page — the [native
+API](/docs/quickstart) covers everything.
 
 Everything documented here is exercised by black-box test suites
 *through the official packages* (e2b 2.31.0, JavaScript and Python)
diff --git a/website/content/docs/files.mdx b/website/content/docs/files.mdx
index b8519cc..010bd08 100644
--- a/website/content/docs/files.mdx
+++ b/website/content/docs/files.mdx
@@ -3,6 +3,10 @@ title: Moving files
 description: Learn how to write and read files in a sandbox, from the SDK or the CLI — and what to do with files over the 16 MiB limit.
 ---
 
+Sandboxes do real work on real files — input data going in, results
+coming out. This page covers the native file verbs, their size limits,
+and the escape hatches for anything bigger.
+
 ## Write files
 
 You can write files into a sandbox with `writeFile` (one file) or
@@ -48,8 +52,9 @@ dor sandbox pull my-agent results/out.csv       # no local path: raw bytes to st
 
 ## Size limits: 16 MiB per file
 
-File content crosses the wire as base64 inside JSON, so each file is
-capped at 16 MiB, write and read alike. A `writeFiles` batch tops out at
+File content travels as base64 (an encoding that turns any bytes into
+plain text, so they fit inside a JSON request), so each file is capped
+at 16 MiB, write and read alike. A `writeFiles` batch tops out at
 48 MiB of request body, and a `readFiles` batch at 48 MiB total.
 
 Reading a file over the cap returns a **413 naming the file's actual
@@ -81,7 +86,7 @@ For bigger files, use one of these instead:
 
 File operations execute *inside* the sandbox, streamed through an
 in-container process — never as host-side writes into the disk image.
-This means a hostile symlink planted in the sandbox can only point at
-the sandbox's own filesystem, and ownership lands on the sandbox user
-naturally. See [Architecture](/docs/architecture) for the boundary this
+This means a hostile symlink (a file that is really a pointer to
+another path) planted in the sandbox can only point at the sandbox's
+own filesystem, and ownership lands on the sandbox user naturally. See [Architecture](/docs/architecture) for the boundary this
 preserves.
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
index 4b05db2..105fcd3 100644
--- a/website/content/docs/http-api.mdx
+++ b/website/content/docs/http-api.mdx
@@ -31,6 +31,7 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | Route | Does | Errors worth knowing |
 | --- | --- | --- |
 | `POST /acquireSandbox` | create, wake, or restore — idempotent per key | 400 invalid policy/unknown template, 429 at the sandbox limit |
+| `POST /updatePolicy` | patch an existing sandbox's [lifecycle policy](/docs/lifecycle#change-the-policy-later) in place; never wakes, never resets the idle clock | 404 unknown key, 400 invalid merged policy |
 | `POST /listSandboxes` | every sandbox and its state; never wakes anything | — |
 | `POST /execCommand` | run a command, buffered | 404 unknown key, 409 archived/restoring |
 | `POST /writeFiles` | batch write, base64 in JSON | 404/409 as above; body over 48 MiB refused |
@@ -43,7 +44,13 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | `POST /listTemplates` | every registered template | — |
 | `POST /removeTemplate` | unregister; idempotent | 409 while sandboxes still use it (names them) |
 | `POST /getHostMetrics` | host snapshot; never wakes anything | — |
+| `POST /getSandboxMetrics` | one sandbox's live CPU/memory/disk sample; `sample` is `null` when nothing is running | 404 unknown key |
+| `POST /listSandboxMetrics` | every measurable sandbox's sample in one answer | — |
 | `POST /listSandboxImages` | each sandbox's born image vs its template's current one | — |
+| `POST /listActivity` | the daemon's recent history, newest first — a bounded ring, not an audit log | — |
+| `POST /getConfig` | effective configuration, read-only; secrets reported present-or-absent, value never sent | — |
+| `POST /getIngress` | domains bound on the daemon's managed reverse proxy, with live DNS and certificate probes | — |
+| `POST /setIngress` | rewrite the managed proxy config to exactly this domain list (empty list unbinds all) | 400 when the daemon manages no proxy |
 
 **Only `acquireSandbox` creates.** The use verbs (`execCommand`, files,
 `rebuildSandbox`) answer 404 for an unknown key rather than creating a
diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdx
index 9299718..a371293 100644
--- a/website/content/docs/index.mdx
+++ b/website/content/docs/index.mdx
@@ -5,8 +5,13 @@ description: Dormice is a self-hosted sandbox platform for AI agents — run it
 
 Dormice gives your AI agents isolated Linux sandboxes where they can
 safely run code, process data, and keep a long-lived workspace — on a
-machine you already own. You install one daemon; it manages the sandboxes
-for you.
+machine you already own. You install one daemon (a program that runs in
+the background continuously); it manages the sandboxes for you.
+
+**New to Docker or self-hosting?** These docs explain every term the
+first time it matters, and [Core concepts](/docs/core-concepts) collects
+them all in one place — start there if words like container, image, or
+reverse proxy are new to you.
 
 Start a sandbox and run a command in a few lines:
 
@@ -31,25 +36,33 @@ console.log(result.stdout); // Hello from Dormice!
   sandbox for the same key — today, tomorrow, next month — with all its
   files intact.
 - **Idle costs almost nothing.** Idle sandboxes cool down on their own
-  (`active → frozen → stopped → archived`), and any acquire brings them
-  back. Measured on real hardware: freezing takes an idle sandbox holding
+  (`active → frozen → stopped → archived` — the
+  [lifecycle](/docs/lifecycle)), and any acquire brings them back.
+  Measured on real hardware: freezing takes an idle sandbox holding
   1 GiB of memory down to ~5 MiB, and waking it takes ~50 ms.
-- **Deploys like a single binary.** One daemon, one SQLite database, one
-  port. No Kubernetes, no external database.
-- **Works with the official E2B SDKs.** The unmodified `e2b` packages
-  (JavaScript and Python) run against Dormice by changing two URLs — see
+- **Deploys like a single binary.** One daemon, one SQLite database (a
+  database that lives in a single file), one port. No Kubernetes, no
+  external database.
+- **Works with the official E2B SDKs.** [E2B](https://e2b.dev) is a
+  popular commercial sandbox cloud that many agent frameworks build on;
+  its unmodified `e2b` packages (JavaScript and Python) run against
+  Dormice by changing two URLs — see
   [Using the official E2B SDKs](/docs/e2b-sdks).
 
 ## How it works
 
-The daemon runs each sandbox as a Docker container under
-[gVisor](https://gvisor.dev), with its own disk. When a sandbox sits
-idle, the daemon suspends its processes and squeezes their memory out to
-swap — so it costs a few megabytes of RAM and wakes in about 50 ms,
-processes still running. The sandbox's data lives on its own disk, not in
-the container, so it survives daemon restarts, host reboots, and even the
-container being deleted. [Architecture](/docs/architecture) has the full
-picture.
+The daemon runs each sandbox as a Docker
+[container](/docs/core-concepts#containers-and-images) hardened with
+[gVisor](/docs/core-concepts#gvisor) (an extra isolation layer that
+keeps untrusted code away from your real machine), and gives each one a
+disk of its own. When a sandbox sits idle, the daemon suspends its
+processes and squeezes their memory out to
+[swap](/docs/core-concepts#swap-and-freezing) — disk space the
+operating system uses as overflow memory — so it costs a few megabytes
+of RAM and wakes in about 50 ms, processes still running. The sandbox's
+data lives on its own disk, not in the container, so it survives daemon
+restarts, host reboots, and even the container being deleted.
+[Architecture](/docs/architecture) has the full picture.
 
 ## Status
 
@@ -60,9 +73,11 @@ production yet.
 
 ## Next steps
 
-1. [Installation](/docs/installation) — set up the daemon on a Linux
+1. [Core concepts](/docs/core-concepts) — the terms these docs use,
+   explained from zero.
+2. [Installation](/docs/installation) — set up the daemon on a Linux
    host with one command.
-2. [Quick start](/docs/quickstart) — acquire your first sandbox and run
+3. [Quick start](/docs/quickstart) — acquire your first sandbox and run
    commands in it.
-3. [Using the official E2B SDKs](/docs/e2b-sdks) — if you already have
+4. [Using the official E2B SDKs](/docs/e2b-sdks) — if you already have
    an E2B application, point it at Dormice.
diff --git a/website/content/docs/installation.mdx b/website/content/docs/installation.mdx
index 7e0c149..3989ec2 100644
--- a/website/content/docs/installation.mdx
+++ b/website/content/docs/installation.mdx
@@ -3,29 +3,47 @@ title: Installation
 description: Install the Dormice daemon on a Linux host with one command.
 ---
 
+Installing Dormice is one command on a fresh Linux server. The command
+downloads an installer script that sets up everything the platform
+needs; you do not need to know Docker or Linux administration — this
+page tells you what to type, and explains what happened afterwards.
+
 ## Install the daemon
 
-Run this as root on a bare Ubuntu/Debian x86_64 host:
+You need a Linux server ([the host](/docs/core-concepts#the-host))
+running Ubuntu or Debian on a regular Intel/AMD CPU (`x86_64`), ideally
+freshly created. Log in as root — the administrator account, which most
+cloud providers give you by default — and run:
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash
 ```
 
-If your host has a slow connection to GitHub and the usual package
-sources, add `-s -- --mirror cn`.
-
-The installer sets up everything — Docker, gVisor, swap, the network
-hardening, the daemon as a systemd service — and finishes by running
-`dor doctor`, a battery of read-only checks that verifies the install
-actually works. You can re-run `dor doctor` at any time.
+The command downloads the install script and runs it in one step. If
+your host has a slow connection to GitHub and the usual package sources
+(common on servers in mainland China), add `-s -- --mirror cn`.
+
+The installer sets up everything —
+[Docker](/docs/core-concepts#containers-and-images) (the container
+runtime), [gVisor](/docs/core-concepts#gvisor) (the extra isolation
+layer around each sandbox),
+[swap](/docs/core-concepts#swap-and-freezing) (the disk-as-overflow-memory
+that makes freezing work), the network hardening, and the daemon itself
+as a systemd service (so it starts on boot and restarts after a crash).
+It finishes by running `dor doctor`, a battery of read-only checks that
+verifies the install actually works. You can re-run `dor doctor` at any
+time.
 
 **The installer is safe to re-run.** Running it again upgrades the code
 and repairs anything that drifted, and never rotates your API token.
 
 ## Get your API token
 
-The installer generates an API token and stores it in the daemon's
-config file. You need it for every client — SDK, CLI, and console:
+The installer generates an [API
+token](/docs/core-concepts#tokens-sdks-and-the-cli) — a long random
+string that acts as the password for programs — and stores it in the
+daemon's config file. You need it for every client — SDK, CLI, and
+console. Print it with:
 
 ```sh
 grep ^DORMICE_API_TOKEN /etc/dormice/env
@@ -36,53 +54,77 @@ grep ^DORMICE_API_TOKEN /etc/dormice/env
 The daemon listens on `127.0.0.1` only — reaching it from another
 machine is a choice you make explicitly, one of two ways.
 
-**Option 1: SSH tunnel** (private, zero setup):
+**Option 1: SSH tunnel** (private, zero setup). SSH — the tool you
+already use to log in to the server — can also carry other traffic
+through its encrypted connection, making a port on the server appear on
+your own machine:
 
 ```sh
 ssh -L 3676:127.0.0.1:3676 root@your-host
 ```
 
-Then use `http://127.0.0.1:3676` as your endpoint, as if the daemon were
-local.
+Keep that command running, and use `http://127.0.0.1:3676` as your
+endpoint, as if the daemon were local.
 
-**Option 2: Reverse proxy** — serves the API, the E2B surface, and the
-web console at once. With Caddy, TLS certificates are automatic once you
+**Option 2: Bind a domain** — serves the API, the E2B surface, and the
+web console at once, over HTTPS. The installer already placed a reverse
+proxy ([Caddy](https://caddyserver.com)) at the server's public door —
+a small program that receives internet requests and forwards them to
+the daemon ([what's a reverse
+proxy?](/docs/core-concepts#reverse-proxies-domains-and-https)). To
 give it a domain:
 
-```text
-your-domain.example {
-	reverse_proxy 127.0.0.1:3676 {
-		flush_interval -1
-	}
-}
-```
-
-**Note:** `flush_interval -1` matters — streamed command output is
-written frame by frame, and a buffering proxy would hold it all back
-until the end. Use HTTPS for anything exposed beyond localhost: the API
-token and the session cookie travel in every request.
+1. Create a DNS A record pointing your domain (say,
+   `dormice.example.com`) at the server's public IP — in the dashboard
+   of whoever sold you the domain.
+2. Bind the domain on the web console's domains page (or with the
+   `setIngress` API verb). The daemon rewrites its managed Caddy
+   config, and Caddy obtains and renews the HTTPS certificate on its
+   own. The domains page shows each domain's real progress — DNS
+   resolution and certificate status — until it turns green.
+
+**Note:** Do not hand-edit the managed Caddy config — the next bind
+rewrites it. If you run your own proxy instead, forward to
+`127.0.0.1:3676` with buffering disabled (`flush_interval -1` in
+Caddy): streamed command output is written frame by frame, and a
+buffering proxy would hold it all back until the end. Use HTTPS for
+anything exposed beyond localhost — the API token and the session
+cookie travel in every request.
 
 ## What the host needs
 
-The installer handles all of this and `dor doctor` verifies it, but
-these are the requirements underneath:
-
-- **Docker + gVisor (`runsc`)**, and root — sandboxes are gVisor
-  containers, and the daemon needs loop mounts and cgroup writes.
-- **Swap, with `vm.swappiness=100`.** Freezing works by pushing idle
-  sandbox memory to swap. gVisor holds sandbox memory in a form the
-  kernel refuses to swap at the default setting — measured on real
-  hardware: 0 bytes reclaimed at the default, 99.5% reclaimed at 100.
-  Some cloud images (Alibaba Cloud, for one) ship `vm.swappiness=0`;
-  check the effective value with `sysctl vm.swappiness`.
-- **Network hardening.** Sandboxes run untrusted code, so the installer
-  blocks the cloud metadata service from containers
-  (`iptables -I DOCKER-USER -d 169.254.0.0/16 -j DROP`, persisted) and
-  disables inter-container traffic (`"icc": false` in `daemon.json`).
+The installer handles all of this and `dor doctor` verifies it — you
+never need to set any of it up by hand. This section just explains what
+the installer changed on your machine and why; skipping it does not
+affect using Dormice.
+
+- **Docker + gVisor (`runsc`), and root.** Sandboxes are
+  [containers](/docs/core-concepts#containers-and-images) hardened with
+  [gVisor](/docs/core-concepts#gvisor), and managing them takes
+  administrator privileges (the daemon attaches each sandbox's disk and
+  adjusts its memory accounting, both root-only operations).
+- **Swap, with `vm.swappiness=100`.** Swap is disk space the operating
+  system uses as overflow memory, and
+  [freezing](/docs/core-concepts#swap-and-freezing) works by pushing
+  idle sandbox memory out to it. The `vm.swappiness` setting is the
+  kernel's willingness to do that — and gVisor holds sandbox memory in
+  a form the kernel refuses to swap at the default setting. Measured on
+  real hardware: 0 bytes reclaimed at the default, 99.5% reclaimed
+  at 100. Some cloud images (Alibaba Cloud, for one) ship
+  `vm.swappiness=0`; check the effective value with
+  `sysctl vm.swappiness`.
+- **Network hardening.** Sandboxes run untrusted code, and a cloud
+  server exposes a special internal address that hands out the
+  machine's cloud credentials to anything that asks (the metadata
+  service). The installer adds a firewall rule so containers can never
+  reach it (`iptables -I DOCKER-USER -d 169.254.0.0/16 -j DROP`,
+  persisted), and stops sandboxes from talking to each other
+  (`"icc": false` in Docker's `daemon.json`).
 - **One machine, one daemon.** The daemon enforces this with a lock and
   refuses to start when its database and the machine's reality don't
   match.
 
 Without a prepared Linux host, the daemon still runs anywhere Node 22+
-runs using an in-memory fake executor — useful for development, not for
-real sandboxes.
+runs using a fake executor — a stand-in that simulates sandboxes in
+memory instead of starting real containers. Useful for developing
+against the API on a laptop, not for real sandboxes.
diff --git a/website/content/docs/lifecycle.mdx b/website/content/docs/lifecycle.mdx
index 746df8d..cfc82c6 100644
--- a/website/content/docs/lifecycle.mdx
+++ b/website/content/docs/lifecycle.mdx
@@ -17,16 +17,20 @@ active ── idle ──▶ frozen ── idle ──▶ stopped ── idle 
 
 - **active** — the container is running, normally.
 - **frozen** — every process is suspended and its memory pushed out to
-  swap. Measured on real hardware: an idle sandbox holding 1 GiB drops to
-  about 5 MiB of resident memory, and wakes in about 50 ms with all its
-  processes still running, exactly where they were.
+  [swap](/docs/core-concepts#swap-and-freezing), the disk space the
+  operating system uses as overflow memory. Measured on real hardware:
+  an idle sandbox holding 1 GiB drops to about 5 MiB of actual RAM, and
+  wakes in about 50 ms with all its processes still running, exactly
+  where they were.
 - **stopped** — the container is shut down; only the disk remains.
   Waking is a cold start from the surviving disk — seconds rather than
   milliseconds. Processes do not survive this step; files do.
-- **archived** — the disk is compressed and shipped to an S3-compatible
-  bucket; nothing remains on the host. This state only exists when you
-  [configure archiving](/docs/archiving). Waking downloads and unpacks
-  the disk, with real progress reporting.
+- **archived** — the disk is compressed and shipped to rented internet
+  storage (an [S3-compatible
+  bucket](/docs/core-concepts#object-storage-s3)); nothing remains on
+  the host. This state only exists when you [configure
+  archiving](/docs/archiving). Waking downloads and unpacks the disk,
+  with real progress reporting.
 
 ## Set the lifecycle policy
 
@@ -53,9 +57,11 @@ freeze ≤ stop ≤ archive.
 
 **Good to know:**
 
-- **Policy is fixed at creation.** A policy sent while acquiring an
-  *existing* sandbox is not applied — the sandbox keeps the policy it was
-  born with. (An invalid policy is still rejected with a 400.)
+- **Acquire never changes an existing sandbox's policy.** A policy sent
+  while acquiring an *existing* sandbox is not applied — the sandbox
+  keeps the policy it was born with. (An invalid policy is still
+  rejected with a 400.) To change it later, use
+  [`updatePolicy`](#change-the-policy-later).
 - **Archiving requires stopping.** Only a stopped sandbox can archive,
   so `archiveAfterSeconds` needs a non-null `stopAfterSeconds`. On a
   daemon without S3 configured, a policy asking to archive is rejected
@@ -69,6 +75,27 @@ A background scanner checks every `DORMICE_SCAN_INTERVAL_SECONDS`
 (default 60) and moves each idle sandbox down at most one state per
 sweep.
 
+## Change the policy later
+
+`updatePolicy` adjusts an existing sandbox's thresholds in place — no
+destroying, no recreating, files untouched:
+
+```ts
+// Promote a sandbox that has been running for days into a
+// resident agent that never cold-starts:
+await client.updatePolicy('my-agent', { stopAfterSeconds: null });
+```
+
+It is a patch: fields you omit keep their current values, and `null`
+still means "never take that step". The merged result is validated by
+the same rules as at creation (ordering included), so an update can
+never produce a policy that creation would have refused.
+
+**Note:** Changing the policy is not sandbox activity. Nothing is woken
+and the idle clock is not reset — the new thresholds apply immediately,
+counting the idle time already accumulated. A frozen sandbox can be
+promoted to never-stop in its sleep.
+
 ## Keep a sandbox warm forever
 
 For a long-lived agent's sandbox, set `stopAfterSeconds: null`:
diff --git a/website/content/docs/meta.json b/website/content/docs/meta.json
index 4d5ddfb..d9f4719 100644
--- a/website/content/docs/meta.json
+++ b/website/content/docs/meta.json
@@ -2,7 +2,7 @@
   "groups": [
     {
       "title": "Getting started",
-      "pages": ["index", "installation", "quickstart"]
+      "pages": ["index", "core-concepts", "installation", "quickstart"]
     },
     {
       "title": "Concepts",
diff --git a/website/content/docs/metrics.mdx b/website/content/docs/metrics.mdx
index 2d0cc55..d8b1286 100644
--- a/website/content/docs/metrics.mdx
+++ b/website/content/docs/metrics.mdx
@@ -15,22 +15,43 @@ exactly as cheap as if you ignored them.
 
 ## Get metrics for one sandbox
 
-The E2B SDK's `getMetrics()` returns an array with one live sample —
-CPU count and usage, memory, and disk:
+The native `getSandboxMetrics` verb returns one live sample — CPU count
+and usage, memory, and disk:
 
 ```ts
-const [m] = await sbx.getMetrics();
-m.memUsed;  // bytes
-m.memTotal;
-m.diskUsed; // real occupancy of the sandbox's disk
-m.diskTotal;
+const sample = await client.getSandboxMetrics('my-agent');
+if (sample) {
+  sample.cpuUsedPct;    // percent of one CPU; can exceed 100
+  sample.memUsedBytes;
+  sample.memTotalBytes;
+  sample.diskUsedBytes; // real occupancy of the sandbox's disk
+  sample.diskTotalBytes;
+}
 ```
 
+The E2B SDK's `getMetrics()` reads the same numbers, returned as an
+array with one sample. Either way:
+
 - A **frozen** sandbox is readable without waking it.
-- A **stopped** sandbox answers an empty array: no container, honestly
-  no sample — never zeros pretending to be measurements.
-- The SDK's `start` / `end` range parameters are accepted and ignored —
-  there is no metrics history, only now.
+- A **stopped** (or archived, or restoring) sandbox has no running
+  container, so the answer is honestly empty — `null` natively, an
+  empty array through E2B — never zeros pretending to be measurements.
+- The E2B SDK's `start` / `end` range parameters are accepted and
+  ignored — there is no metrics history, only now.
+
+## Get metrics for every sandbox at once
+
+`listSandboxMetrics` answers for the whole fleet in a single request —
+a dashboard over N sandboxes costs one call, not N:
+
+```ts
+const samples = await client.listSandboxMetrics();
+// [{ externalId, sandboxId, sample }, …]
+```
+
+Only sandboxes with a running or frozen container appear; colder
+sandboxes are simply absent — the same honesty as `null`, expressed as
+absence.
 
 ## Get metrics for the host
 
diff --git a/website/content/docs/persistence.mdx b/website/content/docs/persistence.mdx
index 7022a51..00d50ff 100644
--- a/website/content/docs/persistence.mdx
+++ b/website/content/docs/persistence.mdx
@@ -3,10 +3,11 @@ title: Sandbox persistence
 description: Everything under /home/user survives freezes, stops, restarts, and archiving. Learn what persists, what doesn't, and how rebuilds work.
 ---
 
-Every sandbox owns a disk: an image file on the host
-(`DORMICE_SANDBOX_DISK_GB`, default 10 GB) mounted at `/home/user`. The
-container around it is replaceable machinery. That gives you one rule to
-remember:
+Every sandbox owns a disk: a single large file on the host that acts as
+a complete private disk (`DORMICE_SANDBOX_DISK_GB`, default 10 GB),
+appearing inside the sandbox as `/home/user`. The
+[container](/docs/core-concepts#containers-and-images) around it is
+replaceable machinery. That gives you one rule to remember:
 
 > **What lives in `/home/user` survives everything short of destroying
 > the sandbox. Everything outside it is container state, and containers
@@ -24,13 +25,14 @@ gVisor host:
   transition.
 - **Daemon restarts and host reboots** — the daemon checks its records
   against reality at boot, and the next wake re-attaches the disk.
-- **`docker container prune`** deleting the container — the next acquire
-  builds a fresh container from the surviving disk: same sandbox ID,
+- **`docker container prune`** (a Docker cleanup command that deletes
+  stopped containers) removing the container — the next acquire builds
+  a fresh container from the surviving disk: same sandbox ID,
   `/home/user` intact.
 - **Out-of-memory** — a sandbox that hits its memory cap
-  (`DORMICE_SANDBOX_MEMORY_GB`, default 2 GB) is killed by gVisor with
-  exit code 137 and recorded as stopped. The same key acquires it right
-  back, files intact.
+  (`DORMICE_SANDBOX_MEMORY_GB`, default 2 GB) is killed with exit
+  code 137, the Linux convention for "forcibly killed", and recorded as
+  stopped. The same key acquires it right back, files intact.
 - **Archive → restore** — the disk round-trips through S3 and comes
   back byte-for-byte.
 
@@ -69,10 +71,12 @@ sandbox sits in the bucket and it comes back bigger — for free.
 
 ## How the disk quota works
 
-The quota is physical: the disk image file is simply that big. A sandbox
-that fills its disk gets `ENOSPC` from its own filesystem — there is no
-accounting layer to game, and the host's disk stays healthy. The image
-is sparse, so a 10 GB promise occupies only what has actually been
-written; disk is overcommitted by default, and
-[`getHostMetrics`](/docs/metrics) reports both the promised and the real
-total so you can watch it.
+The quota is physical: the disk image file is simply that big. A
+sandbox that fills its disk gets `ENOSPC` ("no space left on device")
+from its own filesystem — there is no accounting layer to game, and the
+host's disk stays healthy. The disk file is sparse — the operating
+system only stores the parts that have actually been written — so a
+10 GB promise occupies only what the sandbox really uses. This means
+the promises can add up to more than the host's disk (overcommit), and
+[`getHostMetrics`](/docs/metrics) reports both the promised and the
+real total so you can watch it.
diff --git a/website/content/docs/ports.mdx b/website/content/docs/ports.mdx
index 2ddc593..d2232f5 100644
--- a/website/content/docs/ports.mdx
+++ b/website/content/docs/ports.mdx
@@ -5,7 +5,19 @@ description: Learn how to reach a server running inside a sandbox from the outsi
 
 Anything listening on a port inside a sandbox — a dev server, a
 notebook, an agent's UI — can be reached from outside through the
-daemon's sandbox proxy.
+daemon's sandbox proxy: each sandbox port gets its own preview URL like
+`8000-<sandboxId>.sbx.example.com`.
+
+Setting this up takes three ingredients, each explained in [Core
+concepts](/docs/core-concepts#reverse-proxies-domains-and-https): a
+domain dedicated to sandbox traffic, one wildcard DNS record (a
+phonebook entry matching *every* name under that domain, so each
+sandbox URL resolves without its own record), and a reverse proxy to
+receive the traffic and handle HTTPS.
+
+**Note:** this domain is for sandbox preview traffic only — it is
+separate from the domain you may have bound for the API and console in
+[Installation](/docs/installation#connect-from-another-machine).
 
 ## 1. Set the sandbox domain
 
@@ -32,8 +44,10 @@ one wildcard DNS record plus a reverse proxy that terminates TLS:
 ```
 
 **Note:** `flush_interval -1` keeps streaming responses unbuffered —
-verified with a real terminal session through Caddy. A wildcard
-certificate needs Caddy's DNS challenge; plain HTTP works for a LAN.
+verified with a real terminal session through Caddy. An HTTPS
+certificate covering `*.sbx.example.com` needs Caddy's DNS challenge
+(Caddy proves domain ownership through your DNS provider's API instead
+of per-name web checks); plain HTTP works for a LAN.
 
 ## 3. Get the URL with `getHost()`
 
diff --git a/website/content/docs/quickstart.mdx b/website/content/docs/quickstart.mdx
index a774950..e11beed 100644
--- a/website/content/docs/quickstart.mdx
+++ b/website/content/docs/quickstart.mdx
@@ -3,10 +3,17 @@ title: Quick start
 description: This guide shows you how to acquire your first sandbox, run commands in it, and write files — with the SDK, curl, or the CLI.
 ---
 
+By the end of this page you will have created a sandbox, run a command
+inside it, written a file into it, and destroyed it — from TypeScript,
+from plain `curl`, or from your terminal. It assumes a daemon is
+already running (from [Installation](/docs/installation)).
+
 ## 1. Set your environment variables
 
-You need the daemon's address and its API token
-(from [Installation](/docs/installation)):
+Clients find the daemon through two environment variables — named
+values your shell passes to every program you start. You need the
+daemon's address and its [API
+token](/docs/core-concepts#tokens-sdks-and-the-cli):
 
 ```sh
 export DORMICE_ENDPOINT=http://127.0.0.1:3676
@@ -51,9 +58,10 @@ inside the sandbox, files persist until you destroy it.
 
 ## Use curl instead
 
-Every operation is a plain HTTP RPC route named after the SDK method
-(`POST /acquireSandbox`, `POST /execCommand`, …), authenticated with a
-Bearer token — so curl works anywhere the SDK doesn't reach:
+Every operation is a plain HTTP request named after the SDK method
+(`POST /acquireSandbox`, `POST /execCommand`, …), with the API token
+sent in the `Authorization` header — so curl works anywhere the SDK
+doesn't reach:
 
 ```sh
 curl -X POST http://127.0.0.1:3676/listSandboxes \
diff --git a/website/content/docs/resident-agents.mdx b/website/content/docs/resident-agents.mdx
index 0dcf46e..e1ebff1 100644
--- a/website/content/docs/resident-agents.mdx
+++ b/website/content/docs/resident-agents.mdx
@@ -28,9 +28,9 @@ processes. A runnable version of this pattern lives at
 ## Freezing suspends processes — it does not kill them
 
 A frozen sandbox's processes stop mid-flight and resume exactly where
-they were: a REPL keeps its state, a dev server its sockets, an agent
-process its memory. Nothing running in a resident sandbox is ever killed
-by idleness.
+they were: a REPL (an interactive language session) keeps its state, a
+dev server its connections, an agent process its memory. Nothing
+running in a resident sandbox is ever killed by idleness.
 
 **The flip side:** a background process does not *keep* its sandbox
 warm. Once nothing is watching it, the idle clock runs, the sandbox
@@ -41,8 +41,9 @@ cost a few MiB.
 
 ## What an idle sandbox costs
 
-A frozen sandbox costs a few MiB of resident memory (the rest sits in
-swap), plus a sparse disk that occupies only what was actually written.
+A frozen sandbox costs a few MiB of actual RAM (the rest sits in
+[swap](/docs/core-concepts#swap-and-freezing)), plus a sparse disk that
+occupies only what was actually written.
 That is the entire idle bill — which is why one modest machine can hold
 a long tail of dormant agents.
 
diff --git a/website/content/docs/templates.mdx b/website/content/docs/templates.mdx
index befaf7b..5eb1d84 100644
--- a/website/content/docs/templates.mdx
+++ b/website/content/docs/templates.mdx
@@ -3,9 +3,21 @@ title: Templates
 description: Learn how to create sandboxes from your own Docker images by registering them as templates.
 ---
 
-A template is a name pointing at a Docker image. Dormice deliberately
-has no build pipeline — the host's Docker daemon is already an image
-store, and `docker build` is already the build tool.
+A template is a name pointing at a [Docker
+image](/docs/core-concepts#containers-and-images) — the read-only
+snapshot a sandbox starts from. Register your own image as a template
+and sandboxes created from it come with your tools preinstalled.
+Dormice deliberately has no build pipeline — the host's Docker daemon
+is already an image store, and `docker build` is already the build
+tool.
+
+**Never built a Docker image?** The three-line version: you write a
+`Dockerfile` — a recipe that starts from an existing image and adds
+your tools (`FROM ubuntu:24.04`, then `RUN apt-get install …`) — and
+`docker build -t name:v1 .` bakes it into an image tagged `name:v1`.
+The `:v1` part is the tag: a version label you choose. Docker's own
+[getting-started guide](https://docs.docker.com/get-started/) covers
+the rest.
 
 ## Create a template
 
diff --git a/website/content/docs/upgrading.mdx b/website/content/docs/upgrading.mdx
index bf3eabc..7402516 100644
--- a/website/content/docs/upgrading.mdx
+++ b/website/content/docs/upgrading.mdx
@@ -3,6 +3,11 @@ title: Upgrading
 description: Re-run the installer to upgrade the daemon — learn what survives, what restarts, and how sandbox images move separately.
 ---
 
+Upgrading Dormice is the same one command as installing it, and it
+never touches your sandboxes or their files. This page covers what an
+upgrade changes, what it leaves alone, and how sandbox images upgrade
+on their own separate schedule.
+
 ## Upgrade the daemon
 
 Re-running the installer is the upgrade. It pulls the latest code,
@@ -66,6 +71,7 @@ rebuild simply keep running on the image they were born with.
 The installer refuses to call itself done until the daemon answers
 `/healthz` and `dor doctor` passes. If it stops early, the failed step
 prints what it found; fix that and re-run — it continues from where it
-left off. The daemon's own story is in `journalctl -u dormice -f`, and
+left off. The daemon's own story is in its live log — read it with
+`journalctl -u dormice -f` — and
 [Troubleshooting](/docs/troubleshooting) collects the failures that have
 actually happened.
diff --git a/website/src/lib/docs.ts b/website/src/lib/docs.ts
index 3c77265..2a8af6d 100644
--- a/website/src/lib/docs.ts
+++ b/website/src/lib/docs.ts
@@ -8,6 +8,7 @@ import * as cli from '../../content/docs/cli.mdx';
 import * as commands from '../../content/docs/commands.mdx';
 import * as configuration from '../../content/docs/configuration.mdx';
 import * as consoleDoc from '../../content/docs/console.mdx';
+import * as coreConcepts from '../../content/docs/core-concepts.mdx';
 import * as doctor from '../../content/docs/doctor.mdx';
 import * as e2bDifferences from '../../content/docs/e2b-differences.mdx';
 import * as e2bSdks from '../../content/docs/e2b-sdks.mdx';
@@ -40,6 +41,7 @@ interface DocModule {
 // meta.json name -> module ('index' is the /docs landing page, slug '').
 const modules: Record<string, DocModule> = {
   index: indexDoc,
+  'core-concepts': coreConcepts,
   installation,
   quickstart,
   lifecycle,

From f4256dbdaa79ce7a12a24b0eb1f31ceceab17ce3 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 18:16:32 +0800
Subject: [PATCH 079/133] One click carries the daemon across its own restart:
 applyUpgrade hands install.sh to a systemd transient unit (the unit name is
 the mutex), getUpgradeStatus trusts systemd over the status file's claim, and
 the console dialog says what will break, tails the real log, and waits out
 the reconnect

---
 .../console/src/components/AppSidebar.tsx     |  11 +
 .../console/src/features/activity/kinds.ts    |   3 +
 .../settings/components/UpgradeDialog.tsx     | 259 ++++++++++++++++++
 .../settings/components/VersionCard.tsx       | 104 +++++--
 .../src/features/settings/hooks/useUpgrade.ts |  30 +-
 packages/console/src/lib/api.ts               |  13 +
 packages/console/vite.config.ts               |   2 +
 packages/sdk/src/client.ts                    |  29 ++
 packages/server/src/app.ts                    |  10 +-
 packages/server/src/main.ts                   |   2 +
 packages/server/src/routes/upgrade.ts         |  51 +++-
 packages/server/src/updater.test.ts           | 186 ++++++++++++-
 packages/server/src/updater.ts                | 220 ++++++++++++++-
 packages/shared/src/activity.ts               |   6 +
 packages/shared/src/upgrade.ts                |  72 +++++
 15 files changed, 959 insertions(+), 39 deletions(-)
 create mode 100644 packages/console/src/features/settings/components/UpgradeDialog.tsx

diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index 7abf696..55224a2 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -27,6 +27,7 @@ import {
   SidebarMenuButton,
   SidebarMenuItem,
 } from '@/components/ui/sidebar';
+import { useCachedUpgradable } from '@/features/settings/hooks/useUpgrade';
 import { logout } from '@/lib/api';
 import { MOCK_PAGES_ENABLED } from '@/lib/mock';
 import { clearSessionMarker } from '@/lib/session';
@@ -87,6 +88,8 @@ export function AppSidebar() {
     select: (state) => state.location.pathname,
   });
   const { resolvedTheme, setTheme } = useTheme();
+  // 只读缓存:设置页查过且有新版本才亮,角标自己绝不发请求。
+  const upgradable = useCachedUpgradable();
 
   return (
     <Sidebar variant="inset" className="px-1">
@@ -124,6 +127,14 @@ export function AppSidebar() {
                         <span>{item.label}</span>
                       </SidebarMenuButton>
                       {item.mock && <SidebarMenuBadge>预览</SidebarMenuBadge>}
+                      {item.to === '/settings' && upgradable && (
+                        <SidebarMenuBadge>
+                          <span
+                            className="size-2 rounded-full bg-amber-500"
+                            title="有新版本可升级"
+                          />
+                        </SidebarMenuBadge>
+                      )}
                     </SidebarMenuItem>
                   ))}
                 </SidebarMenu>
diff --git a/packages/console/src/features/activity/kinds.ts b/packages/console/src/features/activity/kinds.ts
index 29a57f1..8a91bc0 100644
--- a/packages/console/src/features/activity/kinds.ts
+++ b/packages/console/src/features/activity/kinds.ts
@@ -20,6 +20,7 @@ export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
   'policy-changed': '策略调整',
   'daemon-started': 'daemon 启动',
   'ingress-updated': '域名配置',
+  'upgrade-started': '发起升级',
 };
 
 // 事件色与沙箱状态徽章同一色系:落到哪个状态就穿哪个颜色;
@@ -51,4 +52,6 @@ export const ACTIVITY_KIND_STYLES: Record<ActivityKind, string> = {
   'daemon-started': 'border-border bg-muted text-muted-foreground',
   'ingress-updated':
     'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  'upgrade-started':
+    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
 };
diff --git a/packages/console/src/features/settings/components/UpgradeDialog.tsx b/packages/console/src/features/settings/components/UpgradeDialog.tsx
new file mode 100644
index 0000000..326161c
--- /dev/null
+++ b/packages/console/src/features/settings/components/UpgradeDialog.tsx
@@ -0,0 +1,259 @@
+import type { GetUpgradeStatusResponse, UpgradeRun } from '@dormice/shared';
+import { useQueryClient } from '@tanstack/react-query';
+import { useEffect, useRef, useState } from 'react';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Spinner } from '@/components/ui/spinner';
+import { ApiError, applyUpgrade, getUpgradeStatus } from '@/lib/api';
+
+/**
+ * 一键升级的两幕:确认(把会发生什么说全 — 包括 daemon 重启会打断
+ * 进行中的终端/exec/watch,以及构建失败自动回退)→ 观察(2 秒轮询
+ * getUpgradeStatus,实时滚日志)。轮询不用查询库而是自己的 setTimeout
+ * 链:daemon 重启造成的失联是升级的预期环节,要显示「重启中」继续等,
+ * 而不是当错误处理。终局以 install.sh 写下的报告为准 — succeeded 意味
+ * 着 daemon 已带着新版本回来并通过 doctor,不是"脚本跑完了"。
+ *
+ * 防「上一次的旧报告」误判:观察态先要见过进行中(unit 活着或报告说
+ * running)才接受终局 — applyUpgrade 刚返回时状态文件可能还是上一轮的。
+ */
+interface UpgradeDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** 打开时升级已在跑(上次没看完/别处发起)— 跳过确认直接观察。 */
+  alreadyRunning: boolean;
+}
+
+export function UpgradeDialog({
+  open,
+  onOpenChange,
+  alreadyRunning,
+}: UpgradeDialogProps) {
+  const queryClient = useQueryClient();
+  const [phase, setPhase] = useState<'confirm' | 'watch'>('confirm');
+  const [launching, setLaunching] = useState(false);
+  const [launchError, setLaunchError] = useState<string | null>(null);
+  const [snapshot, setSnapshot] = useState<GetUpgradeStatusResponse | null>(
+    null,
+  );
+  const [unreachable, setUnreachable] = useState(false);
+  const [outcome, setOutcome] = useState<UpgradeRun | null>(null);
+  const sawProgress = useRef(false);
+
+  // 每次打开都是一场新的升级:上一场的快照与终局不许串场。
+  useEffect(() => {
+    if (!open) return;
+    setPhase(alreadyRunning ? 'watch' : 'confirm');
+    setLaunching(false);
+    setLaunchError(null);
+    setSnapshot(null);
+    setUnreachable(false);
+    setOutcome(null);
+    sawProgress.current = alreadyRunning;
+  }, [open, alreadyRunning]);
+
+  useEffect(() => {
+    if (!open || phase !== 'watch' || outcome !== null) return;
+    let stopped = false;
+    let timer: number | undefined;
+    const tick = async () => {
+      try {
+        const status = await getUpgradeStatus();
+        if (stopped) return;
+        setUnreachable(false);
+        setSnapshot(status);
+        if (status.running || status.last?.state === 'running') {
+          sawProgress.current = true;
+        } else if (sawProgress.current && status.last !== null) {
+          setOutcome(status.last);
+          // 成功后重新问一次版本(新 daemon 的缓存是空的,会真查一次
+          // 并显示已是最新);无论成败,执行窗与配置都过期了。
+          queryClient.invalidateQueries({ queryKey: ['checkUpgrade'] });
+          queryClient.invalidateQueries({ queryKey: ['upgradeStatus'] });
+          queryClient.invalidateQueries({ queryKey: ['config'] });
+          return;
+        }
+      } catch {
+        if (stopped) return;
+        // 失联 = daemon 大概率在重启,升级本身在 systemd unit 里继续。
+        setUnreachable(true);
+      }
+      timer = window.setTimeout(tick, 2000);
+    };
+    tick();
+    return () => {
+      stopped = true;
+      if (timer !== undefined) window.clearTimeout(timer);
+    };
+  }, [open, phase, outcome, queryClient]);
+
+  // 日志跟到底部 — 观察窗要像 tail -f。
+  const logRef = useRef<HTMLPreElement>(null);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: 滚动跟随日志内容
+  useEffect(() => {
+    const el = logRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+  }, [snapshot?.log]);
+
+  const start = async () => {
+    setLaunching(true);
+    setLaunchError(null);
+    try {
+      await applyUpgrade();
+      sawProgress.current = false;
+      setPhase('watch');
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 409) {
+        // 已经有一场在跑 — 那就看它。
+        sawProgress.current = true;
+        setPhase('watch');
+      } else {
+        setLaunchError(error instanceof Error ? error.message : String(error));
+      }
+    } finally {
+      setLaunching(false);
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-2xl">
+        {phase === 'confirm' ? (
+          <>
+            <DialogHeader>
+              <DialogTitle>升级 Dormice</DialogTitle>
+              <DialogDescription>
+                在这台服务器上重跑 install.sh(重跑即升级),全程约几分钟。
+              </DialogDescription>
+            </DialogHeader>
+            <ol className="list-decimal space-y-1.5 pl-5 text-sm">
+              <li>拉取最新代码并重新构建,耗时取决于服务器网络。</li>
+              <li>
+                构建成功后 daemon 重启:
+                <span className="text-foreground font-medium">
+                  进行中的终端、命令执行、文件监听会断开
+                </span>
+                ;沙箱与磁盘不受影响,对账器会接管现场。
+              </li>
+              <li>
+                构建失败会自动回退到当前版本重新构建,daemon 不重启, 照常服务。
+              </li>
+              <li>重启期间控制台会短暂失联,这个弹窗会等它带着新版本回来。</li>
+            </ol>
+            {launchError !== null && (
+              <p className="text-sm text-destructive">
+                无法发起升级:{launchError}
+              </p>
+            )}
+            <DialogFooter>
+              <Button variant="outline" onClick={() => onOpenChange(false)}>
+                取消
+              </Button>
+              <Button disabled={launching} onClick={start}>
+                {launching && <Spinner />}
+                开始升级
+              </Button>
+            </DialogFooter>
+          </>
+        ) : (
+          <WatchBody
+            outcome={outcome}
+            unreachable={unreachable}
+            log={snapshot?.log ?? null}
+            logRef={logRef}
+            onClose={() => onOpenChange(false)}
+          />
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function WatchBody({
+  outcome,
+  unreachable,
+  log,
+  logRef,
+  onClose,
+}: {
+  outcome: UpgradeRun | null;
+  unreachable: boolean;
+  log: string | null;
+  logRef: React.RefObject<HTMLPreElement | null>;
+  onClose: () => void;
+}) {
+  return (
+    <>
+      <DialogHeader>
+        <DialogTitle>
+          {outcome === null
+            ? '升级进行中'
+            : outcome.state === 'succeeded'
+              ? '升级完成'
+              : outcome.state === 'rolled-back'
+                ? '升级失败,已自动回退'
+                : '升级失败'}
+        </DialogTitle>
+        <DialogDescription>
+          {outcome === null ? (
+            unreachable ? (
+              'daemon 正在重启,短暂失联是升级的预期环节;正在等它回来。' +
+              '如果长时间停在这里,ssh 上去看 journalctl -u dormice-upgrade。'
+            ) : (
+              '升级在服务器的 systemd unit 里执行,关掉弹窗也不会中断。'
+            )
+          ) : outcome.state === 'succeeded' ? (
+            <>
+              daemon 已带着新版本回来并通过 doctor 验收
+              {outcome.toCommit !== null && (
+                <>
+                  ,当前运行{' '}
+                  <code className="font-mono">{outcome.toCommit}</code>
+                </>
+              )}
+              。
+            </>
+          ) : outcome.state === 'rolled-back' ? (
+            '构建失败,代码已回退到升级前的版本并重新构建,daemon 未重启、照常服务。修复原因后可再试。'
+          ) : (
+            '查看下方日志与服务器上的 journalctl -u dormice-upgrade;修复原因后在服务器上重跑 install.sh 即可修复安装。'
+          )}
+        </DialogDescription>
+      </DialogHeader>
+
+      {outcome === null && (
+        <div className="flex items-center gap-2 text-sm text-muted-foreground">
+          <Spinner />
+          {unreachable ? '等待 daemon 重启完成' : '实时输出'}
+        </div>
+      )}
+      {outcome !== null && outcome.error !== null && (
+        <p className="text-sm text-destructive">{outcome.error}</p>
+      )}
+      {log !== null && (
+        <pre
+          ref={logRef}
+          className="max-h-64 overflow-y-auto rounded-md border bg-muted/30 p-3 font-mono text-xs leading-relaxed whitespace-pre-wrap"
+        >
+          {log}
+        </pre>
+      )}
+
+      <DialogFooter>
+        <Button
+          variant={outcome?.state === 'succeeded' ? 'default' : 'outline'}
+          onClick={onClose}
+        >
+          {outcome === null ? '转到后台(升级继续)' : '关闭'}
+        </Button>
+      </DialogFooter>
+    </>
+  );
+}
diff --git a/packages/console/src/features/settings/components/VersionCard.tsx b/packages/console/src/features/settings/components/VersionCard.tsx
index c8241f8..21edafa 100644
--- a/packages/console/src/features/settings/components/VersionCard.tsx
+++ b/packages/console/src/features/settings/components/VersionCard.tsx
@@ -1,6 +1,7 @@
 import type { CheckUpgradeResponse } from '@dormice/shared';
 import { RefreshIcon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
+import { useState } from 'react';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import {
@@ -12,17 +13,26 @@ import {
   CardTitle,
 } from '@/components/ui/card';
 import { Spinner } from '@/components/ui/spinner';
-import { useCheckUpgrade, useForceCheckUpgrade } from '../hooks/useUpgrade';
+import {
+  useCheckUpgrade,
+  useForceCheckUpgrade,
+  useUpgradeStatus,
+} from '../hooks/useUpgrade';
+import { UpgradeDialog } from './UpgradeDialog';
 
 /**
  * daemon 自己的版本与升级窗口。「版本」= 构建进 dist 的 git commit
  * (还没有发版 tag,main 上每个提交都过验收链);比较由 daemon 服务端
  * 裁决(upgradable 字段),这里只负责显示 — 与沙箱「可升级」徽章同一
  * 纪律。检查失败如实显示 checkError,绝不把失败装成「已是最新」。
+ * 「升级」按钮只在 daemon 自报一键可用时出现,否则给手动路径与原因。
  */
 export function VersionCard() {
   const { data, isPending, isError, error } = useCheckUpgrade();
   const force = useForceCheckUpgrade();
+  const status = useUpgradeStatus();
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const running = status.data?.running ?? false;
 
   return (
     <Card>
@@ -48,6 +58,20 @@ export function VersionCard() {
         </CardAction>
       </CardHeader>
       <CardContent className="flex flex-col gap-3">
+        {running && (
+          <div className="flex items-center justify-between gap-2 rounded-md border border-amber-500/40 bg-amber-500/10 px-3 py-2 text-sm">
+            <span className="flex items-center gap-2">
+              <Spinner /> 升级正在进行
+            </span>
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => setDialogOpen(true)}
+            >
+              查看进度
+            </Button>
+          </div>
+        )}
         {isPending ? (
           <div className="flex items-center gap-2 text-sm text-muted-foreground">
             <Spinner /> 检查版本
@@ -55,14 +79,37 @@ export function VersionCard() {
         ) : isError ? (
           <p className="text-sm text-destructive">检查失败:{error.message}</p>
         ) : (
-          <VersionBody data={data} />
+          <VersionBody
+            data={data}
+            oneClick={
+              status.data?.available
+                ? { onUpgrade: () => setDialogOpen(true), running }
+                : { reason: status.data?.unavailableReason ?? null }
+            }
+          />
         )}
       </CardContent>
+      <UpgradeDialog
+        open={dialogOpen}
+        onOpenChange={setDialogOpen}
+        alreadyRunning={running}
+      />
     </Card>
   );
 }
 
-function VersionBody({ data }: { data: CheckUpgradeResponse }) {
+/** 一键可用 → 按钮;不可用 → 手动指引 + daemon 自报的原因。 */
+type OneClick =
+  | { onUpgrade: () => void; running: boolean }
+  | { reason: string | null };
+
+function VersionBody({
+  data,
+  oneClick,
+}: {
+  data: CheckUpgradeResponse;
+  oneClick: OneClick;
+}) {
   const { current, check, checkError } = data;
   return (
     <>
@@ -91,7 +138,7 @@ function VersionBody({ data }: { data: CheckUpgradeResponse }) {
 
       {check &&
         (check.upgradable ? (
-          <UpgradePreview check={check} />
+          <UpgradePreview check={check} oneClick={oneClick} />
         ) : check.aheadBy > 0 ? (
           <p className="text-sm text-amber-600 dark:text-amber-400">
             本地比远端 main 多 {check.aheadBy} 个提交(代码有分叉)
@@ -111,22 +158,35 @@ function VersionBody({ data }: { data: CheckUpgradeResponse }) {
 
 function UpgradePreview({
   check,
+  oneClick,
 }: {
   check: NonNullable<CheckUpgradeResponse['check']>;
+  oneClick: OneClick;
 }) {
   return (
     <div className="flex flex-col gap-2">
-      <div className="flex items-center gap-2 text-sm">
-        <Badge
-          variant="outline"
-          className="border-amber-500/40 bg-amber-500/10 font-medium text-amber-600 dark:text-amber-400"
-        >
-          可升级
-        </Badge>
-        <span>
-          落后 {check.behindBy} 个提交,最新{' '}
-          <code className="font-mono">{check.latest.commit}</code>
-        </span>
+      <div className="flex items-center justify-between gap-2 text-sm">
+        <div className="flex items-center gap-2">
+          <Badge
+            variant="outline"
+            className="border-amber-500/40 bg-amber-500/10 font-medium text-amber-600 dark:text-amber-400"
+          >
+            可升级
+          </Badge>
+          <span>
+            落后 {check.behindBy} 个提交,最新{' '}
+            <code className="font-mono">{check.latest.commit}</code>
+          </span>
+        </div>
+        {'onUpgrade' in oneClick && (
+          <Button
+            size="sm"
+            disabled={oneClick.running}
+            onClick={oneClick.onUpgrade}
+          >
+            升级到最新
+          </Button>
+        )}
       </div>
       <ul className="max-h-48 overflow-y-auto rounded-md border bg-muted/30 p-3 font-mono text-xs leading-relaxed">
         {check.commits.map((entry) => (
@@ -145,9 +205,17 @@ function UpgradePreview({
           </li>
         )}
       </ul>
-      <p className="text-sm text-muted-foreground">
-        升级方式:在服务器上重跑 install.sh(重跑即升级,不轮换 API token)。
-      </p>
+      {'reason' in oneClick && (
+        <p className="text-sm text-muted-foreground">
+          一键升级在这台 daemon 上不可用
+          {oneClick.reason !== null && (
+            <>
+              (<span className="font-mono text-xs">{oneClick.reason}</span>)
+            </>
+          )}
+          ;在服务器上重跑 install.sh 即可升级(重跑即升级,不轮换 API token)。
+        </p>
+      )}
     </div>
   );
 }
diff --git a/packages/console/src/features/settings/hooks/useUpgrade.ts b/packages/console/src/features/settings/hooks/useUpgrade.ts
index c44fbab..1544711 100644
--- a/packages/console/src/features/settings/hooks/useUpgrade.ts
+++ b/packages/console/src/features/settings/hooks/useUpgrade.ts
@@ -1,5 +1,5 @@
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { checkUpgrade } from '@/lib/api';
+import { checkUpgrade, getUpgradeStatus } from '@/lib/api';
 
 /**
  * 版本检查只在打开设置页与点按钮时发生 — 刻意不做后台轮询(检查会打
@@ -23,3 +23,31 @@ export function useForceCheckUpgrade() {
     onSuccess: (data) => queryClient.setQueryData(['checkUpgrade'], data),
   });
 }
+
+/**
+ * 升级执行窗:一键升级可不可用、systemd unit 是否活着、上一次运行的
+ * 报告。全是本机读数(systemctl + 状态文件),不打网络 — 版本卡拿它
+ * 决定「升级」按钮还是手动指引。升级弹窗里的 2 秒轮询是弹窗自己的
+ * setTimeout 链(daemon 重启的失联是预期环节,查询库的重试语义不合身)。
+ */
+export function useUpgradeStatus() {
+  return useQuery({
+    queryKey: ['upgradeStatus'],
+    queryFn: getUpgradeStatus,
+    staleTime: 15_000,
+    retry: false,
+  });
+}
+
+/**
+ * 侧栏角标的只读缓存视图:绝不自己发请求(检查只在设置页与按钮发生,
+ * 角标不该成为第二个 phone-home 入口),设置页查过且可升级才亮。
+ */
+export function useCachedUpgradable(): boolean {
+  const { data } = useQuery({
+    queryKey: ['checkUpgrade'],
+    queryFn: () => checkUpgrade(),
+    enabled: false,
+  });
+  return data?.check?.upgradable ?? false;
+}
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 608c5c7..9607d40 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -1,10 +1,12 @@
 import type {
   AcquireRequest,
   AcquireResponse,
+  ApplyUpgradeResponse,
   CheckUpgradeResponse,
   GetConfigResponse,
   GetIngressResponse,
   GetSandboxMetricsResponse,
+  GetUpgradeStatusResponse,
   HostMetricsResponse,
   LifecyclePolicyOverride,
   ListActivityResponse,
@@ -147,6 +149,17 @@ export const getConfig = () => rpc<GetConfigResponse>('/getConfig');
 export const checkUpgrade = (force = false) =>
   rpc<CheckUpgradeResponse>('/checkUpgrade', { force });
 
+// The one-click upgrade: the daemon hands install.sh to a systemd unit
+// that outlives its own restart, then answers { started: true }. Progress
+// lives in getUpgradeStatus; expect the daemon to restart near the end.
+export const applyUpgrade = () =>
+  rpc<ApplyUpgradeResponse>('/applyUpgrade', {});
+
+// The upgrade execution window: availability, unit liveness (from systemd,
+// not the status file's claim), the last run's report and the log tail.
+export const getUpgradeStatus = () =>
+  rpc<GetUpgradeStatusResponse>('/getUpgradeStatus', {});
+
 // The daemon's front door: whether it manages a reverse proxy config, and
 // every bound domain with live probes (DNS record, certificate served).
 export const getIngress = () => rpc<GetIngressResponse>('/getIngress');
diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index 2184d38..33dcb0d 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -38,6 +38,8 @@ export default defineConfig({
       '/listActivity': 'http://127.0.0.1:3676',
       '/getConfig': 'http://127.0.0.1:3676',
       '/checkUpgrade': 'http://127.0.0.1:3676',
+      '/applyUpgrade': 'http://127.0.0.1:3676',
+      '/getUpgradeStatus': 'http://127.0.0.1:3676',
       '/getIngress': 'http://127.0.0.1:3676',
       '/setIngress': 'http://127.0.0.1:3676',
       // The terminal speaks the envd surface directly, like the e2b SDK.
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index ce123c2..c7e766d 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -1,7 +1,9 @@
 import {
   type AcquireResponse,
   type ActivityEvent,
+  type ApplyUpgradeResponse,
   acquireResponseSchema,
+  applyUpgradeResponseSchema,
   type CheckUpgradeResponse,
   checkUpgradeResponseSchema,
   DEFAULT_EXEC_TIMEOUT_SECONDS,
@@ -11,9 +13,11 @@ import {
   execCommandResponseSchema,
   type GetConfigResponse,
   type GetIngressResponse,
+  type GetUpgradeStatusResponse,
   getConfigResponseSchema,
   getIngressResponseSchema,
   getSandboxMetricsResponseSchema,
+  getUpgradeStatusResponseSchema,
   type HostMetricsResponse,
   hostMetricsResponseSchema,
   type LifecyclePolicyOverride,
@@ -240,6 +244,31 @@ export class Dormice {
     return checkUpgradeResponseSchema.parse(data);
   }
 
+  /**
+   * The one-click upgrade: the daemon launches install.sh (re-running it
+   * IS the upgrade) in a systemd transient unit that outlives the daemon's
+   * own restart. Returns as soon as the unit started — watch it land with
+   * getUpgradeStatus. 400 when one-click is unavailable (fake executor, no
+   * git checkout, no systemd); 409 when an upgrade is already running.
+   * Expect the daemon to restart near the end: in-flight execs, terminals
+   * and watchers break, sandboxes and their disks are untouched.
+   */
+  async applyUpgrade(): Promise<ApplyUpgradeResponse> {
+    const data = await this.rpc('applyUpgrade', {});
+    return applyUpgradeResponseSchema.parse(data);
+  }
+
+  /**
+   * The upgrade execution window: whether one-click is available at all,
+   * whether the systemd unit is alive right now, the last run's report
+   * (state, commits, error) as install.sh wrote it, and the log tail. A
+   * run that died without reporting comes back as an honest failure.
+   */
+  async getUpgradeStatus(): Promise<GetUpgradeStatusResponse> {
+    const data = await this.rpc('getUpgradeStatus', {});
+    return getUpgradeStatusResponseSchema.parse(data);
+  }
+
   /**
    * The daemon's managed front door (the reverse proxy in front of it):
    * whether one is managed at all, and every bound domain with live probes
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 68c979f..81df2a6 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -1,4 +1,5 @@
 import http from 'node:http';
+import nodePath from 'node:path';
 import fastifyCookie from '@fastify/cookie';
 import fastify, { type FastifyError, type FastifyServerFactory } from 'fastify';
 import {
@@ -103,7 +104,12 @@ export function buildApp({
   archiver,
   ingress,
   sources = configSources(),
-  updater = new Updater({ repoDir: null, build: readBuildInfo() }),
+  updater = new Updater({
+    repoDir: null,
+    build: readBuildInfo(),
+    statusDir: nodePath.join(config.DORMICE_DATA_DIR, 'upgrade'),
+    executor: config.DORMICE_EXECUTOR,
+  }),
 }: AppDeps) {
   // The archive default is adjudicated once, here, by the archiver's
   // presence: with one, new sandboxes archive after a week of idleness;
@@ -206,7 +212,7 @@ export function buildApp({
       sources,
       archiveDefaultSeconds,
     });
-    await api.register(upgradeRoutes, { updater });
+    await api.register(upgradeRoutes, { updater, db });
   });
 
   // The web console: account + session endpoints (open — setup and login
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 53fa84f..7c7b831 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -133,6 +133,8 @@ const build = readBuildInfo();
 const updater = new Updater({
   repoDir: existsSync(path.join(repoRoot, '.git')) ? repoRoot : null,
   build,
+  statusDir: path.join(config.DORMICE_DATA_DIR, 'upgrade'),
+  executor: config.DORMICE_EXECUTOR,
 });
 log.info(
   build
diff --git a/packages/server/src/routes/upgrade.ts b/packages/server/src/routes/upgrade.ts
index 6fbe5c3..ac9670d 100644
--- a/packages/server/src/routes/upgrade.ts
+++ b/packages/server/src/routes/upgrade.ts
@@ -1,24 +1,33 @@
 import {
+  applyUpgradeRequestSchema,
+  applyUpgradeResponseSchema,
   checkUpgradeRequestSchema,
   checkUpgradeResponseSchema,
+  getUpgradeStatusRequestSchema,
+  getUpgradeStatusResponseSchema,
 } from '@dormice/shared';
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import { recordActivity } from '../db/activity';
+import type { Db } from '../db/db';
 import type { Updater } from '../updater';
 
 export interface UpgradeRoutesOptions {
   updater: Updater;
+  db: Db;
 }
 
 /**
- * The daemon's own upgrade window: what commit am I, what does origin's
- * main have that I lack. Checking reaches the network exactly when asked
- * (no background phone-home — the check runs on an operator's click, and
- * a server-side cache keeps repeats cheap); failures are honest data in
- * checkError, not invented freshness.
+ * The daemon's own upgrade surface: what commit am I (checkUpgrade), pull
+ * the trigger (applyUpgrade), watch it land (getUpgradeStatus). Checking
+ * reaches the network exactly when asked — no background phone-home — and
+ * a server-side cache keeps repeats cheap. Applying hands install.sh to a
+ * systemd transient unit that outlives the daemon's own restart; only the
+ * launch is recorded in the activity ring, because the daemon that would
+ * record "finished" is the one being replaced.
  */
 export const upgradeRoutes: FastifyPluginAsyncZod<
   UpgradeRoutesOptions
-> = async (app, { updater }) => {
+> = async (app, { updater, db }) => {
   app.post(
     '/checkUpgrade',
     {
@@ -29,4 +38,34 @@ export const upgradeRoutes: FastifyPluginAsyncZod<
     },
     async (request) => updater.check(request.body.force),
   );
+
+  app.post(
+    '/applyUpgrade',
+    {
+      schema: {
+        body: applyUpgradeRequestSchema,
+        response: { 200: applyUpgradeResponseSchema },
+      },
+    },
+    async () => {
+      await updater.apply();
+      const current = updater.current;
+      recordActivity(db, {
+        kind: 'upgrade-started',
+        detail: `one-click upgrade launched${current ? ` from ${current.commit}` : ''} (systemd unit dormice-upgrade)`,
+      });
+      return { started: true as const };
+    },
+  );
+
+  app.post(
+    '/getUpgradeStatus',
+    {
+      schema: {
+        body: getUpgradeStatusRequestSchema,
+        response: { 200: getUpgradeStatusResponseSchema },
+      },
+    },
+    async () => updater.status(),
+  );
 };
diff --git a/packages/server/src/updater.test.ts b/packages/server/src/updater.test.ts
index 431517e..c1fd408 100644
--- a/packages/server/src/updater.test.ts
+++ b/packages/server/src/updater.test.ts
@@ -1,15 +1,19 @@
-import { mkdtempSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { checkUpgradeResponseSchema } from '@dormice/shared';
+import {
+  checkUpgradeResponseSchema,
+  getUpgradeStatusResponseSchema,
+} from '@dormice/shared';
 import { execaSync } from 'execa';
 import { beforeAll, describe, expect, it } from 'vitest';
-import { Updater } from './updater';
+import { type RunCommand, Updater, type UpdaterOptions } from './updater';
 import type { BuildInfo } from './version';
 
 // The updater against real git: a fixture origin, a clone that plays the
 // installed daemon, and builds pinned to specific commits. Everything is
-// local paths — the network is never touched.
+// local paths — the network is never touched. systemd-run/systemctl are
+// injected (RunCommand), so the launch path runs on any host.
 
 function git(cwd: string, ...args: string[]): string {
   return execaSync('git', args, { cwd }).stdout.trim();
@@ -46,11 +50,34 @@ let clone: string;
 /** The identity of the clone's HEAD at "install time". */
 let installedBuild: BuildInfo;
 
+/** The systemd side, happy to do anything — apply tests override pieces. */
+const okRun: RunCommand = async () => ({
+  exitCode: 0,
+  stdout: '',
+  stderr: '',
+});
+
+function updaterFor(overrides: Partial<UpdaterOptions> = {}): Updater {
+  return new Updater({
+    repoDir: clone,
+    build: installedBuild,
+    statusDir: mkdtempSync(path.join(tmpdir(), 'dormice-status-')),
+    executor: 'docker',
+    run: okRun,
+    ...overrides,
+  });
+}
+
 beforeAll(() => {
   const root = mkdtempSync(path.join(tmpdir(), 'dormice-updater-'));
   origin = path.join(root, 'origin');
   clone = path.join(root, 'clone');
   execaSync('git', ['init', '-q', '-b', 'main', origin]);
+  // The tree carries a stand-in installer: apply() copies and launches
+  // deploy/install.sh, and availability checks it exists.
+  mkdirSync(path.join(origin, 'deploy'));
+  writeFileSync(path.join(origin, 'deploy', 'install.sh'), '#!/bin/bash\n');
+  execaSync('git', ['add', '-A'], { cwd: origin });
   commit(origin, 'first');
   commit(origin, 'second');
   execaSync('git', ['clone', '-q', origin, clone]);
@@ -59,7 +86,7 @@ beforeAll(() => {
 
 describe('Updater.check', () => {
   it('reports up to date when the build matches origin main', async () => {
-    const updater = new Updater({ repoDir: clone, build: installedBuild });
+    const updater = updaterFor();
     const answer = await updater.check();
     const parsed = checkUpgradeResponseSchema.parse(answer);
     expect(parsed.checkError).toBeNull();
@@ -77,7 +104,7 @@ describe('Updater.check', () => {
   it('reports behind commits newest first and adjudicates upgradable', async () => {
     const third = commit(origin, 'third');
     const fourth = commit(origin, 'fourth');
-    const updater = new Updater({ repoDir: clone, build: installedBuild });
+    const updater = updaterFor();
     const answer = await updater.check();
     expect(answer.checkError).toBeNull();
     expect(answer.check).toMatchObject({
@@ -90,7 +117,7 @@ describe('Updater.check', () => {
   });
 
   it('serves the second answer from cache and refetches on force', async () => {
-    const updater = new Updater({ repoDir: clone, build: installedBuild });
+    const updater = updaterFor();
     const first = await updater.check();
     expect(first.check?.cached).toBe(false);
     const behindThen = first.check?.behindBy ?? 0;
@@ -111,7 +138,7 @@ describe('Updater.check', () => {
     // upgrade that cannot apply.
     commit(clone, 'local only');
     try {
-      const updater = new Updater({ repoDir: clone, build: buildAt(clone) });
+      const updater = updaterFor({ build: buildAt(clone) });
       const answer = await updater.check();
       expect(answer.checkError).toBeNull();
       expect(answer.check?.aheadBy).toBe(1);
@@ -122,10 +149,10 @@ describe('Updater.check', () => {
   });
 
   it('is honest without a checkout, without a build identity, and on a dead remote', async () => {
-    const noRepo = new Updater({ repoDir: null, build: installedBuild });
+    const noRepo = updaterFor({ repoDir: null });
     expect((await noRepo.check()).checkError).toMatch(/git checkout/);
 
-    const noBuild = new Updater({ repoDir: clone, build: null });
+    const noBuild = updaterFor({ build: null });
     const answer = await noBuild.check();
     expect(answer.current).toBeNull();
     expect(answer.checkError).toMatch(/version identity/);
@@ -138,9 +165,146 @@ describe('Updater.check', () => {
       ['remote', 'add', 'origin', path.join(broken, 'does-not-exist')],
       { cwd: broken },
     );
-    const deadRemote = new Updater({ repoDir: broken, build: buildAt(broken) });
+    const deadRemote = updaterFor({ repoDir: broken, build: buildAt(broken) });
     const dead = await deadRemote.check();
     expect(dead.check).toBeNull();
     expect(dead.checkError).toMatch(/fetch failed/);
   });
 });
+
+describe('Updater.apply and status', () => {
+  it('refuses one-click on the fake executor and without a checkout', async () => {
+    const fake = updaterFor({ executor: 'fake' });
+    await expect(fake.apply()).rejects.toMatchObject({ statusCode: 400 });
+    const status = await fake.status();
+    expect(status.available).toBe(false);
+    expect(status.unavailableReason).toMatch(/fake executor/);
+
+    const noRepo = updaterFor({ repoDir: null });
+    expect((await noRepo.status()).unavailableReason).toMatch(/git checkout/);
+  });
+
+  it('launches install.sh in a transient unit built from daemon-side paths only', async () => {
+    const statusDir = mkdtempSync(path.join(tmpdir(), 'dormice-status-'));
+    const calls: Array<{ file: string; args: string[] }> = [];
+    const updater = updaterFor({
+      statusDir,
+      run: async (file, args) => {
+        calls.push({ file, args });
+        return { exitCode: 0, stdout: '', stderr: '' };
+      },
+    });
+    await updater.apply();
+
+    const launch = calls.at(-1);
+    expect(launch?.file).toBe('systemd-run');
+    expect(launch?.args).toContain('--unit');
+    expect(launch?.args).toContain('dormice-upgrade');
+    expect(launch?.args).toContain('--collect');
+    const command = launch?.args.at(-1) ?? '';
+    // The copy, not the tree's file (git pull would replace it mid-read),
+    // reporting into the status dir, output tee'd next to it.
+    expect(command).toContain(`${statusDir}/install.sh`);
+    expect(command).toContain('--status-dir');
+    expect(command).toContain('upgrade.log');
+    // A local-path origin is not the cn mirror.
+    expect(command).not.toContain('--mirror');
+    expect(existsSync(path.join(statusDir, 'install.sh'))).toBe(true);
+  });
+
+  it('passes --mirror cn when the origin was cloned through the mirror', async () => {
+    const mirrored = mkdtempSync(path.join(tmpdir(), 'dormice-mirrored-'));
+    execaSync('git', ['clone', '-q', origin, mirrored]);
+    execaSync(
+      'git',
+      [
+        'remote',
+        'set-url',
+        'origin',
+        'https://ghfast.top/https://github.com/BitMiracle-AI/Dormice.git',
+      ],
+      { cwd: mirrored },
+    );
+    const calls: string[] = [];
+    const updater = updaterFor({
+      repoDir: mirrored,
+      run: async (_file, args) => {
+        calls.push(args.at(-1) ?? '');
+        return { exitCode: 0, stdout: '', stderr: '' };
+      },
+    });
+    await updater.apply();
+    expect(calls.at(-1)).toContain("--mirror' 'cn'");
+  });
+
+  it('maps a live unit to an honest 409', async () => {
+    const updater = updaterFor({
+      run: async (_file, args) =>
+        args[0] === '--version'
+          ? { exitCode: 0, stdout: '', stderr: '' }
+          : {
+              exitCode: 1,
+              stdout: '',
+              stderr:
+                'Failed to start transient service unit: Unit dormice-upgrade.service already exists.',
+            },
+    });
+    await expect(updater.apply()).rejects.toMatchObject({ statusCode: 409 });
+  });
+
+  it('adjudicates a dead runner into a failure and tails the log', async () => {
+    const statusDir = mkdtempSync(path.join(tmpdir(), 'dormice-status-'));
+    writeFileSync(
+      path.join(statusDir, 'status.json'),
+      JSON.stringify({
+        state: 'running',
+        startedAt: '2026-07-15T08:00:00Z',
+        finishedAt: null,
+        fromCommit: 'abc1234',
+        toCommit: null,
+        error: null,
+      }),
+    );
+    writeFileSync(path.join(statusDir, 'upgrade.log'), '==> build\nboom\n');
+    // systemd-run answers the availability probe; systemctl says the unit
+    // is not active — the "running" claim in the file is a dead process.
+    const updater = updaterFor({
+      statusDir,
+      run: async (file) =>
+        file === 'systemctl'
+          ? { exitCode: 3, stdout: '', stderr: '' }
+          : { exitCode: 0, stdout: '', stderr: '' },
+    });
+    const status = getUpgradeStatusResponseSchema.parse(await updater.status());
+    expect(status.available).toBe(true);
+    expect(status.running).toBe(false);
+    expect(status.last?.state).toBe('failed');
+    expect(status.last?.error).toMatch(/died without reporting/);
+    expect(status.log).toContain('boom');
+  });
+
+  it('reports a finished run exactly as install.sh wrote it', async () => {
+    const statusDir = mkdtempSync(path.join(tmpdir(), 'dormice-status-'));
+    const run = {
+      state: 'rolled-back',
+      startedAt: '2026-07-15T08:00:00Z',
+      finishedAt: '2026-07-15T08:05:00Z',
+      fromCommit: 'abc1234',
+      toCommit: 'def5678',
+      error: 'failed during: build',
+    };
+    writeFileSync(path.join(statusDir, 'status.json'), JSON.stringify(run));
+    const updater = updaterFor({
+      statusDir,
+      run: async (file) =>
+        file === 'systemctl'
+          ? { exitCode: 3, stdout: '', stderr: '' }
+          : { exitCode: 0, stdout: '', stderr: '' },
+    });
+    const status = await updater.status();
+    expect(status.last).toEqual(run);
+    // No run ever happened elsewhere: last is null, not invented.
+    const fresh = updaterFor();
+    expect((await fresh.status()).last).toBeNull();
+  });
+});
diff --git a/packages/server/src/updater.ts b/packages/server/src/updater.ts
index f6ca99e..7b89dd1 100644
--- a/packages/server/src/updater.ts
+++ b/packages/server/src/updater.ts
@@ -1,5 +1,14 @@
-import type { CheckUpgradeResponse } from '@dormice/shared';
+import { existsSync } from 'node:fs';
+import { copyFile, mkdir, open, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  type CheckUpgradeResponse,
+  type GetUpgradeStatusResponse,
+  type UpgradeRun,
+  upgradeRunSchema,
+} from '@dormice/shared';
 import { execa } from 'execa';
+import { httpError } from './http-error';
 import type { BuildInfo } from './version';
 
 /**
@@ -14,12 +23,43 @@ import type { BuildInfo } from './version';
  * running process — checking is always safe. The result is cached so a
  * console session does not hammer the network; `force` is the "check now"
  * button. Failures come back as data (checkError), never invented.
+ *
+ * Applying is a different animal: the daemon cannot upgrade itself (the
+ * upgrade's last step restarts it, killing its own children), so apply()
+ * hands install.sh to a systemd transient unit and steps aside — the unit
+ * outlives the restart, tees its output where status() can read it, and
+ * its name is the mutex against a double-click. The upgrade command line
+ * is composed entirely from daemon-side paths: nothing from any request
+ * ever reaches it.
  */
 
 const CHECK_CACHE_MS = 3600_000;
 /** Changelog preview cap — the wire is a preview, not the full history. */
 const CHANGELOG_LIMIT = 50;
 const FETCH_TIMEOUT_MS = 30_000;
+const UNIT = 'dormice-upgrade';
+/** Wire tail of the upgrade log — the full file stays on the host. */
+const LOG_TAIL_BYTES = 16 * 1024;
+
+/**
+ * How the updater launches processes for apply/status (systemd-run,
+ * systemctl). Injectable so tests exercise the launch path on hosts
+ * without systemd; git stays un-injected — the tests run real git against
+ * fixture repositories.
+ */
+export type RunCommand = (
+  file: string,
+  args: string[],
+) => Promise<{ exitCode: number | undefined; stdout: string; stderr: string }>;
+
+const defaultRun: RunCommand = async (file, args) => {
+  const result = await execa(file, args, { reject: false });
+  return {
+    exitCode: result.exitCode,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+};
 
 export interface UpdaterOptions {
   /**
@@ -30,6 +70,11 @@ export interface UpdaterOptions {
   repoDir: string | null;
   /** The identity baked into this build (version.ts). */
   build: BuildInfo | null;
+  /** Where the upgrade unit writes status.json and its log: <DATA_DIR>/upgrade. */
+  statusDir: string;
+  /** One-click upgrade is a real install's move; the fake executor refuses. */
+  executor: 'fake' | 'docker';
+  run?: RunCommand;
 }
 
 type Check = NonNullable<CheckUpgradeResponse['check']>;
@@ -37,11 +82,24 @@ type Check = NonNullable<CheckUpgradeResponse['check']>;
 export class Updater {
   private readonly repoDir: string | null;
   private readonly build: BuildInfo | null;
+  private readonly statusDir: string;
+  private readonly executor: 'fake' | 'docker';
+  private readonly run: RunCommand;
   private cache: { at: number; check: Check } | null = null;
+  /** Probed once — every input (executor, checkout, systemd) is boot-stable. */
+  private availabilityReason: string | null | undefined;
 
   constructor(options: UpdaterOptions) {
     this.repoDir = options.repoDir;
     this.build = options.build;
+    this.statusDir = options.statusDir;
+    this.executor = options.executor;
+    this.run = options.run ?? defaultRun;
+  }
+
+  /** The identity baked into the running build — local, never networked. */
+  get current(): BuildInfo | null {
+    return this.build;
   }
 
   async check(force = false): Promise<CheckUpgradeResponse> {
@@ -116,6 +174,161 @@ export class Updater {
     };
   }
 
+  /**
+   * Launch the one-click upgrade: install.sh in a systemd transient unit.
+   * The script is copied out of the tree first — its own first step is
+   * `git pull`, which must not replace the file bash is reading. The
+   * mirror choice is derived from the origin URL (an install done with
+   * --mirror cn cloned through the mirror prefix), so no separate knob.
+   */
+  async apply(): Promise<void> {
+    const reason = await this.availability();
+    if (reason !== null) {
+      throw httpError(400, `one-click upgrade unavailable: ${reason}`);
+    }
+    // availability() already refused a null repoDir; this narrows the type.
+    if (this.repoDir === null) throw new Error('unreachable');
+    await mkdir(this.statusDir, { recursive: true });
+    const script = path.join(this.statusDir, 'install.sh');
+    await copyFile(path.join(this.repoDir, 'deploy', 'install.sh'), script);
+    const args = ['--status-dir', this.statusDir];
+    if (await this.originUsesMirror()) args.push('--mirror', 'cn');
+    const logFile = path.join(this.statusDir, 'upgrade.log');
+    const command = `exec bash ${quote(script)} ${args.map(quote).join(' ')} >${quote(logFile)} 2>&1`;
+    const launch = await this.run('systemd-run', [
+      '--unit',
+      UNIT,
+      // Garbage-collect the unit when it ends, success or failure — the
+      // name must be reusable for the next upgrade.
+      '--collect',
+      '--description',
+      'Dormice self-upgrade (install.sh)',
+      '/bin/bash',
+      '-c',
+      command,
+    ]);
+    if (launch.exitCode !== 0) {
+      const stderr = launch.stderr.trim();
+      // The unit name is the mutex: systemd refuses a second one.
+      if (stderr.includes('already exists')) {
+        throw httpError(
+          409,
+          'an upgrade is already running — wait for it to finish (systemd unit dormice-upgrade)',
+        );
+      }
+      throw httpError(
+        500,
+        `failed to launch the upgrade: ${stderr.slice(0, 300) || 'systemd-run gave no reason'}`,
+      );
+    }
+  }
+
+  /**
+   * The execution window: unit liveness from systemd (never from the
+   * status file's claim), the last run's report, and the log tail. A
+   * status file stuck at "running" with no live unit is adjudicated into
+   * an honest failure — an upgrade that died without reporting must not
+   * look like one that never ends.
+   */
+  async status(): Promise<GetUpgradeStatusResponse> {
+    const reason = await this.availability();
+    const running = await this.unitActive();
+    let last = await this.readRun();
+    if (last !== null && last.state === 'running' && !running) {
+      last = {
+        ...last,
+        state: 'failed',
+        error:
+          'the upgrade process died without reporting an outcome — see the log and journalctl -u dormice-upgrade',
+      };
+    }
+    return {
+      available: reason === null,
+      unavailableReason: reason,
+      running,
+      last,
+      log: await this.readLogTail(),
+    };
+  }
+
+  private async availability(): Promise<string | null> {
+    if (this.availabilityReason === undefined) {
+      this.availabilityReason = await this.probeAvailability();
+    }
+    return this.availabilityReason;
+  }
+
+  private async probeAvailability(): Promise<string | null> {
+    if (this.executor !== 'docker') {
+      return 'one-click upgrade is for a real install (docker executor) — this daemon runs the fake executor';
+    }
+    if (this.repoDir === null) {
+      return 'the daemon does not run from a git checkout';
+    }
+    if (!existsSync(path.join(this.repoDir, 'deploy', 'install.sh'))) {
+      return 'deploy/install.sh is missing from the checkout';
+    }
+    // Presence of systemd-run covers the platform question too — a
+    // non-systemd host simply does not have it.
+    const probe = await this.run('systemd-run', ['--version']);
+    if (probe.exitCode !== 0) {
+      return 'systemd-run is not available — one-click upgrade needs a systemd host';
+    }
+    return null;
+  }
+
+  private async originUsesMirror(): Promise<boolean> {
+    try {
+      const url = await this.git(['remote', 'get-url', 'origin']);
+      return url.includes('ghfast.top');
+    } catch {
+      return false;
+    }
+  }
+
+  private async unitActive(): Promise<boolean> {
+    const result = await this.run('systemctl', [
+      'is-active',
+      '--quiet',
+      `${UNIT}.service`,
+    ]);
+    return result.exitCode === 0;
+  }
+
+  private async readRun(): Promise<UpgradeRun | null> {
+    try {
+      const raw = await readFile(
+        path.join(this.statusDir, 'status.json'),
+        'utf8',
+      );
+      const parsed = upgradeRunSchema.safeParse(JSON.parse(raw));
+      return parsed.success ? parsed.data : null;
+    } catch {
+      // Missing or torn file: no report is a valid answer, not a crash.
+      return null;
+    }
+  }
+
+  private async readLogTail(): Promise<string | null> {
+    try {
+      const file = path.join(this.statusDir, 'upgrade.log');
+      const size = (await stat(file)).size;
+      const want = Math.min(size, LOG_TAIL_BYTES);
+      const handle = await open(file, 'r');
+      try {
+        const { buffer, bytesRead } = await handle.read({
+          buffer: Buffer.alloc(want),
+          position: size - want,
+        });
+        return buffer.subarray(0, bytesRead).toString('utf8');
+      } finally {
+        await handle.close();
+      }
+    } catch {
+      return null;
+    }
+  }
+
   private async git(args: string[], timeout = 10_000): Promise<string> {
     const result = await execa('git', args, {
       cwd: this.repoDir ?? undefined,
@@ -132,6 +345,11 @@ export class Updater {
   }
 }
 
+/** Single-quote for the shell: the one metacharacter inside is `'` itself. */
+function quote(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
 function parseCommitLine(line: string): { commit: string; title: string } {
   const tab = line.indexOf('\t');
   // A title containing a tab keeps its tail; a missing tab (never happens
diff --git a/packages/shared/src/activity.ts b/packages/shared/src/activity.ts
index c017686..adf9c52 100644
--- a/packages/shared/src/activity.ts
+++ b/packages/shared/src/activity.ts
@@ -29,6 +29,12 @@ export const ACTIVITY_KINDS = [
   'daemon-started',
   /** An operator bound or cleared the console domain through setIngress. */
   'ingress-updated',
+  /**
+   * An operator launched the one-click self-upgrade (applyUpgrade). Only
+   * the launch is recorded — the outcome lives in getUpgradeStatus, and
+   * the daemon that would record "finished" is the one being replaced.
+   */
+  'upgrade-started',
 ] as const;
 
 export const activityKindSchema = z.enum(ACTIVITY_KINDS);
diff --git a/packages/shared/src/upgrade.ts b/packages/shared/src/upgrade.ts
index cdf6601..36b07d7 100644
--- a/packages/shared/src/upgrade.ts
+++ b/packages/shared/src/upgrade.ts
@@ -76,3 +76,75 @@ export const checkUpgradeResponseSchema = z.object({
 });
 
 export type CheckUpgradeResponse = z.infer<typeof checkUpgradeResponseSchema>;
+
+/**
+ * applyUpgrade() — the one-click upgrade. The daemon launches install.sh
+ * (re-running it IS the upgrade — one script for manual and one-click) in
+ * a systemd transient unit, detached from its own lifetime: the upgrade's
+ * last step restarts the daemon, and a child process would die with its
+ * parent mid-build. The unit name doubles as the mutex — a second apply
+ * while one runs is refused with 409, the Coolify double-click corruption
+ * made structural. The verb takes no parameters on purpose: nothing from
+ * the request ever reaches a root command line.
+ *
+ * Refused (400) when one-click is unavailable — fake executor, no git
+ * checkout, no systemd. Watch progress with getUpgradeStatus.
+ */
+export const applyUpgradeRequestSchema = z.object({});
+
+export type ApplyUpgradeRequest = z.infer<typeof applyUpgradeRequestSchema>;
+
+export const applyUpgradeResponseSchema = z.object({
+  started: z.literal(true),
+});
+
+export type ApplyUpgradeResponse = z.infer<typeof applyUpgradeResponseSchema>;
+
+/**
+ * What install.sh reports into status.json (--status-dir): the whole
+ * truth of one run. `rolled-back` means the build failed after git pull
+ * and the code was put back and rebuilt at the commit that was running —
+ * the daemon was not restarted and keeps serving.
+ */
+export const upgradeRunSchema = z.object({
+  state: z.enum(['running', 'succeeded', 'failed', 'rolled-back']),
+  startedAt: z.iso.datetime(),
+  finishedAt: z.iso.datetime().nullable(),
+  /** The commit that was running before the pull; null on a fresh install. */
+  fromCommit: z.string().nullable(),
+  /** The commit the checkout moved to; null until the pull happened. */
+  toCommit: z.string().nullable(),
+  error: z.string().nullable(),
+});
+
+export type UpgradeRun = z.infer<typeof upgradeRunSchema>;
+
+/**
+ * getUpgradeStatus() — the upgrade execution window. `running` is read
+ * from systemd (the unit's liveness, not the status file's claim): a
+ * status file stuck at "running" with no live unit means the process died
+ * without reporting, and the daemon adjudicates that into an honest
+ * failure instead of showing an upgrade that never ends.
+ */
+export const getUpgradeStatusRequestSchema = z.object({});
+
+export type GetUpgradeStatusRequest = z.infer<
+  typeof getUpgradeStatusRequestSchema
+>;
+
+export const getUpgradeStatusResponseSchema = z.object({
+  /** Can this daemon one-click upgrade itself at all? */
+  available: z.boolean(),
+  /** Why not, when available is false — the console shows the manual path instead. */
+  unavailableReason: z.string().nullable(),
+  /** Is the systemd unit alive right now? */
+  running: z.boolean(),
+  /** The most recent run's report; null when no one-click upgrade ever ran. */
+  last: upgradeRunSchema.nullable(),
+  /** The tail of the run's output — real progress, straight from the script. */
+  log: z.string().nullable(),
+});
+
+export type GetUpgradeStatusResponse = z.infer<
+  typeof getUpgradeStatusResponseSchema
+>;

From f1b930851642c4635bbb2f958f69cebade83b369 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 19:38:30 +0800
Subject: [PATCH 080/133] =?UTF-8?q?The=20upgrade=20watch=20stops=20trustin?=
 =?UTF-8?q?g=20luck:=20the=20dialog=20judges=20endings=20by=20report=20ide?=
 =?UTF-8?q?ntity=20(a=20startedAt=20baseline=20=E2=80=94=20the=20previous?=
 =?UTF-8?q?=20run's=20report=20never=20passes=20as=20this=20run's,=20and?=
 =?UTF-8?q?=20a=20run=20that=20dies=20before=20the=20first=20poll=20still?=
 =?UTF-8?q?=20lands=20as=20an=20honest=20failure),=20dialog=20state=20init?=
 =?UTF-8?q?ializes=20only=20at=20open=20so=20invalidation=20echoes=20can't?=
 =?UTF-8?q?=20reset=20a=20shown=20ending=20back=20to=20the=20confirm=20act?=
 =?UTF-8?q?,=20the=20version=20card=20polls=20while=20a=20run=20lives=20an?=
 =?UTF-8?q?d=20surfaces=20the=20last=20failure=20instead=20of=20letting=20?=
 =?UTF-8?q?a=20backgrounded=20upgrade=20fail=20in=20silence,=20success=20o?=
 =?UTF-8?q?ffers=20a=20console=20reload=20before=20the=20old=20build's=20r?=
 =?UTF-8?q?oute=20chunks=20404,=20and=20a=20hung=20git=20fetch=20names=20i?=
 =?UTF-8?q?ts=20timeout?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../settings/components/UpgradeDialog.tsx     | 52 ++++++++++++-------
 .../settings/components/VersionCard.tsx       | 52 ++++++++++++++++---
 .../src/features/settings/hooks/useUpgrade.ts |  5 +-
 packages/server/src/updater.ts                |  5 ++
 4 files changed, 87 insertions(+), 27 deletions(-)

diff --git a/packages/console/src/features/settings/components/UpgradeDialog.tsx b/packages/console/src/features/settings/components/UpgradeDialog.tsx
index 326161c..649714b 100644
--- a/packages/console/src/features/settings/components/UpgradeDialog.tsx
+++ b/packages/console/src/features/settings/components/UpgradeDialog.tsx
@@ -21,20 +21,25 @@ import { ApiError, applyUpgrade, getUpgradeStatus } from '@/lib/api';
  * 而不是当错误处理。终局以 install.sh 写下的报告为准 — succeeded 意味
  * 着 daemon 已带着新版本回来并通过 doctor,不是"脚本跑完了"。
  *
- * 防「上一次的旧报告」误判:观察态先要见过进行中(unit 活着或报告说
- * running)才接受终局 — applyUpgrade 刚返回时状态文件可能还是上一轮的。
+ * 防「上一次的旧报告」误判靠报告身份:发起前记下现存报告的 startedAt
+ * 作基线,只接受非基线的终局 — applyUpgrade 刚返回时读到的还是上一轮
+ * 的旧报告(等于基线,拒);升级进程若在第一次轮询前就死掉,daemon 会
+ * 把它裁决成带新 startedAt 的 failed 报告(非基线,收),不会永远转圈。
  */
 interface UpgradeDialogProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   /** 打开时升级已在跑(上次没看完/别处发起)— 跳过确认直接观察。 */
   alreadyRunning: boolean;
+  /** 打开时现存报告的 startedAt(没有 = null)— 终局裁决的基线。 */
+  baselineStartedAt: string | null;
 }
 
 export function UpgradeDialog({
   open,
   onOpenChange,
   alreadyRunning,
+  baselineStartedAt,
 }: UpgradeDialogProps) {
   const queryClient = useQueryClient();
   const [phase, setPhase] = useState<'confirm' | 'watch'>('confirm');
@@ -45,19 +50,25 @@ export function UpgradeDialog({
   );
   const [unreachable, setUnreachable] = useState(false);
   const [outcome, setOutcome] = useState<UpgradeRun | null>(null);
-  const sawProgress = useRef(false);
+  const baseline = useRef<string | null>(null);
 
-  // 每次打开都是一场新的升级:上一场的快照与终局不许串场。
+  // 弹窗状态只在打开那一刻初始化(effect 只依赖 open):上一场的快照与
+  // 终局不许串场;而观察期间查询失效会翻动 alreadyRunning 等 prop,那是
+  // 轮询的回声,不是重新打开 — 决不能把正在显示的终局重置回确认幕。
+  const openedWith = useRef({ alreadyRunning, baselineStartedAt });
+  openedWith.current = { alreadyRunning, baselineStartedAt };
   useEffect(() => {
     if (!open) return;
-    setPhase(alreadyRunning ? 'watch' : 'confirm');
+    const opened = openedWith.current;
+    setPhase(opened.alreadyRunning ? 'watch' : 'confirm');
     setLaunching(false);
     setLaunchError(null);
     setSnapshot(null);
     setUnreachable(false);
     setOutcome(null);
-    sawProgress.current = alreadyRunning;
-  }, [open, alreadyRunning]);
+    // 已在跑的那场不是这里发起的,没有基线可对照:见到什么终局收什么。
+    baseline.current = opened.alreadyRunning ? null : opened.baselineStartedAt;
+  }, [open]);
 
   useEffect(() => {
     if (!open || phase !== 'watch' || outcome !== null) return;
@@ -69,9 +80,13 @@ export function UpgradeDialog({
         if (stopped) return;
         setUnreachable(false);
         setSnapshot(status);
-        if (status.running || status.last?.state === 'running') {
-          sawProgress.current = true;
-        } else if (sawProgress.current && status.last !== null) {
+        // 终局 = unit 已死且报告不是基线那份。startedAt 即报告身份:同一
+        // 场运行的中途与终局报告共享它,上一场的旧报告则等于基线被拒。
+        if (
+          !status.running &&
+          status.last !== null &&
+          status.last.startedAt !== baseline.current
+        ) {
           setOutcome(status.last);
           // 成功后重新问一次版本(新 daemon 的缓存是空的,会真查一次
           // 并显示已是最新);无论成败,执行窗与配置都过期了。
@@ -107,12 +122,11 @@ export function UpgradeDialog({
     setLaunchError(null);
     try {
       await applyUpgrade();
-      sawProgress.current = false;
       setPhase('watch');
     } catch (error) {
       if (error instanceof ApiError && error.status === 409) {
-        // 已经有一场在跑 — 那就看它。
-        sawProgress.current = true;
+        // 已经有一场在跑 — 那就看它:不是这里发起的,没有基线可对照。
+        baseline.current = null;
         setPhase('watch');
       } else {
         setLaunchError(error instanceof Error ? error.message : String(error));
@@ -218,7 +232,7 @@ function WatchBody({
                   <code className="font-mono">{outcome.toCommit}</code>
                 </>
               )}
-              。
+              。当前页面还是旧版控制台,点「刷新控制台」加载新版。
             </>
           ) : outcome.state === 'rolled-back' ? (
             '构建失败,代码已回退到升级前的版本并重新构建,daemon 未重启、照常服务。修复原因后可再试。'
@@ -247,12 +261,14 @@ function WatchBody({
       )}
 
       <DialogFooter>
-        <Button
-          variant={outcome?.state === 'succeeded' ? 'default' : 'outline'}
-          onClick={onClose}
-        >
+        <Button variant="outline" onClick={onClose}>
           {outcome === null ? '转到后台(升级继续)' : '关闭'}
         </Button>
+        {outcome?.state === 'succeeded' && (
+          // 升级重建了控制台:路由块按内容哈希按需加载,旧构建的块已被
+          // 清掉,不刷新的话继续导航会撞 404。
+          <Button onClick={() => window.location.reload()}>刷新控制台</Button>
+        )}
       </DialogFooter>
     </>
   );
diff --git a/packages/console/src/features/settings/components/VersionCard.tsx b/packages/console/src/features/settings/components/VersionCard.tsx
index 21edafa..81c7830 100644
--- a/packages/console/src/features/settings/components/VersionCard.tsx
+++ b/packages/console/src/features/settings/components/VersionCard.tsx
@@ -1,7 +1,8 @@
 import type { CheckUpgradeResponse } from '@dormice/shared';
 import { RefreshIcon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
-import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { useEffect, useRef, useState } from 'react';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import {
@@ -33,6 +34,19 @@ export function VersionCard() {
   const status = useUpgradeStatus();
   const [dialogOpen, setDialogOpen] = useState(false);
   const running = status.data?.running ?? false;
+  const last = status.data?.last ?? null;
+
+  // 升级跑完(running 翻回 false)重新裁决版本与配置。弹窗开着时它自己
+  // 会做这次失效;这里兜住弹窗已关、升级在后台跑完的那条路。
+  const queryClient = useQueryClient();
+  const wasRunning = useRef(false);
+  useEffect(() => {
+    if (wasRunning.current && !running) {
+      queryClient.invalidateQueries({ queryKey: ['checkUpgrade'] });
+      queryClient.invalidateQueries({ queryKey: ['config'] });
+    }
+    wasRunning.current = running;
+  }, [running, queryClient]);
 
   return (
     <Card>
@@ -72,6 +86,23 @@ export function VersionCard() {
             </Button>
           </div>
         )}
+        {/* 后台跑完的失败/回退不能无声消失:上一份报告就在这里说话。 */}
+        {!running &&
+          last !== null &&
+          (last.state === 'failed' || last.state === 'rolled-back') && (
+            <p className="text-sm text-destructive">
+              上次一键升级
+              {last.state === 'rolled-back' ? '构建失败,已自动回退' : '失败'}
+              {last.finishedAt !== null &&
+                `(${new Date(last.finishedAt).toLocaleString()})`}
+              {last.error !== null && <>:{last.error}</>}
+            </p>
+          )}
+        {force.isError && (
+          <p className="text-sm text-destructive">
+            检查失败:{force.error.message}
+          </p>
+        )}
         {isPending ? (
           <div className="flex items-center gap-2 text-sm text-muted-foreground">
             <Spinner /> 检查版本
@@ -82,9 +113,12 @@ export function VersionCard() {
           <VersionBody
             data={data}
             oneClick={
-              status.data?.available
-                ? { onUpgrade: () => setDialogOpen(true), running }
-                : { reason: status.data?.unavailableReason ?? null }
+              status.data === undefined
+                ? // 执行窗还没答复:既不许诺按钮,也不指控「不可用」。
+                  null
+                : status.data.available
+                  ? { onUpgrade: () => setDialogOpen(true), running }
+                  : { reason: status.data.unavailableReason }
             }
           />
         )}
@@ -93,15 +127,17 @@ export function VersionCard() {
         open={dialogOpen}
         onOpenChange={setDialogOpen}
         alreadyRunning={running}
+        baselineStartedAt={last?.startedAt ?? null}
       />
     </Card>
   );
 }
 
-/** 一键可用 → 按钮;不可用 → 手动指引 + daemon 自报的原因。 */
+/** 一键可用 → 按钮;不可用 → 手动指引 + daemon 自报的原因;null = 还不知道。 */
 type OneClick =
   | { onUpgrade: () => void; running: boolean }
-  | { reason: string | null };
+  | { reason: string | null }
+  | null;
 
 function VersionBody({
   data,
@@ -178,7 +214,7 @@ function UpgradePreview({
             <code className="font-mono">{check.latest.commit}</code>
           </span>
         </div>
-        {'onUpgrade' in oneClick && (
+        {oneClick !== null && 'onUpgrade' in oneClick && (
           <Button
             size="sm"
             disabled={oneClick.running}
@@ -205,7 +241,7 @@ function UpgradePreview({
           </li>
         )}
       </ul>
-      {'reason' in oneClick && (
+      {oneClick !== null && 'reason' in oneClick && (
         <p className="text-sm text-muted-foreground">
           一键升级在这台 daemon 上不可用
           {oneClick.reason !== null && (
diff --git a/packages/console/src/features/settings/hooks/useUpgrade.ts b/packages/console/src/features/settings/hooks/useUpgrade.ts
index 1544711..2fbc043 100644
--- a/packages/console/src/features/settings/hooks/useUpgrade.ts
+++ b/packages/console/src/features/settings/hooks/useUpgrade.ts
@@ -28,7 +28,9 @@ export function useForceCheckUpgrade() {
  * 升级执行窗:一键升级可不可用、systemd unit 是否活着、上一次运行的
  * 报告。全是本机读数(systemctl + 状态文件),不打网络 — 版本卡拿它
  * 决定「升级」按钮还是手动指引。升级弹窗里的 2 秒轮询是弹窗自己的
- * setTimeout 链(daemon 重启的失联是预期环节,查询库的重试语义不合身)。
+ * setTimeout 链(daemon 重启的失联是预期环节,查询库的重试语义不合身);
+ * 这里只在有升级在跑时自轮询 — 横幅与「上次运行」的结局要能自愈,
+ * 不能指望弹窗一直开着。
  */
 export function useUpgradeStatus() {
   return useQuery({
@@ -36,6 +38,7 @@ export function useUpgradeStatus() {
     queryFn: getUpgradeStatus,
     staleTime: 15_000,
     retry: false,
+    refetchInterval: (query) => (query.state.data?.running ? 5000 : false),
   });
 }
 
diff --git a/packages/server/src/updater.ts b/packages/server/src/updater.ts
index 7b89dd1..ebc8ded 100644
--- a/packages/server/src/updater.ts
+++ b/packages/server/src/updater.ts
@@ -336,6 +336,11 @@ export class Updater {
       reject: false,
     });
     if (result.exitCode !== 0) {
+      // A hung fetch (unreachable mirror, packet-dropping middlebox) is the
+      // most common failure here — name it instead of "exit unknown".
+      if (result.timedOut) {
+        throw new Error(`git ${args[0]} timed out after ${timeout / 1000}s`);
+      }
       const stderr = (result.stderr ?? '').trim();
       throw new Error(
         `git ${args[0]} failed: ${stderr.slice(0, 300) || `exit ${result.exitCode ?? 'unknown'}`}`,

From fa58f2b5b512747a698d5899396458f414495b65 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 19:48:42 +0800
Subject: [PATCH 081/133] =?UTF-8?q?The=20double-apply=20refusal=20stops=20?=
 =?UTF-8?q?parsing=20prose:=20whether=20a=20second=20one-click=20upgrade?=
 =?UTF-8?q?=20gets=20its=20honest=20409=20is=20adjudicated=20by=20asking?=
 =?UTF-8?q?=20systemd=20if=20the=20unit=20is=20alive=20=E2=80=94=20systemd?=
 =?UTF-8?q?=20255=20phrases=20the=20launch=20refusal=20"was=20already=20lo?=
 =?UTF-8?q?aded=20or=20has=20a=20fragment=20file"=20where=20older=20versio?=
 =?UTF-8?q?ns=20said=20"already=20exists",=20caught=20live=20on=20real=20h?=
 =?UTF-8?q?ardware=20when=20the=20mutex=20held=20but=20answered=20as=20a?=
 =?UTF-8?q?=20raw=20500?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/server/src/updater.test.ts | 30 +++++++++++++++++++++++++----
 packages/server/src/updater.ts      |  9 ++++++---
 2 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/packages/server/src/updater.test.ts b/packages/server/src/updater.test.ts
index c1fd408..fa7f74d 100644
--- a/packages/server/src/updater.test.ts
+++ b/packages/server/src/updater.test.ts
@@ -237,21 +237,43 @@ describe('Updater.apply and status', () => {
     expect(calls.at(-1)).toContain("--mirror' 'cn'");
   });
 
-  it('maps a live unit to an honest 409', async () => {
+  it('maps a refused launch with a live unit to an honest 409', async () => {
+    // The refusal wording is systemd 255's, verbatim from the real machine
+    // — the adjudication must not depend on it: the unit's liveness is
+    // what makes this a "someone is already upgrading", not the prose.
     const updater = updaterFor({
-      run: async (_file, args) =>
-        args[0] === '--version'
+      run: async (file, args) =>
+        file === 'systemctl' || args[0] === '--version'
           ? { exitCode: 0, stdout: '', stderr: '' }
           : {
               exitCode: 1,
               stdout: '',
               stderr:
-                'Failed to start transient service unit: Unit dormice-upgrade.service already exists.',
+                'Failed to start transient service unit: Unit dormice-upgrade.service was already loaded or has a fragment file.',
             },
     });
     await expect(updater.apply()).rejects.toMatchObject({ statusCode: 409 });
   });
 
+  it('maps a failed launch with no live unit to a 500 carrying stderr', async () => {
+    const updater = updaterFor({
+      run: async (file, args) =>
+        args[0] === '--version'
+          ? { exitCode: 0, stdout: '', stderr: '' }
+          : file === 'systemctl'
+            ? { exitCode: 3, stdout: '', stderr: '' }
+            : {
+                exitCode: 1,
+                stdout: '',
+                stderr: 'Interactive authentication required.',
+              },
+    });
+    await expect(updater.apply()).rejects.toMatchObject({
+      statusCode: 500,
+      message: expect.stringContaining('Interactive authentication required'),
+    });
+  });
+
   it('adjudicates a dead runner into a failure and tails the log', async () => {
     const statusDir = mkdtempSync(path.join(tmpdir(), 'dormice-status-'));
     writeFileSync(
diff --git a/packages/server/src/updater.ts b/packages/server/src/updater.ts
index ebc8ded..71d3704 100644
--- a/packages/server/src/updater.ts
+++ b/packages/server/src/updater.ts
@@ -208,14 +208,17 @@ export class Updater {
       command,
     ]);
     if (launch.exitCode !== 0) {
-      const stderr = launch.stderr.trim();
-      // The unit name is the mutex: systemd refuses a second one.
-      if (stderr.includes('already exists')) {
+      // The unit name is the mutex, but systemd phrases the refusal more
+      // than one way ("already exists"; "was already loaded or has a
+      // fragment file" on systemd 255, caught on real hardware) — so ask
+      // systemd whether the unit is alive instead of parsing prose.
+      if (await this.unitActive()) {
         throw httpError(
           409,
           'an upgrade is already running — wait for it to finish (systemd unit dormice-upgrade)',
         );
       }
+      const stderr = launch.stderr.trim();
       throw httpError(
         500,
         `failed to launch the upgrade: ${stderr.slice(0, 300) || 'systemd-run gave no reason'}`,

From 41180606c7fc9741b81a66919dd07d6d16ff6cd7 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 20:00:34 +0800
Subject: [PATCH 082/133] =?UTF-8?q?The=20site=20learns=20its=20own=20addre?=
 =?UTF-8?q?ss=20and=20how=20to=20ship=20itself:=20dormice.dev=20becomes=20?=
 =?UTF-8?q?a=20plain=20constant=20in=20site.ts=20(the=20domain=20is=20deci?=
 =?UTF-8?q?ded,=20so=20no=20env-var=20ceremony),=20canonical/OG/sitemap/ro?=
 =?UTF-8?q?bots=20grow=20from=20it,=20and=20a=20Dockerfile=20bakes=20the?=
 =?UTF-8?q?=20static=20export=20into=20a=20Caddy=20image=20for=20Dokploy?=
 =?UTF-8?q?=20to=20build=20and=20route=20=E2=80=94=20the=20alias=20hostnam?=
 =?UTF-8?q?es=20301=20home=20from=20inside?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .dockerignore                     |  8 ++++++++
 website/Caddyfile                 | 22 ++++++++++++++++++++++
 website/Dockerfile                | 19 +++++++++++++++++++
 website/scripts/generate-llms.mjs | 13 ++++++++-----
 website/src/app/layout.tsx        | 13 ++++++++++++-
 website/src/app/robots.ts         | 13 +++++++++++++
 website/src/app/sitemap.ts        | 15 +++++++++++++++
 website/src/lib/site.ts           |  9 +++++++--
 8 files changed, 104 insertions(+), 8 deletions(-)
 create mode 100644 .dockerignore
 create mode 100644 website/Caddyfile
 create mode 100644 website/Dockerfile
 create mode 100644 website/src/app/robots.ts
 create mode 100644 website/src/app/sitemap.ts

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..f6706a6
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,8 @@
+# Keeps local docker builds of website/Dockerfile from uploading build
+# artifacts and dependency trees; a CI/Dokploy clone is clean anyway.
+**/node_modules
+**/dist
+**/.next
+**/out
+.git
+e2e
diff --git a/website/Caddyfile b/website/Caddyfile
new file mode 100644
index 0000000..dde0ce6
--- /dev/null
+++ b/website/Caddyfile
@@ -0,0 +1,22 @@
+# Serves the static export inside the website container. The platform's
+# reverse proxy (Dokploy's Traefik) owns TLS and routes all four hostnames
+# here, so HTTPS stays off and hostname redirects match on the Host header.
+{
+	auto_https off
+}
+
+:80 {
+	# dormice.dev is the one canonical origin.
+	@alias host www.dormice.dev dormice.app www.dormice.app
+	redir @alias https://dormice.dev{uri} 301
+
+	root * /srv
+	encode zstd gzip
+	# The export writes docs/quickstart.html while links say /docs/quickstart.
+	try_files {path} {path}.html
+	file_server
+	handle_errors {
+		rewrite * /404.html
+		file_server
+	}
+}
diff --git a/website/Dockerfile b/website/Dockerfile
new file mode 100644
index 0000000..ebd1626
--- /dev/null
+++ b/website/Dockerfile
@@ -0,0 +1,19 @@
+# Builds the static website and serves it with Caddy. Written for Dokploy
+# (build type: Dockerfile, context: repo root, dockerfile: website/Dockerfile);
+# TLS is terminated by the platform's reverse proxy in front, so the Caddy in
+# here only serves files and answers redirects — see website/Caddyfile.
+#
+# The build context must be the repo root: the pnpm lockfile and workspace
+# manifest live there, even though the website has no workspace dependencies.
+FROM node:22-alpine AS build
+RUN corepack enable
+WORKDIR /repo
+COPY pnpm-workspace.yaml package.json pnpm-lock.yaml tsconfig.base.json ./
+COPY website/package.json website/
+RUN pnpm install --frozen-lockfile --filter @dormice/website
+COPY website/ website/
+RUN pnpm --filter @dormice/website build
+
+FROM caddy:2-alpine
+COPY website/Caddyfile /etc/caddy/Caddyfile
+COPY --from=build /repo/website/out /srv
diff --git a/website/scripts/generate-llms.mjs b/website/scripts/generate-llms.mjs
index 4582ec0..cac9e6b 100644
--- a/website/scripts/generate-llms.mjs
+++ b/website/scripts/generate-llms.mjs
@@ -6,10 +6,10 @@
 //
 // content/docs/meta.json stays the single decision point for grouping and
 // order (same as src/lib/docs.ts); the assertions below fail the build when
-// the directory and meta.json drift. Links are root-relative so the output
-// works before the deployment domain is decided — set SITE_URL to make them
-// absolute. No fallback origin: a made-up domain in a published file is
-// worse than a relative link.
+// the directory and meta.json drift. Links default to the production origin
+// (the same literal as SITE_URL in src/lib/site.ts — this script cannot
+// import TS); set SITE_URL in the environment only to preview against
+// another origin.
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -21,7 +21,10 @@ const websiteDir = path.resolve(
 const contentDir = path.join(websiteDir, 'content/docs');
 const outDir = path.join(websiteDir, 'out');
 
-const siteUrl = (process.env.SITE_URL ?? '').replace(/\/+$/, '');
+const siteUrl = (process.env.SITE_URL ?? 'https://dormice.dev').replace(
+  /\/+$/,
+  '',
+);
 
 /** Parse an .mdx file into { title, description, body } or throw naming the file. */
 async function parseDoc(name) {
diff --git a/website/src/app/layout.tsx b/website/src/app/layout.tsx
index 94f01fa..b3c70b1 100644
--- a/website/src/app/layout.tsx
+++ b/website/src/app/layout.tsx
@@ -4,15 +4,26 @@ import { SiteFooter } from '@/components/SiteFooter';
 import { SiteHeader } from '@/components/SiteHeader';
 import { ThemeProvider } from '@/components/ThemeProvider';
 import { docGroups } from '@/lib/docs';
-import { SITE_DESCRIPTION, SITE_TITLE } from '@/lib/site';
+import { SITE_DESCRIPTION, SITE_TITLE, SITE_URL } from '@/lib/site';
 import './global.css';
 
 export const metadata: Metadata = {
+  metadataBase: new URL(SITE_URL),
   title: {
     default: SITE_TITLE,
     template: '%s | Dormice',
   },
   description: SITE_DESCRIPTION,
+  // Relative canonical: each statically exported page resolves it against
+  // metadataBase to its own path, so no per-page metadata is needed.
+  alternates: { canonical: './' },
+  openGraph: {
+    title: SITE_TITLE,
+    description: SITE_DESCRIPTION,
+    url: SITE_URL,
+    siteName: 'Dormice',
+    type: 'website',
+  },
 };
 
 export default function Layout({ children }: { children: ReactNode }) {
diff --git a/website/src/app/robots.ts b/website/src/app/robots.ts
new file mode 100644
index 0000000..9021b0f
--- /dev/null
+++ b/website/src/app/robots.ts
@@ -0,0 +1,13 @@
+import type { MetadataRoute } from 'next';
+import { SITE_URL } from '@/lib/site';
+
+// Emitted as out/robots.txt at build time; output:'export' requires the
+// route to declare itself static.
+export const dynamic = 'force-static';
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: { userAgent: '*', allow: '/' },
+    sitemap: `${SITE_URL}/sitemap.xml`,
+  };
+}
diff --git a/website/src/app/sitemap.ts b/website/src/app/sitemap.ts
new file mode 100644
index 0000000..fb18507
--- /dev/null
+++ b/website/src/app/sitemap.ts
@@ -0,0 +1,15 @@
+import type { MetadataRoute } from 'next';
+import { docs } from '@/lib/docs';
+import { SITE_URL } from '@/lib/site';
+
+// Driven by the docs registry: a new page in meta.json lands in the sitemap
+// with no change here. Emitted as out/sitemap.xml at build time —
+// output:'export' requires the route to declare itself static.
+export const dynamic = 'force-static';
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  return [
+    { url: `${SITE_URL}/` },
+    ...docs.map((entry) => ({ url: `${SITE_URL}${entry.href}` })),
+  ];
+}
diff --git a/website/src/lib/site.ts b/website/src/lib/site.ts
index 9639586..cb1fa79 100644
--- a/website/src/lib/site.ts
+++ b/website/src/lib/site.ts
@@ -1,10 +1,15 @@
 // Site-wide constants, collected in one place so the layout metadata, the
 // landing sections and the chrome never drift apart. Page-local copy stays
 // in its section component; only text used from more than one place lives
-// here. SITE_URL (canonical/OG/sitemap) is deliberately absent until the
-// deployment target — GitHub Pages vs a domain — is decided.
+// here.
 export const GITHUB_URL = 'https://github.com/BitMiracle-AI/Dormice';
 
+// The production origin (canonical/OG/sitemap/robots). A plain constant, not
+// an env var: the domain is decided and permanent, and requiring an env var
+// would break the "root pnpm build needs no environment" invariant.
+// scripts/generate-llms.mjs carries the same literal (it cannot import TS).
+export const SITE_URL = 'https://dormice.dev';
+
 export const SITE_TITLE = 'Dormice — the SQLite of agent sandboxes';
 
 export const SITE_DESCRIPTION =

From 950223677330e289a71cc822c538b356bf114dad Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 22:00:48 +0800
Subject: [PATCH 083/133] The bare origin learns hospitality: a browser
 knocking on / is walked to /console, while machines still get their honest
 404

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/server/src/routes/console.test.ts | 32 ++++++++++++++++++++++
 packages/server/src/routes/console.ts      | 11 ++++++++
 2 files changed, 43 insertions(+)

diff --git a/packages/server/src/routes/console.test.ts b/packages/server/src/routes/console.test.ts
index 78c98ca..a59b968 100644
--- a/packages/server/src/routes/console.test.ts
+++ b/packages/server/src/routes/console.test.ts
@@ -361,6 +361,38 @@ describe('POST /console/auth/logout', () => {
   });
 });
 
+describe('GET / — the bare-origin redirect', () => {
+  it('sends a browser (html Accept) to /console/', async () => {
+    const res = await testApp(fixtureDist()).inject({
+      method: 'GET',
+      url: '/',
+      headers: { accept: 'text/html,application/xhtml+xml;q=0.9,*/*;q=0.8' },
+    });
+    expect(res.statusCode).toBe(302);
+    expect(res.headers.location).toBe('/console/');
+  });
+
+  it('keeps the honest 404 for non-browser clients', async () => {
+    // curl's default is Accept: */* — no html, no redirect.
+    const res = await testApp(fixtureDist()).inject({
+      method: 'GET',
+      url: '/',
+      headers: { accept: '*/*' },
+    });
+    expect(res.statusCode).toBe(404);
+    expect(res.json().message).toContain('not found');
+  });
+
+  it('redirects even when the console is not built — the 404 there points at pnpm build', async () => {
+    const res = await testApp().inject({
+      method: 'GET',
+      url: '/',
+      headers: { accept: 'text/html' },
+    });
+    expect(res.statusCode).toBe(302);
+  });
+});
+
 describe('static console at /console', () => {
   it('serves index.html and assets from the injected dist', async () => {
     const app = testApp(fixtureDist());
diff --git a/packages/server/src/routes/console.ts b/packages/server/src/routes/console.ts
index 373226d..28452b6 100644
--- a/packages/server/src/routes/console.ts
+++ b/packages/server/src/routes/console.ts
@@ -213,6 +213,17 @@ export const consoleRoutes: FastifyPluginAsyncZod<
     }),
   );
 
+  // The bare-origin convenience: a browser landing on / is a human looking
+  // for the console — send them there (even unbuilt, /console's "run pnpm
+  // build" 404 beats "route not found"). Machines never GET / with an html
+  // Accept, so they keep the honest 404 from the app-wide arbiter.
+  app.get('/', async (request, reply) => {
+    if (request.headers.accept?.includes('text/html')) {
+      return reply.redirect('/console/');
+    }
+    return reply.callNotFound();
+  });
+
   if (consoleDistDir) {
     await app.register(
       async (scope) => {

From cc13c371c59c4aa128ab1989d484671237ccd376 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 15 Jul 2026 22:26:30 +0800
Subject: [PATCH 084/133] The website image build accepts a registry override:
 --build-arg NPM_REGISTRY points pnpm at a mirror where registry.npmjs.org is
 throttled to death (measured from a mainland connection: two of 668 tarballs
 simply never arrive), defaulting to the real registry

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 website/Dockerfile | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/website/Dockerfile b/website/Dockerfile
index ebd1626..8da19db 100644
--- a/website/Dockerfile
+++ b/website/Dockerfile
@@ -10,7 +10,14 @@ RUN corepack enable
 WORKDIR /repo
 COPY pnpm-workspace.yaml package.json pnpm-lock.yaml tsconfig.base.json ./
 COPY website/package.json website/
-RUN pnpm install --frozen-lockfile --filter @dormice/website
+# Override for building where registry.npmjs.org is slow or unreachable
+# (mainland China): --build-arg NPM_REGISTRY=https://registry.npmmirror.com
+ARG NPM_REGISTRY=https://registry.npmjs.org/
+# The store lives in a BuildKit cache mount: downloaded tarballs survive
+# failed and repeated builds instead of starting over.
+RUN --mount=type=cache,target=/pnpm-store \
+    pnpm install --frozen-lockfile --filter @dormice/website \
+      --store-dir /pnpm-store --registry "$NPM_REGISTRY"
 COPY website/ website/
 RUN pnpm --filter @dormice/website build
 

From a4ea67c34740363b048e31c61a77bbaf083f94d8 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 01:58:31 +0800
Subject: [PATCH 085/133] =?UTF-8?q?The=20daemon=20learns=20to=20remember:?=
 =?UTF-8?q?=20a=2030-second=20sampler=20lands=20every=20measurable=20sandb?=
 =?UTF-8?q?ox's=20CPU/memory/disk=20and=20the=20fleet's=20five-state=20cou?=
 =?UTF-8?q?nts=20in=20two=20ledger=20tables=20(per-sandbox=20history=20fol?=
 =?UTF-8?q?lows=20the=20sandboxId=20across=20rebuilds=20and=20cascades=20w?=
 =?UTF-8?q?ith=20destroy;=20fleet=20snapshots=20belong=20to=20nobody=20and?=
 =?UTF-8?q?=20keep=20a=20fixed=2030=20days),=20getSandboxMetricsHistory=20?=
 =?UTF-8?q?and=20getFleetTimeline=20slice=20them=20=E2=80=94=20past=20360?=
 =?UTF-8?q?=20points=20the=20answer=20is=20bucketed=20by=20per-field=20max?=
 =?UTF-8?q?ima=20so=20spikes=20survive,=20and=20a=20window=20the=20daemon?=
 =?UTF-8?q?=20slept=20through=20shows=20the=20gap,=20never=20an=20interpol?=
 =?UTF-8?q?ation=20=E2=80=94=20the=20E2B=20metrics=20endpoint=20answers=20?=
 =?UTF-8?q?start/end=20from=20this=20real=20history=20instead=20of=20a=20s?=
 =?UTF-8?q?ingle=20now-sample=20(a=20just-born=20sandbox=20still=20gets=20?=
 =?UTF-8?q?one=20live=20reading=20when=20its=20window=20reaches=20now:=20t?=
 =?UTF-8?q?hat=20surface's=20politeness=20alone,=20the=20native=20verb=20r?=
 =?UTF-8?q?eports=20silence=20as=20silence),=20and=20the=20console=20grows?=
 =?UTF-8?q?=20the=20concurrency=20curve=20with=20window=20peak,=20per-sand?=
 =?UTF-8?q?box=20history=20charts=20and=20a=20quick-connect=20card?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 e2e/src/setup/daemon.ts                       |   3 +
 packages/console/src/components/Snippet.tsx   |  33 ++
 .../features/connect/pages/ConnectPage.tsx    |  65 +--
 .../console/src/features/connect/snippets.ts  |  46 ++
 .../overview/components/FleetOverview.tsx     | 353 +++++++++++++++
 .../overview/components/OverviewCards.tsx     |  67 +--
 .../overview/components/QuickConnectCard.tsx  |  35 ++
 .../overview/hooks/useFleetTimeline.ts        |  40 ++
 .../features/overview/pages/OverviewPage.tsx  |  10 +-
 .../sandboxes/components/MetricsPanel.tsx     | 288 ++++++++----
 .../console/src/features/sandboxes/format.ts  |  30 ++
 .../features/sandboxes/hooks/useSandboxes.ts  |  22 +
 .../features/settings/pages/SettingsPage.tsx  |   4 +
 packages/console/src/lib/api.ts               |  22 +
 .../server/drizzle/0007_metrics-history.sql   |  24 +
 .../server/drizzle/meta/0007_snapshot.json    | 425 ++++++++++++++++++
 packages/server/src/config.test.ts            |  21 +
 packages/server/src/config.ts                 |  23 +
 packages/server/src/db/metrics.ts             | 258 +++++++++++
 packages/server/src/db/schema.ts              | 105 ++++-
 packages/server/src/e2b/control.ts            | 100 ++++-
 packages/server/src/index.ts                  |   1 +
 packages/server/src/lifecycle.ts              |   5 +
 packages/server/src/main.ts                   |  23 +
 packages/server/src/metrics-sampler.test.ts   | 216 +++++++++
 packages/server/src/metrics-sampler.ts        |  78 ++++
 packages/server/src/routes/host.ts            |  67 ++-
 .../server/src/routes/observability.test.ts   | 213 +++++++++
 packages/shared/src/host.ts                   |   9 +-
 packages/shared/src/metrics.ts                | 124 ++++-
 30 files changed, 2464 insertions(+), 246 deletions(-)
 create mode 100644 packages/console/src/components/Snippet.tsx
 create mode 100644 packages/console/src/features/connect/snippets.ts
 create mode 100644 packages/console/src/features/overview/components/FleetOverview.tsx
 create mode 100644 packages/console/src/features/overview/components/QuickConnectCard.tsx
 create mode 100644 packages/console/src/features/overview/hooks/useFleetTimeline.ts
 create mode 100644 packages/server/drizzle/0007_metrics-history.sql
 create mode 100644 packages/server/drizzle/meta/0007_snapshot.json
 create mode 100644 packages/server/src/db/metrics.ts
 create mode 100644 packages/server/src/metrics-sampler.test.ts
 create mode 100644 packages/server/src/metrics-sampler.ts

diff --git a/e2e/src/setup/daemon.ts b/e2e/src/setup/daemon.ts
index 7a70d3f..589fb11 100644
--- a/e2e/src/setup/daemon.ts
+++ b/e2e/src/setup/daemon.ts
@@ -78,6 +78,9 @@ export default async function setup(project: TestProject) {
       // Sweep every second so lifecycle tests run on second-scale policies
       // instead of the production default of days.
       DORMICE_SCAN_INTERVAL_SECONDS: '1',
+      // Sample every second so history verbs have rows to answer with
+      // inside a test's lifetime.
+      DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS: '1',
       // A wildcard sandbox domain so getHost() and the port proxy are
       // exercised — no DNS needed, tests spoof the Host header locally.
       DORMICE_SANDBOX_DOMAIN: 'sbx.dormice.test',
diff --git a/packages/console/src/components/Snippet.tsx b/packages/console/src/components/Snippet.tsx
new file mode 100644
index 0000000..b301488
--- /dev/null
+++ b/packages/console/src/components/Snippet.tsx
@@ -0,0 +1,33 @@
+import { Copy01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import { copyText } from '@/lib/copy';
+
+/**
+ * A copyable code block — the connect page's and the overview's shared
+ * snippet skin, one copy button in the corner, toast on both outcomes.
+ */
+export function Snippet({ code }: { code: string }) {
+  return (
+    <div className="relative rounded-md border bg-muted/30">
+      <Button
+        variant="ghost"
+        size="icon-sm"
+        className="absolute top-1.5 right-1.5"
+        aria-label="复制到剪贴板"
+        onClick={() =>
+          copyText(code).then(
+            () => toast.success('已复制'),
+            () => toast.error('复制失败 — 请手动选中文本'),
+          )
+        }
+      >
+        <HugeiconsIcon icon={Copy01Icon} />
+      </Button>
+      <pre className="overflow-x-auto p-4 pr-12 font-mono text-xs leading-relaxed">
+        <code>{code}</code>
+      </pre>
+    </div>
+  );
+}
diff --git a/packages/console/src/features/connect/pages/ConnectPage.tsx b/packages/console/src/features/connect/pages/ConnectPage.tsx
index e742235..739f340 100644
--- a/packages/console/src/features/connect/pages/ConnectPage.tsx
+++ b/packages/console/src/features/connect/pages/ConnectPage.tsx
@@ -1,7 +1,4 @@
-import { Copy01Icon } from '@hugeicons/core-free-icons';
-import { HugeiconsIcon } from '@hugeicons/react';
-import { toast } from 'sonner';
-import { Button } from '@/components/ui/button';
+import { Snippet } from '@/components/Snippet';
 import {
   Card,
   CardContent,
@@ -9,31 +6,7 @@ import {
   CardHeader,
   CardTitle,
 } from '@/components/ui/card';
-import { copyText } from '@/lib/copy';
-
-function Snippet({ code }: { code: string }) {
-  return (
-    <div className="relative rounded-md border bg-muted/30">
-      <Button
-        variant="ghost"
-        size="icon-sm"
-        className="absolute top-1.5 right-1.5"
-        aria-label="复制到剪贴板"
-        onClick={() =>
-          copyText(code).then(
-            () => toast.success('已复制'),
-            () => toast.error('复制失败 — 请手动选中文本'),
-          )
-        }
-      >
-        <HugeiconsIcon icon={Copy01Icon} />
-      </Button>
-      <pre className="overflow-x-auto p-4 pr-12 font-mono text-xs leading-relaxed">
-        <code>{code}</code>
-      </pre>
-    </div>
-  );
-}
+import { cliSnippet, e2bSnippet, sdkSnippet } from '../snippets';
 
 /**
  * Read-only connection instructions. The endpoint is simply this page's
@@ -45,34 +18,6 @@ function Snippet({ code }: { code: string }) {
 export function ConnectPage() {
   const origin = window.location.origin;
 
-  const e2bSnippet = `import { Sandbox } from 'e2b';
-
-const sandbox = await Sandbox.create({
-  apiKey: 'e2b_<your API token>',
-  apiUrl: '${origin}/e2b/api',
-  sandboxUrl: '${origin}/e2b/envd',
-  // Dormice 扩展:同一个 externalId 永远回到同一个沙箱。
-  metadata: { externalId: 'my-project' },
-});
-
-const result = await sandbox.commands.run('echo hello from dormice');`;
-
-  const sdkSnippet = `import { Dormice } from '@dormice/sdk';
-
-const client = new Dormice({
-  endpoint: '${origin}',
-  token: '<your API token>',
-});
-
-await client.acquireSandbox('my-project');
-const result = await client.execCommand('my-project', 'echo hello');`;
-
-  const cliSnippet = `export DORMICE_ENDPOINT=${origin}
-export DORMICE_API_TOKEN=<your API token>
-
-dor sandbox ls
-dor sandbox exec my-project 'uname -r'`;
-
   return (
     <div className="mx-auto w-full max-w-3xl">
       <div className="mb-1">
@@ -98,7 +43,7 @@ dor sandbox exec my-project 'uname -r'`;
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Snippet code={e2bSnippet} />
+            <Snippet code={e2bSnippet(origin)} />
           </CardContent>
         </Card>
 
@@ -111,7 +56,7 @@ dor sandbox exec my-project 'uname -r'`;
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Snippet code={sdkSnippet} />
+            <Snippet code={sdkSnippet(origin)} />
           </CardContent>
         </Card>
 
@@ -124,7 +69,7 @@ dor sandbox exec my-project 'uname -r'`;
             </CardDescription>
           </CardHeader>
           <CardContent>
-            <Snippet code={cliSnippet} />
+            <Snippet code={cliSnippet(origin)} />
           </CardContent>
         </Card>
       </div>
diff --git a/packages/console/src/features/connect/snippets.ts b/packages/console/src/features/connect/snippets.ts
new file mode 100644
index 0000000..ae3a428
--- /dev/null
+++ b/packages/console/src/features/connect/snippets.ts
@@ -0,0 +1,46 @@
+/**
+ * 接入示例的单一来源:连接页与总览页的快速接入卡共用这里的模板,
+ * 不各自手写第二份。endpoint 永远是当前页面 origin — daemon 自己
+ * 托管控制台,浏览器怎么到的,SDK 就怎么到。
+ */
+
+export const e2bSnippet = (origin: string) => `import { Sandbox } from 'e2b';
+
+const sandbox = await Sandbox.create({
+  apiKey: 'e2b_<your API token>',
+  apiUrl: '${origin}/e2b/api',
+  sandboxUrl: '${origin}/e2b/envd',
+  // Dormice 扩展:同一个 externalId 永远回到同一个沙箱。
+  metadata: { externalId: 'my-project' },
+});
+
+const result = await sandbox.commands.run('echo hello from dormice');`;
+
+/** 总览页快速接入卡的精简版:两个 URL 一个前缀,一眼看完。 */
+export const e2bQuickSnippet = (
+  origin: string,
+) => `import { Sandbox } from 'e2b';
+
+const sandbox = await Sandbox.create({
+  apiKey: 'e2b_<your API token>',
+  apiUrl: '${origin}/e2b/api',
+  sandboxUrl: '${origin}/e2b/envd',
+});`;
+
+export const sdkSnippet = (
+  origin: string,
+) => `import { Dormice } from '@dormice/sdk';
+
+const client = new Dormice({
+  endpoint: '${origin}',
+  token: '<your API token>',
+});
+
+await client.acquireSandbox('my-project');
+const result = await client.execCommand('my-project', 'echo hello');`;
+
+export const cliSnippet = (origin: string) => `export DORMICE_ENDPOINT=${origin}
+export DORMICE_API_TOKEN=<your API token>
+
+dor sandbox ls
+dor sandbox exec my-project 'uname -r'`;
diff --git a/packages/console/src/features/overview/components/FleetOverview.tsx b/packages/console/src/features/overview/components/FleetOverview.tsx
new file mode 100644
index 0000000..46c928e
--- /dev/null
+++ b/packages/console/src/features/overview/components/FleetOverview.tsx
@@ -0,0 +1,353 @@
+import type { GetFleetTimelineResponse, SandboxState } from '@dormice/shared';
+import {
+  Activity01Icon,
+  ArrowUpRight01Icon,
+  PackageIcon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
+import { Link } from '@tanstack/react-router';
+import { useState } from 'react';
+import { Area, AreaChart, CartesianGrid, XAxis, YAxis } from 'recharts';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import {
+  type ChartConfig,
+  ChartContainer,
+  ChartLegend,
+  ChartLegendContent,
+  ChartTooltip,
+  ChartTooltipContent,
+} from '@/components/ui/chart';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import { Skeleton } from '@/components/ui/skeleton';
+import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
+import { STATE_COLORS, STATE_LABELS } from '@/features/sandboxes/format';
+import { pctOf } from '@/lib/format';
+import { cn } from '@/lib/utils';
+import {
+  TIMELINE_RANGES,
+  type TimelineRangeKey,
+  useFleetTimeline,
+} from '../hooks/useFleetTimeline';
+import { useHostMetrics } from '../hooks/useHostMetrics';
+
+/**
+ * 堆叠顺序:活跃垫底(它是主角,贴着基线最好读),往上依次是越来越冷
+ * 的状态 — 面积图从下往上就是"从热到冷",与生命周期同向。
+ */
+const STACK_ORDER: SandboxState[] = [
+  'active',
+  'frozen',
+  'stopped',
+  'archived',
+  'restoring',
+];
+
+const chartConfig = Object.fromEntries(
+  STACK_ORDER.map((state) => [
+    state,
+    { label: STATE_LABELS[state], theme: STATE_COLORS[state].chart },
+  ]),
+) satisfies ChartConfig;
+
+type ChartRow = { at: number } & Record<SandboxState, number | null>;
+
+/**
+ * 时间线点 → 图表行,并在采样断档处插一行 null:daemon 停机的时段
+ * 曲线要如实断开(connectNulls 关着),不许把空窗连成一条谎线。断档
+ * 的判据是点距超过期望间距的 3 倍 — 期望间距优先用服务端的桶宽,原始
+ * 样本则取中位点距(采样间隔是服务端配置,客户端不猜死值)。
+ */
+function toChartRows(
+  points: GetFleetTimelineResponse['points'],
+  bucketSeconds: number | null,
+): ChartRow[] {
+  const rows: ChartRow[] = points.map((p) => ({
+    at: Date.parse(p.at),
+    ...p.byState,
+  }));
+  const first = rows[0];
+  if (rows.length < 2 || first === undefined) return rows;
+
+  const deltas: number[] = [];
+  for (let i = 1; i < rows.length; i++) {
+    const prev = rows[i - 1];
+    const cur = rows[i];
+    if (prev !== undefined && cur !== undefined) deltas.push(cur.at - prev.at);
+  }
+  deltas.sort((a, b) => a - b);
+  const expectedMs =
+    bucketSeconds !== null
+      ? bucketSeconds * 1000
+      : (deltas[Math.floor(deltas.length / 2)] ?? 0);
+
+  const withGaps: ChartRow[] = [first];
+  for (let i = 1; i < rows.length; i++) {
+    const prev = rows[i - 1];
+    const cur = rows[i];
+    if (prev === undefined || cur === undefined) continue;
+    if (expectedMs > 0 && cur.at - prev.at > 3 * expectedMs) {
+      withGaps.push({
+        at: Math.round((prev.at + cur.at) / 2),
+        active: null,
+        frozen: null,
+        stopped: null,
+        archived: null,
+        restoring: null,
+      });
+    }
+    withGaps.push(cur);
+  }
+  return withGaps;
+}
+
+/** 长窗口给日期,短窗口给钟点 — 刻度只说这个窗口内有区分度的部分。 */
+function tickFormatter(range: TimelineRangeKey): (ms: number) => string {
+  if (range === '7d' || range === '30d') {
+    return (ms) => {
+      const d = new Date(ms);
+      return `${d.getMonth() + 1}/${d.getDate()}`;
+    };
+  }
+  return (ms) =>
+    new Date(ms).toLocaleTimeString('zh-CN', {
+      hour12: false,
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+}
+
+/** tooltip 与峰值注脚共用的完整时刻写法。 */
+function fullClock(ms: number): string {
+  return new Date(ms).toLocaleString('zh-CN', {
+    hour12: false,
+    month: 'numeric',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+function StatCard({
+  icon,
+  label,
+  value,
+  hint,
+  to,
+}: {
+  icon: NonNullable<HugeiconsProps['icon']>;
+  label: string;
+  value: string;
+  hint: string;
+  to?: string;
+}) {
+  const card = (
+    <Card size="sm">
+      <CardContent className="flex flex-col gap-2">
+        <div className="flex items-center gap-1.5 text-sm text-muted-foreground">
+          <HugeiconsIcon icon={icon} className="size-4" strokeWidth={1.8} />
+          {label}
+        </div>
+        <div className="text-2xl font-semibold tabular-nums">{value}</div>
+        <div className="text-xs text-muted-foreground">{hint}</div>
+      </CardContent>
+    </Card>
+  );
+  if (!to) return card;
+  return (
+    <Link
+      to={to}
+      className="block rounded-[min(var(--radius-4xl),24px)] transition-shadow hover:ring-2 hover:ring-primary/30"
+    >
+      {card}
+    </Link>
+  );
+}
+
+/**
+ * 舰队并发一览:三张统计卡(当前活跃 5 秒一刷、窗口峰值与总数)加一张
+ * 按状态堆叠的走势图。当前值来自 /getHostMetrics 快照;历史与峰值来自
+ * /getFleetTimeline — daemon 的采样器 30 秒落一行,窗口峰值由原始行现算,
+ * 分桶抹不掉它。
+ */
+export function FleetOverview() {
+  const [range, setRange] = useState<TimelineRangeKey>('24h');
+  const host = useHostMetrics();
+  const timeline = useFleetTimeline(range);
+  const rangeLabel =
+    TIMELINE_RANGES.find((r) => r.key === range)?.label ?? range;
+
+  if (host.isError || timeline.isError) {
+    const message = host.isError
+      ? host.error.message
+      : (timeline.error?.message ?? '');
+    return (
+      <Alert variant="destructive">
+        <AlertDescription>{message}</AlertDescription>
+      </Alert>
+    );
+  }
+
+  if (!host.data || !timeline.data) {
+    // 骨架镜像真实结构:三张统计卡 + 一张图表卡,高度与加载完成后一致。
+    return (
+      <section className="flex flex-col gap-4">
+        <div className="grid gap-4 sm:grid-cols-3">
+          {['active', 'peak', 'total'].map((slot) => (
+            <Card key={slot} size="sm">
+              <CardContent className="flex flex-col gap-2">
+                <Skeleton className="h-5 w-16" />
+                <Skeleton className="h-8 w-24" />
+                <Skeleton className="h-4 w-32" />
+              </CardContent>
+            </Card>
+          ))}
+        </div>
+        <Card>
+          <CardHeader>
+            <Skeleton className="h-5 w-32" />
+            <Skeleton className="h-4 w-48" />
+          </CardHeader>
+          <CardContent>
+            <Skeleton className="h-[280px] w-full" />
+          </CardContent>
+        </Card>
+      </section>
+    );
+  }
+
+  const { sandboxes } = host.data;
+  const { points, bucketSeconds, peak } = timeline.data;
+  const rows = toChartRows(points, bucketSeconds);
+
+  return (
+    <section className="flex flex-col gap-4">
+      <div className="grid gap-4 sm:grid-cols-3">
+        <StatCard
+          icon={Activity01Icon}
+          label="当前活跃"
+          value={String(sandboxes.byState.active)}
+          hint="此刻正在运行的沙箱 — 其余状态都不占 CPU"
+        />
+        <StatCard
+          icon={ArrowUpRight01Icon}
+          label={`${rangeLabel}内峰值`}
+          value={peak === null ? '—' : String(peak.active)}
+          hint={
+            peak === null
+              ? '窗口内还没有采样'
+              : `活跃并发最高点,出现于 ${fullClock(Date.parse(peak.at))}`
+          }
+        />
+        <StatCard
+          icon={PackageIcon}
+          label="沙箱总数"
+          value={`${sandboxes.total} / ${sandboxes.maxSandboxes}`}
+          hint={`容量上限 ${sandboxes.maxSandboxes},已用 ${Math.round(pctOf(sandboxes.total, sandboxes.maxSandboxes))}%`}
+          to="/sandboxes"
+        />
+      </div>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>沙箱并发走势</CardTitle>
+          <CardDescription>
+            各状态沙箱数量随时间的变化 — 活跃掉下去、冻结涨上来,就是
+            「空闲即免费」在发生。
+          </CardDescription>
+          <CardAction>
+            <ToggleGroup
+              value={[range]}
+              onValueChange={(value: unknown[]) => {
+                // base-ui 允许再点一下取消选中(空数组)— 档位必须常有,忽略。
+                const next = value[0];
+                if (typeof next === 'string') {
+                  setRange(next as TimelineRangeKey);
+                }
+              }}
+              variant="outline"
+              size="sm"
+            >
+              {TIMELINE_RANGES.map((r) => (
+                <ToggleGroupItem key={r.key} value={r.key}>
+                  {r.label}
+                </ToggleGroupItem>
+              ))}
+            </ToggleGroup>
+          </CardAction>
+        </CardHeader>
+        <CardContent>
+          {rows.length < 2 ? (
+            <Empty className={cn('border border-dashed', 'h-[280px]')}>
+              <EmptyHeader>
+                <EmptyTitle>窗口内还没有走势可画</EmptyTitle>
+                <EmptyDescription>
+                  daemon 每 30 秒落一次采样,攒够两个点就开始画;daemon
+                  停机的时段没有采样,曲线会如实断开。
+                </EmptyDescription>
+              </EmptyHeader>
+            </Empty>
+          ) : (
+            <ChartContainer config={chartConfig} className="h-[280px] w-full">
+              <AreaChart data={rows} margin={{ left: 4, right: 12, top: 4 }}>
+                <CartesianGrid vertical={false} />
+                <XAxis
+                  dataKey="at"
+                  type="number"
+                  domain={['dataMin', 'dataMax']}
+                  tickFormatter={tickFormatter(range)}
+                  tickLine={false}
+                  axisLine={false}
+                  minTickGap={48}
+                />
+                <YAxis
+                  width={36}
+                  allowDecimals={false}
+                  tickLine={false}
+                  axisLine={false}
+                  tickCount={4}
+                />
+                <ChartTooltip
+                  content={
+                    <ChartTooltipContent
+                      labelFormatter={(_, payload) =>
+                        fullClock((payload?.[0]?.payload as { at: number }).at)
+                      }
+                    />
+                  }
+                />
+                <ChartLegend content={<ChartLegendContent />} />
+                {STACK_ORDER.map((state) => (
+                  <Area
+                    key={state}
+                    dataKey={state}
+                    stackId="fleet"
+                    type="monotone"
+                    stroke={`var(--color-${state})`}
+                    fill={`var(--color-${state})`}
+                    fillOpacity={0.35}
+                    strokeWidth={2}
+                    isAnimationActive={false}
+                    connectNulls={false}
+                  />
+                ))}
+              </AreaChart>
+            </ChartContainer>
+          )}
+        </CardContent>
+      </Card>
+    </section>
+  );
+}
diff --git a/packages/console/src/features/overview/components/OverviewCards.tsx b/packages/console/src/features/overview/components/OverviewCards.tsx
index 6bdff1d..619b683 100644
--- a/packages/console/src/features/overview/components/OverviewCards.tsx
+++ b/packages/console/src/features/overview/components/OverviewCards.tsx
@@ -1,9 +1,7 @@
-import type { HostMetricsResponse } from '@dormice/shared';
 import {
   CpuIcon,
   Database01Icon,
   HardDriveIcon,
-  PackageIcon,
   RamMemoryIcon,
   SnowIcon,
 } from '@hugeicons/core-free-icons';
@@ -13,10 +11,10 @@ import type { ReactNode } from 'react';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import { Card, CardContent } from '@/components/ui/card';
 import { Skeleton } from '@/components/ui/skeleton';
-import { STATE_LABELS } from '@/features/sandboxes/format';
 import { formatBytes, pctOf } from '@/lib/format';
 import { cn } from '@/lib/utils';
 import { useHostMetrics } from '../hooks/useHostMetrics';
+import { QuickConnectCard } from './QuickConnectCard';
 
 /**
  * Usage meter: the fill carries severity (quiet below 75%, amber to 90%,
@@ -84,48 +82,15 @@ function StatCard({
   );
 }
 
-// The lifecycle rungs shown in the fleet card, coldest last — same hues as
-// SandboxStateBadge so the two read as one system. archived and restoring
-// only appear once they exist (no archiver yet — nothing is promised).
-const STATE_DOTS: Array<{
-  key: keyof HostMetricsResponse['sandboxes']['byState'];
-  dot: string;
-  alwaysShown: boolean;
-}> = [
-  { key: 'active', dot: 'bg-emerald-500', alwaysShown: true },
-  { key: 'frozen', dot: 'bg-sky-500', alwaysShown: true },
-  { key: 'stopped', dot: 'bg-muted-foreground/50', alwaysShown: true },
-  { key: 'archived', dot: 'bg-violet-500', alwaysShown: false },
-  { key: 'restoring', dot: 'bg-amber-500', alwaysShown: false },
-];
-
-function StateCounts({
-  byState,
-}: {
-  byState: HostMetricsResponse['sandboxes']['byState'];
-}) {
-  return (
-    <span className="flex flex-wrap gap-x-3 gap-y-1">
-      {STATE_DOTS.filter((s) => s.alwaysShown || byState[s.key] > 0).map(
-        (s) => (
-          <span key={s.key} className="inline-flex items-center gap-1.5">
-            <span className={cn('size-2 rounded-full', s.dot)} />
-            <span className="font-medium text-foreground">
-              {byState[s.key]}
-            </span>
-            {STATE_LABELS[s.key]}
-          </span>
-        ),
-      )}
-    </span>
-  );
-}
-
 /**
- * The dashboard's card row: is the host healthy, and what does the fleet
- * cost it? Swap and the data disk get equal billing with CPU and memory
- * because on this platform they are the two that kill: full swap ends
- * "idle is free", a full data disk ends creation entirely.
+ * The dashboard's host rows: is the machine healthy, and what do the
+ * sandbox disks cost it? Swap and the data disk get equal billing with CPU
+ * and memory because on this platform they are the two that kill: full
+ * swap ends "idle is free", a full data disk ends creation entirely. The
+ * fleet's own numbers (counts, states, the concurrency curve) live in
+ * FleetOverview above — this section is the machine's story. The quick
+ * connect card is static and shares the bottom row, so loading and loaded
+ * states keep the same shape.
  */
 export function OverviewCards() {
   const query = useHostMetrics();
@@ -158,13 +123,14 @@ export function OverviewCards() {
           {['cpu', 'memory', 'swap', 'data-disk'].map(bones)}
         </div>
         <div className="grid gap-4 md:grid-cols-2">
-          {['sandboxes', 'sandbox-disks'].map(bones)}
+          {bones('sandbox-disks')}
+          <QuickConnectCard />
         </div>
       </section>
     );
   }
 
-  const { host, dataDisk, sandboxes, sandboxDisks } = query.data;
+  const { host, dataDisk, sandboxDisks } = query.data;
   const memUsed = host.memTotalBytes - host.memAvailableBytes;
 
   return (
@@ -236,14 +202,6 @@ export function OverviewCards() {
       </div>
 
       <div className="grid gap-4 md:grid-cols-2">
-        <StatCard
-          icon={PackageIcon}
-          label="沙箱"
-          value={`${sandboxes.total} / ${sandboxes.maxSandboxes}`}
-          hint={<StateCounts byState={sandboxes.byState} />}
-          pct={pctOf(sandboxes.total, sandboxes.maxSandboxes)}
-          to="/sandboxes"
-        />
         <StatCard
           icon={Database01Icon}
           label="沙箱磁盘"
@@ -252,6 +210,7 @@ export function OverviewCards() {
           pct={pctOf(sandboxDisks.actualBytes, sandboxDisks.nominalBytes)}
           to="/sandboxes"
         />
+        <QuickConnectCard />
       </div>
     </section>
   );
diff --git a/packages/console/src/features/overview/components/QuickConnectCard.tsx b/packages/console/src/features/overview/components/QuickConnectCard.tsx
new file mode 100644
index 0000000..cabd4b6
--- /dev/null
+++ b/packages/console/src/features/overview/components/QuickConnectCard.tsx
@@ -0,0 +1,35 @@
+import { Link } from '@tanstack/react-router';
+import { Snippet } from '@/components/Snippet';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import { e2bQuickSnippet } from '@/features/connect/snippets';
+
+/**
+ * 总览页的快速接入卡:官方 e2b 包换两个 URL 直连 — 产品的一句话卖点,
+ * 放在第一屏。完整的三种接入方式(E2B / 原生 SDK / CLI)在连接页。
+ */
+export function QuickConnectCard() {
+  const origin = window.location.origin;
+  return (
+    <Card size="sm">
+      <CardHeader>
+        <CardTitle>快速接入</CardTitle>
+        <CardDescription>
+          官方 <code className="font-mono">e2b</code> 包换两个 URL 直连;token 在
+          daemon 主机的 <code className="font-mono">/etc/dormice/env</code> 里。
+          <Link to="/connect" className="text-primary hover:underline">
+            全部接入方式
+          </Link>
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Snippet code={e2bQuickSnippet(origin)} />
+      </CardContent>
+    </Card>
+  );
+}
diff --git a/packages/console/src/features/overview/hooks/useFleetTimeline.ts b/packages/console/src/features/overview/hooks/useFleetTimeline.ts
new file mode 100644
index 0000000..f36e49f
--- /dev/null
+++ b/packages/console/src/features/overview/hooks/useFleetTimeline.ts
@@ -0,0 +1,40 @@
+import { useQuery } from '@tanstack/react-query';
+import { getFleetTimeline } from '@/lib/api';
+
+/** 时间档位与其毫秒宽度 — 切换器与查询共用一份。 */
+export const TIMELINE_RANGES = [
+  { key: '1h', label: '1 小时', spanMs: 3600_000 },
+  { key: '24h', label: '24 小时', spanMs: 24 * 3600_000 },
+  { key: '7d', label: '7 天', spanMs: 7 * 86_400_000 },
+  { key: '30d', label: '30 天', spanMs: 30 * 86_400_000 },
+] as const;
+
+export type TimelineRangeKey = (typeof TIMELINE_RANGES)[number]['key'];
+
+export function rangeSpanMs(key: TimelineRangeKey): number {
+  // TIMELINE_RANGES 穷尽了 key 的取值,find 必中。
+  const range = TIMELINE_RANGES.find((r) => r.key === key);
+  if (!range) throw new Error(`unknown timeline range ${key}`);
+  return range.spanMs;
+}
+
+/**
+ * 舰队时间线,跟随档位轮询。30 秒一刷 — 与 daemon 的采样间隔同步,
+ * 更快只是重复读到同一批快照。窗口在每次 queryFn 里现算,所以长开的
+ * 页面窗口会随时间滑动。
+ */
+export function useFleetTimeline(range: TimelineRangeKey) {
+  return useQuery({
+    queryKey: ['fleetTimeline', range],
+    queryFn: () => {
+      const end = Date.now();
+      const start = end - rangeSpanMs(range);
+      return getFleetTimeline(
+        new Date(start).toISOString(),
+        new Date(end).toISOString(),
+      );
+    },
+    refetchInterval: 30_000,
+    retry: false,
+  });
+}
diff --git a/packages/console/src/features/overview/pages/OverviewPage.tsx b/packages/console/src/features/overview/pages/OverviewPage.tsx
index 0916046..d51be0f 100644
--- a/packages/console/src/features/overview/pages/OverviewPage.tsx
+++ b/packages/console/src/features/overview/pages/OverviewPage.tsx
@@ -1,8 +1,11 @@
+import { FleetOverview } from '../components/FleetOverview';
 import { OverviewCards } from '../components/OverviewCards';
 
 /**
- * 回答两个问题:这台机器还好吗、这群沙箱花了它多少。数字全部来自
- * /getHostMetrics 单次快照 — 观察窗,不是监控系统。
+ * 回答三个问题:沙箱群现在多忙、一段时间以来多忙(daemon 采样器落库的
+ * 舰队时间线,含窗口峰值)、这台机器还好吗。当前值来自 /getHostMetrics
+ * 快照,走势来自 /getFleetTimeline 历史;快速接入卡把「换两个 URL 直连」
+ * 放上第一屏。
  */
 export function OverviewPage() {
   return (
@@ -10,9 +13,10 @@ export function OverviewPage() {
       <div>
         <h1 className="text-2xl font-semibold">仪表盘</h1>
         <p className="text-sm text-muted-foreground">
-          这台机器的健康状况,与沙箱群花掉的资源。
+          沙箱群的并发走势,与这台机器的健康状况。
         </p>
       </div>
+      <FleetOverview />
       <OverviewCards />
     </>
   );
diff --git a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
index d835609..02f6bb0 100644
--- a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
@@ -5,8 +5,9 @@ import {
   RamMemoryIcon,
 } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
-import { useEffect, useState } from 'react';
+import { useState } from 'react';
 import { CartesianGrid, Line, LineChart, XAxis, YAxis } from 'recharts';
+import { Alert, AlertDescription } from '@/components/ui/alert';
 import { Card, CardContent } from '@/components/ui/card';
 import {
   type ChartConfig,
@@ -21,10 +22,14 @@ import {
   EmptyTitle,
 } from '@/components/ui/empty';
 import { Spinner } from '@/components/ui/spinner';
+import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
 import { formatBytes, pctOf } from '@/lib/format';
 import { cn } from '@/lib/utils';
 import { since } from '../format';
-import { useSandboxMetrics } from '../hooks/useSandboxes';
+import {
+  useSandboxMetrics,
+  useSandboxMetricsHistory,
+} from '../hooks/useSandboxes';
 
 function Meter({ pct }: { pct: number }) {
   const clamped = Math.min(100, Math.max(0, pct));
@@ -72,39 +77,85 @@ function MetricCard({
   );
 }
 
-/** 滚动窗口容量:5 秒一拍 × 120 点 ≈ 最近 10 分钟。 */
-const HISTORY_CAP = 120;
+/** 历史档位 — daemon 留 7 天逐沙箱样本,档位到 7 天为止。 */
+const HISTORY_RANGES = [
+  { key: '1h', label: '1 小时', spanMs: 3600_000 },
+  { key: '24h', label: '24 小时', spanMs: 24 * 3600_000 },
+  { key: '7d', label: '7 天', spanMs: 7 * 86_400_000 },
+] as const;
+
+type HistoryRangeKey = (typeof HISTORY_RANGES)[number]['key'];
+
+/** 短窗口给钟点,7 天窗口给日期 — 刻度只说窗口内有区分度的部分。 */
+function clockFor(range: HistoryRangeKey): (ms: number) => string {
+  if (range === '7d') {
+    return (ms) => {
+      const d = new Date(ms);
+      return `${d.getMonth() + 1}/${d.getDate()}`;
+    };
+  }
+  return (ms) =>
+    new Date(ms).toLocaleTimeString('zh-CN', {
+      hour12: false,
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+}
+
+/** tooltip 用的完整时刻。 */
+const fullClock = (ms: number) =>
+  new Date(ms).toLocaleString('zh-CN', {
+    hour12: false,
+    month: 'numeric',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+
+type SeriesPoint = { at: number; value: number | null };
 
 /**
- * 面板打开期间的采样累积。daemon 刻意不存指标历史(观察窗不是监控
- * 系统),但"刚才那一下是不是内存尖峰"值得回答 — 历史就攒在浏览器里,
- * 换沙箱清零,关面板即忘。
+ * 样本 → 单序列,并在采样断档处插一个 null 点:沙箱停着或 daemon 停机
+ * 的时段没有样本,曲线要如实断开(connectNulls 关着),不许连成谎线。
+ * 断档判据 = 点距超过期望间距 3 倍;期望间距优先用服务端桶宽,原始样本
+ * 取中位点距。
  */
-function useSampleHistory(
-  sandboxId: string,
-  latest: SandboxMetricsSample | null | undefined,
-): SandboxMetricsSample[] {
-  const [history, setHistory] = useState<SandboxMetricsSample[]>([]);
-  // 换沙箱清零:render 期重置(React 官方推荐形),不多跑一轮 effect。
-  const [prevId, setPrevId] = useState(sandboxId);
-  if (prevId !== sandboxId) {
-    setPrevId(sandboxId);
-    setHistory([]);
+function toSeries(
+  samples: SandboxMetricsSample[],
+  pick: (s: SandboxMetricsSample) => number,
+  bucketSeconds: number | null,
+): SeriesPoint[] {
+  const points: SeriesPoint[] = samples.map((s) => ({
+    at: Date.parse(s.timestamp),
+    value: pick(s),
+  }));
+  const first = points[0];
+  if (points.length < 2 || first === undefined) return points;
+
+  const deltas: number[] = [];
+  for (let i = 1; i < points.length; i++) {
+    const prev = points[i - 1];
+    const cur = points[i];
+    if (prev !== undefined && cur !== undefined) deltas.push(cur.at - prev.at);
   }
-  useEffect(() => {
-    if (!latest) return;
-    setHistory((prev) =>
-      prev.at(-1)?.timestamp === latest.timestamp
-        ? prev
-        : [...prev.slice(-(HISTORY_CAP - 1)), latest],
-    );
-  }, [latest]);
-  return history;
-}
+  deltas.sort((a, b) => a - b);
+  const expectedMs =
+    bucketSeconds !== null
+      ? bucketSeconds * 1000
+      : (deltas[Math.floor(deltas.length / 2)] ?? 0);
 
-/** 时间轴刻度:HH:MM:SS,窗口只有分钟级,日期是噪声。 */
-const clock = (ms: number) =>
-  new Date(ms).toLocaleTimeString('zh-CN', { hour12: false });
+  const withGaps: SeriesPoint[] = [first];
+  for (let i = 1; i < points.length; i++) {
+    const prev = points[i - 1];
+    const cur = points[i];
+    if (prev === undefined || cur === undefined) continue;
+    if (expectedMs > 0 && cur.at - prev.at > 3 * expectedMs) {
+      withGaps.push({ at: Math.round((prev.at + cur.at) / 2), value: null });
+    }
+    withGaps.push(cur);
+  }
+  return withGaps;
+}
 
 /**
  * 一个度量一张小图,单系列单轴(不同量纲绝不共轴)。线色用主题的
@@ -114,12 +165,14 @@ const clock = (ms: number) =>
 function HistoryChart({
   title,
   data,
+  xTickFormatter,
   tickFormatter,
   valueFormatter,
   domainMax,
 }: {
   title: string;
-  data: Array<{ at: number; value: number }>;
+  data: SeriesPoint[];
+  xTickFormatter: (ms: number) => string;
   tickFormatter: (value: number) => string;
   valueFormatter: (value: number) => string;
   domainMax?: number;
@@ -138,7 +191,7 @@ function HistoryChart({
               dataKey="at"
               type="number"
               domain={['dataMin', 'dataMax']}
-              tickFormatter={clock}
+              tickFormatter={xTickFormatter}
               tickLine={false}
               axisLine={false}
               minTickGap={48}
@@ -155,7 +208,7 @@ function HistoryChart({
               content={
                 <ChartTooltipContent
                   labelFormatter={(_, payload) =>
-                    clock((payload?.[0]?.payload as { at: number }).at)
+                    fullClock((payload?.[0]?.payload as { at: number }).at)
                   }
                   formatter={(value) => valueFormatter(Number(value))}
                 />
@@ -168,6 +221,7 @@ function HistoryChart({
               strokeWidth={2}
               dot={false}
               isAnimationActive={false}
+              connectNulls={false}
             />
           </LineChart>
         </ChartContainer>
@@ -177,110 +231,150 @@ function HistoryChart({
 }
 
 /**
- * 单沙箱指标:5 秒一拍的单次快照(观察窗不是监控系统)。观察不唤醒 —
- * 冻结的沙箱睡着也能读(cgroup 记账还在),停了的沙箱没有容器可测,
- * daemon 答 null,这里出空态而不是把它吵醒。
+ * 单沙箱指标:上半是 5 秒一拍的当前值(观察不唤醒 — 冻结的沙箱睡着
+ * 也能读,停了的沙箱没有容器可测,daemon 答 null,这里出空态而不是把
+ * 它吵醒);下半是 daemon 采样器落库的历史(30 秒一刷)。两半各自处理
+ * 空态:沙箱停着时当前值区出空态,历史照常在 — 历史是历史。
  */
 export function MetricsPanel({ sandbox }: { sandbox: Sandbox }) {
-  const { data, isPending, isError, error } = useSandboxMetrics(
-    sandbox.externalId,
-  );
-  // Hook 在任何 early return 之前:面板打开期间持续累积,换沙箱清零。
-  const history = useSampleHistory(sandbox.sandboxId, data?.sample);
+  const [range, setRange] = useState<HistoryRangeKey>('1h');
+  const live = useSandboxMetrics(sandbox.externalId);
+  const spanMs =
+    HISTORY_RANGES.find((r) => r.key === range)?.spanMs ?? 3600_000;
+  const history = useSandboxMetricsHistory(sandbox.externalId, spanMs);
 
-  if (isPending) {
+  if (live.isPending) {
     return (
       <div className="flex items-center gap-2 text-sm text-muted-foreground">
         <Spinner /> 读取指标
       </div>
     );
   }
-  if (isError) {
+  if (live.isError) {
     return (
       <Empty className="border border-dashed">
         <EmptyHeader>
           <EmptyTitle>读取失败</EmptyTitle>
-          <EmptyDescription>{error.message}</EmptyDescription>
-        </EmptyHeader>
-      </Empty>
-    );
-  }
-  const sample = data.sample;
-  if (sample === null) {
-    return (
-      <Empty className="border border-dashed">
-        <EmptyHeader>
-          <EmptyTitle>没有运行中的容器可测</EmptyTitle>
-          <EmptyDescription>
-            沙箱现在没有活着的容器(已停止/已归档)。观察不唤醒 —
-            打开终端或执行命令才会把它叫醒。
-          </EmptyDescription>
+          <EmptyDescription>{live.error.message}</EmptyDescription>
         </EmptyHeader>
       </Empty>
     );
   }
+  const sample = live.data.sample;
+  const samples = history.data?.samples ?? [];
+  const bucketSeconds = history.data?.bucketSeconds ?? null;
+  const lastSample = samples.at(-1) ?? sample;
 
   return (
     <div className="flex flex-col gap-3">
-      <div className="grid gap-4 sm:grid-cols-2 xl:grid-cols-3">
-        <MetricCard
-          icon={CpuIcon}
-          label="CPU"
-          value={`${Math.round(sample.cpuUsedPct)}%`}
-          hint={`${sample.cpuCount} 核 · 百分比按单核计`}
-          pct={sample.cpuUsedPct / sample.cpuCount}
-        />
-        <MetricCard
-          icon={RamMemoryIcon}
-          label="内存"
-          value={formatBytes(sample.memUsedBytes)}
-          hint={`共 ${formatBytes(sample.memTotalBytes)} · 缓存 ${formatBytes(sample.memCacheBytes)}`}
-          pct={pctOf(sample.memUsedBytes, sample.memTotalBytes)}
-        />
-        <MetricCard
-          icon={HardDriveIcon}
-          label="磁盘"
-          value={formatBytes(sample.diskUsedBytes)}
-          hint={`名义 ${formatBytes(sample.diskTotalBytes)} — 稀疏镜像只为真实内容付费`}
-          pct={pctOf(sample.diskUsedBytes, sample.diskTotalBytes)}
-        />
+      {sample === null ? (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyTitle>没有运行中的容器可测</EmptyTitle>
+            <EmptyDescription>
+              沙箱现在没有活着的容器(已停止/已归档)。观察不唤醒 —
+              打开终端或执行命令才会把它叫醒。下方的历史走势还在。
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      ) : (
+        <div className="grid gap-4 sm:grid-cols-2 xl:grid-cols-3">
+          <MetricCard
+            icon={CpuIcon}
+            label="CPU"
+            value={`${Math.round(sample.cpuUsedPct)}%`}
+            hint={`${sample.cpuCount} 核 · 百分比按单核计`}
+            pct={sample.cpuUsedPct / sample.cpuCount}
+          />
+          <MetricCard
+            icon={RamMemoryIcon}
+            label="内存"
+            value={formatBytes(sample.memUsedBytes)}
+            hint={`共 ${formatBytes(sample.memTotalBytes)} · 缓存 ${formatBytes(sample.memCacheBytes)}`}
+            pct={pctOf(sample.memUsedBytes, sample.memTotalBytes)}
+          />
+          <MetricCard
+            icon={HardDriveIcon}
+            label="磁盘"
+            value={formatBytes(sample.diskUsedBytes)}
+            hint={`名义 ${formatBytes(sample.diskTotalBytes)} — 稀疏镜像只为真实内容付费`}
+            pct={pctOf(sample.diskUsedBytes, sample.diskTotalBytes)}
+          />
+        </div>
+      )}
+
+      <div className="flex items-center justify-between gap-3">
+        <div className="text-sm font-medium">历史走势</div>
+        <ToggleGroup
+          value={[range]}
+          onValueChange={(value: unknown[]) => {
+            // base-ui 允许再点一下取消选中(空数组)— 档位必须常有,忽略。
+            const next = value[0];
+            if (typeof next === 'string') setRange(next as HistoryRangeKey);
+          }}
+          variant="outline"
+          size="sm"
+        >
+          {HISTORY_RANGES.map((r) => (
+            <ToggleGroupItem key={r.key} value={r.key}>
+              {r.label}
+            </ToggleGroupItem>
+          ))}
+        </ToggleGroup>
       </div>
-      {history.length >= 2 && (
+
+      {history.isError ? (
+        <Alert variant="destructive">
+          <AlertDescription>{history.error.message}</AlertDescription>
+        </Alert>
+      ) : samples.length < 2 ? (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyTitle>窗口内还没有走势可画</EmptyTitle>
+            <EmptyDescription>
+              daemon 每 30 秒采一次样,攒够两个点就开始画;沙箱停着或 daemon
+              停机的时段没有样本,曲线会如实断开。
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      ) : (
         <div className="grid gap-4 xl:grid-cols-3">
           <HistoryChart
             title="CPU 走势"
-            data={history.map((s) => ({
-              at: Date.parse(s.timestamp),
-              value: Math.round(s.cpuUsedPct),
-            }))}
+            data={toSeries(
+              samples,
+              (s) => Math.round(s.cpuUsedPct),
+              bucketSeconds,
+            )}
+            xTickFormatter={clockFor(range)}
             tickFormatter={(v) => `${v}%`}
             valueFormatter={(v) => `${v}%(按单核计)`}
           />
           <HistoryChart
             title="内存走势"
-            data={history.map((s) => ({
-              at: Date.parse(s.timestamp),
-              value: s.memUsedBytes,
-            }))}
+            data={toSeries(samples, (s) => s.memUsedBytes, bucketSeconds)}
+            xTickFormatter={clockFor(range)}
             tickFormatter={(v) => formatBytes(v)}
             valueFormatter={(v) => formatBytes(v)}
-            domainMax={sample.memTotalBytes}
+            domainMax={lastSample?.memTotalBytes}
           />
           <HistoryChart
             title="磁盘走势"
-            data={history.map((s) => ({
-              at: Date.parse(s.timestamp),
-              value: s.diskUsedBytes,
-            }))}
+            data={toSeries(samples, (s) => s.diskUsedBytes, bucketSeconds)}
+            xTickFormatter={clockFor(range)}
             tickFormatter={(v) => formatBytes(v)}
             valueFormatter={(v) => formatBytes(v)}
           />
         </div>
       )}
+
       <p className="text-xs text-muted-foreground">
-        单次快照,5 秒刷新;本次读数取自 {since(sample.timestamp)}前。
-        {history.length >= 2 &&
-          `走势为本面板打开以来的采样(最多约 ${Math.round((HISTORY_CAP * 5) / 60)} 分钟),daemon 不存历史。`}
+        {sample !== null &&
+          `当前值 5 秒刷新,本次读数取自 ${since(sample.timestamp)}前。`}
+        历史由 daemon
+        后台采样落库;沙箱睡着照样测(观察不唤醒),停止后曲线如实断流。
+        {bucketSeconds !== null &&
+          `窗口较长,已按每 ${Math.round(bucketSeconds / 60)} 分钟一桶聚合,每点为桶内峰值。`}
       </p>
     </div>
   );
diff --git a/packages/console/src/features/sandboxes/format.ts b/packages/console/src/features/sandboxes/format.ts
index 065bdee..0776666 100644
--- a/packages/console/src/features/sandboxes/format.ts
+++ b/packages/console/src/features/sandboxes/format.ts
@@ -9,6 +9,36 @@ export const STATE_LABELS: Record<SandboxState, string> = {
   restoring: '恢复中',
 };
 
+/**
+ * 五态的颜色,单一来源:dot 是文字旁小圆点的 tailwind 类,chart 是
+ * 堆叠面积图的填充色(明暗两面各自过了 dataviz 验证器:亮面 600 级、
+ * 暗面紫色升回 500——相邻对 CVD 分离与 3:1 对比度全过)。stopped 刻意
+ * 是灰:熄灭态读作灰正是它的含义,身份另由图例、tooltip 与固定堆叠位
+ * 承载。色相与 SandboxStateBadge 同族,整站读作一套系统。
+ */
+export const STATE_COLORS: Record<
+  SandboxState,
+  { dot: string; chart: { light: string; dark: string } }
+> = {
+  active: {
+    dot: 'bg-emerald-500',
+    chart: { light: '#059669', dark: '#059669' },
+  },
+  frozen: { dot: 'bg-sky-500', chart: { light: '#0284c7', dark: '#0284c7' } },
+  stopped: {
+    dot: 'bg-muted-foreground/50',
+    chart: { light: '#64748b', dark: '#64748b' },
+  },
+  archived: {
+    dot: 'bg-violet-500',
+    chart: { light: '#7c3aed', dark: '#8b5cf6' },
+  },
+  restoring: {
+    dot: 'bg-amber-500',
+    chart: { light: '#d97706', dark: '#d97706' },
+  },
+};
+
 /** 时长的中文写法:45秒 / 5分12秒 / 3小时20分 / 2天4小时,最多两段。 */
 export function formatDuration(totalSeconds: number): string {
   const s = Math.max(0, Math.floor(totalSeconds));
diff --git a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
index a7b4ddd..7c15fb2 100644
--- a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
+++ b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
@@ -4,6 +4,7 @@ import {
   acquireSandbox,
   destroySandbox,
   getSandboxMetrics,
+  getSandboxMetricsHistory,
   listSandboxes,
   listSandboxImages,
   listSandboxMetrics,
@@ -49,6 +50,27 @@ export function useSandboxMetrics(externalId: string) {
   });
 }
 
+/**
+ * 单沙箱指标历史,30 秒一刷 — 与 daemon 采样间隔同步,更快只是重复读到
+ * 同一批样本。窗口每次 queryFn 现算,长开的面板窗口随时间滑动;历史键
+ * 在 sandboxId 上,换壳(rebuild)不断线。
+ */
+export function useSandboxMetricsHistory(externalId: string, spanMs: number) {
+  return useQuery({
+    queryKey: ['sandbox-metrics-history', externalId, spanMs],
+    queryFn: () => {
+      const end = Date.now();
+      return getSandboxMetricsHistory(
+        externalId,
+        new Date(end - spanMs).toISOString(),
+        new Date(end).toISOString(),
+      );
+    },
+    refetchInterval: 30_000,
+    retry: false,
+  });
+}
+
 /**
  * 全部可测沙箱的资源快照,一个请求管一整张表(逐行发 getSandboxMetrics
  * 是 N 倍浪费)。答案里没出现 = 没有容器可测(停止/归档),不是 0。
diff --git a/packages/console/src/features/settings/pages/SettingsPage.tsx b/packages/console/src/features/settings/pages/SettingsPage.tsx
index 228d1ff..2a047bb 100644
--- a/packages/console/src/features/settings/pages/SettingsPage.tsx
+++ b/packages/console/src/features/settings/pages/SettingsPage.tsx
@@ -34,6 +34,10 @@ const KEY_HINTS: Record<string, string> = {
   DORMICE_DATA_DIR: '沙箱磁盘镜像的家(disks/*.img);归档临时文件也在这里',
   DORMICE_MAX_SANDBOXES: '创建上限(撞上回 429);唤醒永不受限 — 磁盘才是真瓶颈',
   DORMICE_SCAN_INTERVAL_SECONDS: '空闲扫描周期:每一轮把到阈值的沙箱降一格温度',
+  DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS:
+    '指标采样周期:历史曲线的分辨率,总览走势与指标历史都按它落库',
+  DORMICE_METRICS_RETENTION_HOURS:
+    '逐沙箱指标样本的保留时长;舰队状态计数恒保 30 天,不随它走',
   DORMICE_SANDBOX_DISK_GB: '每个沙箱磁盘的名义大小;稀疏镜像只为真实内容付费',
   DORMICE_SANDBOX_CPUS: '每个沙箱的 CPU 配额',
   DORMICE_SANDBOX_MEMORY_GB:
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 9607d40..6b574b5 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -4,7 +4,9 @@ import type {
   ApplyUpgradeResponse,
   CheckUpgradeResponse,
   GetConfigResponse,
+  GetFleetTimelineResponse,
   GetIngressResponse,
+  GetSandboxMetricsHistoryResponse,
   GetSandboxMetricsResponse,
   GetUpgradeStatusResponse,
   HostMetricsResponse,
@@ -127,6 +129,26 @@ export const getSandboxMetrics = (externalId: string) =>
 export const listSandboxMetrics = () =>
   rpc<ListSandboxMetricsResponse>('/listSandboxMetrics');
 
+// One sandbox's sampled past, sliced by an ISO window. Past 360 points the
+// daemon buckets the answer (per-field maxima — spikes survive); a window
+// the daemon was down for shows the gap, never an interpolation.
+export const getSandboxMetricsHistory = (
+  externalId: string,
+  start: string,
+  end: string,
+) =>
+  rpc<GetSandboxMetricsHistoryResponse>('/getSandboxMetricsHistory', {
+    externalId,
+    start,
+    end,
+  });
+
+// Fleet state counts over time — the concurrency curve's data. Bucketed
+// points are whole raw snapshots (byState always sums to total); peak is
+// computed from raw rows and immune to bucketing.
+export const getFleetTimeline = (start: string, end: string) =>
+  rpc<GetFleetTimelineResponse>('/getFleetTimeline', { start, end });
+
 // Every sandbox's image lineage: the born image of the current shell (null
 // when no shell exists), the image the next shell would boot, and whether a
 // rebuild would change anything — the window answering "who still runs an
diff --git a/packages/server/drizzle/0007_metrics-history.sql b/packages/server/drizzle/0007_metrics-history.sql
new file mode 100644
index 0000000..23b2c1d
--- /dev/null
+++ b/packages/server/drizzle/0007_metrics-history.sql
@@ -0,0 +1,24 @@
+CREATE TABLE `fleet_snapshots` (
+	`at` text PRIMARY KEY NOT NULL,
+	`active` integer NOT NULL,
+	`frozen` integer NOT NULL,
+	`stopped` integer NOT NULL,
+	`archived` integer NOT NULL,
+	`restoring` integer NOT NULL,
+	`total` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `sandbox_metrics_samples` (
+	`sandbox_id` text NOT NULL,
+	`at` text NOT NULL,
+	`cpu_count` real NOT NULL,
+	`cpu_used_pct` real NOT NULL,
+	`mem_used_bytes` integer NOT NULL,
+	`mem_total_bytes` integer NOT NULL,
+	`mem_cache_bytes` integer NOT NULL,
+	`disk_used_bytes` integer NOT NULL,
+	`disk_total_bytes` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `sandbox_metrics_samples_sandbox_at_idx` ON `sandbox_metrics_samples` (`sandbox_id`,`at`);--> statement-breakpoint
+CREATE INDEX `sandbox_metrics_samples_at_idx` ON `sandbox_metrics_samples` (`at`);
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/0007_snapshot.json b/packages/server/drizzle/meta/0007_snapshot.json
new file mode 100644
index 0000000..9f42ce8
--- /dev/null
+++ b/packages/server/drizzle/meta/0007_snapshot.json
@@ -0,0 +1,425 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "6e4558a9-bd0e-4071-b93c-d45bfd1de122",
+  "prevId": "d0819d46-b25a-4912-9417-22b2cf192b7c",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_id": {
+          "name": "external_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "fleet_snapshots": {
+      "name": "fleet_snapshots",
+      "columns": {
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active": {
+          "name": "active",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "frozen": {
+          "name": "frozen",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stopped": {
+          "name": "stopped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archived": {
+          "name": "archived",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "restoring": {
+          "name": "restoring",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "total": {
+          "name": "total",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandbox_metrics_samples": {
+      "name": "sandbox_metrics_samples",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_count": {
+          "name": "cpu_count",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_used_pct": {
+          "name": "cpu_used_pct",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_used_bytes": {
+          "name": "mem_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_total_bytes": {
+          "name": "mem_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_cache_bytes": {
+          "name": "mem_cache_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_used_bytes": {
+          "name": "disk_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_total_bytes": {
+          "name": "disk_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "sandbox_metrics_samples_sandbox_at_idx": {
+          "name": "sandbox_metrics_samples_sandbox_at_idx",
+          "columns": [
+            "sandbox_id",
+            "at"
+          ],
+          "isUnique": false
+        },
+        "sandbox_metrics_samples_at_idx": {
+          "name": "sandbox_metrics_samples_at_idx",
+          "columns": [
+            "at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_id": {
+          "name": "external_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_external_id_unique": {
+          "name": "sandboxes_external_id_unique",
+          "columns": [
+            "external_id"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/src/config.test.ts b/packages/server/src/config.test.ts
index c35a15d..66576ab 100644
--- a/packages/server/src/config.test.ts
+++ b/packages/server/src/config.test.ts
@@ -56,6 +56,27 @@ describe('loadConfig executor knobs', () => {
   });
 });
 
+describe('the metrics sampler knobs', () => {
+  it('defaults: 30s interval, 168h retention', () => {
+    const config = loadConfig(TOKEN);
+    expect(config.DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS).toBe(30);
+    expect(config.DORMICE_METRICS_RETENTION_HOURS).toBe(168);
+  });
+
+  it('parses overrides and rejects a non-positive interval', () => {
+    const config = loadConfig({
+      ...TOKEN,
+      DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS: '5',
+      DORMICE_METRICS_RETENTION_HOURS: '24',
+    });
+    expect(config.DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS).toBe(5);
+    expect(config.DORMICE_METRICS_RETENTION_HOURS).toBe(24);
+    expect(() =>
+      loadConfig({ ...TOKEN, DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS: '0' }),
+    ).toThrow();
+  });
+});
+
 describe('the S3 set', () => {
   const S3 = {
     DORMICE_S3_ENDPOINT: 'http://127.0.0.1:9000',
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index 125443c..22f54c8 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -19,6 +19,27 @@ const envSchema = z.object({
   DORMICE_NODE_ID: z.string().default('node-1'),
   /** How often the idle scanner sweeps the ledger. */
   DORMICE_SCAN_INTERVAL_SECONDS: z.coerce.number().int().positive().default(60),
+  /**
+   * How often the metrics sampler persists a reading per measurable sandbox
+   * plus one fleet state-count row — the resolution of every history curve.
+   */
+  DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS: z.coerce
+    .number()
+    .int()
+    .positive()
+    .default(30),
+  /**
+   * How long per-sandbox samples live (fleet rows are fixed at 30 days —
+   * FLEET_SNAPSHOT_KEEP_DAYS). A knob because volume scales with the fleet:
+   * at the 30s default, a worst-case 100 always-hot sandboxes over the
+   * default 7 days is ~2M rows — fine for SQLite, but the operator of such
+   * a box may want to trade history depth for disk.
+   */
+  DORMICE_METRICS_RETENTION_HOURS: z.coerce
+    .number()
+    .int()
+    .positive()
+    .default(168),
   /**
    * How many sandboxes may exist at once. The binding resource is disk:
    * every sandbox holds a disk image, and an unbounded acquire loop fills
@@ -194,6 +215,8 @@ export const CONFIG_KEYS: Record<keyof Config, { sensitive: boolean }> = {
   DORMICE_DATA_DIR: { sensitive: false },
   DORMICE_MAX_SANDBOXES: { sensitive: false },
   DORMICE_SCAN_INTERVAL_SECONDS: { sensitive: false },
+  DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS: { sensitive: false },
+  DORMICE_METRICS_RETENTION_HOURS: { sensitive: false },
   DORMICE_SANDBOX_DISK_GB: { sensitive: false },
   DORMICE_SANDBOX_CPUS: { sensitive: false },
   DORMICE_SANDBOX_MEMORY_GB: { sensitive: false },
diff --git a/packages/server/src/db/metrics.ts b/packages/server/src/db/metrics.ts
new file mode 100644
index 0000000..0f005ce
--- /dev/null
+++ b/packages/server/src/db/metrics.ts
@@ -0,0 +1,258 @@
+import { and, asc, desc, eq, gte, inArray, lt, lte } from 'drizzle-orm';
+import type { SandboxMetrics } from '../executor/executor';
+import type { Db } from './db';
+import {
+  type FleetSnapshotRow,
+  fleetSnapshots,
+  type SandboxMetricsSampleRow,
+  sandboxes,
+  sandboxMetricsSamples,
+} from './schema';
+
+/**
+ * How long fleet snapshots live. Not a knob: the dashboard's widest range
+ * (30 days) defines the need, and at one small row per tick the table stays
+ * a few megabytes — nobody sizes an explanation window (ACTIVITY_KEEP's
+ * reasoning). Per-sandbox samples DO get a knob
+ * (DORMICE_METRICS_RETENTION_HOURS): their volume scales with fleet size.
+ */
+export const FLEET_SNAPSHOT_KEEP_DAYS = 30;
+
+/**
+ * The most points a history answer carries. One ceiling for every consumer
+ * (native verbs and the E2B slice alike): past it the server buckets, so a
+ * 30-day window costs ~360 points on the wire instead of 86k raw rows no
+ * chart could draw anyway.
+ */
+export const MAX_POINTS = 360;
+
+export interface FleetCounts {
+  active: number;
+  frozen: number;
+  stopped: number;
+  archived: number;
+  restoring: number;
+  total: number;
+}
+
+export interface MetricsTickInput {
+  /** ISO 8601 UTC — the tick's single timestamp, shared by every row. */
+  at: string;
+  fleetCounts: FleetCounts;
+  samples: Array<{ sandboxId: string; metrics: SandboxMetrics }>;
+  retentionHours: number;
+}
+
+/**
+ * Writes one sampler tick — fleet snapshot, per-sandbox samples, and both
+ * retention prunes — in a single synchronous transaction: a tick's data is
+ * either fully visible or not at all. Sampling (async, ~1s per container)
+ * happened before this call; better-sqlite3 transactions cannot span an
+ * await, so "collect first, write once" is not a choice but a law.
+ *
+ * Samples are re-filtered against the ledger inside the transaction: a
+ * sandbox destroyed while its reading was in flight must not leave orphan
+ * history rows behind.
+ */
+export function insertMetricsTick(db: Db, input: MetricsTickInput): void {
+  const sampleCutoff = new Date(
+    Date.parse(input.at) - input.retentionHours * 3600_000,
+  ).toISOString();
+  const fleetCutoff = new Date(
+    Date.parse(input.at) - FLEET_SNAPSHOT_KEEP_DAYS * 86_400_000,
+  ).toISOString();
+
+  db.transaction((tx) => {
+    tx.insert(fleetSnapshots)
+      .values({ at: input.at, ...input.fleetCounts })
+      .run();
+
+    if (input.samples.length > 0) {
+      const liveIds = new Set(
+        tx
+          .select({ sandboxId: sandboxes.sandboxId })
+          .from(sandboxes)
+          .where(
+            inArray(
+              sandboxes.sandboxId,
+              input.samples.map((s) => s.sandboxId),
+            ),
+          )
+          .all()
+          .map((r) => r.sandboxId),
+      );
+      const rows = input.samples
+        .filter((s) => liveIds.has(s.sandboxId))
+        .map((s) => ({ sandboxId: s.sandboxId, at: input.at, ...s.metrics }));
+      if (rows.length > 0) {
+        tx.insert(sandboxMetricsSamples).values(rows).run();
+      }
+    }
+
+    tx.delete(sandboxMetricsSamples)
+      .where(lt(sandboxMetricsSamples.at, sampleCutoff))
+      .run();
+    tx.delete(fleetSnapshots).where(lt(fleetSnapshots.at, fleetCutoff)).run();
+  });
+}
+
+/**
+ * The destroy cascade: a sandbox whose disk is gone has no owner for its
+ * history. Fleet snapshots are untouched — they belong to no sandbox.
+ */
+export function deleteSandboxMetricsSamples(db: Db, sandboxId: string): void {
+  db.delete(sandboxMetricsSamples)
+    .where(eq(sandboxMetricsSamples.sandboxId, sandboxId))
+    .run();
+}
+
+/** Ascending slice — ISO strings compare lexicographically as time. */
+export function querySandboxSamples(
+  db: Db,
+  sandboxId: string,
+  startIso: string,
+  endIso: string,
+): SandboxMetricsSampleRow[] {
+  return db
+    .select()
+    .from(sandboxMetricsSamples)
+    .where(
+      and(
+        eq(sandboxMetricsSamples.sandboxId, sandboxId),
+        gte(sandboxMetricsSamples.at, startIso),
+        lte(sandboxMetricsSamples.at, endIso),
+      ),
+    )
+    .orderBy(asc(sandboxMetricsSamples.at))
+    .all();
+}
+
+/** Ascending slice of fleet snapshots. */
+export function queryFleetSnapshots(
+  db: Db,
+  startIso: string,
+  endIso: string,
+): FleetSnapshotRow[] {
+  return db
+    .select()
+    .from(fleetSnapshots)
+    .where(
+      and(gte(fleetSnapshots.at, startIso), lte(fleetSnapshots.at, endIso)),
+    )
+    .orderBy(asc(fleetSnapshots.at))
+    .all();
+}
+
+/**
+ * The window's concurrency peak, from raw rows so no bucketing can flatten
+ * it: highest active count, and the earliest instant it was observed.
+ */
+export function queryFleetPeak(
+  db: Db,
+  startIso: string,
+  endIso: string,
+): { active: number; at: string } | null {
+  const row = db
+    .select({ active: fleetSnapshots.active, at: fleetSnapshots.at })
+    .from(fleetSnapshots)
+    .where(
+      and(gte(fleetSnapshots.at, startIso), lte(fleetSnapshots.at, endIso)),
+    )
+    .orderBy(desc(fleetSnapshots.active), asc(fleetSnapshots.at))
+    .limit(1)
+    .get();
+  return row ?? null;
+}
+
+/**
+ * Resolves a history verb's optional ISO window: end defaults to now, start
+ * to end minus the verb's default span. One resolver for both verbs so
+ * "defaults" cannot drift apart. Parseability is the request schema's job
+ * (a malformed timestamp is rejected as a 400 at the door, never NaN here).
+ */
+export function resolveWindow(
+  start: string | undefined,
+  end: string | undefined,
+  defaultSpanMs: number,
+  now: Date,
+): { startIso: string; endIso: string; startMs: number; endMs: number } {
+  const endMs = end !== undefined ? Date.parse(end) : now.getTime();
+  const startMs =
+    start !== undefined ? Date.parse(start) : endMs - defaultSpanMs;
+  return {
+    startIso: new Date(startMs).toISOString(),
+    endIso: new Date(endMs).toISOString(),
+    startMs,
+    endMs,
+  };
+}
+
+/**
+ * Decides the answer's granularity: raw under MAX_POINTS, bucketed past it.
+ * The server picks — one ruling for every caller, clients never negotiate.
+ */
+export function resolveBucketSeconds(
+  rawCount: number,
+  startMs: number,
+  endMs: number,
+): number | null {
+  if (rawCount <= MAX_POINTS) return null;
+  return Math.max(1, Math.ceil((endMs - startMs) / 1000 / MAX_POINTS));
+}
+
+function bucketIndex(atIso: string, startMs: number, bucketSeconds: number) {
+  return Math.floor((Date.parse(atIso) - startMs) / (bucketSeconds * 1000));
+}
+
+/**
+ * Buckets per-sandbox samples by per-field max: someone reading history is
+ * hunting for spikes, and averaging erases exactly what they came for. Each
+ * metric is charted alone (never sharing an axis), so an independent
+ * per-field envelope is honest within every chart. The bucket's timestamp
+ * is its start — a synthetic instant, which callers' copy must say.
+ */
+export function bucketSamples(
+  rows: SandboxMetricsSampleRow[],
+  startMs: number,
+  bucketSeconds: number,
+): SandboxMetricsSampleRow[] {
+  const buckets = new Map<number, SandboxMetricsSampleRow>();
+  for (const row of rows) {
+    const idx = bucketIndex(row.at, startMs, bucketSeconds);
+    const seen = buckets.get(idx);
+    if (!seen) {
+      buckets.set(idx, {
+        ...row,
+        at: new Date(startMs + idx * bucketSeconds * 1000).toISOString(),
+      });
+      continue;
+    }
+    seen.cpuCount = Math.max(seen.cpuCount, row.cpuCount);
+    seen.cpuUsedPct = Math.max(seen.cpuUsedPct, row.cpuUsedPct);
+    seen.memUsedBytes = Math.max(seen.memUsedBytes, row.memUsedBytes);
+    seen.memTotalBytes = Math.max(seen.memTotalBytes, row.memTotalBytes);
+    seen.memCacheBytes = Math.max(seen.memCacheBytes, row.memCacheBytes);
+    seen.diskUsedBytes = Math.max(seen.diskUsedBytes, row.diskUsedBytes);
+    seen.diskTotalBytes = Math.max(seen.diskTotalBytes, row.diskTotalBytes);
+  }
+  return [...buckets.entries()].sort(([a], [b]) => a - b).map(([, row]) => row);
+}
+
+/**
+ * Buckets fleet snapshots by keeping each bucket's LAST raw row whole —
+ * never per-state maxima, which would count a sandbox mid-transition twice
+ * and break byState summing to total. Every emitted point is a snapshot
+ * that really happened; the peak travels separately (queryFleetPeak).
+ */
+export function bucketSnapshots(
+  rows: FleetSnapshotRow[],
+  startMs: number,
+  bucketSeconds: number,
+): FleetSnapshotRow[] {
+  const buckets = new Map<number, FleetSnapshotRow>();
+  for (const row of rows) {
+    // Rows arrive ascending, so a later row simply overwrites the bucket.
+    buckets.set(bucketIndex(row.at, startMs, bucketSeconds), row);
+  }
+  return [...buckets.entries()].sort(([a], [b]) => a - b).map(([, row]) => row);
+}
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index 17ce4d0..3922541 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -1,5 +1,11 @@
 import { ACTIVITY_KINDS, SANDBOX_STATES } from '@dormice/shared';
-import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import {
+  index,
+  integer,
+  real,
+  sqliteTable,
+  text,
+} from 'drizzle-orm/sqlite-core';
 
 /**
  * The ledger. SQLite is the ledger, Docker is reality, and the daemon's core
@@ -30,12 +36,16 @@ export const sandboxes = sqliteTable('sandboxes', {
   template: text('template'),
   createdAt: text('created_at').notNull(),
   lastActiveAt: text('last_active_at').notNull(),
+  /**
+   * JSON object of caller labels (string→string), NULL = none. Written by
+   * both faces — native acquire/updateMetadata and E2B create — filtered on
+   * by the E2B list and echoed everywhere a sandbox view is.
+   */
+  metadata: text('metadata'),
   /**
    * The E2B surface's columns. All NULL / defaulted for natively-acquired
    * sandboxes — the native lifecycle never reads them.
    */
-  /** JSON object; E2B metadata, persisted for list filtering and echo. */
-  metadata: text('metadata'),
   /** JSON object; sandbox-level default envs, merged under per-command envs. */
   envs: text('envs'),
   /** ISO 8601; the E2B timeout's absolute deadline. NULL = no deadline. */
@@ -89,6 +99,75 @@ export const activity = sqliteTable('activity', {
 
 export type ActivityRow = typeof activity.$inferSelect;
 
+/**
+ * Per-sandbox metrics history, written by the background sampler every
+ * DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS for each measurable (running or
+ * paused) sandbox. The daemon keeps this history because it is a
+ * compatibility contract — the E2B metrics endpoint slices by start/end —
+ * and because nothing outside the ledger can measure per-sandbox; host
+ * trends still belong to Prometheus.
+ *
+ * Two tables, not one: this and fleet_snapshots differ in unit of meaning
+ * (one sandbox's resources vs the whole fleet's state counts), retention
+ * (DORMICE_METRICS_RETENTION_HOURS vs a fixed 30 days) and deletion path
+ * (destroy cascades here, never there).
+ *
+ * Keyed by sandboxId, not externalId: rebuild replaces the shell but keeps
+ * the sandboxId, so history stays continuous across rebuilds; destroy
+ * deletes by the same key. No autoincrement id — rows have no "Nth entry"
+ * meaning (unlike the activity ring, where id IS the ring position).
+ */
+export const sandboxMetricsSamples = sqliteTable(
+  'sandbox_metrics_samples',
+  {
+    sandboxId: text('sandbox_id').notNull(),
+    /** ISO 8601 UTC. */
+    at: text('at').notNull(),
+    cpuCount: real('cpu_count').notNull(),
+    cpuUsedPct: real('cpu_used_pct').notNull(),
+    memUsedBytes: integer('mem_used_bytes').notNull(),
+    memTotalBytes: integer('mem_total_bytes').notNull(),
+    memCacheBytes: integer('mem_cache_bytes').notNull(),
+    diskUsedBytes: integer('disk_used_bytes').notNull(),
+    diskTotalBytes: integer('disk_total_bytes').notNull(),
+  },
+  (table) => [
+    // Slice queries and the destroy cascade both hit the (sandbox, time)
+    // prefix; retention pruning walks time alone.
+    index('sandbox_metrics_samples_sandbox_at_idx').on(
+      table.sandboxId,
+      table.at,
+    ),
+    index('sandbox_metrics_samples_at_idx').on(table.at),
+  ],
+);
+
+export type SandboxMetricsSampleRow = typeof sandboxMetricsSamples.$inferSelect;
+
+/**
+ * Fleet state counts over time, one row per sampler tick: the data behind
+ * the console's concurrency curve and peak. Owned by no sandbox — destroy
+ * never touches it — and kept a fixed 30 days (the dashboard's widest
+ * range defines the need; like ACTIVITY_KEEP, nobody tunes the size of an
+ * explanation window).
+ *
+ * Five explicit state columns instead of a JSON blob: the window peak is
+ * max(active) in one SQL aggregate, and the stacked chart needs each state
+ * addressable. `total` is stored redundantly so readers never re-derive it.
+ */
+export const fleetSnapshots = sqliteTable('fleet_snapshots', {
+  /** ISO 8601 UTC; one row per tick, so time itself is the key. */
+  at: text('at').primaryKey(),
+  active: integer('active').notNull(),
+  frozen: integer('frozen').notNull(),
+  stopped: integer('stopped').notNull(),
+  archived: integer('archived').notNull(),
+  restoring: integer('restoring').notNull(),
+  total: integer('total').notNull(),
+});
+
+export type FleetSnapshotRow = typeof fleetSnapshots.$inferSelect;
+
 /**
  * The console's one human account (the fixed id makes "at most one row" a
  * schema fact, not a convention). The API token stays the root of trust:
@@ -111,3 +190,23 @@ export const consoleAccount = sqliteTable('console_account', {
 });
 
 export type ConsoleAccountRow = typeof consoleAccount.$inferSelect;
+
+/**
+ * The daemon's own secrets — one row, fixed id, same singleton pattern as
+ * console_account. envdSigningSecret is the HMAC key behind every envd
+ * access token and signed file URL. It is deliberately NOT the API token:
+ * with an independent key, rotating the token no longer voids in-flight
+ * envd tokens and signed URLs, and a future multi-key world has one answer
+ * to "which key do we derive from" — this one.
+ *
+ * Unlike sessionSecret there is no verb that regenerates it, so reading it
+ * once at startup is safe. Born lazily on first use (get-or-create), not
+ * by migration — a migration cannot mint randomness.
+ */
+export const daemonSecrets = sqliteTable('daemon_secrets', {
+  id: integer('id').primaryKey(),
+  envdSigningSecret: text('envd_signing_secret').notNull(),
+  createdAt: text('created_at').notNull(),
+});
+
+export type DaemonSecretsRow = typeof daemonSecrets.$inferSelect;
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index cb8e8fb..7893385 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -12,6 +12,12 @@ import {
   setPausedByUser,
   touch,
 } from '../db/ledger';
+import {
+  bucketSamples,
+  querySandboxSamples,
+  resolveBucketSeconds,
+  resolveWindow,
+} from '../db/metrics';
 import type { SandboxRow } from '../db/schema';
 import { findTemplate, resolveImage } from '../db/templates';
 import {
@@ -86,7 +92,15 @@ const notFound = (sandboxId: string) =>
 
 export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   app,
-  { config, db, executor, locks, archiver, archiveDefaultSeconds },
+  {
+    config,
+    db,
+    executor,
+    locks,
+    archiver,
+    archiveDefaultSeconds,
+    envdSigningSecret,
+  },
 ) => {
   /**
    * The archive detour, taken before any slot work: E2B has no restoring
@@ -174,7 +188,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       clientID: row.nodeId,
       ...templateFields(row),
       envdVersion: ENVD_VERSION,
-      envdAccessToken: mintEnvdToken(config.DORMICE_API_TOKEN, row.sandboxId),
+      envdAccessToken: mintEnvdToken(envdSigningSecret, row.sandboxId),
       ...domainField,
     };
   }
@@ -320,8 +334,11 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
           nodeId: config.DORMICE_NODE_ID,
           policy: resolvePolicy(undefined, archiveDefaultSeconds),
           template,
+          metadata:
+            body.metadata && Object.keys(body.metadata).length > 0
+              ? JSON.stringify(body.metadata)
+              : null,
           e2b: {
-            metadata: body.metadata ? JSON.stringify(body.metadata) : null,
             envs:
               body.envVars && Object.keys(body.envVars).length > 0
                 ? JSON.stringify(body.envVars)
@@ -371,23 +388,78 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     return infoView(row, state);
   });
 
-  // The SDK sends start/end (unix seconds) to slice a metrics history; we
-  // keep none — the daemon is an observation window, not a monitoring
-  // system — so the answer is always one sample, taken now. loose() admits
-  // the query without acting on it.
+  // The SDK sends start/end (unix seconds) to slice a metrics history, and
+  // since the sampler landed we have one — the slice is answered from the
+  // ledger's samples, bucketed past 360 points like the native history
+  // verb (per-field maxima; one ceiling for every consumer). Unix seconds
+  // are this surface's dialect: translated to ISO here at the boundary,
+  // never inside. loose() still admits the query fields we ignore.
+  //
+  // A sandbox created moments ago has no samples yet; when the window comes
+  // back empty and the sandbox is physically measurable, we take one live
+  // reading — real E2B answers data within seconds of creation, and an
+  // empty array would read as breakage. The native verb deliberately does
+  // NOT do this: the native face reports silence as silence, the fallback
+  // is this compatibility surface's politeness alone.
   app.get(
     '/sandboxes/:id/metrics',
-    { schema: { querystring: z.object({}).loose() } },
+    {
+      schema: {
+        querystring: z
+          .object({
+            start: z.coerce.number().int().optional(),
+            end: z.coerce.number().int().optional(),
+          })
+          .loose(),
+      },
+    },
     async (request) => {
       const { id } = request.params as { id: string };
+      const { start, end } = request.query as {
+        start?: number;
+        end?: number;
+      };
       const { row } = findLive(id);
-      // Physical stopped/archived: nothing is running to measure, and
-      // measuring must never wake a sandbox (observation is not activity —
-      // the same principle that keeps list from waking). [] is the honest
-      // answer, and a legal one to the SDK.
-      if (row.state !== 'active' && row.state !== 'frozen') return [];
-      const m = await executor.metrics(row.sandboxId);
+      const measurable = row.state === 'active' || row.state === 'frozen';
+
       const now = new Date();
+      const { startIso, endIso, startMs, endMs } = resolveWindow(
+        start === undefined ? undefined : new Date(start * 1000).toISOString(),
+        end === undefined ? undefined : new Date(end * 1000).toISOString(),
+        3600_000,
+        now,
+      );
+      const rows = querySandboxSamples(db, row.sandboxId, startIso, endIso);
+      const bucketSeconds = resolveBucketSeconds(rows.length, startMs, endMs);
+      const sliced =
+        bucketSeconds === null
+          ? rows
+          : bucketSamples(rows, startMs, bucketSeconds);
+
+      if (sliced.length > 0) {
+        return sliced.map((sample) => ({
+          timestamp: sample.at,
+          timestampUnix: Math.floor(Date.parse(sample.at) / 1000),
+          cpuCount: sample.cpuCount,
+          cpuUsedPct: sample.cpuUsedPct,
+          memUsed: sample.memUsedBytes,
+          memTotal: sample.memTotalBytes,
+          memCache: sample.memCacheBytes,
+          diskUsed: sample.diskUsedBytes,
+          diskTotal: sample.diskTotalBytes,
+        }));
+      }
+
+      // Physical stopped/archived with no history in the window: nothing is
+      // running to measure, and measuring must never wake a sandbox
+      // (observation is not activity — the same principle that keeps list
+      // from waking). [] is the honest answer, and a legal one to the SDK.
+      // The live fallback also only applies when the window reaches "now" —
+      // a reading taken now must not answer for an explicitly past window.
+      const windowIncludesNow =
+        now.getTime() >= startMs && now.getTime() <= endMs;
+      if (!measurable || !windowIncludesNow) return [];
+      const m = await executor.metrics(row.sandboxId);
       return [
         {
           timestamp: now.toISOString(),
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index 94985b6..f7f7e80 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -13,5 +13,6 @@ export {
 export type { ContainerState, Executor } from './executor/executor';
 export { FakeExecutor } from './executor/fake';
 export { KeyedQueue, SKIPPED } from './keyed-queue';
+export { type SampleResult, sampleOnce } from './metrics-sampler';
 export { type ReconcileResult, reconcile } from './reconciler';
 export { type ScanResult, scanOnce } from './scanner';
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index 1c02e39..21f3454 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -7,6 +7,7 @@ import {
   setPausedByUser,
   transition,
 } from './db/ledger';
+import { deleteSandboxMetricsSamples } from './db/metrics';
 import type { SandboxRow } from './db/schema';
 import { resolveImage } from './db/templates';
 import type { Executor } from './executor/executor';
@@ -94,6 +95,9 @@ export async function destroySandbox(
     }
     await store.delete(objectKey(sandboxId));
     deleteSandbox(db, sandboxId);
+    // With the disk gone its metrics history has no owner; fleet snapshots
+    // belong to no sandbox and stay.
+    deleteSandboxMetricsSamples(db, sandboxId);
     recordActivity(db, {
       kind: activity.kind,
       externalId: row.externalId,
@@ -104,6 +108,7 @@ export async function destroySandbox(
   }
   await executor.destroy(sandboxId);
   deleteSandbox(db, sandboxId);
+  deleteSandboxMetricsSamples(db, sandboxId);
   if (row) {
     recordActivity(db, {
       kind: activity.kind,
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 7c7b831..67c5208 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -15,6 +15,7 @@ import type { Executor } from './executor/executor';
 import { FakeExecutor } from './executor/fake';
 import { Ingress } from './ingress';
 import { KeyedQueue } from './keyed-queue';
+import { sampleOnce } from './metrics-sampler';
 import { reconcile } from './reconciler';
 import { scanOnce } from './scanner';
 import { locallyClaimedCount, startupGuard } from './startup-guard';
@@ -229,3 +230,25 @@ async function tick() {
   }
 }
 setTimeout(tick, config.DORMICE_SCAN_INTERVAL_SECONDS * 1000);
+
+// The metrics sampler's own chained ticker — deliberately not a passenger
+// on the heartbeat, whose ticks legitimately run 45s+ (memory.reclaim) and
+// would turn the sampling cadence into jitter. The first shot fires
+// immediately: a restart's gap in the curves should equal the downtime, not
+// downtime plus one interval. Same failure stance as the heartbeat: log,
+// never fatal, next tick retries.
+async function metricsTick() {
+  try {
+    await sampleOnce(db, executor, new Date(), {
+      retentionHours: config.DORMICE_METRICS_RETENTION_HOURS,
+    });
+  } catch (error) {
+    app.log.error(error, 'metrics sampler tick failed');
+  } finally {
+    setTimeout(
+      metricsTick,
+      config.DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS * 1000,
+    );
+  }
+}
+setTimeout(metricsTick, 0);
diff --git a/packages/server/src/metrics-sampler.test.ts b/packages/server/src/metrics-sampler.test.ts
new file mode 100644
index 0000000..68154ba
--- /dev/null
+++ b/packages/server/src/metrics-sampler.test.ts
@@ -0,0 +1,216 @@
+import { fileURLToPath } from 'node:url';
+import { count } from 'drizzle-orm';
+import { describe, expect, it } from 'vitest';
+import { buildApp } from './app';
+import { CONFIG_KEYS, type ConfigSources, loadConfig } from './config';
+import { migrateDb, openDb } from './db/db';
+import { FLEET_SNAPSHOT_KEEP_DAYS, insertMetricsTick } from './db/metrics';
+import { fleetSnapshots, sandboxMetricsSamples } from './db/schema';
+import { FakeExecutor } from './executor/fake';
+import { KeyedQueue } from './keyed-queue';
+import { freezeSandbox, stopSandbox } from './lifecycle';
+import { sampleOnce } from './metrics-sampler';
+
+// The sampler, unit-level: one tick's writes, the measurable-states gate,
+// the vanished-container skip, retention pruning and the destroy cascade.
+// Time is injected (`now`), never slept on — the scanner's rule.
+
+const MIGRATIONS = fileURLToPath(new URL('../drizzle', import.meta.url));
+const TOKEN = 'test-token-test-token-test-token';
+const authed = { authorization: `Bearer ${TOKEN}` };
+
+function fixedSources(): ConfigSources {
+  const all = Object.fromEntries(
+    Object.keys(CONFIG_KEYS).map((key) => [key, 'default']),
+  ) as ConfigSources;
+  return { ...all, DORMICE_API_TOKEN: 'env' };
+}
+
+function harness() {
+  const db = openDb(':memory:');
+  migrateDb(db, MIGRATIONS);
+  const config = loadConfig({
+    DORMICE_DB_PATH: ':memory:',
+    DORMICE_API_TOKEN: TOKEN,
+  });
+  const executor = new FakeExecutor();
+  const locks = new KeyedQueue();
+  const app = buildApp({
+    config,
+    db,
+    executor,
+    locks,
+    logger: false,
+    sources: fixedSources(),
+  });
+  return { app, db, executor, locks };
+}
+
+type App = ReturnType<typeof harness>['app'];
+
+async function acquire(app: App, externalId: string) {
+  const res = await app.inject({
+    method: 'POST',
+    url: '/acquireSandbox',
+    headers: authed,
+    payload: { externalId },
+  });
+  expect(res.statusCode).toBe(200);
+  return res.json().sandbox as { sandboxId: string };
+}
+
+function sampleRows(db: ReturnType<typeof harness>['db']) {
+  return db.select().from(sandboxMetricsSamples).all();
+}
+
+function fleetRows(db: ReturnType<typeof harness>['db']) {
+  return db.select().from(fleetSnapshots).all();
+}
+
+describe('sampleOnce', () => {
+  it('writes one fleet row and one sample per measurable sandbox', async () => {
+    const { app, db, executor } = harness();
+    await acquire(app, 'hot');
+    const napping = await acquire(app, 'napping');
+    await freezeSandbox(db, executor, napping.sandboxId);
+    const cold = await acquire(app, 'cold');
+    await freezeSandbox(db, executor, cold.sandboxId);
+    await stopSandbox(db, executor, cold.sandboxId);
+
+    const now = new Date('2026-07-15T10:00:00.000Z');
+    const result = await sampleOnce(db, executor, now, { retentionHours: 168 });
+
+    // Active and frozen are measured; stopped has no container and is not.
+    expect(result).toEqual({ sampled: 2, skipped: 0 });
+    const fleet = fleetRows(db);
+    expect(fleet).toEqual([
+      {
+        at: now.toISOString(),
+        active: 1,
+        frozen: 1,
+        stopped: 1,
+        archived: 0,
+        restoring: 0,
+        total: 3,
+      },
+    ]);
+    const samples = sampleRows(db);
+    expect(samples).toHaveLength(2);
+    for (const row of samples) {
+      expect(row.at).toBe(now.toISOString());
+      expect(row.memTotalBytes).toBeGreaterThan(0);
+    }
+    // Observation is not activity: the frozen sandbox is still frozen.
+    expect((await executor.listContainers()).get(napping.sandboxId)).toBe(
+      'paused',
+    );
+  });
+
+  it('skips a vanished container without failing the tick', async () => {
+    const { app, db, executor } = harness();
+    await acquire(app, 'alive');
+    const doomed = await acquire(app, 'doomed');
+    // The container dies physically, past the ledger (gVisor OOM does this
+    // for real) — the row still says active, the reading throws.
+    await executor.freeze(doomed.sandboxId);
+    await executor.stop(doomed.sandboxId);
+
+    const now = new Date('2026-07-15T10:00:00.000Z');
+    const result = await sampleOnce(db, executor, now, { retentionHours: 168 });
+    expect(result).toEqual({ sampled: 1, skipped: 1 });
+    expect(sampleRows(db)).toHaveLength(1);
+    // The fleet row still lands: state counts come from the ledger, not
+    // from what happened to be measurable.
+    expect(fleetRows(db)).toHaveLength(1);
+  });
+
+  it('prunes samples past retention and fleet rows past 30 days', async () => {
+    const { app, db, executor } = harness();
+    await acquire(app, 'steady');
+
+    const early = new Date('2026-07-01T00:00:00.000Z');
+    await sampleOnce(db, executor, early, { retentionHours: 168 });
+
+    // One retention window plus a minute later: the early sample must fall,
+    // the early fleet row (well within 30 days) must survive.
+    const later = new Date(early.getTime() + 168 * 3600_000 + 60_000);
+    await sampleOnce(db, executor, later, { retentionHours: 168 });
+    expect(sampleRows(db).map((r) => r.at)).toEqual([later.toISOString()]);
+    expect(fleetRows(db).map((r) => r.at)).toEqual([
+      early.toISOString(),
+      later.toISOString(),
+    ]);
+
+    // Past the fleet's own 30-day window the early fleet row falls too.
+    const ancientCutoff = new Date(
+      early.getTime() + (FLEET_SNAPSHOT_KEEP_DAYS * 24 + 1) * 3600_000,
+    );
+    await sampleOnce(db, executor, ancientCutoff, { retentionHours: 168 });
+    expect(fleetRows(db).map((r) => r.at)).toEqual([
+      later.toISOString(),
+      ancientCutoff.toISOString(),
+    ]);
+  });
+
+  it("destroy cascades to the sandbox's samples and nobody else's", async () => {
+    const { app, db, executor } = harness();
+    const victim = await acquire(app, 'victim');
+    await acquire(app, 'bystander');
+    await sampleOnce(db, executor, new Date('2026-07-15T10:00:00.000Z'), {
+      retentionHours: 168,
+    });
+    expect(sampleRows(db)).toHaveLength(2);
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/destroySandbox',
+      headers: authed,
+      payload: { externalId: 'victim' },
+    });
+    expect(res.statusCode).toBe(200);
+
+    const remaining = sampleRows(db);
+    expect(remaining).toHaveLength(1);
+    expect(remaining[0]?.sandboxId).not.toBe(victim.sandboxId);
+    // Fleet snapshots belong to no sandbox: untouched.
+    expect(fleetRows(db)).toHaveLength(1);
+  });
+
+  it('drops a sample whose sandbox was destroyed mid-read (no orphan rows)', () => {
+    const { db } = harness();
+    // Straight to the writer: a reading collected for a sandbox that no
+    // longer has a ledger row must be filtered inside the transaction.
+    insertMetricsTick(db, {
+      at: '2026-07-15T10:00:00.000Z',
+      fleetCounts: {
+        active: 0,
+        frozen: 0,
+        stopped: 0,
+        archived: 0,
+        restoring: 0,
+        total: 0,
+      },
+      samples: [
+        {
+          sandboxId: 'ghost',
+          metrics: {
+            cpuCount: 1,
+            cpuUsedPct: 0,
+            memUsedBytes: 1,
+            memTotalBytes: 2,
+            memCacheBytes: 0,
+            diskUsedBytes: 1,
+            diskTotalBytes: 2,
+          },
+        },
+      ],
+      retentionHours: 168,
+    });
+    const total = db
+      .select({ n: count() })
+      .from(sandboxMetricsSamples)
+      .get() as { n: number };
+    expect(total.n).toBe(0);
+    expect(fleetRows(db)).toHaveLength(1);
+  });
+});
diff --git a/packages/server/src/metrics-sampler.ts b/packages/server/src/metrics-sampler.ts
new file mode 100644
index 0000000..5863d0b
--- /dev/null
+++ b/packages/server/src/metrics-sampler.ts
@@ -0,0 +1,78 @@
+import type { Db } from './db/db';
+import { countByState, listSandboxes } from './db/ledger';
+import { insertMetricsTick } from './db/metrics';
+import type { Executor, SandboxMetrics } from './executor/executor';
+
+/**
+ * The metrics sampler: one tick reads every measurable sandbox and the
+ * fleet's state census, and persists both. This is the daemon keeping
+ * history — a reversal of the original "observation window, not a
+ * monitoring system" stance, overturned for three reasons (2026-07-15):
+ * the E2B metrics endpoint's start/end slice is a compatibility contract
+ * we were answering with a single sample; per-sandbox readings cannot be
+ * scraped from outside the ledger (host trends still belong to
+ * Prometheus); and the console was hoarding session-local history in the
+ * browser as a workaround. What did NOT reverse: observation never wakes a
+ * sandbox — executor.metrics reads running and paused containers alike and
+ * starts nothing — and a window the daemon slept through stays honestly
+ * empty.
+ *
+ * Runs on its own chained ticker, not the heartbeat's: a heartbeat tick
+ * legitimately runs 45s+ (memory.reclaim), and sampling cadence must not
+ * inherit that jitter.
+ */
+
+export interface SampleResult {
+  /** Measurable sandboxes whose reading landed in the ledger. */
+  sampled: number;
+  /** Measurable sandboxes skipped — container vanished mid-reading. */
+  skipped: number;
+}
+
+/**
+ * One sampling pass. `now` is injected so tests can travel in time instead
+ * of sleeping (the scanner's rule). Readings run in parallel — one
+ * docker-stats sample costs about a second, serial would scale the tick
+ * with the fleet — and a container that vanishes mid-reading is skipped,
+ * never invented. All rows land in a single synchronous transaction after
+ * the async reads complete (insertMetricsTick).
+ */
+export async function sampleOnce(
+  db: Db,
+  executor: Executor,
+  now: Date,
+  opts: { retentionHours: number },
+): Promise<SampleResult> {
+  const rows = listSandboxes(db);
+  const { byState, total } = countByState(rows);
+  const measurable = rows.filter(
+    (row) => row.state === 'active' || row.state === 'frozen',
+  );
+  const readings = await Promise.all(
+    measurable.map(
+      async (
+        row,
+      ): Promise<{ sandboxId: string; metrics: SandboxMetrics } | null> => {
+        try {
+          return {
+            sandboxId: row.sandboxId,
+            metrics: await executor.metrics(row.sandboxId),
+          };
+        } catch {
+          return null;
+        }
+      },
+    ),
+  );
+  const samples = readings.filter((reading) => reading !== null);
+  insertMetricsTick(db, {
+    at: now.toISOString(),
+    fleetCounts: { ...byState, total },
+    samples,
+    retentionHours: opts.retentionHours,
+  });
+  return {
+    sampled: samples.length,
+    skipped: measurable.length - samples.length,
+  };
+}
diff --git a/packages/server/src/routes/host.ts b/packages/server/src/routes/host.ts
index 7cce607..f50ec7b 100644
--- a/packages/server/src/routes/host.ts
+++ b/packages/server/src/routes/host.ts
@@ -1,9 +1,20 @@
 import os from 'node:os';
-import { hostMetricsResponseSchema, SANDBOX_STATES } from '@dormice/shared';
+import {
+  getFleetTimelineRequestSchema,
+  getFleetTimelineResponseSchema,
+  hostMetricsResponseSchema,
+} from '@dormice/shared';
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import type { Config } from '../config';
 import type { Db } from '../db/db';
-import { listSandboxes } from '../db/ledger';
+import { countByState, listSandboxes } from '../db/ledger';
+import {
+  bucketSnapshots,
+  queryFleetPeak,
+  queryFleetSnapshots,
+  resolveBucketSeconds,
+  resolveWindow,
+} from '../db/metrics';
 import type { Executor } from '../executor/executor';
 import { CpuSampler, readDiskSpace, readHostMemory } from '../host-metrics';
 
@@ -39,10 +50,7 @@ export const hostRoutes: FastifyPluginAsyncZod<HostRoutesOptions> = async (
     },
     async () => {
       const rows = listSandboxes(db);
-      const byState = Object.fromEntries(
-        SANDBOX_STATES.map((state) => [state, 0]),
-      ) as Record<(typeof SANDBOX_STATES)[number], number>;
-      for (const row of rows) byState[row.state] += 1;
+      const { byState, total } = countByState(rows);
 
       const memory = await readHostMemory();
       const dataDisk = await readDiskSpace(config.DORMICE_DATA_DIR);
@@ -56,7 +64,7 @@ export const hostRoutes: FastifyPluginAsyncZod<HostRoutesOptions> = async (
           ? { path: config.DORMICE_DATA_DIR, ...dataDisk }
           : null,
         sandboxes: {
-          total: rows.length,
+          total,
           maxSandboxes: config.DORMICE_MAX_SANDBOXES,
           byState,
         },
@@ -64,4 +72,49 @@ export const hostRoutes: FastifyPluginAsyncZod<HostRoutesOptions> = async (
       };
     },
   );
+
+  // The fleet's past: state counts per sampler tick, sliced and (past 360
+  // points) bucketed. Buckets carry whole raw snapshots — the last one in
+  // the bucket — so byState always sums to total; the concurrency peak is
+  // computed from raw rows and travels beside the points, immune to
+  // bucketing. A window the daemon slept through simply has no rows: the
+  // gap IS the answer.
+  app.post(
+    '/getFleetTimeline',
+    {
+      schema: {
+        body: getFleetTimelineRequestSchema,
+        response: { 200: getFleetTimelineResponseSchema },
+      },
+    },
+    async (request) => {
+      const { startIso, endIso, startMs, endMs } = resolveWindow(
+        request.body.start,
+        request.body.end,
+        24 * 3600_000,
+        new Date(),
+      );
+      const rows = queryFleetSnapshots(db, startIso, endIso);
+      const bucketSeconds = resolveBucketSeconds(rows.length, startMs, endMs);
+      const points =
+        bucketSeconds === null
+          ? rows
+          : bucketSnapshots(rows, startMs, bucketSeconds);
+      return {
+        points: points.map((row) => ({
+          at: row.at,
+          byState: {
+            active: row.active,
+            frozen: row.frozen,
+            stopped: row.stopped,
+            archived: row.archived,
+            restoring: row.restoring,
+          },
+          total: row.total,
+        })),
+        bucketSeconds,
+        peak: queryFleetPeak(db, startIso, endIso),
+      };
+    },
+  );
 };
diff --git a/packages/server/src/routes/observability.test.ts b/packages/server/src/routes/observability.test.ts
index 02e4005..c9fd771 100644
--- a/packages/server/src/routes/observability.test.ts
+++ b/packages/server/src/routes/observability.test.ts
@@ -6,6 +6,8 @@ import {
   type ActivityEvent,
   type ConfigEntry,
   getConfigResponseSchema,
+  getFleetTimelineResponseSchema,
+  getSandboxMetricsHistoryResponseSchema,
   getSandboxMetricsResponseSchema,
   listActivityResponseSchema,
   listSandboxImagesResponseSchema,
@@ -19,10 +21,12 @@ import { MemStore } from '../archive/mem-store';
 import { CONFIG_KEYS, type ConfigSources, loadConfig } from '../config';
 import { ACTIVITY_KEEP, recordActivity } from '../db/activity';
 import { migrateDb, openDb } from '../db/db';
+import { insertMetricsTick, MAX_POINTS } from '../db/metrics';
 import { activity } from '../db/schema';
 import { FAKE_BASE_IMAGE, FakeExecutor } from '../executor/fake';
 import { KeyedQueue } from '../keyed-queue';
 import { freezeSandbox, stopSandbox } from '../lifecycle';
+import { sampleOnce } from '../metrics-sampler';
 import { ARCHIVE_DEFAULT_SECONDS } from '../policy';
 import { reconcile } from '../reconciler';
 import { scanOnce } from '../scanner';
@@ -279,6 +283,215 @@ describe('getSandboxMetrics', () => {
   });
 });
 
+describe('getSandboxMetricsHistory', () => {
+  /** Crafted metrics; only the fields under test vary. */
+  function reading(cpuUsedPct = 10) {
+    return {
+      cpuCount: 1,
+      cpuUsedPct,
+      memUsedBytes: 64,
+      memTotalBytes: 2048,
+      memCacheBytes: 0,
+      diskUsedBytes: 10,
+      diskTotalBytes: 100,
+    };
+  }
+
+  it('404s an unknown key instead of inventing a sandbox', async () => {
+    const { app } = testApp();
+    const res = await rpc(app, '/getSandboxMetricsHistory', {
+      externalId: 'nobody',
+    });
+    expect(res.statusCode).toBe(404);
+  });
+
+  it('answers an empty window honestly — never a live fallback', async () => {
+    const { app } = testApp();
+    await rpc(app, '/acquireSandbox', { externalId: 'fresh' });
+    // The sandbox is running and measurable, but the sampler never ticked:
+    // the native face reports silence as silence (the E2B face is the one
+    // that takes a live reading, as compatibility politeness).
+    const res = await rpc(app, '/getSandboxMetricsHistory', {
+      externalId: 'fresh',
+    });
+    expect(res.statusCode).toBe(200);
+    const body = getSandboxMetricsHistoryResponseSchema.parse(res.json());
+    expect(body).toEqual({ samples: [], bucketSeconds: null });
+  });
+
+  it('rejects an unparseable timestamp at the door', async () => {
+    const { app } = testApp();
+    await rpc(app, '/acquireSandbox', { externalId: 'strict' });
+    const res = await rpc(app, '/getSandboxMetricsHistory', {
+      externalId: 'strict',
+      start: 'yesterday-ish',
+    });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('slices by start/end, ascending', async () => {
+    const { app, db, executor } = testApp();
+    await rpc(app, '/acquireSandbox', { externalId: 'sliced' });
+    const t0 = Date.parse('2026-07-15T10:00:00.000Z');
+    for (let i = 0; i < 3; i += 1) {
+      await sampleOnce(db, executor, new Date(t0 + i * 30_000), {
+        retentionHours: 168,
+      });
+    }
+    const res = await rpc(app, '/getSandboxMetricsHistory', {
+      externalId: 'sliced',
+      start: new Date(t0 + 15_000).toISOString(),
+      end: new Date(t0 + 65_000).toISOString(),
+    });
+    const { samples, bucketSeconds } =
+      getSandboxMetricsHistoryResponseSchema.parse(res.json());
+    expect(bucketSeconds).toBe(null);
+    expect(samples.map((s) => s.timestamp)).toEqual([
+      new Date(t0 + 30_000).toISOString(),
+      new Date(t0 + 60_000).toISOString(),
+    ]);
+  });
+
+  it('buckets past MAX_POINTS by per-field max — the spike survives', async () => {
+    const { app, db } = testApp();
+    const created = (
+      await rpc(app, '/acquireSandbox', { externalId: 'spiky' })
+    ).json().sandbox;
+    const t0 = Date.parse('2026-07-15T00:00:00.000Z');
+    const rows = MAX_POINTS + 40;
+    for (let i = 0; i < rows; i += 1) {
+      insertMetricsTick(db, {
+        at: new Date(t0 + i * 30_000).toISOString(),
+        fleetCounts: {
+          active: 1,
+          frozen: 0,
+          stopped: 0,
+          archived: 0,
+          restoring: 0,
+          total: 1,
+        },
+        // One reading spikes; every neighbor idles. Averaging would bury it.
+        samples: [
+          {
+            sandboxId: created.sandboxId,
+            metrics: reading(i === 200 ? 95 : 5),
+          },
+        ],
+        retentionHours: 168,
+      });
+    }
+    const res = await rpc(app, '/getSandboxMetricsHistory', {
+      externalId: 'spiky',
+      start: new Date(t0).toISOString(),
+      end: new Date(t0 + rows * 30_000).toISOString(),
+    });
+    const { samples, bucketSeconds } =
+      getSandboxMetricsHistoryResponseSchema.parse(res.json());
+    expect(bucketSeconds).not.toBe(null);
+    expect(samples.length).toBeLessThanOrEqual(MAX_POINTS);
+    // Ascending, and the bucket holding the spike reports the spike.
+    const times = samples.map((s) => Date.parse(s.timestamp));
+    expect([...times].sort((a, b) => a - b)).toEqual(times);
+    expect(Math.max(...samples.map((s) => s.cpuUsedPct))).toBe(95);
+  });
+});
+
+describe('getFleetTimeline', () => {
+  it('answers an empty window with no points and a null peak', async () => {
+    const { app } = testApp();
+    const res = await rpc(app, '/getFleetTimeline', {});
+    expect(res.statusCode).toBe(200);
+    const body = getFleetTimelineResponseSchema.parse(res.json());
+    expect(body).toEqual({ points: [], bucketSeconds: null, peak: null });
+  });
+
+  it('returns snapshots ascending with byState summing to total', async () => {
+    const { app, db, executor } = testApp();
+    await rpc(app, '/acquireSandbox', { externalId: 'one' });
+    const t0 = Date.parse('2026-07-15T10:00:00.000Z');
+    await sampleOnce(db, executor, new Date(t0), { retentionHours: 168 });
+    await rpc(app, '/acquireSandbox', { externalId: 'two' });
+    await sampleOnce(db, executor, new Date(t0 + 30_000), {
+      retentionHours: 168,
+    });
+
+    const res = await rpc(app, '/getFleetTimeline', {
+      start: new Date(t0 - 1000).toISOString(),
+      end: new Date(t0 + 60_000).toISOString(),
+    });
+    const { points, bucketSeconds, peak } =
+      getFleetTimelineResponseSchema.parse(res.json());
+    expect(bucketSeconds).toBe(null);
+    expect(points.map((p) => p.at)).toEqual([
+      new Date(t0).toISOString(),
+      new Date(t0 + 30_000).toISOString(),
+    ]);
+    for (const point of points) {
+      const sum = Object.values(point.byState).reduce((a, b) => a + b, 0);
+      expect(sum).toBe(point.total);
+    }
+    expect(peak).toEqual({
+      active: 2,
+      at: new Date(t0 + 30_000).toISOString(),
+    });
+  });
+
+  it('computes the peak from raw rows — bucketing cannot flatten it', async () => {
+    const { app, db } = testApp();
+    const t0 = Date.parse('2026-07-15T00:00:00.000Z');
+    const counts = (active: number) => ({
+      active,
+      frozen: 0,
+      stopped: 0,
+      archived: 0,
+      restoring: 0,
+      total: active,
+    });
+    const rows = MAX_POINTS + 40;
+    for (let i = 0; i < rows; i += 1) {
+      insertMetricsTick(db, {
+        at: new Date(t0 + i * 30_000).toISOString(),
+        fleetCounts: counts(1),
+        samples: [],
+        retentionHours: 168,
+      });
+    }
+    // A spike squeezed between two grid rows of its own bucket: the bucket
+    // keeps its LAST whole snapshot, so no point ever shows 9 — the peak
+    // field is the only honest carrier.
+    insertMetricsTick(db, {
+      at: new Date(t0 + 200 * 30_000 + 1000).toISOString(),
+      fleetCounts: counts(9),
+      samples: [],
+      retentionHours: 168,
+    });
+    insertMetricsTick(db, {
+      at: new Date(t0 + 200 * 30_000 + 2000).toISOString(),
+      fleetCounts: counts(1),
+      samples: [],
+      retentionHours: 168,
+    });
+
+    const res = await rpc(app, '/getFleetTimeline', {
+      start: new Date(t0).toISOString(),
+      end: new Date(t0 + rows * 30_000).toISOString(),
+    });
+    const { points, bucketSeconds, peak } =
+      getFleetTimelineResponseSchema.parse(res.json());
+    expect(bucketSeconds).not.toBe(null);
+    expect(points.length).toBeLessThanOrEqual(MAX_POINTS);
+    expect(peak).toEqual({
+      active: 9,
+      at: new Date(t0 + 200 * 30_000 + 1000).toISOString(),
+    });
+    // Whole-snapshot buckets: sums still hold after bucketing.
+    for (const point of points) {
+      const sum = Object.values(point.byState).reduce((a, b) => a + b, 0);
+      expect(sum).toBe(point.total);
+    }
+  });
+});
+
 describe('listSandboxMetrics', () => {
   it('measures active and frozen sandboxes; colder states are absent', async () => {
     const { app, db, executor } = testApp();
diff --git a/packages/shared/src/host.ts b/packages/shared/src/host.ts
index f0393fc..32c97ed 100644
--- a/packages/shared/src/host.ts
+++ b/packages/shared/src/host.ts
@@ -3,9 +3,12 @@ import { z } from 'zod';
 /**
  * getHostMetrics() — the observation window into the machine itself: is the
  * host healthy, and what do the sandboxes collectively cost it? A single
- * point-in-time snapshot, deliberately not a metrics history (that is a
- * monitoring system's job — point Prometheus at the box for trends).
- * Observation never wakes a sandbox and never touches lifecycle.
+ * point-in-time snapshot: host-level trends (CPU, memory, disk) remain a
+ * monitoring system's job — point Prometheus at the box. What the daemon
+ * does keep is its own domain history — per-sandbox samples and fleet state
+ * counts (getFleetTimeline in metrics.ts), which no external monitor can
+ * reconstruct from outside the ledger. Observation never wakes a sandbox
+ * and never touches lifecycle.
  *
  * Readings a platform cannot produce are null, honestly — never zero, never
  * invented: swap and /proc are Linux facts, and the data directory only
diff --git a/packages/shared/src/metrics.ts b/packages/shared/src/metrics.ts
index eb8b8e5..c1e3225 100644
--- a/packages/shared/src/metrics.ts
+++ b/packages/shared/src/metrics.ts
@@ -4,11 +4,11 @@ import { externalIdSchema } from './sandbox';
 /**
  * getSandboxMetrics(externalId) — one sandbox's point-in-time resource
  * reading: the per-sandbox sibling of getHostMetrics, and the native twin
- * of the E2B surface's metrics endpoint (same executor reading, same
- * single-sample answer — the daemon keeps no metrics history). Observation
- * never wakes a sandbox: a frozen sandbox is measured as it sleeps, and a
- * sandbox with no running container answers null instead of being started
- * just to be looked at.
+ * of the E2B surface's metrics endpoint (same executor reading). For the
+ * past instead of the present, getSandboxMetricsHistory below serves the
+ * daemon's sampled history. Observation never wakes a sandbox: a frozen
+ * sandbox is measured as it sleeps, and a sandbox with no running container
+ * answers null instead of being started just to be looked at.
  */
 export const sandboxMetricsSampleSchema = z.object({
   /** ISO 8601 UTC — when the reading was taken. */
@@ -69,3 +69,117 @@ export const listSandboxMetricsResponseSchema = z.object({
 export type ListSandboxMetricsResponse = z.infer<
   typeof listSandboxMetricsResponseSchema
 >;
+
+/**
+ * getSandboxMetricsHistory(externalId, start?, end?) — the sampled past of
+ * one sandbox. The daemon's background sampler persists a reading per
+ * measurable sandbox every DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS; this
+ * verb slices that history. History exists because it is a compatibility
+ * contract (the E2B metrics endpoint takes start/end) and because no
+ * external monitor can measure per-sandbox from outside the ledger —
+ * host-level trends still belong to Prometheus.
+ *
+ * Wire honesty rules:
+ * - start/end are ISO 8601 (unix seconds are the E2B surface's dialect,
+ *   translated at that boundary). Defaults: end = now, start = end - 1h.
+ * - The window's raw rows are returned as-is up to 360 points; past that
+ *   the server buckets them (bucketSeconds says how wide) and each bucket
+ *   reports its per-field max — a caller reading history is hunting for
+ *   spikes, and averaging would erase exactly what they came for.
+ * - Gaps are real: a daemon that was down sampled nothing, and the answer
+ *   shows the hole instead of interpolating over it.
+ * - An unsampled sandbox answers an empty array — never a made-up reading.
+ */
+/**
+ * A parseable timestamp, rejected at the door: a malformed start/end would
+ * otherwise turn into NaN arithmetic deep in the window resolver.
+ */
+const isoTimestampSchema = z
+  .string()
+  .refine((value) => !Number.isNaN(Date.parse(value)), {
+    message: 'must be an ISO 8601 timestamp',
+  });
+
+export const getSandboxMetricsHistoryRequestSchema = z.object({
+  externalId: externalIdSchema,
+  /** ISO 8601; defaults to one hour before `end`. */
+  start: isoTimestampSchema.optional(),
+  /** ISO 8601; defaults to now. */
+  end: isoTimestampSchema.optional(),
+});
+
+export type GetSandboxMetricsHistoryRequest = z.infer<
+  typeof getSandboxMetricsHistoryRequestSchema
+>;
+
+export const getSandboxMetricsHistoryResponseSchema = z.object({
+  /** Ascending by timestamp. */
+  samples: z.array(sandboxMetricsSampleSchema),
+  /** Null when raw samples were returned unbucketed. */
+  bucketSeconds: z.number().int().positive().nullable(),
+});
+
+export type GetSandboxMetricsHistoryResponse = z.infer<
+  typeof getSandboxMetricsHistoryResponseSchema
+>;
+
+/**
+ * getFleetTimeline(start?, end?) — how many sandboxes sat in each state
+ * over time: the fleet-level sibling of getSandboxMetricsHistory, and the
+ * product's own story ("idle is free" is visible as active falling while
+ * frozen rises). One snapshot row per sampler tick, kept 30 days.
+ *
+ * Bucketing differs from the per-sandbox verb on purpose: a bucket reports
+ * its last raw snapshot whole, never per-state maxima — independent maxima
+ * would double-count a sandbox mid-transition and the stacked counts would
+ * stop summing to total. The concurrency peak is instead computed from the
+ * window's raw rows and carried separately in `peak`, so no bucketing can
+ * flatten it.
+ */
+export const fleetTimelinePointSchema = z.object({
+  /** ISO 8601 UTC — when the snapshot was taken. */
+  at: z.string(),
+  byState: z.object({
+    active: z.number().int(),
+    frozen: z.number().int(),
+    stopped: z.number().int(),
+    archived: z.number().int(),
+    restoring: z.number().int(),
+  }),
+  total: z.number().int(),
+});
+
+export type FleetTimelinePoint = z.infer<typeof fleetTimelinePointSchema>;
+
+export const getFleetTimelineRequestSchema = z.object({
+  /** ISO 8601; defaults to 24 hours before `end`. */
+  start: isoTimestampSchema.optional(),
+  /** ISO 8601; defaults to now. */
+  end: isoTimestampSchema.optional(),
+});
+
+export type GetFleetTimelineRequest = z.infer<
+  typeof getFleetTimelineRequestSchema
+>;
+
+export const getFleetTimelineResponseSchema = z.object({
+  /** Ascending by timestamp. */
+  points: z.array(fleetTimelinePointSchema),
+  /** Null when raw snapshots were returned unbucketed. */
+  bucketSeconds: z.number().int().positive().nullable(),
+  /**
+   * Highest active count in the window, from raw rows (not buckets), with
+   * the earliest instant it was observed. Null when the window holds no
+   * snapshots at all.
+   */
+  peak: z
+    .object({
+      active: z.number().int(),
+      at: z.string(),
+    })
+    .nullable(),
+});
+
+export type GetFleetTimelineResponse = z.infer<
+  typeof getFleetTimelineResponseSchema
+>;

From 292c1e44dcb6374024b1e7ff3aaed81defc05a88 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 01:59:16 +0800
Subject: [PATCH 086/133] =?UTF-8?q?Grouping=20becomes=20a=20tagging=20prob?=
 =?UTF-8?q?lem,=20not=20an=20entity=20problem:=20the=20native=20face=20lea?=
 =?UTF-8?q?rns=20the=20metadata=20column=20E2B=20already=20wrote=20?=
 =?UTF-8?q?=E2=80=94=20string-to-string=20labels=20stored=20when=20acquire?=
 =?UTF-8?q?=20creates=20the=20sandbox=20(an=20idempotent=20re-acquire=20ke?=
 =?UTF-8?q?eps=20the=20stored=20set,=20same=20manners=20as=20policy=20and?=
 =?UTF-8?q?=20template),=20replaced=20wholesale=20by=20a=20new=20updateMet?=
 =?UTF-8?q?adata=20verb=20({}=20clears;=20a=20pure=20ledger=20write=20that?=
 =?UTF-8?q?=20never=20wakes=20and=20never=20resets=20the=20idle=20clock),?=
 =?UTF-8?q?=20echoed=20as=20{}=20never=20null=20in=20every=20sandbox=20vie?=
 =?UTF-8?q?w=20=E2=80=94=20with=20dor=20sandbox=20meta=20to=20show=20or=20?=
 =?UTF-8?q?relabel=20from=20the=20shell,=20an=20SDK=20method,=20console=20?=
 =?UTF-8?q?label=20chips=20and=20a=20filter=20whose=20options=20grow=20fro?=
 =?UTF-8?q?m=20the=20fleet's=20own=20labels=20instead=20of=20a=20maintaine?=
 =?UTF-8?q?d=20group=20list,=20and=20a=20metadata-changed=20line=20in=20th?=
 =?UTF-8?q?e=20activity=20feed?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 e2e/src/cli.test.ts                           |  33 +++++
 e2e/src/native.test.ts                        |  75 ++++++++++
 packages/cli/src/commands.test.ts             |  43 +++++-
 packages/cli/src/commands.ts                  |  54 +++++++
 packages/cli/src/main.ts                      |  28 ++++
 packages/console/scripts/seed.mjs             |  11 +-
 .../console/src/features/activity/kinds.ts    |   3 +
 .../sandboxes/pages/SandboxDetailPage.tsx     |  17 +++
 .../sandboxes/pages/SandboxesPage.tsx         |  52 ++++++-
 packages/console/vite.config.ts               |   1 +
 packages/sdk/src/client.ts                    |  73 ++++++++-
 packages/server/src/app.test.ts               | 126 ++++++++++++++++
 packages/server/src/db/ledger.ts              |  50 ++++++-
 packages/server/src/routes/sandboxes.ts       | 139 +++++++++++++++++-
 packages/shared/src/acquire.ts                |  13 +-
 packages/shared/src/activity.ts               |   2 +
 packages/shared/src/index.ts                  |   1 +
 packages/shared/src/sandbox.ts                |  13 ++
 packages/shared/src/update-metadata.ts        |  35 +++++
 skills/dormice/SKILL.md                       |   8 +-
 website/content/docs/http-api.mdx             |  13 +-
 21 files changed, 766 insertions(+), 24 deletions(-)
 create mode 100644 packages/shared/src/update-metadata.ts

diff --git a/e2e/src/cli.test.ts b/e2e/src/cli.test.ts
index d63d273..267cce2 100644
--- a/e2e/src/cli.test.ts
+++ b/e2e/src/cli.test.ts
@@ -44,6 +44,39 @@ describe('dor CLI against a real daemon', () => {
     expect(stdout).toContain(created.sandbox.sandboxId);
   });
 
+  it('sandbox meta shows, replaces and clears labels through the real binary', async () => {
+    const sdk = new Dormice({
+      endpoint: inject('dormiceEndpoint'),
+      token: inject('dormiceToken'),
+    });
+    await sdk.acquireSandbox('cli-meta-key', {
+      metadata: { app: 'crawler', env: 'prod' },
+    });
+
+    // ls renders the labels in the METADATA column.
+    const listed = await cli('sandbox', 'ls');
+    expect(listed.stdout).toMatch(/METADATA/);
+    expect(listed.stdout).toContain('app=crawler,env=prod');
+
+    const shown = await cli('sandbox', 'meta', 'cli-meta-key');
+    expect(shown.stdout).toBe('app=crawler,env=prod\n');
+
+    const replaced = await cli('sandbox', 'meta', 'cli-meta-key', 'app=ci');
+    expect(replaced.stdout).toContain('is now app=ci.');
+
+    const cleared = await cli('sandbox', 'meta', 'cli-meta-key', '--clear');
+    expect(cleared.stdout).toContain('Cleared metadata');
+    const empty = await cli('sandbox', 'meta', 'cli-meta-key');
+    expect(empty.stdout).toBe('No metadata.\n');
+
+    // A word that is not key=value is named in the error, before any RPC.
+    await expect(
+      cli('sandbox', 'meta', 'cli-meta-key', 'not-a-label'),
+    ).rejects.toMatchObject({
+      stderr: expect.stringContaining('not key=value'),
+    });
+  });
+
   it('sandbox destroy destroys and is idempotent', async () => {
     const sdk = new Dormice({
       endpoint: inject('dormiceEndpoint'),
diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index b6e4bc3..e7a3dd4 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -57,6 +57,34 @@ describe('native API over a real daemon', () => {
     });
   });
 
+  it('labels a sandbox at acquire, relabels through updateMetadata, and the list shows it', async () => {
+    const created = await client().acquireSandbox('meta-key', {
+      metadata: { app: 'crawler', env: 'prod' },
+    });
+    expect(created.sandbox.metadata).toEqual({ app: 'crawler', env: 'prod' });
+
+    // Creation-time only: a second acquire's labels do not apply.
+    const again = await client().acquireSandbox('meta-key', {
+      metadata: { app: 'other' },
+    });
+    expect(again.sandbox.metadata).toEqual({ app: 'crawler', env: 'prod' });
+
+    // Full replacement through the update verb — env is gone, not merged.
+    const updated = await client().updateMetadata('meta-key', {
+      app: 'assistant',
+    });
+    expect(updated.sandbox.metadata).toEqual({ app: 'assistant' });
+
+    const listed = await client().listSandboxes();
+    expect(listed.find((s) => s.externalId === 'meta-key')?.metadata).toEqual({
+      app: 'assistant',
+    });
+
+    // {} clears; a label-less sandbox still reads {} — never null.
+    const cleared = await client().updateMetadata('meta-key', {});
+    expect(cleared.sandbox.metadata).toEqual({});
+  });
+
   it('rejects a policy override that breaks the ordering rule', async () => {
     await expect(
       client().acquireSandbox('bad-policy-key', {
@@ -560,4 +588,51 @@ describe('the observability verbs over a real daemon', () => {
     expect(mine.map((e) => e.kind)).toEqual(['destroyed', 'created']);
     expect(mine[1]?.detail).toContain('acquireSandbox');
   });
+
+  it('getSandboxMetricsHistory fills up as the sampler ticks, and 404s after destroy', async () => {
+    await client().acquireSandbox('obs-history-key');
+    // The exam daemon samples every second — wait for the first row to
+    // land, on real wall-clock time.
+    const deadline = Date.now() + 15_000;
+    let history = await client().getSandboxMetricsHistory('obs-history-key');
+    while (history.samples.length < 1 && Date.now() < deadline) {
+      await sleep(0.5);
+      history = await client().getSandboxMetricsHistory('obs-history-key');
+    }
+    expect(history.samples.length).toBeGreaterThanOrEqual(1);
+    // The SDK already validated the shape against the shared schema;
+    // spot-check the readings are real.
+    const newest = history.samples.at(-1);
+    expect(newest?.memTotalBytes).toBeGreaterThan(0);
+    expect(newest?.diskTotalBytes).toBeGreaterThan(0);
+    // A short window comes back raw, not bucketed.
+    expect(history.bucketSeconds).toBe(null);
+
+    await client().destroySandbox('obs-history-key');
+    await expect(
+      client().getSandboxMetricsHistory('obs-history-key'),
+    ).rejects.toMatchObject({ name: 'DormiceApiError', status: 404 });
+  });
+
+  it('getFleetTimeline reports points and a peak once the fleet was seen', async () => {
+    await client().acquireSandbox('obs-timeline-key');
+    const deadline = Date.now() + 15_000;
+    let timeline = await client().getFleetTimeline();
+    // Wait for a tick that observed at least one sandbox alive.
+    while (
+      (timeline.points.length < 1 || (timeline.peak?.active ?? 0) < 1) &&
+      Date.now() < deadline
+    ) {
+      await sleep(0.5);
+      timeline = await client().getFleetTimeline();
+    }
+    expect(timeline.points.length).toBeGreaterThanOrEqual(1);
+    expect(timeline.peak?.active).toBeGreaterThanOrEqual(1);
+    // Whole-snapshot points: byState always sums to total.
+    for (const point of timeline.points) {
+      const sum = Object.values(point.byState).reduce((a, b) => a + b, 0);
+      expect(sum).toBe(point.total);
+    }
+    await client().destroySandbox('obs-timeline-key');
+  });
 });
diff --git a/packages/cli/src/commands.test.ts b/packages/cli/src/commands.test.ts
index f456ff5..6f4ecd4 100644
--- a/packages/cli/src/commands.test.ts
+++ b/packages/cli/src/commands.test.ts
@@ -11,10 +11,12 @@ import {
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import {
   clientFromEnv,
+  parseLabels,
   pullSavedMessage,
   sandboxDestroy,
   sandboxExec,
   sandboxLs,
+  sandboxMeta,
   sandboxPull,
   sandboxPush,
   sandboxRebuild,
@@ -96,17 +98,40 @@ describe('sandbox commands over real HTTP', () => {
   });
 
   it('ls renders one aligned row per sandbox', async () => {
-    const alice = await client.acquireSandbox('alice');
+    const alice = await client.acquireSandbox('alice', {
+      metadata: { app: 'demo' },
+    });
     await client.acquireSandbox('bob');
 
     const output = await sandboxLs(client);
     const lines = output.split('\n');
     expect(lines[0]).toMatch(
-      /^USER KEY\s{2,}STATE\s{2,}SANDBOX ID\s{2,}LAST ACTIVE$/,
+      /^USER KEY\s{2,}STATE\s{2,}SANDBOX ID\s{2,}LAST ACTIVE\s{2,}METADATA$/,
     );
     expect(output).toMatch(/alice\s{2,}active/);
     expect(output).toMatch(/bob\s{2,}active/);
     expect(output).toContain(alice.sandbox.sandboxId);
+    expect(output).toContain('app=demo');
+  });
+
+  it('meta shows, replaces and clears the label set', async () => {
+    await client.acquireSandbox('labeled', {
+      metadata: { app: 'demo', env: 'prod' },
+    });
+    expect(await sandboxMeta(client, 'labeled', null)).toBe(
+      'app=demo,env=prod',
+    );
+    expect(await sandboxMeta(client, 'labeled', { app: 'ci' })).toBe(
+      'Metadata for key "labeled" is now app=ci.',
+    );
+    expect(await sandboxMeta(client, 'labeled', {})).toBe(
+      'Cleared metadata for key "labeled".',
+    );
+    expect(await sandboxMeta(client, 'labeled', null)).toBe('No metadata.');
+    await expect(sandboxMeta(client, 'nobody', null)).rejects.toThrow(
+      /acquire it first/,
+    );
+    await client.destroySandbox('labeled');
   });
 
   it('neutralizes control characters a hostile external id smuggles in', async () => {
@@ -181,6 +206,20 @@ describe('sandbox commands over real HTTP', () => {
   });
 });
 
+describe('parseLabels', () => {
+  it('splits on the first = only — values keep their own', () => {
+    expect(parseLabels(['app=crawler', 'note=a=b'])).toEqual({
+      app: 'crawler',
+      note: 'a=b',
+    });
+  });
+
+  it('names the offending word when it is not key=value', () => {
+    expect(() => parseLabels(['nope'])).toThrow(/"nope" is not key=value/);
+    expect(() => parseLabels(['=value'])).toThrow(/not key=value/);
+  });
+});
+
 describe('template commands over real HTTP', () => {
   it('add, ls and rm walk the registration life end to end', async () => {
     expect(await templateLs(client)).toBe('No templates.');
diff --git a/packages/cli/src/commands.ts b/packages/cli/src/commands.ts
index a7caab4..249e8d8 100644
--- a/packages/cli/src/commands.ts
+++ b/packages/cli/src/commands.ts
@@ -31,11 +31,19 @@ export function clientFromEnv(
   return new Dormice({ endpoint, token });
 }
 
+/** One line per label set, `k=v,k=v`; shared by ls and meta. */
+function formatMetadata(metadata: Record<string, string>): string {
+  return Object.entries(metadata)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(',');
+}
+
 const COLUMNS: { header: string; value: (s: Sandbox) => string }[] = [
   { header: 'USER KEY', value: (s) => s.externalId },
   { header: 'STATE', value: (s) => s.state },
   { header: 'SANDBOX ID', value: (s) => s.sandboxId },
   { header: 'LAST ACTIVE', value: (s) => s.lastActiveAt },
+  { header: 'METADATA', value: (s) => formatMetadata(s.metadata) },
 ];
 
 /**
@@ -73,6 +81,52 @@ export async function sandboxLs(client: Dormice): Promise<string> {
   );
 }
 
+/**
+ * Parses `key=value` label arguments for `dor sandbox meta`. Split on the
+ * FIRST `=` only — values may contain `=` (base64, URLs), keys may not.
+ */
+export function parseLabels(args: string[]): Record<string, string> {
+  const labels: Record<string, string> = {};
+  for (const arg of args) {
+    const eq = arg.indexOf('=');
+    if (eq <= 0) {
+      throw new Error(
+        `label "${arg}" is not key=value — e.g. dor sandbox meta my-key app=crawler env=prod`,
+      );
+    }
+    labels[arg.slice(0, eq)] = arg.slice(eq + 1);
+  }
+  return labels;
+}
+
+/**
+ * `dor sandbox meta <externalId> [key=value ...]`: no labels = show the
+ * current set; labels (or --clear) = full replacement, the verb's wire
+ * semantics stated plainly. A pure ledger write — nothing is woken.
+ */
+export async function sandboxMeta(
+  client: Dormice,
+  externalId: string,
+  labels: Record<string, string> | null,
+): Promise<string> {
+  if (labels === null) {
+    // Read path: the native list is the one read the daemon offers.
+    const sandbox = (await client.listSandboxes()).find(
+      (s) => s.externalId === externalId,
+    );
+    if (!sandbox) {
+      throw new Error(`no sandbox for key "${externalId}" — acquire it first`);
+    }
+    const line = formatMetadata(sandbox.metadata);
+    return line ? printable(line) : 'No metadata.';
+  }
+  const { sandbox } = await client.updateMetadata(externalId, labels);
+  const line = formatMetadata(sandbox.metadata);
+  return line
+    ? `Metadata for key "${printable(externalId)}" is now ${printable(line)}.`
+    : `Cleared metadata for key "${printable(externalId)}".`;
+}
+
 export interface ExecOutput {
   stdout: string;
   stderr: string;
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index df20665..1cd2c62 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -8,10 +8,12 @@ import path from 'node:path';
 import { Command } from 'commander';
 import {
   clientFromEnv,
+  parseLabels,
   pullSavedMessage,
   sandboxDestroy,
   sandboxExec,
   sandboxLs,
+  sandboxMeta,
   sandboxPull,
   sandboxPush,
   sandboxRebuild,
@@ -125,6 +127,32 @@ sandbox
     },
   );
 
+sandbox
+  .command('meta')
+  .description(
+    'Show or replace the labels on the sandbox behind a key (replacement is total; a pure ledger write, nothing is woken)',
+  )
+  .argument('<externalId>', 'the external id whose sandbox to label')
+  .argument(
+    '[labels...]',
+    'key=value pairs forming the NEW complete label set; omitted = show the current one',
+  )
+  .option('--clear', 'remove every label')
+  .action(
+    async (externalId: string, labels: string[], opts: { clear?: boolean }) => {
+      if (opts.clear && labels.length > 0) {
+        throw new Error('--clear and key=value labels are mutually exclusive');
+      }
+      console.log(
+        await sandboxMeta(
+          clientFromEnv(process.env),
+          externalId,
+          opts.clear ? {} : labels.length > 0 ? parseLabels(labels) : null,
+        ),
+      );
+    },
+  );
+
 sandbox
   .command('rebuild')
   .description(
diff --git a/packages/console/scripts/seed.mjs b/packages/console/scripts/seed.mjs
index 844713b..b5af365 100644
--- a/packages/console/scripts/seed.mjs
+++ b/packages/console/scripts/seed.mjs
@@ -69,41 +69,50 @@ const sandboxes = [
     externalId: 'demo-agent',
     policy: { freezeAfterSeconds: 300, stopAfterSeconds: null },
     template: 'claude-code',
+    metadata: { app: 'assistant', env: 'prod' },
   },
   {
     externalId: 'web-scraper',
     policy: { freezeAfterSeconds: 5 },
     template: 'python-ml',
+    metadata: { app: 'crawler', env: 'prod' },
   },
   {
     externalId: 'build-runner',
     policy: { freezeAfterSeconds: 3, stopAfterSeconds: 8 },
+    metadata: { app: 'ci' },
   },
   {
     externalId: 'docs-writer',
     policy: { freezeAfterSeconds: 5 },
     template: 'node-agent',
+    metadata: { app: 'assistant', env: 'staging' },
   },
   {
     externalId: 'email-triage',
     policy: { freezeAfterSeconds: 600, stopAfterSeconds: null },
+    metadata: { app: 'assistant', env: 'prod' },
   },
   {
     externalId: 'ci-check',
     policy: { freezeAfterSeconds: 4, stopAfterSeconds: 10 },
+    metadata: { app: 'ci' },
   },
   {
     externalId: 'data-pipeline',
     policy: { freezeAfterSeconds: 900 },
     template: 'python-ml',
+    metadata: { app: 'crawler', env: 'staging' },
   },
+  // 刻意不带标签:列表的标签列该有留白的样子,筛选也筛得掉它。
   { externalId: 'scratch' },
 ];
-for (const { externalId, policy, template } of sandboxes) {
+for (const { externalId, policy, template, metadata } of sandboxes) {
   await rpc('/acquireSandbox', {
     externalId,
     ...(policy ? { policy } : {}),
     ...(template ? { template } : {}),
+    ...(metadata ? { metadata } : {}),
   });
   console.log(`沙箱  ${externalId}`);
 }
diff --git a/packages/console/src/features/activity/kinds.ts b/packages/console/src/features/activity/kinds.ts
index 8a91bc0..ea55da7 100644
--- a/packages/console/src/features/activity/kinds.ts
+++ b/packages/console/src/features/activity/kinds.ts
@@ -18,6 +18,7 @@ export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
   'restore-failed': '恢复失败',
   reconciled: '对账修复',
   'policy-changed': '策略调整',
+  'metadata-changed': '标签调整',
   'daemon-started': 'daemon 启动',
   'ingress-updated': '域名配置',
   'upgrade-started': '发起升级',
@@ -49,6 +50,8 @@ export const ACTIVITY_KIND_STYLES: Record<ActivityKind, string> = {
     'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
   'policy-changed':
     'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  'metadata-changed':
+    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
   'daemon-started': 'border-border bg-muted text-muted-foreground',
   'ingress-updated':
     'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index a73404b..2a09447 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -5,6 +5,7 @@ import {
   useSearch,
 } from '@tanstack/react-router';
 import type { ReactNode } from 'react';
+import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent } from '@/components/ui/card';
 import {
@@ -149,6 +150,22 @@ export function SandboxDetailPage() {
                         : lineage.image}
                   </Row>
                 )}
+                {Object.keys(sandbox.metadata).length > 0 && (
+                  <Row label="标签">
+                    <span className="inline-flex flex-wrap justify-end gap-1">
+                      {Object.entries(sandbox.metadata).map(([key, value]) => (
+                        <Badge
+                          key={key}
+                          variant="outline"
+                          className="max-w-[14rem] truncate font-mono text-xs font-normal text-muted-foreground"
+                          title={`${key}=${value}`}
+                        >
+                          {key}={value}
+                        </Badge>
+                      ))}
+                    </span>
+                  </Row>
+                )}
                 <Row label="节点">{sandbox.nodeId}</Row>
                 <Row label="端点">{sandbox.endpoint}</Row>
                 <Row label="创建于">
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index f5625e3..baa3550 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -26,6 +26,7 @@ import {
   AlertDialogTitle,
   AlertDialogTrigger,
 } from '@/components/ui/alert-dialog';
+import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Checkbox } from '@/components/ui/checkbox';
 import {
@@ -81,6 +82,33 @@ const STATE_FILTERS: Array<SandboxState> = [
 type SortKey = 'externalId' | 'lastActiveAt' | 'createdAt';
 type Sort = { key: SortKey; dir: 1 | -1 };
 
+/** 一个沙箱的标签摊平成 "key=value" 串 — 筛选项与展示共用同一拼法。 */
+function labelPairs(sandbox: Sandbox): string[] {
+  return Object.entries(sandbox.metadata).map(
+    ([key, value]) => `${key}=${value}`,
+  );
+}
+
+/** 标签列的一格:小 chips,长值截断、全文挂 hover;没标签就空着不占眼睛。 */
+function MetadataChips({ sandbox }: { sandbox: Sandbox }) {
+  const pairs = labelPairs(sandbox);
+  if (pairs.length === 0) return null;
+  return (
+    <span className="inline-flex max-w-[16rem] flex-wrap gap-1">
+      {pairs.map((pair) => (
+        <Badge
+          key={pair}
+          variant="outline"
+          className="max-w-[10rem] truncate font-mono text-xs font-normal text-muted-foreground"
+          title={pair}
+        >
+          {pair}
+        </Badge>
+      ))}
+    </span>
+  );
+}
+
 /**
  * 资源列的一格:数值紧凑,细节挂 hover;占比过线换警示色,和指标 tab
  * 的 Meter 同一套阈值。value 为 null = 这行没被测到(没有容器可测)。
@@ -279,9 +307,17 @@ export function SandboxesPage() {
   );
   const [search, setSearch] = useState('');
   const [stateFilter, setStateFilter] = useState<'all' | SandboxState>('all');
+  // 值是 "key=value" 串,'' = 全部。选项从舰队现有标签去重而来 —
+  // 分组不是实体,就是按标签筛,所以没有可维护的"组列表"要管。
+  const [metadataFilter, setMetadataFilter] = useState('');
   const [selected, setSelected] = useState<Set<string>>(new Set());
   const [sort, setSort] = useState<Sort | null>(null);
 
+  const metadataOptions = useMemo(() => {
+    const pairs = new Set(sandboxes.flatMap(labelPairs));
+    return [...pairs].sort().map((pair) => ({ value: pair, label: pair }));
+  }, [sandboxes]);
+
   const toggleSort = (key: SortKey) =>
     setSort((prev) =>
       prev?.key === key
@@ -293,6 +329,8 @@ export function SandboxesPage() {
     const matched = sandboxes.filter(
       (sandbox) =>
         (stateFilter === 'all' || sandbox.state === stateFilter) &&
+        (metadataFilter === '' ||
+          labelPairs(sandbox).includes(metadataFilter)) &&
         (search === '' ||
           sandbox.externalId.toLowerCase().includes(search.toLowerCase())),
     );
@@ -300,7 +338,7 @@ export function SandboxesPage() {
     return [...matched].sort(
       (a, b) => a[sort.key].localeCompare(b[sort.key]) * sort.dir,
     );
-  }, [sandboxes, stateFilter, search, sort]);
+  }, [sandboxes, stateFilter, metadataFilter, search, sort]);
 
   // 选中集随现实收敛:被别处销毁的沙箱不该留在选中里撑数字。
   const selectedVisible = filtered.filter((s) => selected.has(s.externalId));
@@ -360,6 +398,14 @@ export function SandboxesPage() {
             setStateFilter(value === '' ? 'all' : (value as SandboxState))
           }
         />
+        {metadataOptions.length > 0 && (
+          <FilterMenu
+            label="标签"
+            value={metadataFilter}
+            options={metadataOptions}
+            onChange={setMetadataFilter}
+          />
+        )}
         <span className="text-sm text-muted-foreground">
           {filtered.length} / {sandboxes.length} 个
         </span>
@@ -424,6 +470,7 @@ export function SandboxesPage() {
               </TableHead>
               <TableHead>状态</TableHead>
               <TableHead>模板</TableHead>
+              <TableHead>标签</TableHead>
               <TableHead className="text-right">CPU</TableHead>
               <TableHead className="text-right">内存</TableHead>
               <TableHead className="text-right">磁盘</TableHead>
@@ -484,6 +531,9 @@ export function SandboxesPage() {
                     />
                   </span>
                 </TableCell>
+                <TableCell>
+                  <MetadataChips sandbox={sandbox} />
+                </TableCell>
                 {(() => {
                   const m = metricsOf.get(sandbox.externalId);
                   if (!m) {
diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index 33dcb0d..0b86c36 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -29,6 +29,7 @@ export default defineConfig({
       '/acquireSandbox': 'http://127.0.0.1:3676',
       '/rebuildSandbox': 'http://127.0.0.1:3676',
       '/updatePolicy': 'http://127.0.0.1:3676',
+      '/updateMetadata': 'http://127.0.0.1:3676',
       '/listTemplates': 'http://127.0.0.1:3676',
       '/registerTemplate': 'http://127.0.0.1:3676',
       '/removeTemplate': 'http://127.0.0.1:3676',
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index c7e766d..6815bd5 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -12,10 +12,14 @@ import {
   type ExecCommandResponse,
   execCommandResponseSchema,
   type GetConfigResponse,
+  type GetFleetTimelineResponse,
   type GetIngressResponse,
+  type GetSandboxMetricsHistoryResponse,
   type GetUpgradeStatusResponse,
   getConfigResponseSchema,
+  getFleetTimelineResponseSchema,
   getIngressResponseSchema,
+  getSandboxMetricsHistoryResponseSchema,
   getSandboxMetricsResponseSchema,
   getUpgradeStatusResponseSchema,
   type HostMetricsResponse,
@@ -37,11 +41,14 @@ import {
   registerTemplateResponseSchema,
   removeTemplateResponseSchema,
   type Sandbox,
+  type SandboxMetadata,
   type SandboxMetricsSample,
   type SetIngressResponse,
   setIngressResponseSchema,
   type Template,
+  type UpdateMetadataResponse,
   type UpdatePolicyResponse,
+  updateMetadataResponseSchema,
   updatePolicyResponseSchema,
   type WriteFileResponse,
   type WriteFilesResponse,
@@ -105,6 +112,12 @@ export interface AcquireSandboxOptions {
    * unknown name is a 400.
    */
   template?: string;
+  /**
+   * Labels stored when this acquire creates the sandbox. Same rules as
+   * policy: creation-time only — relabel an existing sandbox through
+   * updateMetadata.
+   */
+  metadata?: SandboxMetadata;
 }
 
 /** A non-2xx answer from the daemon, carrying the HTTP status and the server's message. */
@@ -143,6 +156,7 @@ export class Dormice {
       externalId,
       policy: options?.policy,
       template: options?.template,
+      metadata: options?.metadata,
     });
     // Never trust the wire blindly: parsing against the shared schema makes
     // a version-skewed or misbehaving server fail loudly right here.
@@ -168,10 +182,10 @@ export class Dormice {
   }
 
   /**
-   * One sandbox's point-in-time resource reading (CPU, memory, disk) — a
-   * single sample, the daemon keeps no history. Observation never wakes:
-   * a frozen sandbox is measured as it sleeps, and with no running
-   * container (stopped, archived, restoring) the sample is null.
+   * One sandbox's point-in-time resource reading (CPU, memory, disk).
+   * Observation never wakes: a frozen sandbox is measured as it sleeps,
+   * and with no running container (stopped, archived, restoring) the
+   * sample is null. For the past, see getSandboxMetricsHistory.
    */
   async getSandboxMetrics(
     externalId: string,
@@ -180,6 +194,44 @@ export class Dormice {
     return getSandboxMetricsResponseSchema.parse(data).sample;
   }
 
+  /**
+   * One sandbox's sampled history, sliced by an optional ISO window
+   * (default: the last hour). Past 360 points the server buckets the
+   * answer — `bucketSeconds` says how wide — and each bucket reports its
+   * per-field maxima, so spikes survive. An unsampled window answers an
+   * empty array, never an invented reading; a window the daemon was down
+   * for shows the gap.
+   */
+  async getSandboxMetricsHistory(
+    externalId: string,
+    options?: { start?: string; end?: string },
+  ): Promise<GetSandboxMetricsHistoryResponse> {
+    const data = await this.rpc('getSandboxMetricsHistory', {
+      externalId,
+      start: options?.start,
+      end: options?.end,
+    });
+    return getSandboxMetricsHistoryResponseSchema.parse(data);
+  }
+
+  /**
+   * Fleet state counts over time (default window: the last 24 hours) —
+   * how many sandboxes sat active/frozen/stopped/archived/restoring at
+   * each sampler tick. Bucketed points are whole raw snapshots (byState
+   * always sums to total); `peak` carries the window's highest active
+   * count from raw rows, immune to bucketing.
+   */
+  async getFleetTimeline(options?: {
+    start?: string;
+    end?: string;
+  }): Promise<GetFleetTimelineResponse> {
+    const data = await this.rpc('getFleetTimeline', {
+      start: options?.start,
+      end: options?.end,
+    });
+    return getFleetTimelineResponseSchema.parse(data);
+  }
+
   /**
    * Every measurable sandbox's reading in one answer — a view over N
    * sandboxes costs one request instead of N. Presence means measured:
@@ -323,6 +375,19 @@ export class Dormice {
     return updatePolicyResponseSchema.parse(data);
   }
 
+  /**
+   * Replaces the sandbox's label set in place — full replacement, `{}`
+   * clears every label. A pure ledger write: nothing is woken, and the
+   * idle clock is not refreshed. Unknown key: 404 — not a creator.
+   */
+  async updateMetadata(
+    externalId: string,
+    metadata: SandboxMetadata,
+  ): Promise<UpdateMetadataResponse> {
+    const data = await this.rpc('updateMetadata', { externalId, metadata });
+    return updateMetadataResponseSchema.parse(data);
+  }
+
   /**
    * Destroys the sandbox behind an external id — container and disk are gone
    * for good. Idempotent like acquire: a key that has no sandbox is not an
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index b16db3a..e2090ae 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -180,6 +180,41 @@ describe('POST /acquireSandbox', () => {
     });
     expect(res.statusCode).toBe(400);
   });
+
+  it('stores metadata at creation and echoes {} when none was given', async () => {
+    const { app } = testApp();
+    const labeled = await acquire(app, {
+      externalId: 'alice',
+      metadata: { app: 'crawler', env: 'prod' },
+    });
+    expect(labeled.json().sandbox.metadata).toEqual({
+      app: 'crawler',
+      env: 'prod',
+    });
+    const bare = await acquire(app, { externalId: 'bob' });
+    expect(bare.json().sandbox.metadata).toEqual({});
+  });
+
+  it('keeps stored metadata on the idempotent path, but a malformed value is still a 400', async () => {
+    const { app } = testApp();
+    await acquire(app, {
+      externalId: 'alice',
+      metadata: { app: 'crawler' },
+    });
+    // Same rule as policy/template: creation-time only, never an update.
+    const again = await acquire(app, {
+      externalId: 'alice',
+      metadata: { app: 'other' },
+    });
+    expect(again.json().sandbox.metadata).toEqual({ app: 'crawler' });
+    // Non-string values are outside the label contract — the caller's
+    // mistake even though it would not have applied.
+    const bad = await acquire(app, {
+      externalId: 'alice',
+      metadata: { app: 42 },
+    });
+    expect(bad.statusCode).toBe(400);
+  });
 });
 
 describe('error shape', () => {
@@ -946,6 +981,97 @@ describe('POST /updatePolicy', () => {
   });
 });
 
+describe('POST /updateMetadata', () => {
+  it('replaces the label set wholesale and does not refresh the idle clock', async () => {
+    const { app } = testApp();
+    const created = (
+      await acquire(app, {
+        externalId: 'alice',
+        metadata: { app: 'crawler', env: 'staging' },
+      })
+    ).json();
+
+    // Full replacement: env is gone, not merged.
+    const res = await rpc(app, '/updateMetadata', {
+      externalId: 'alice',
+      metadata: { app: 'assistant' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().sandbox.metadata).toEqual({ app: 'assistant' });
+    // Relabeling is not activity: the idle countdown keeps running.
+    expect(res.json().sandbox.lastActiveAt).toBe(created.sandbox.lastActiveAt);
+
+    const events = (await rpc(app, '/listActivity')).json().events;
+    expect(events[0]).toMatchObject({
+      kind: 'metadata-changed',
+      externalId: 'alice',
+      detail: 'app=assistant',
+    });
+  });
+
+  it('clears every label with {} and says so in the history', async () => {
+    const { app } = testApp();
+    await acquire(app, { externalId: 'alice', metadata: { app: 'crawler' } });
+    const res = await rpc(app, '/updateMetadata', {
+      externalId: 'alice',
+      metadata: {},
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().sandbox.metadata).toEqual({});
+    const events = (await rpc(app, '/listActivity')).json().events;
+    expect(events[0]).toMatchObject({
+      kind: 'metadata-changed',
+      detail: 'cleared',
+    });
+  });
+
+  it('relabels a frozen sandbox without waking it — a pure ledger write', async () => {
+    const { app, db, executor, locks } = testApp();
+    const created = (await acquire(app, { externalId: 'alice' })).json();
+    await scanOnce(
+      db,
+      executor,
+      locks,
+      after(
+        created.sandbox.lastActiveAt,
+        DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
+      ),
+    );
+    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+
+    const res = await rpc(app, '/updateMetadata', {
+      externalId: 'alice',
+      metadata: { team: 'blue' },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().sandbox.state).toBe('frozen');
+    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+  });
+
+  it('answers 404 for an unknown key — updateMetadata is not a creator', async () => {
+    const res = await rpc(testApp().app, '/updateMetadata', {
+      externalId: 'nobody',
+      metadata: { app: 'x' },
+    });
+    expect(res.statusCode).toBe(404);
+    expect(res.json().message).toMatch(/acquire it first/);
+  });
+
+  it('treats a no-change replacement as the goal state and writes no history', async () => {
+    const { app } = testApp();
+    await acquire(app, { externalId: 'alice', metadata: { app: 'crawler' } });
+    const res = await rpc(app, '/updateMetadata', {
+      externalId: 'alice',
+      metadata: { app: 'crawler' },
+    });
+    expect(res.statusCode).toBe(200);
+    const events = (await rpc(app, '/listActivity')).json().events;
+    expect(
+      events.some((e: { kind: string }) => e.kind === 'metadata-changed'),
+    ).toBe(false);
+  });
+});
+
 describe('POST /destroySandbox', () => {
   it('destroys the container and forgets the key', async () => {
     const { app, executor } = testApp();
diff --git a/packages/server/src/db/ledger.ts b/packages/server/src/db/ledger.ts
index 21fac0b..0f87394 100644
--- a/packages/server/src/db/ledger.ts
+++ b/packages/server/src/db/ledger.ts
@@ -1,4 +1,8 @@
-import type { LifecyclePolicy, SandboxState } from '@dormice/shared';
+import {
+  type LifecyclePolicy,
+  SANDBOX_STATES,
+  type SandboxState,
+} from '@dormice/shared';
 import { count, eq } from 'drizzle-orm';
 import { recordActivity } from './activity';
 import type { Db } from './db';
@@ -36,10 +40,15 @@ export interface CreateSandboxInput {
   policy: LifecyclePolicy;
   /** Template the sandbox is created from; absent/null means the base image. */
   template?: string | null;
+  /**
+   * Caller labels, JSON-serialized, stored verbatim. Both faces write it:
+   * native acquire and E2B create carry the same string→string map into the
+   * same column.
+   */
+  metadata?: string | null;
   /** E2B-surface extras; native acquire never sets them. */
   e2b?: {
-    /** JSON-serialized objects, stored verbatim. */
-    metadata: string | null;
+    /** JSON-serialized object, stored verbatim. */
     envs: string | null;
     deadlineAt: string;
     onDeadline: 'kill' | 'pause';
@@ -60,7 +69,7 @@ export function createSandbox(db: Db, input: CreateSandboxInput): SandboxRow {
     template: input.template ?? null,
     createdAt: now,
     lastActiveAt: now,
-    metadata: input.e2b?.metadata ?? null,
+    metadata: input.metadata ?? null,
     envs: input.e2b?.envs ?? null,
     deadlineAt: input.e2b?.deadlineAt ?? null,
     onDeadline: input.e2b?.onDeadline ?? null,
@@ -109,6 +118,18 @@ export function listSandboxes(db: Db): SandboxRow[] {
   return db.select().from(sandboxes).all();
 }
 
+/** State census over a listing — getHostMetrics and the metrics sampler share it. */
+export function countByState(rows: SandboxRow[]): {
+  byState: Record<SandboxState, number>;
+  total: number;
+} {
+  const byState = Object.fromEntries(
+    SANDBOX_STATES.map((state) => [state, 0]),
+  ) as Record<SandboxState, number>;
+  for (const row of rows) byState[row.state] += 1;
+  return { byState, total: rows.length };
+}
+
 /** How many sandboxes exist, for the capacity check at acquire. */
 export function countSandboxes(db: Db): number {
   return db.select({ n: count() }).from(sandboxes).get()?.n ?? 0;
@@ -183,6 +204,27 @@ export function updatePolicy(
   return row;
 }
 
+/**
+ * Replaces the label set wholesale. Ledger-only, same manners as
+ * updatePolicy: no container work, no state change, and deliberately no
+ * touch — relabeling is not sandbox activity.
+ */
+export function updateMetadata(
+  db: Db,
+  sandboxId: string,
+  metadata: string | null,
+): SandboxRow {
+  db.update(sandboxes)
+    .set({ metadata })
+    .where(eq(sandboxes.sandboxId, sandboxId))
+    .run();
+  const row = findBySandboxId(db, sandboxId);
+  if (!row) {
+    throw new Error(`sandbox ${sandboxId} not found`);
+  }
+  return row;
+}
+
 /** Marks an explicit E2B pause; wakes clear it (an awake sandbox is not paused). */
 export function setPausedByUser(
   db: Db,
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index ea966d8..7656d8f 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -6,6 +6,8 @@ import {
   destroySandboxResponseSchema,
   execCommandRequestSchema,
   execCommandResponseSchema,
+  getSandboxMetricsHistoryRequestSchema,
+  getSandboxMetricsHistoryResponseSchema,
   getSandboxMetricsRequestSchema,
   getSandboxMetricsResponseSchema,
   type LifecyclePolicy,
@@ -24,6 +26,9 @@ import {
   rebuildSandboxResponseSchema,
   resolveSandboxPath,
   type Sandbox,
+  type SandboxMetadata,
+  updateMetadataRequestSchema,
+  updateMetadataResponseSchema,
   updatePolicyRequestSchema,
   updatePolicyResponseSchema,
   WRITE_FILES_BODY_LIMIT_BYTES,
@@ -44,8 +49,15 @@ import {
   findByExternalId,
   listSandboxes,
   touch,
+  updateMetadata,
   updatePolicy,
 } from '../db/ledger';
+import {
+  bucketSamples,
+  querySandboxSamples,
+  resolveBucketSeconds,
+  resolveWindow,
+} from '../db/metrics';
 import type { SandboxRow } from '../db/schema';
 import { findTemplate, resolveImage } from '../db/templates';
 import { startExecHeartbeat } from '../exec-heartbeat';
@@ -90,11 +102,25 @@ function toSandbox(row: SandboxRow, endpoint: string): Sandbox {
       archiveAfterSeconds: row.archiveAfterSeconds,
     },
     template: row.template,
+    metadata: row.metadata ? JSON.parse(row.metadata) : {},
     createdAt: row.createdAt,
     lastActiveAt: row.lastActiveAt,
   };
 }
 
+/**
+ * Label map -> column value. An empty set is stored as NULL, not "{}": the
+ * column has meant "no labels = NULL" since the E2B surface introduced it,
+ * and the view normalizes both spellings to {} anyway.
+ */
+function serializeMetadata(
+  metadata: SandboxMetadata | undefined,
+): string | null {
+  return metadata && Object.keys(metadata).length > 0
+    ? JSON.stringify(metadata)
+    : null;
+}
+
 export const sandboxRoutes: FastifyPluginAsyncZod<
   SandboxRoutesOptions
 > = async (
@@ -116,6 +142,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     externalId: string,
     policy: LifecyclePolicy,
     template: string | null,
+    metadata: string | null,
   ): Promise<AcquireOutcome> {
     const existing = findByExternalId(db, externalId);
     if (existing?.state === 'archived' || existing?.state === 'restoring') {
@@ -153,8 +180,9 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     if (existing) {
       // Wake whatever cold state it is in (a single jump back to active),
       // then refresh the idle clock — an acquire is what "activity" means.
-      // A requested template is not applied: like policy, it takes effect
-      // only when this acquire creates the sandbox.
+      // Requested template and metadata are not applied: like policy, they
+      // take effect only when this acquire creates the sandbox (metadata
+      // has its own update verb, updateMetadata).
       const awake = await wakeSandbox(db, executor, existing);
       return { status: 'ready', row: touch(db, awake.sandboxId) };
     }
@@ -187,6 +215,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         nodeId: config.DORMICE_NODE_ID,
         policy,
         template,
+        metadata,
       }),
     };
   }
@@ -232,7 +261,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request, reply) => {
-      const { externalId, policy: override, template } = request.body;
+      const { externalId, policy: override, template, metadata } = request.body;
 
       // Validate the policy before taking the key's slot, so a queued
       // rejection can only come from the work itself, never from another
@@ -270,7 +299,12 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       }
 
       const outcome = await locks.run(externalId, () =>
-        findOrCreate(externalId, policy, template ?? null),
+        findOrCreate(
+          externalId,
+          policy,
+          template ?? null,
+          serializeMetadata(metadata),
+        ),
       );
       if (outcome.status === 'restoring') {
         return {
@@ -301,10 +335,11 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
   );
 
   // One sandbox's point-in-time resource reading — the native twin of the
-  // E2B metrics endpoint, same rules: a single sample (no history kept),
-  // and observation never wakes anything. A frozen sandbox is measured as
-  // it sleeps (its cgroup accounting stays readable); with no running
-  // container there is nothing to measure and the answer is an honest null.
+  // E2B metrics endpoint. Observation never wakes anything: a frozen
+  // sandbox is measured as it sleeps (its cgroup accounting stays
+  // readable); with no running container there is nothing to measure and
+  // the answer is an honest null. The past lives one verb down, in
+  // getSandboxMetricsHistory.
   app.post(
     '/getSandboxMetrics',
     {
@@ -330,6 +365,52 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     },
   );
 
+  // The sampled past of one sandbox, sliced by an optional ISO window
+  // (default: the last hour) and bucketed past 360 points — each bucket
+  // reporting per-field maxima, because history readers hunt spikes and
+  // averages erase them. An unsampled window answers an empty array; the
+  // native face never takes a live reading to fill silence (the E2B face
+  // does, as compatibility politeness — the asymmetry is deliberate).
+  // History is keyed by sandboxId under the hood, so it survives rebuilds.
+  app.post(
+    '/getSandboxMetricsHistory',
+    {
+      schema: {
+        body: getSandboxMetricsHistoryRequestSchema,
+        response: { 200: getSandboxMetricsHistoryResponseSchema },
+      },
+    },
+    async (request) => {
+      const { externalId, start, end } = request.body;
+      const row = findByExternalId(db, externalId);
+      if (!row) {
+        throw httpError(
+          404,
+          `no sandbox for key "${externalId}" — acquire it first`,
+        );
+      }
+      const { startIso, endIso, startMs, endMs } = resolveWindow(
+        start,
+        end,
+        3600_000,
+        new Date(),
+      );
+      const rows = querySandboxSamples(db, row.sandboxId, startIso, endIso);
+      const bucketSeconds = resolveBucketSeconds(rows.length, startMs, endMs);
+      const sliced =
+        bucketSeconds === null
+          ? rows
+          : bucketSamples(rows, startMs, bucketSeconds);
+      return {
+        samples: sliced.map(({ sandboxId: _, at, ...metrics }) => ({
+          timestamp: at,
+          ...metrics,
+        })),
+        bucketSeconds,
+      };
+    },
+  );
+
   // Every measurable sandbox in one answer: the list view's food. Readings
   // run in parallel because one docker-stats sample costs about a second —
   // serial would scale the answer with the fleet. Presence means measured:
@@ -738,6 +819,48 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     },
   );
 
+  app.post(
+    '/updateMetadata',
+    {
+      schema: {
+        body: updateMetadataRequestSchema,
+        response: { 200: updateMetadataResponseSchema },
+      },
+    },
+    async (request) => {
+      const { externalId, metadata } = request.body;
+      const serialized = serializeMetadata(metadata);
+      // Inside the slot for the same reason as updatePolicy: a concurrent
+      // destroy must not delete the row between check and write.
+      const row = await locks.run(externalId, async () => {
+        const existing = findByExternalId(db, externalId);
+        if (!existing) {
+          // Not a creator: an unknown key is a typo, same manners as rebuild.
+          throw httpError(
+            404,
+            `no sandbox for key "${externalId}" — acquire it first`,
+          );
+        }
+        if ((existing.metadata ?? null) === serialized) {
+          // The goal state already holds; a no-op writes no history.
+          return existing;
+        }
+        const updated = updateMetadata(db, existing.sandboxId, serialized);
+        recordActivity(db, {
+          kind: 'metadata-changed',
+          externalId,
+          sandboxId: updated.sandboxId,
+          detail:
+            Object.entries(metadata)
+              .map(([key, value]) => `${key}=${value}`)
+              .join(', ') || 'cleared',
+        });
+        return updated;
+      });
+      return { sandbox: toSandbox(row, endpoint) };
+    },
+  );
+
   app.post(
     '/destroySandbox',
     {
diff --git a/packages/shared/src/acquire.ts b/packages/shared/src/acquire.ts
index d222c1a..efe65b0 100644
--- a/packages/shared/src/acquire.ts
+++ b/packages/shared/src/acquire.ts
@@ -1,6 +1,10 @@
 import { z } from 'zod';
 import { lifecyclePolicyOverrideSchema } from './policy';
-import { externalIdSchema, sandboxSchema } from './sandbox';
+import {
+  externalIdSchema,
+  sandboxMetadataSchema,
+  sandboxSchema,
+} from './sandbox';
 import { templateNameSchema } from './templates';
 
 /**
@@ -24,6 +28,13 @@ export const acquireRequestSchema = z.object({
    * template name is still answered with a 400, never silently ignored.
    */
   template: templateNameSchema.optional(),
+  /**
+   * Labels stored when this acquire creates the sandbox; omitted means no
+   * labels. Same rules as policy: an existing sandbox keeps its stored
+   * metadata — acquire is not an update verb, updateMetadata is — but a
+   * malformed value is still answered with a 400, never silently ignored.
+   */
+  metadata: sandboxMetadataSchema.optional(),
 });
 
 export type AcquireRequest = z.infer<typeof acquireRequestSchema>;
diff --git a/packages/shared/src/activity.ts b/packages/shared/src/activity.ts
index adf9c52..d7e6d68 100644
--- a/packages/shared/src/activity.ts
+++ b/packages/shared/src/activity.ts
@@ -26,6 +26,8 @@ export const ACTIVITY_KINDS = [
   'reconciled',
   /** updatePolicy rewrote a sandbox's lifecycle thresholds (ledger-only). */
   'policy-changed',
+  /** updateMetadata replaced a sandbox's label set (ledger-only). */
+  'metadata-changed',
   'daemon-started',
   /** An operator bound or cleared the console domain through setIngress. */
   'ingress-updated',
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index d96a96d..fd2025d 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -14,5 +14,6 @@ export * from './rebuild';
 export * from './sandbox';
 export * from './states';
 export * from './templates';
+export * from './update-metadata';
 export * from './update-policy';
 export * from './upgrade';
diff --git a/packages/shared/src/sandbox.ts b/packages/shared/src/sandbox.ts
index f35e8c6..29688d9 100644
--- a/packages/shared/src/sandbox.ts
+++ b/packages/shared/src/sandbox.ts
@@ -12,6 +12,17 @@ import { templateNameSchema } from './templates';
  */
 export const externalIdSchema = z.string().min(1).max(128);
 
+/**
+ * Caller-owned labels on a sandbox — a string→string map, opaque to the
+ * daemon. Grouping is a tagging problem, not an entity problem: no project
+ * table, no tenancy, just labels the caller filters on. String values (not
+ * arbitrary JSON) because the E2B surface's metadata filter compares them
+ * as strings, and one column serves both surfaces.
+ */
+export const sandboxMetadataSchema = z.record(z.string(), z.string());
+
+export type SandboxMetadata = z.infer<typeof sandboxMetadataSchema>;
+
 /**
  * A sandbox as reported by the daemon — the wire shape shared by the HTTP
  * API, the SDK, and the web console.
@@ -38,6 +49,8 @@ export const sandboxSchema = z.object({
    * shell always boots the template's *current* image.
    */
   template: templateNameSchema.nullable(),
+  /** Always an object — `{}` when the sandbox carries no labels. */
+  metadata: sandboxMetadataSchema,
   createdAt: z.iso.datetime(),
   lastActiveAt: z.iso.datetime(),
 });
diff --git a/packages/shared/src/update-metadata.ts b/packages/shared/src/update-metadata.ts
new file mode 100644
index 0000000..8dd0988
--- /dev/null
+++ b/packages/shared/src/update-metadata.ts
@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import {
+  externalIdSchema,
+  sandboxMetadataSchema,
+  sandboxSchema,
+} from './sandbox';
+
+/**
+ * updateMetadata(externalId, metadata) — the update verb acquire deliberately
+ * is not. Without it, a sandbox could only ever be labeled at birth: the
+ * fleet you already run would be un-groupable forever.
+ *
+ * Full replacement, not a patch: metadata is one label set, and "what you
+ * send is what is stored" reads unambiguously — `{}` clears every label.
+ * Per-key patching would need a tombstone convention (null? absent?) for
+ * deletes, complexity a tag map doesn't earn.
+ *
+ * A pure ledger write, like updatePolicy: no container is touched, no wake,
+ * and the idle clock is NOT refreshed — relabeling is not sandbox activity.
+ */
+export const updateMetadataRequestSchema = z.object({
+  externalId: externalIdSchema,
+  metadata: sandboxMetadataSchema,
+});
+
+export type UpdateMetadataRequest = z.infer<typeof updateMetadataRequestSchema>;
+
+/** The sandbox as it stands after the update (state untouched). */
+export const updateMetadataResponseSchema = z.object({
+  sandbox: sandboxSchema,
+});
+
+export type UpdateMetadataResponse = z.infer<
+  typeof updateMetadataResponseSchema
+>;
diff --git a/skills/dormice/SKILL.md b/skills/dormice/SKILL.md
index ae8c938..c471d1a 100644
--- a/skills/dormice/SKILL.md
+++ b/skills/dormice/SKILL.md
@@ -108,8 +108,11 @@ curl -X POST http://127.0.0.1:3676/acquireSandbox \
   -d '{"externalId": "my-agent"}'
 ```
 
-Verbs: `acquireSandbox`, `updatePolicy` (patch an existing sandbox's
-lifecycle policy in place — no wake, no destroy), `listSandboxes`,
+Verbs: `acquireSandbox` (optionally with `metadata` — string-to-string
+labels stored at creation for grouping/filtering), `updatePolicy` (patch
+an existing sandbox's lifecycle policy in place — no wake, no destroy),
+`updateMetadata` (replace an existing sandbox's label set wholesale,
+`{}` clears — same no-wake manners), `listSandboxes`,
 `execCommand`, `writeFiles` / `writeFile`, `readFile` / `readFiles`,
 `rebuildSandbox` (fresh container, `/home/user` kept), `destroySandbox`,
 `registerTemplate` / `listTemplates` / `removeTemplate`,
@@ -133,6 +136,7 @@ dor sandbox exec my-agent 'uname -r'  # exit code passes through
 dor sandbox push my-agent ./data.csv  # → /home/user/data.csv
 dor sandbox pull my-agent notes.txt
 dor sandbox rebuild my-agent          # fresh container, /home/user kept
+dor sandbox meta my-agent app=crawler # replace labels (no args = show)
 dor sandbox destroy my-agent
 dor doctor                            # can this machine run sandboxes?
 ```
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
index 105fcd3..5472086 100644
--- a/website/content/docs/http-api.mdx
+++ b/website/content/docs/http-api.mdx
@@ -32,6 +32,7 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | --- | --- | --- |
 | `POST /acquireSandbox` | create, wake, or restore — idempotent per key | 400 invalid policy/unknown template, 429 at the sandbox limit |
 | `POST /updatePolicy` | patch an existing sandbox's [lifecycle policy](/docs/lifecycle#change-the-policy-later) in place; never wakes, never resets the idle clock | 404 unknown key, 400 invalid merged policy |
+| `POST /updateMetadata` | replace an existing sandbox's label set wholesale (`{}` clears); never wakes, never resets the idle clock | 404 unknown key |
 | `POST /listSandboxes` | every sandbox and its state; never wakes anything | — |
 | `POST /execCommand` | run a command, buffered | 404 unknown key, 409 archived/restoring |
 | `POST /writeFiles` | batch write, base64 in JSON | 404/409 as above; body over 48 MiB refused |
@@ -66,10 +67,20 @@ Everything that returns a sandbox returns this shape:
   "sandboxId": "8b1e…-uuid", "externalId": "my-agent",
   "state": "active", "nodeId": "…", "endpoint": "http://127.0.0.1:3676",
   "policy": { "freezeAfterSeconds": 600, "stopAfterSeconds": 259200, "archiveAfterSeconds": null },
-  "template": null, "createdAt": "…", "lastActiveAt": "…"
+  "template": null, "metadata": { "app": "crawler", "env": "prod" },
+  "createdAt": "…", "lastActiveAt": "…"
 }
 ```
 
+`metadata` is your own string-to-string labels — pass it to
+`acquireSandbox` at creation (`{"externalId": "…", "metadata": {"app": "crawler"}}`),
+relabel later with `updateMetadata`, group and filter on it in the
+console or your own `listSandboxes` loop. The daemon never interprets
+it; a sandbox without labels reads `{}`, never `null`. Like `policy`
+and `template`, the value on `acquireSandbox` applies only when that
+call creates the sandbox — an existing sandbox keeps its stored labels,
+which is what `updateMetadata` is for.
+
 `state` is one of `active | frozen | stopped | archived | restoring`
 (the [lifecycle states](/docs/lifecycle)). `acquireSandbox` wraps it in
 a union: `{ "status": "ready", "sandbox": … }`, or — when the sandbox is

From 81f08afaa15ee82274fb5117945b161a229135f0 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 01:59:46 +0800
Subject: [PATCH 087/133] =?UTF-8?q?Envd=20tokens=20and=20signed=20file=20U?=
 =?UTF-8?q?RLs=20stop=20deriving=20from=20the=20API=20token:=20a=20daemon?=
 =?UTF-8?q?=5Fsecrets=20singleton=20row=20carries=20an=20independent=20sig?=
 =?UTF-8?q?ning=20secret=20(born=20lazily=20at=20first=20boot=20by=20get-o?=
 =?UTF-8?q?r-create=20=E2=80=94=20a=20migration=20cannot=20mint=20randomne?=
 =?UTF-8?q?ss),=20so=20rotating=20the=20token=20no=20longer=20voids=20ever?=
 =?UTF-8?q?y=20in-flight=20envd=20token=20and=20signed=20URL,=20and=20the?=
 =?UTF-8?q?=20coming=20multi-key=20world=20has=20one=20answer=20to=20which?=
 =?UTF-8?q?=20key=20credentials=20derive=20from;=20equality=20auth=20is=20?=
 =?UTF-8?q?untouched,=20the=20compat=20suite=20pins=20the=20divorce=20?=
 =?UTF-8?q?=E2=80=94=20a=20token=20derived=20from=20the=20API=20token=20no?=
 =?UTF-8?q?=20longer=20opens=20the=20envd=20door=20=E2=80=94=20and=20crede?=
 =?UTF-8?q?ntials=20minted=20before=20this=20upgrade=20expire=20once,=20at?=
 =?UTF-8?q?=20the=20restart?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 e2e/src/e2b.test.ts                           |  41 +-
 .../server/drizzle/0008_daemon-secrets.sql    |   5 +
 .../server/drizzle/meta/0008_snapshot.json    | 456 ++++++++++++++++++
 packages/server/drizzle/meta/_journal.json    |  14 +
 packages/server/src/app.ts                    |   8 +
 packages/server/src/db/secrets.ts             |  38 ++
 packages/server/src/e2b/compat.test.ts        | 119 +++--
 packages/server/src/e2b/deps.ts               |   5 +
 packages/server/src/e2b/envd/index.ts         |   7 +-
 packages/server/src/e2b/protocol.ts           |  19 +-
 packages/server/src/e2b/signed-files.ts       |   3 +-
 packages/server/src/e2b/signing.ts            |   4 +-
 packages/server/src/routes/console.test.ts    |  20 +-
 packages/server/src/routes/console.ts         |  25 +-
 14 files changed, 693 insertions(+), 71 deletions(-)
 create mode 100644 packages/server/drizzle/0008_daemon-secrets.sql
 create mode 100644 packages/server/drizzle/meta/0008_snapshot.json
 create mode 100644 packages/server/src/db/secrets.ts

diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index cacc892..10d05c5 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -1,4 +1,3 @@
-import { createHmac } from 'node:crypto';
 import http from 'node:http';
 import { Dormice } from '@dormice/sdk';
 import { CommandExitError, Sandbox } from 'e2b';
@@ -244,12 +243,15 @@ describe('official e2b SDK against the daemon', () => {
     }
   });
 
-  it('getMetrics answers one live sample; a killed sandbox refuses', async () => {
+  it('getMetrics answers at least one sample; a killed sandbox refuses', async () => {
     const sbx = await Sandbox.create(connection());
     try {
+      // The 1s sampler may already have rows, and the live fallback covers
+      // the window before its first tick — either way, never empty. The
+      // newest sample sits last (history is ascending).
       const metrics = await sbx.getMetrics();
-      expect(metrics).toHaveLength(1);
-      const m = metrics[0];
+      expect(metrics.length).toBeGreaterThanOrEqual(1);
+      const m = metrics.at(-1);
       if (!m) throw new Error('unreachable');
       expect(m.timestamp).toBeInstanceOf(Date);
       expect(Math.abs(m.timestamp.getTime() - Date.now())).toBeLessThan(60_000);
@@ -576,8 +578,23 @@ describe('official e2b SDK against the daemon', () => {
     const sbx = await Sandbox.create(connection());
     try {
       // The JS SDK never calls these three; drive them as raw Connect unary
-      // posts, the way a sync SDK would. The access token is the documented
-      // envd HMAC — this stays a black-box network test.
+      // posts, the way a sync SDK would. The access token comes off the
+      // wire (connect echoes it) — it derives from the daemon's signing
+      // secret, so no client can compute it locally, this test included.
+      const connectRes = await fetch(
+        `${inject('dormiceEndpoint')}/e2b/api/sandboxes/${sbx.sandboxId}/connect`,
+        {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            'x-api-key': `e2b_${inject('dormiceToken')}`,
+          },
+          body: JSON.stringify({}),
+        },
+      );
+      const { envdAccessToken } = (await connectRes.json()) as {
+        envdAccessToken: string;
+      };
       const rpc = async (method: string, body: Record<string, unknown>) => {
         const res = await fetch(
           `${inject('dormiceEndpoint')}/e2b/envd/filesystem.Filesystem/${method}`,
@@ -586,9 +603,7 @@ describe('official e2b SDK against the daemon', () => {
             headers: {
               'content-type': 'application/json',
               'e2b-sandbox-id': sbx.sandboxId,
-              'x-access-token': createHmac('sha256', inject('dormiceToken'))
-                .update(`envd:${sbx.sandboxId}`)
-                .digest('hex'),
+              'x-access-token': envdAccessToken,
             },
             body: JSON.stringify(body),
           },
@@ -752,20 +767,22 @@ describe.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
     it('metrics watch a real disk fill: dd 5 MiB and diskUsed grows', async () => {
       const sbx = await Sandbox.create(connection());
       try {
-        const before = (await sbx.getMetrics())[0];
+        // History is ascending — the NEWEST sample is last, and reading the
+        // first would keep watching a stale baseline forever.
+        const before = (await sbx.getMetrics()).at(-1);
         if (!before) throw new Error('no baseline sample');
         await sbx.commands.run(
           'dd if=/dev/zero of=/home/user/fill.bin bs=1M count=5 conv=fsync',
         );
         // Re-read until the filesystem's accounting catches up.
-        let after = (await sbx.getMetrics())[0];
+        let after = (await sbx.getMetrics()).at(-1);
         const deadline = Date.now() + 20_000;
         while (
           (after?.diskUsed ?? 0) <= before.diskUsed &&
           Date.now() < deadline
         ) {
           await sleep(0.5);
-          after = (await sbx.getMetrics())[0];
+          after = (await sbx.getMetrics()).at(-1);
         }
         expect(after?.diskUsed ?? 0).toBeGreaterThan(before.diskUsed);
       } finally {
diff --git a/packages/server/drizzle/0008_daemon-secrets.sql b/packages/server/drizzle/0008_daemon-secrets.sql
new file mode 100644
index 0000000..47353db
--- /dev/null
+++ b/packages/server/drizzle/0008_daemon-secrets.sql
@@ -0,0 +1,5 @@
+CREATE TABLE `daemon_secrets` (
+	`id` integer PRIMARY KEY NOT NULL,
+	`envd_signing_secret` text NOT NULL,
+	`created_at` text NOT NULL
+);
diff --git a/packages/server/drizzle/meta/0008_snapshot.json b/packages/server/drizzle/meta/0008_snapshot.json
new file mode 100644
index 0000000..5c888d4
--- /dev/null
+++ b/packages/server/drizzle/meta/0008_snapshot.json
@@ -0,0 +1,456 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "3eb1672c-b687-49d5-8830-e89294ffc780",
+  "prevId": "6e4558a9-bd0e-4071-b93c-d45bfd1de122",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_id": {
+          "name": "external_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "daemon_secrets": {
+      "name": "daemon_secrets",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "envd_signing_secret": {
+          "name": "envd_signing_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "fleet_snapshots": {
+      "name": "fleet_snapshots",
+      "columns": {
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active": {
+          "name": "active",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "frozen": {
+          "name": "frozen",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stopped": {
+          "name": "stopped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archived": {
+          "name": "archived",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "restoring": {
+          "name": "restoring",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "total": {
+          "name": "total",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandbox_metrics_samples": {
+      "name": "sandbox_metrics_samples",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_count": {
+          "name": "cpu_count",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_used_pct": {
+          "name": "cpu_used_pct",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_used_bytes": {
+          "name": "mem_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_total_bytes": {
+          "name": "mem_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_cache_bytes": {
+          "name": "mem_cache_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_used_bytes": {
+          "name": "disk_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_total_bytes": {
+          "name": "disk_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "sandbox_metrics_samples_sandbox_at_idx": {
+          "name": "sandbox_metrics_samples_sandbox_at_idx",
+          "columns": [
+            "sandbox_id",
+            "at"
+          ],
+          "isUnique": false
+        },
+        "sandbox_metrics_samples_at_idx": {
+          "name": "sandbox_metrics_samples_at_idx",
+          "columns": [
+            "at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_id": {
+          "name": "external_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_external_id_unique": {
+          "name": "sandboxes_external_id_unique",
+          "columns": [
+            "external_id"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index 188bf61..51c55d6 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -50,6 +50,20 @@
       "when": 1783919540066,
       "tag": "0006_external-id",
       "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "6",
+      "when": 1784125951820,
+      "tag": "0007_metrics-history",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "6",
+      "when": 1784127595513,
+      "tag": "0008_daemon-secrets",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 81df2a6..1b4f399 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -14,6 +14,7 @@ import { requireApiAuth } from './auth';
 import { type Config, type ConfigSources, configSources } from './config';
 import { getConsoleAccount } from './db/account';
 import type { Db } from './db/db';
+import { getOrCreateSigningSecret } from './db/secrets';
 import { registerE2bCompat } from './e2b';
 import { ProcessTable } from './e2b/process-table';
 import { WatcherTable } from './e2b/watcher-table';
@@ -193,6 +194,11 @@ export function buildApp({
     () => getConsoleAccount(db)?.sessionSecret ?? null,
   );
 
+  // The envd/signed-URL derivation base. Captured once — unlike the session
+  // secret there is no verb that rotates it (see db/secrets.ts) — and NOT
+  // the API token: the two credentials must rotate independently.
+  const envdSigningSecret = getOrCreateSigningSecret(db);
+
   app.register(async (api) => {
     api.addHook('onRequest', apiAuth);
     await api.register(sandboxRoutes, {
@@ -224,6 +230,7 @@ export function buildApp({
       db,
       apiAuth,
       consoleDistDir,
+      envdSigningSecret,
     });
   });
 
@@ -243,6 +250,7 @@ export function buildApp({
       watchers,
       archiver,
       archiveDefaultSeconds,
+      envdSigningSecret,
     });
   });
 
diff --git a/packages/server/src/db/secrets.ts b/packages/server/src/db/secrets.ts
new file mode 100644
index 0000000..ec605b2
--- /dev/null
+++ b/packages/server/src/db/secrets.ts
@@ -0,0 +1,38 @@
+import { randomBytes } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import type { Db } from './db';
+import { daemonSecrets } from './schema';
+
+/**
+ * The daemon's signing secret (see the schema comment for why it is not
+ * the API token). A singleton like the console account; born on the first
+ * daemon start after the migration, then permanent — no verb regenerates
+ * it, so callers may read it once at startup.
+ *
+ * Losing the ledger loses the secret and with it every in-flight envd
+ * token and signed URL — the right outcome, since it also loses the
+ * sandboxes those credentials pointed at.
+ */
+const SECRETS_ID = 1;
+
+export function getOrCreateSigningSecret(db: Db): string {
+  const existing = db
+    .select()
+    .from(daemonSecrets)
+    .where(eq(daemonSecrets.id, SECRETS_ID))
+    .get();
+  if (existing) {
+    return existing.envdSigningSecret;
+  }
+  const secret = randomBytes(32).toString('hex');
+  // Synchronous better-sqlite3 + the ledger's exclusive lock: no second
+  // writer can race this insert into a duplicate.
+  db.insert(daemonSecrets)
+    .values({
+      id: SECRETS_ID,
+      envdSigningSecret: secret,
+      createdAt: new Date().toISOString(),
+    })
+    .run();
+  return secret;
+}
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 1052a93..b2c6c27 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -12,8 +12,10 @@ import { objectKey } from '../archive/store';
 import { loadConfig } from '../config';
 import { migrateDb, openDb } from '../db/db';
 import { findBySandboxId, setDeadline } from '../db/ledger';
+import { getOrCreateSigningSecret } from '../db/secrets';
 import { FAKE_BASE_IMAGE, FakeExecutor } from '../executor/fake';
 import { KeyedQueue } from '../keyed-queue';
+import { sampleOnce } from '../metrics-sampler';
 import { scanOnce } from '../scanner';
 import { mintEnvdToken } from './protocol';
 
@@ -64,10 +66,12 @@ async function createSandbox(
   return res.json();
 }
 
-function envdHeaders(sandboxID: string) {
+// The envd token derives from the app's ledger-stored signing secret, not
+// the API token — get-or-create returns the one buildApp already minted.
+function envdHeaders(t: TestApp, sandboxID: string) {
   return {
     'e2b-sandbox-id': sandboxID,
-    'x-access-token': mintEnvdToken(TOKEN, sandboxID),
+    'x-access-token': mintEnvdToken(getOrCreateSigningSecret(t.db), sandboxID),
   };
 }
 
@@ -80,7 +84,7 @@ function envdRpc(
   return t.app.inject({
     method: 'POST',
     url: `/e2b/envd${url}`,
-    headers: envdHeaders(sandboxID),
+    headers: envdHeaders(t, sandboxID),
     payload,
   });
 }
@@ -135,7 +139,7 @@ function startCommand(
     method: 'POST',
     url: '/e2b/envd/process.Process/Start',
     headers: {
-      ...envdHeaders(sandboxID),
+      ...envdHeaders(t, sandboxID),
       'content-type': 'application/connect+json',
       ...opts.headers,
     },
@@ -149,7 +153,7 @@ function startPty(t: TestApp, sandboxID: string) {
     method: 'POST',
     url: '/e2b/envd/process.Process/Start',
     headers: {
-      ...envdHeaders(sandboxID),
+      ...envdHeaders(t, sandboxID),
       'content-type': 'application/connect+json',
     },
     payload: enveloped({
@@ -168,7 +172,7 @@ function connectProcess(t: TestApp, sandboxID: string, pid: number) {
     method: 'POST',
     url: '/e2b/envd/process.Process/Connect',
     headers: {
-      ...envdHeaders(sandboxID),
+      ...envdHeaders(t, sandboxID),
       'content-type': 'application/connect+json',
     },
     payload: enveloped({ process: { pid } }),
@@ -212,7 +216,11 @@ describe('E2B control plane', () => {
     const first = await createSandbox(t);
     const second = await createSandbox(t);
     expect(first.sandboxID).not.toBe(second.sandboxID);
-    expect(first.envdAccessToken).toBe(mintEnvdToken(TOKEN, first.sandboxID));
+    // Minted from the ledger's signing secret — deliberately NOT something
+    // the API token can recompute.
+    expect(first.envdAccessToken).toBe(
+      mintEnvdToken(getOrCreateSigningSecret(t.db), first.sandboxID),
+    );
     expect(t.executor.stateOf(first.sandboxID)).toBe('running');
   });
 
@@ -400,15 +408,14 @@ describe('E2B control plane', () => {
     expect(findBySandboxId(t.db, sandboxID)?.state).toBe('stopped');
   });
 
-  it('metrics answers one sample in SDK field names; start/end accepted, ignored', async () => {
+  it('metrics with no history takes one live reading, SDK field names', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t);
-    // start/end slice a history we do not keep — one sample, taken now.
-    const res = await control(
-      t,
-      'GET',
-      `/sandboxes/${sandboxID}/metrics?start=1&end=2`,
-    );
+    // The sampler never ticked: the window is empty, the sandbox measurable
+    // and the default window reaches "now" — the compatibility fallback
+    // answers one live sample (real E2B has data seconds after create; an
+    // empty array would read as breakage).
+    const res = await control(t, 'GET', `/sandboxes/${sandboxID}/metrics`);
     expect(res.statusCode).toBe(200);
     const samples = res.json();
     expect(samples).toHaveLength(1);
@@ -426,6 +433,43 @@ describe('E2B control plane', () => {
     expect(m.diskTotal).toBeGreaterThan(0);
   });
 
+  it('metrics slices the sampled history by start/end (unix seconds)', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    // Three sampler ticks 30s apart, in the recent past.
+    const t0 = Date.now() - 120_000;
+    for (let i = 0; i < 3; i += 1) {
+      await sampleOnce(t.db, t.executor, new Date(t0 + i * 30_000), {
+        retentionHours: 168,
+      });
+    }
+    // A window around the middle tick: exactly that sample, ISO and unix
+    // spellings agreeing.
+    const start = Math.floor((t0 + 15_000) / 1000);
+    const end = Math.floor((t0 + 45_000) / 1000);
+    const res = await control(
+      t,
+      'GET',
+      `/sandboxes/${sandboxID}/metrics?start=${start}&end=${end}`,
+    );
+    expect(res.statusCode).toBe(200);
+    const samples = res.json();
+    expect(samples).toHaveLength(1);
+    expect(samples[0].timestamp).toBe(new Date(t0 + 30_000).toISOString());
+    expect(samples[0].timestampUnix).toBe(Math.floor((t0 + 30_000) / 1000));
+
+    // An explicitly past window with no rows answers [] — the live fallback
+    // never fills a window that does not reach "now" (a reading taken now
+    // would land outside it, a lie).
+    const past = await control(
+      t,
+      'GET',
+      `/sandboxes/${sandboxID}/metrics?start=1&end=2`,
+    );
+    expect(past.statusCode).toBe(200);
+    expect(past.json()).toEqual([]);
+  });
+
   it('metrics reads a frozen sandbox without waking it; a stopped one answers []', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t, { timeout: 86400 });
@@ -437,13 +481,15 @@ describe('E2B control plane', () => {
     await scanOnce(t.db, t.executor, t.locks, later);
     expect(t.executor.stateOf(sandboxID)).toBe('paused');
 
+    // No history: the fallback measures the paused container as it sleeps.
     const frozen = await control(t, 'GET', `/sandboxes/${sandboxID}/metrics`);
     expect(frozen.statusCode).toBe(200);
     expect(frozen.json()).toHaveLength(1);
     // Observation is not activity: still paused afterwards.
     expect(t.executor.stateOf(sandboxID)).toBe('paused');
 
-    // keepMemory:false parks it stopped — nothing runs, so no samples.
+    // keepMemory:false parks it stopped — nothing runs, no history was
+    // sampled, and the fallback refuses to measure a dead container.
     await control(t, 'POST', `/sandboxes/${sandboxID}/pause`, {
       memory: false,
     });
@@ -560,6 +606,23 @@ describe('E2B envd surface', () => {
     expect(res.json().code).toBe('unauthenticated');
   });
 
+  it('a token derived from the API token no longer opens the envd door', async () => {
+    // The decoupling pin: envd tokens derive from the ledger's signing
+    // secret. If someone re-couples them to the API token, this goes red.
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const res = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/filesystem.Filesystem/Stat',
+      headers: {
+        'e2b-sandbox-id': sandboxID,
+        'x-access-token': mintEnvdToken(TOKEN, sandboxID),
+      },
+      payload: { path: '/home/user' },
+    });
+    expect(res.statusCode).toBe(401);
+  });
+
   it('files round-trip over plain HTTP: multipart up, raw bytes down, content-length exact', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t);
@@ -580,7 +643,7 @@ describe('E2B envd surface', () => {
       method: 'POST',
       url: '/e2b/envd/files?username=user',
       headers: {
-        ...envdHeaders(sandboxID),
+        ...envdHeaders(t, sandboxID),
         'content-type': `multipart/form-data; boundary=${boundary}`,
       },
       payload: body,
@@ -593,7 +656,7 @@ describe('E2B envd surface', () => {
     const down = await t.app.inject({
       method: 'GET',
       url: '/e2b/envd/files?path=/home/user/nested/up.txt&username=user',
-      headers: envdHeaders(sandboxID),
+      headers: envdHeaders(t, sandboxID),
     });
     expect(down.statusCode).toBe(200);
     expect(down.headers['content-length']).toBe(String(content.length));
@@ -602,7 +665,7 @@ describe('E2B envd surface', () => {
     const missing = await t.app.inject({
       method: 'GET',
       url: '/e2b/envd/files?path=/home/user/void.txt',
-      headers: envdHeaders(sandboxID),
+      headers: envdHeaders(t, sandboxID),
     });
     expect(missing.statusCode).toBe(404);
     expect(missing.json().code).toBe('not_found');
@@ -615,7 +678,7 @@ describe('E2B envd surface', () => {
       method: 'POST',
       url: '/e2b/envd/files?path=raw.bin&username=user',
       headers: {
-        ...envdHeaders(sandboxID),
+        ...envdHeaders(t, sandboxID),
         'content-type': 'application/octet-stream',
       },
       payload: Buffer.from([1, 2, 3, 250]),
@@ -637,7 +700,7 @@ describe('E2B envd surface', () => {
       method: 'POST',
       url: '/e2b/envd/files?path=zipped.txt&username=user',
       headers: {
-        ...envdHeaders(sandboxID),
+        ...envdHeaders(t, sandboxID),
         'content-type': 'application/octet-stream',
         'content-encoding': 'gzip',
       },
@@ -648,7 +711,7 @@ describe('E2B envd surface', () => {
     const down = await t.app.inject({
       method: 'GET',
       url: '/e2b/envd/files?path=zipped.txt&username=user',
-      headers: envdHeaders(sandboxID),
+      headers: envdHeaders(t, sandboxID),
     });
     expect(down.body).toBe(plain);
   });
@@ -670,7 +733,7 @@ describe('E2B envd surface', () => {
       method: 'POST',
       url: '/e2b/envd/files?path=/home/user/dir/f.txt',
       headers: {
-        ...envdHeaders(sandboxID),
+        ...envdHeaders(t, sandboxID),
         'content-type': 'application/octet-stream',
       },
       payload: 'content!',
@@ -828,14 +891,14 @@ describe('E2B envd surface', () => {
     const stat = await t.app.inject({
       method: 'POST',
       url: '/e2b/envd/filesystem.Filesystem/Stat',
-      headers: { ...envdHeaders(sandboxID), ...basic('root') },
+      headers: { ...envdHeaders(t, sandboxID), ...basic('root') },
       payload: { path: '/home/user' },
     });
     expect(stat.statusCode).toBe(200);
     const statRefused = await t.app.inject({
       method: 'POST',
       url: '/e2b/envd/filesystem.Filesystem/Stat',
-      headers: { ...envdHeaders(sandboxID), ...basic('nobody') },
+      headers: { ...envdHeaders(t, sandboxID), ...basic('nobody') },
       payload: { path: '/home/user' },
     });
     expect(statRefused.statusCode).toBe(401);
@@ -848,7 +911,7 @@ describe('E2B envd surface', () => {
     const filesRefused = await t.app.inject({
       method: 'GET',
       url: '/e2b/envd/files?path=x&username=nobody',
-      headers: envdHeaders(sandboxID),
+      headers: envdHeaders(t, sandboxID),
     });
     expect(filesRefused.statusCode).toBe(401);
     expect(filesRefused.json().message).toBe("invalid username: 'nobody'");
@@ -1176,7 +1239,7 @@ describe('E2B envd surface', () => {
       method: 'POST',
       url: '/e2b/envd/filesystem.Filesystem/WatchDir',
       headers: {
-        ...envdHeaders(sandboxID),
+        ...envdHeaders(t, sandboxID),
         'content-type': 'application/connect+json',
         'connect-timeout-ms': String(deadlineMs),
       },
@@ -1405,7 +1468,7 @@ async function putFile(
     method: 'POST',
     url: `/e2b/envd/files?path=${encodeURIComponent(path)}`,
     headers: {
-      ...envdHeaders(sandboxID),
+      ...envdHeaders(t, sandboxID),
       'content-type': 'application/octet-stream',
     },
     payload: content,
@@ -1497,7 +1560,7 @@ describe('signed file URLs at the daemon root', () => {
     const back = await t.app.inject({
       method: 'GET',
       url: '/e2b/envd/files?path=signed/oct.txt',
-      headers: envdHeaders(sandboxID),
+      headers: envdHeaders(t, sandboxID),
     });
     expect(back.body).toBe('octets through the signed door\n');
   });
diff --git a/packages/server/src/e2b/deps.ts b/packages/server/src/e2b/deps.ts
index 4337863..9e5e1b6 100644
--- a/packages/server/src/e2b/deps.ts
+++ b/packages/server/src/e2b/deps.ts
@@ -26,4 +26,9 @@ export interface E2bDeps {
   archiver?: Archiver;
   /** buildApp's one adjudication of the archive policy default (null = off). */
   archiveDefaultSeconds: number | null;
+  /**
+   * HMAC key for envd access tokens and signed URLs — the ledger's
+   * signing secret, never the API token (they rotate independently).
+   */
+  envdSigningSecret: string;
 }
diff --git a/packages/server/src/e2b/envd/index.ts b/packages/server/src/e2b/envd/index.ts
index c339e0e..d7648c6 100644
--- a/packages/server/src/e2b/envd/index.ts
+++ b/packages/server/src/e2b/envd/index.ts
@@ -25,7 +25,7 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   app,
   deps,
 ) => {
-  const { config, db } = deps;
+  const { db } = deps;
   await app.register(multipart, {
     limits: {
       // The disk quota is the ceiling; a route-level cap would just be a
@@ -84,10 +84,7 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     const sandboxId = sandboxIdOf(request);
     const header = request.headers['x-access-token'];
     const token = Array.isArray(header) ? header[0] : header;
-    if (
-      !token ||
-      !verifyEnvdToken(config.DORMICE_API_TOKEN, sandboxId, token)
-    ) {
+    if (!token || !verifyEnvdToken(deps.envdSigningSecret, sandboxId, token)) {
       throw new E2bError(401, 'unauthenticated', 'invalid envd access token');
     }
   });
diff --git a/packages/server/src/e2b/protocol.ts b/packages/server/src/e2b/protocol.ts
index b2b4a0d..0755b81 100644
--- a/packages/server/src/e2b/protocol.ts
+++ b/packages/server/src/e2b/protocol.ts
@@ -55,25 +55,30 @@ export function connectError(code: string, message: string): E2bError {
 const sha256 = (value: string) => createHash('sha256').update(value).digest();
 
 /**
- * The per-sandbox envd access token: HMAC(API token, sandbox id). Stateless
- * — any daemon holding the API token can verify it without a lookup, and
- * the SDK treats the value as opaque (it just echoes what create returned).
+ * The per-sandbox envd access token: HMAC(signing secret, sandbox id).
+ * Stateless — the daemon verifies without a lookup, and the SDK treats the
+ * value as opaque (it just echoes what create returned). Keyed by the
+ * ledger's signing secret, not the API token, so the two credentials
+ * rotate independently — no client can (or should) recompute this.
  */
-export function mintEnvdToken(apiToken: string, sandboxId: string): string {
-  return createHmac('sha256', apiToken)
+export function mintEnvdToken(
+  signingSecret: string,
+  sandboxId: string,
+): string {
+  return createHmac('sha256', signingSecret)
     .update(`envd:${sandboxId}`)
     .digest('hex');
 }
 
 export function verifyEnvdToken(
-  apiToken: string,
+  signingSecret: string,
   sandboxId: string,
   presented: string,
 ): boolean {
   // Hash both sides so timingSafeEqual gets equal lengths, constant-time.
   return timingSafeEqual(
     sha256(presented),
-    sha256(mintEnvdToken(apiToken, sandboxId)),
+    sha256(mintEnvdToken(signingSecret, sandboxId)),
   );
 }
 
diff --git a/packages/server/src/e2b/signed-files.ts b/packages/server/src/e2b/signed-files.ts
index b4f8929..edc9c51 100644
--- a/packages/server/src/e2b/signed-files.ts
+++ b/packages/server/src/e2b/signed-files.ts
@@ -24,7 +24,6 @@ export const signedFileRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   app,
   deps,
 ) => {
-  const { config } = deps;
   // Same parser set as the envd surface: the upload shapes are identical.
   await app.register(multipart, {
     limits: {
@@ -87,7 +86,7 @@ export const signedFileRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         : Number(query.signature_expiration);
     const row = findRowBySignature(
       deps.db,
-      config.DORMICE_API_TOKEN,
+      deps.envdSigningSecret,
       {
         path: query.path ?? '',
         operation,
diff --git a/packages/server/src/e2b/signing.ts b/packages/server/src/e2b/signing.ts
index 0a86e19..1cd73e2 100644
--- a/packages/server/src/e2b/signing.ts
+++ b/packages/server/src/e2b/signing.ts
@@ -54,7 +54,7 @@ const sha256 = (value: string) => createHash('sha256').update(value).digest();
  */
 export function findRowBySignature(
   db: Db,
-  apiToken: string,
+  signingSecret: string,
   material: SignatureMaterial,
   presented: string,
 ): SandboxRow | undefined {
@@ -62,7 +62,7 @@ export function findRowBySignature(
   for (const row of listSandboxes(db)) {
     if (e2bView(row, now) === 'dead') continue;
     const expected = fileSignature(
-      mintEnvdToken(apiToken, row.sandboxId),
+      mintEnvdToken(signingSecret, row.sandboxId),
       material,
     );
     if (timingSafeEqual(sha256(expected), sha256(presented))) return row;
diff --git a/packages/server/src/routes/console.test.ts b/packages/server/src/routes/console.test.ts
index a59b968..c15fc76 100644
--- a/packages/server/src/routes/console.test.ts
+++ b/packages/server/src/routes/console.test.ts
@@ -16,7 +16,6 @@ import {
 } from '../auth';
 import { loadConfig } from '../config';
 import { migrateDb, openDb } from '../db/db';
-import { verifyEnvdToken } from '../e2b/protocol';
 import { FakeExecutor } from '../executor/fake';
 import { KeyedQueue } from '../keyed-queue';
 
@@ -320,16 +319,29 @@ describe('POST /console/envdToken', () => {
     });
   }
 
-  it('a session cookie mints the exact token the envd surface verifies', async () => {
+  it('a session cookie mints the exact token the envd surface accepts', async () => {
     const app = testApp();
     await setup(app);
     const cookie = sessionCookie(await login(app));
     const res = await mint(app, cookie.value);
     expect(res.statusCode).toBe(200);
     const { envdAccessToken } = res.json() as { envdAccessToken: string };
-    expect(verifyEnvdToken(TOKEN, 'sb-terminal', envdAccessToken)).toBe(true);
+    // The envd surface itself is the judge — the token derives from the
+    // ledger's signing secret, which nothing outside the daemon (this test
+    // included) can recompute. Auth passing shows as anything-but-401.
+    const probe = (sandboxId: string) =>
+      app.inject({
+        method: 'POST',
+        url: '/e2b/envd/filesystem.Filesystem/Stat',
+        headers: {
+          'e2b-sandbox-id': sandboxId,
+          'x-access-token': envdAccessToken,
+        },
+        payload: { path: '/home/user' },
+      });
+    expect((await probe('sb-terminal')).statusCode).not.toBe(401);
     // Per-sandbox: the same token opens no other sandbox.
-    expect(verifyEnvdToken(TOKEN, 'sb-other', envdAccessToken)).toBe(false);
+    expect((await probe('sb-other')).statusCode).toBe(401);
   });
 
   it('goes through the API-wide arbiter: no console header, no token', async () => {
diff --git a/packages/server/src/routes/console.ts b/packages/server/src/routes/console.ts
index 28452b6..23c8ae8 100644
--- a/packages/server/src/routes/console.ts
+++ b/packages/server/src/routes/console.ts
@@ -28,6 +28,11 @@ export interface ConsoleRoutesOptions {
    * /console answers an honest 404 instead of guessing at paths.
    */
   consoleDistDir?: string;
+  /**
+   * HMAC key for the envd tokens this surface mints — the ledger's signing
+   * secret, never the API token (they rotate independently).
+   */
+  envdSigningSecret: string;
 }
 
 // No Secure flag: the daemon speaks plain http on 127.0.0.1 by design, and
@@ -54,7 +59,7 @@ const messageResponse = z.object({ message: z.string() });
  */
 export const consoleRoutes: FastifyPluginAsyncZod<
   ConsoleRoutesOptions
-> = async (app, { config, db, apiAuth, consoleDistDir }) => {
+> = async (app, { config, db, apiAuth, consoleDistDir, envdSigningSecret }) => {
   // Per-app, not module-global: each daemon (and each test app) gets its
   // own counters. Shared by login and setup — both are credential guesses.
   const throttle = new LoginThrottle();
@@ -188,12 +193,13 @@ export const consoleRoutes: FastifyPluginAsyncZod<
   );
 
   // The console's terminal speaks to the envd surface directly — the same
-  // wire the e2b SDK uses — but envd auth is the per-sandbox HMAC, which
-  // only an API-token holder can compute and the browser deliberately is
-  // not one. This trades the session for exactly one sandbox's token; the
-  // API-wide arbiter guards it, so the cookie path also needs the console
-  // header. Minting is stateless on purpose (like the token itself): a
-  // made-up sandboxId yields a token that opens nothing.
+  // wire the e2b SDK uses — but envd auth is the per-sandbox HMAC keyed by
+  // the daemon's signing secret, which never leaves the daemon and the
+  // browser deliberately never holds. This trades the session for exactly
+  // one sandbox's token; the API-wide arbiter guards it, so the cookie path
+  // also needs the console header. Minting is stateless on purpose (like
+  // the secret itself): a made-up sandboxId yields a token that opens
+  // nothing.
   app.post(
     '/console/envdToken',
     {
@@ -206,10 +212,7 @@ export const consoleRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => ({
-      envdAccessToken: mintEnvdToken(
-        config.DORMICE_API_TOKEN,
-        request.body.sandboxId,
-      ),
+      envdAccessToken: mintEnvdToken(envdSigningSecret, request.body.sandboxId),
     }),
   );
 

From a93dc909f0f7a9a808c85d61099ac17f6bab6efc Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 02:13:18 +0800
Subject: [PATCH 088/133] The metrics history chain survives its own review,
 four honesty gaps closed: E2B start/end seconds beyond what a JS Date can
 represent get their 400 at the door instead of a RangeError-turned-500 (the
 same rejection the native verbs already had from isoTimestampSchema), the
 gap-breaking rule that snaps a curve over daemon downtime moves from two
 divergent copies into one shared home, switching a time range keeps the
 previous answer on screen instead of collapsing the card to skeletons
 (keepPreviousData), a still-loading history shows a spinner instead of
 falsely claiming the window holds no trend, and the copy stops hardcoding the
 30-second sampling interval that is in fact a knob

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../overview/components/FleetOverview.tsx     | 55 ++++++-------------
 .../overview/hooks/useFleetTimeline.ts        |  8 ++-
 .../sandboxes/components/MetricsPanel.tsx     | 48 ++++++----------
 .../features/sandboxes/hooks/useSandboxes.ts  | 15 +++--
 packages/console/src/lib/chart-gaps.ts        | 46 ++++++++++++++++
 packages/server/src/e2b/compat.test.ts        |  9 +++
 packages/server/src/e2b/control.ts            | 18 +++++-
 7 files changed, 120 insertions(+), 79 deletions(-)
 create mode 100644 packages/console/src/lib/chart-gaps.ts

diff --git a/packages/console/src/features/overview/components/FleetOverview.tsx b/packages/console/src/features/overview/components/FleetOverview.tsx
index 46c928e..a2cfdc8 100644
--- a/packages/console/src/features/overview/components/FleetOverview.tsx
+++ b/packages/console/src/features/overview/components/FleetOverview.tsx
@@ -34,6 +34,7 @@ import {
 import { Skeleton } from '@/components/ui/skeleton';
 import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
 import { STATE_COLORS, STATE_LABELS } from '@/features/sandboxes/format';
+import { withGapBreaks } from '@/lib/chart-gaps';
 import { pctOf } from '@/lib/format';
 import { cn } from '@/lib/utils';
 import {
@@ -65,10 +66,8 @@ const chartConfig = Object.fromEntries(
 type ChartRow = { at: number } & Record<SandboxState, number | null>;
 
 /**
- * 时间线点 → 图表行,并在采样断档处插一行 null:daemon 停机的时段
- * 曲线要如实断开(connectNulls 关着),不许把空窗连成一条谎线。断档
- * 的判据是点距超过期望间距的 3 倍 — 期望间距优先用服务端的桶宽,原始
- * 样本则取中位点距(采样间隔是服务端配置,客户端不猜死值)。
+ * 时间线点 → 图表行;断档处由 withGapBreaks 插一行全 null,daemon
+ * 停机的时段曲线如实断开(connectNulls 关着)。
  */
 function toChartRows(
   points: GetFleetTimelineResponse['points'],
@@ -78,39 +77,19 @@ function toChartRows(
     at: Date.parse(p.at),
     ...p.byState,
   }));
-  const first = rows[0];
-  if (rows.length < 2 || first === undefined) return rows;
-
-  const deltas: number[] = [];
-  for (let i = 1; i < rows.length; i++) {
-    const prev = rows[i - 1];
-    const cur = rows[i];
-    if (prev !== undefined && cur !== undefined) deltas.push(cur.at - prev.at);
-  }
-  deltas.sort((a, b) => a - b);
-  const expectedMs =
-    bucketSeconds !== null
-      ? bucketSeconds * 1000
-      : (deltas[Math.floor(deltas.length / 2)] ?? 0);
-
-  const withGaps: ChartRow[] = [first];
-  for (let i = 1; i < rows.length; i++) {
-    const prev = rows[i - 1];
-    const cur = rows[i];
-    if (prev === undefined || cur === undefined) continue;
-    if (expectedMs > 0 && cur.at - prev.at > 3 * expectedMs) {
-      withGaps.push({
-        at: Math.round((prev.at + cur.at) / 2),
-        active: null,
-        frozen: null,
-        stopped: null,
-        archived: null,
-        restoring: null,
-      });
-    }
-    withGaps.push(cur);
-  }
-  return withGaps;
+  return withGapBreaks(
+    rows,
+    bucketSeconds,
+    (row) => row.at,
+    (at) => ({
+      at,
+      active: null,
+      frozen: null,
+      stopped: null,
+      archived: null,
+      restoring: null,
+    }),
+  );
 }
 
 /** 长窗口给日期,短窗口给钟点 — 刻度只说这个窗口内有区分度的部分。 */
@@ -294,7 +273,7 @@ export function FleetOverview() {
               <EmptyHeader>
                 <EmptyTitle>窗口内还没有走势可画</EmptyTitle>
                 <EmptyDescription>
-                  daemon 每 30 秒落一次采样,攒够两个点就开始画;daemon
+                  daemon 定期落采样(默认每 30 秒),攒够两个点就开始画; daemon
                   停机的时段没有采样,曲线会如实断开。
                 </EmptyDescription>
               </EmptyHeader>
diff --git a/packages/console/src/features/overview/hooks/useFleetTimeline.ts b/packages/console/src/features/overview/hooks/useFleetTimeline.ts
index f36e49f..e2a5e38 100644
--- a/packages/console/src/features/overview/hooks/useFleetTimeline.ts
+++ b/packages/console/src/features/overview/hooks/useFleetTimeline.ts
@@ -1,4 +1,4 @@
-import { useQuery } from '@tanstack/react-query';
+import { keepPreviousData, useQuery } from '@tanstack/react-query';
 import { getFleetTimeline } from '@/lib/api';
 
 /** 时间档位与其毫秒宽度 — 切换器与查询共用一份。 */
@@ -19,9 +19,10 @@ export function rangeSpanMs(key: TimelineRangeKey): number {
 }
 
 /**
- * 舰队时间线,跟随档位轮询。30 秒一刷 — 与 daemon 的采样间隔同步,
+ * 舰队时间线,跟随档位轮询。30 秒一刷 — 与 daemon 的默认采样间隔同步,
  * 更快只是重复读到同一批快照。窗口在每次 queryFn 里现算,所以长开的
- * 页面窗口会随时间滑动。
+ * 页面窗口会随时间滑动。切换档位时沿用上一档的数据顶住新答案到来
+ * (keepPreviousData),整卡不塌回骨架屏。
  */
 export function useFleetTimeline(range: TimelineRangeKey) {
   return useQuery({
@@ -36,5 +37,6 @@ export function useFleetTimeline(range: TimelineRangeKey) {
     },
     refetchInterval: 30_000,
     retry: false,
+    placeholderData: keepPreviousData,
   });
 }
diff --git a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
index 02f6bb0..d5d14cd 100644
--- a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
@@ -23,6 +23,7 @@ import {
 } from '@/components/ui/empty';
 import { Spinner } from '@/components/ui/spinner';
 import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
+import { withGapBreaks } from '@/lib/chart-gaps';
 import { formatBytes, pctOf } from '@/lib/format';
 import { cn } from '@/lib/utils';
 import { since } from '../format';
@@ -115,10 +116,8 @@ const fullClock = (ms: number) =>
 type SeriesPoint = { at: number; value: number | null };
 
 /**
- * 样本 → 单序列,并在采样断档处插一个 null 点:沙箱停着或 daemon 停机
- * 的时段没有样本,曲线要如实断开(connectNulls 关着),不许连成谎线。
- * 断档判据 = 点距超过期望间距 3 倍;期望间距优先用服务端桶宽,原始样本
- * 取中位点距。
+ * 样本 → 单序列;断档处由 withGapBreaks 插一个 null 点,沙箱停着或
+ * daemon 停机的时段曲线如实断开(connectNulls 关着)。
  */
 function toSeries(
   samples: SandboxMetricsSample[],
@@ -129,32 +128,12 @@ function toSeries(
     at: Date.parse(s.timestamp),
     value: pick(s),
   }));
-  const first = points[0];
-  if (points.length < 2 || first === undefined) return points;
-
-  const deltas: number[] = [];
-  for (let i = 1; i < points.length; i++) {
-    const prev = points[i - 1];
-    const cur = points[i];
-    if (prev !== undefined && cur !== undefined) deltas.push(cur.at - prev.at);
-  }
-  deltas.sort((a, b) => a - b);
-  const expectedMs =
-    bucketSeconds !== null
-      ? bucketSeconds * 1000
-      : (deltas[Math.floor(deltas.length / 2)] ?? 0);
-
-  const withGaps: SeriesPoint[] = [first];
-  for (let i = 1; i < points.length; i++) {
-    const prev = points[i - 1];
-    const cur = points[i];
-    if (prev === undefined || cur === undefined) continue;
-    if (expectedMs > 0 && cur.at - prev.at > 3 * expectedMs) {
-      withGaps.push({ at: Math.round((prev.at + cur.at) / 2), value: null });
-    }
-    withGaps.push(cur);
-  }
-  return withGaps;
+  return withGapBreaks(
+    points,
+    bucketSeconds,
+    (p) => p.at,
+    (at) => ({ at, value: null }),
+  );
 }
 
 /**
@@ -327,13 +306,18 @@ export function MetricsPanel({ sandbox }: { sandbox: Sandbox }) {
         <Alert variant="destructive">
           <AlertDescription>{history.error.message}</AlertDescription>
         </Alert>
+      ) : history.isPending ? (
+        // 历史还在路上时不许说"没有走势"— 空态是断言,loading 不是。
+        <div className="flex items-center gap-2 text-sm text-muted-foreground">
+          <Spinner /> 读取历史走势
+        </div>
       ) : samples.length < 2 ? (
         <Empty className="border border-dashed">
           <EmptyHeader>
             <EmptyTitle>窗口内还没有走势可画</EmptyTitle>
             <EmptyDescription>
-              daemon 每 30 秒采一次样,攒够两个点就开始画;沙箱停着或 daemon
-              停机的时段没有样本,曲线会如实断开。
+              daemon 定期采样(默认每 30 秒),攒够两个点就开始画;沙箱停着 或
+              daemon 停机的时段没有样本,曲线会如实断开。
             </EmptyDescription>
           </EmptyHeader>
         </Empty>
diff --git a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
index 7c15fb2..ebfb735 100644
--- a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
+++ b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
@@ -1,5 +1,10 @@
 import type { AcquireRequest, LifecyclePolicyOverride } from '@dormice/shared';
-import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import {
+  keepPreviousData,
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from '@tanstack/react-query';
 import {
   acquireSandbox,
   destroySandbox,
@@ -51,9 +56,10 @@ export function useSandboxMetrics(externalId: string) {
 }
 
 /**
- * 单沙箱指标历史,30 秒一刷 — 与 daemon 采样间隔同步,更快只是重复读到
- * 同一批样本。窗口每次 queryFn 现算,长开的面板窗口随时间滑动;历史键
- * 在 sandboxId 上,换壳(rebuild)不断线。
+ * 单沙箱指标历史,30 秒一刷 — 与 daemon 的默认采样间隔同步,更快只是
+ * 重复读到同一批样本。窗口每次 queryFn 现算,长开的面板窗口随时间滑动;
+ * 历史键在 sandboxId 上,换壳(rebuild)不断线。切换档位时沿用上一档
+ * 的数据顶住新答案到来(keepPreviousData),图表不塌回空态。
  */
 export function useSandboxMetricsHistory(externalId: string, spanMs: number) {
   return useQuery({
@@ -68,6 +74,7 @@ export function useSandboxMetricsHistory(externalId: string, spanMs: number) {
     },
     refetchInterval: 30_000,
     retry: false,
+    placeholderData: keepPreviousData,
   });
 }
 
diff --git a/packages/console/src/lib/chart-gaps.ts b/packages/console/src/lib/chart-gaps.ts
new file mode 100644
index 0000000..555ee50
--- /dev/null
+++ b/packages/console/src/lib/chart-gaps.ts
@@ -0,0 +1,46 @@
+/**
+ * 采样断档处插一个 null 行:沙箱停着或 daemon 停机的时段没有样本,
+ * 曲线要如实断开(配合 recharts 的 connectNulls={false}),不许把空窗
+ * 连成一条谎线。断档的判据是点距超过期望间距的 3 倍 — 期望间距优先用
+ * 服务端的桶宽,原始样本则取中位点距(采样间隔是服务端配置,客户端
+ * 不猜死值)。总览堆叠图与指标 tab 的走势图共用这一条规则:断在哪里
+ * 只许有一种裁决。
+ *
+ * `atOf` 取一行的毫秒时刻,`gapRowAt` 造一行全 null 的断点行(时刻取
+ * 断档两端的中点)。行必须按时间升序进来 — 服务端本就按升序答。
+ */
+export function withGapBreaks<T>(
+  rows: T[],
+  bucketSeconds: number | null,
+  atOf: (row: T) => number,
+  gapRowAt: (atMs: number) => T,
+): T[] {
+  const first = rows[0];
+  if (rows.length < 2 || first === undefined) return rows;
+
+  const deltas: number[] = [];
+  for (let i = 1; i < rows.length; i++) {
+    const prev = rows[i - 1];
+    const cur = rows[i];
+    if (prev !== undefined && cur !== undefined) {
+      deltas.push(atOf(cur) - atOf(prev));
+    }
+  }
+  deltas.sort((a, b) => a - b);
+  const expectedMs =
+    bucketSeconds !== null
+      ? bucketSeconds * 1000
+      : (deltas[Math.floor(deltas.length / 2)] ?? 0);
+
+  const withGaps: T[] = [first];
+  for (let i = 1; i < rows.length; i++) {
+    const prev = rows[i - 1];
+    const cur = rows[i];
+    if (prev === undefined || cur === undefined) continue;
+    if (expectedMs > 0 && atOf(cur) - atOf(prev) > 3 * expectedMs) {
+      withGaps.push(gapRowAt(Math.round((atOf(prev) + atOf(cur)) / 2)));
+    }
+    withGaps.push(cur);
+  }
+  return withGaps;
+}
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index b2c6c27..022895b 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -468,6 +468,15 @@ describe('E2B control plane', () => {
     );
     expect(past.statusCode).toBe(200);
     expect(past.json()).toEqual([]);
+
+    // Seconds beyond what a JS Date can represent are rejected at the door
+    // as a 400 — never a RangeError-turned-500 deep in the handler.
+    const absurd = await control(
+      t,
+      'GET',
+      `/sandboxes/${sandboxID}/metrics?start=9000000000000`,
+    );
+    expect(absurd.statusCode).toBe(400);
   });
 
   it('metrics reads a frozen sandbox without waking it; a stopped one answers []', async () => {
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index 7893385..1fb8dc4 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -407,8 +407,22 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       schema: {
         querystring: z
           .object({
-            start: z.coerce.number().int().optional(),
-            end: z.coerce.number().int().optional(),
+            // Bounded to what a JS Date can represent (±8.64e15 ms, so
+            // ±8.64e12 s): past it new Date().toISOString() throws, and
+            // garbage input deserves a 400 at the door, never a 500 — the
+            // same rejection the native verbs get from isoTimestampSchema.
+            start: z.coerce
+              .number()
+              .int()
+              .gte(-8_640_000_000_000)
+              .lte(8_640_000_000_000)
+              .optional(),
+            end: z.coerce
+              .number()
+              .int()
+              .gte(-8_640_000_000_000)
+              .lte(8_640_000_000_000)
+              .optional(),
           })
           .loose(),
       },

From bcac3e07f642c8b873ad8a2699925eebb138ad04 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 02:54:13 +0800
Subject: [PATCH 089/133] The dashboard learns openasi's posture: one range
 switcher rules the page, stat cards grow big numbers and a sparkline, and the
 concurrency chart gains a host-health companion at 3:1

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../overview/components/FleetChart.tsx        | 223 ++++++++++++
 .../overview/components/FleetOverview.tsx     | 332 ------------------
 .../overview/components/FleetStatCards.tsx    |  92 +++++
 .../overview/components/HostHealthCard.tsx    | 180 ++++++++++
 .../features/overview/components/Meter.tsx    |  25 ++
 .../overview/components/OverviewCards.tsx     | 217 ------------
 .../overview/components/RangeSwitcher.tsx     |  71 ++++
 .../overview/components/SandboxDisksCard.tsx  |  44 +++
 .../overview/components/Sparkline.tsx         |  84 +++++
 .../features/overview/components/StatCard.tsx |  88 +++++
 .../console/src/features/overview/format.ts   |  28 ++
 .../features/overview/pages/OverviewPage.tsx  |  45 ++-
 12 files changed, 867 insertions(+), 562 deletions(-)
 create mode 100644 packages/console/src/features/overview/components/FleetChart.tsx
 delete mode 100644 packages/console/src/features/overview/components/FleetOverview.tsx
 create mode 100644 packages/console/src/features/overview/components/FleetStatCards.tsx
 create mode 100644 packages/console/src/features/overview/components/HostHealthCard.tsx
 create mode 100644 packages/console/src/features/overview/components/Meter.tsx
 delete mode 100644 packages/console/src/features/overview/components/OverviewCards.tsx
 create mode 100644 packages/console/src/features/overview/components/RangeSwitcher.tsx
 create mode 100644 packages/console/src/features/overview/components/SandboxDisksCard.tsx
 create mode 100644 packages/console/src/features/overview/components/Sparkline.tsx
 create mode 100644 packages/console/src/features/overview/components/StatCard.tsx
 create mode 100644 packages/console/src/features/overview/format.ts

diff --git a/packages/console/src/features/overview/components/FleetChart.tsx b/packages/console/src/features/overview/components/FleetChart.tsx
new file mode 100644
index 0000000..a19b054
--- /dev/null
+++ b/packages/console/src/features/overview/components/FleetChart.tsx
@@ -0,0 +1,223 @@
+import type { GetFleetTimelineResponse, SandboxState } from '@dormice/shared';
+import { Area, AreaChart, CartesianGrid, XAxis, YAxis } from 'recharts';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import {
+  type ChartConfig,
+  ChartContainer,
+  ChartLegend,
+  ChartLegendContent,
+  ChartTooltip,
+  ChartTooltipContent,
+} from '@/components/ui/chart';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import { Skeleton } from '@/components/ui/skeleton';
+import { STATE_COLORS, STATE_LABELS } from '@/features/sandboxes/format';
+import { cn } from '@/lib/utils';
+import { fullClock, tickFormatter } from '../format';
+import {
+  type TimelineRangeKey,
+  useFleetTimeline,
+} from '../hooks/useFleetTimeline';
+
+/**
+ * 堆叠顺序:活跃垫底(它是主角,贴着基线最好读),往上依次是越来越冷
+ * 的状态 — 面积图从下往上就是"从热到冷",与生命周期同向。
+ *
+ * 图形保持面积图不抄 openasi 的条形图:它画的是"每个桶发生了多少请求"
+ * (流量),我们画的是"每一刻各状态有多少沙箱"(存量水位)— 水位就该
+ * 用面积。
+ */
+const STACK_ORDER: SandboxState[] = [
+  'active',
+  'frozen',
+  'stopped',
+  'archived',
+  'restoring',
+];
+
+const chartConfig = Object.fromEntries(
+  STACK_ORDER.map((state) => [
+    state,
+    { label: STATE_LABELS[state], theme: STATE_COLORS[state].chart },
+  ]),
+) satisfies ChartConfig;
+
+type ChartRow = { at: number } & Record<SandboxState, number | null>;
+
+/**
+ * 时间线点 → 图表行,并在采样断档处插一行 null:daemon 停机的时段
+ * 曲线要如实断开(connectNulls 关着),不许把空窗连成一条谎线。断档
+ * 的判据是点距超过期望间距的 3 倍 — 期望间距优先用服务端的桶宽,原始
+ * 样本则取中位点距(采样间隔是服务端配置,客户端不猜死值)。
+ */
+function toChartRows(
+  points: GetFleetTimelineResponse['points'],
+  bucketSeconds: number | null,
+): ChartRow[] {
+  const rows: ChartRow[] = points.map((p) => ({
+    at: Date.parse(p.at),
+    ...p.byState,
+  }));
+  const first = rows[0];
+  if (rows.length < 2 || first === undefined) return rows;
+
+  const deltas: number[] = [];
+  for (let i = 1; i < rows.length; i++) {
+    const prev = rows[i - 1];
+    const cur = rows[i];
+    if (prev !== undefined && cur !== undefined) deltas.push(cur.at - prev.at);
+  }
+  deltas.sort((a, b) => a - b);
+  const expectedMs =
+    bucketSeconds !== null
+      ? bucketSeconds * 1000
+      : (deltas[Math.floor(deltas.length / 2)] ?? 0);
+
+  const withGaps: ChartRow[] = [first];
+  for (let i = 1; i < rows.length; i++) {
+    const prev = rows[i - 1];
+    const cur = rows[i];
+    if (prev === undefined || cur === undefined) continue;
+    if (expectedMs > 0 && cur.at - prev.at > 3 * expectedMs) {
+      withGaps.push({
+        at: Math.round((prev.at + cur.at) / 2),
+        active: null,
+        frozen: null,
+        stopped: null,
+        archived: null,
+        restoring: null,
+      });
+    }
+    withGaps.push(cur);
+  }
+  return withGaps;
+}
+
+/**
+ * 舰队并发走势卡:按状态堆叠的面积图,档位由页头的全局切换器驱动。
+ * flex 布局把图撑满卡片剩余高度 — 页面把这张卡拉到与右侧宿主健康卡
+ * 等高(3:1 网格),图有多高由卡说了算,不写死像素。
+ */
+export function FleetChart({
+  range,
+  className,
+}: {
+  range: TimelineRangeKey;
+  className?: string;
+}) {
+  const timeline = useFleetTimeline(range);
+
+  return (
+    <Card className={cn('flex flex-col', className)}>
+      <CardHeader>
+        <CardTitle>沙箱并发走势</CardTitle>
+        <CardDescription>
+          各状态沙箱数量随时间的变化 — 活跃掉下去、冻结涨上来,就是
+          「空闲即免费」在发生。
+        </CardDescription>
+      </CardHeader>
+      <CardContent className="flex min-h-0 flex-1 flex-col">
+        <FleetChartBody range={range} timeline={timeline} />
+      </CardContent>
+    </Card>
+  );
+}
+
+function FleetChartBody({
+  range,
+  timeline,
+}: {
+  range: TimelineRangeKey;
+  timeline: ReturnType<typeof useFleetTimeline>;
+}) {
+  if (timeline.isError) {
+    return (
+      <div className="flex min-h-[260px] flex-1 items-center justify-center text-sm text-destructive">
+        {timeline.error.message}
+      </div>
+    );
+  }
+
+  if (!timeline.data) {
+    return <Skeleton className="min-h-[260px] w-full flex-1 rounded-xl" />;
+  }
+
+  const { points, bucketSeconds } = timeline.data;
+  const rows = toChartRows(points, bucketSeconds);
+
+  if (rows.length < 2) {
+    return (
+      <Empty className="min-h-[260px] flex-1 border border-dashed">
+        <EmptyHeader>
+          <EmptyTitle>窗口内还没有走势可画</EmptyTitle>
+          <EmptyDescription>
+            daemon 每 30 秒落一次采样,攒够两个点就开始画;daemon
+            停机的时段没有采样,曲线会如实断开。
+          </EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    );
+  }
+
+  return (
+    <ChartContainer
+      config={chartConfig}
+      className="aspect-auto h-full min-h-[260px] w-full flex-1"
+    >
+      <AreaChart data={rows} margin={{ left: 4, right: 12, top: 4 }}>
+        <CartesianGrid vertical={false} />
+        <XAxis
+          dataKey="at"
+          type="number"
+          domain={['dataMin', 'dataMax']}
+          tickFormatter={tickFormatter(range)}
+          tickLine={false}
+          axisLine={false}
+          minTickGap={48}
+        />
+        <YAxis
+          width={36}
+          allowDecimals={false}
+          tickLine={false}
+          axisLine={false}
+          tickCount={4}
+        />
+        <ChartTooltip
+          content={
+            <ChartTooltipContent
+              labelFormatter={(_, payload) =>
+                fullClock((payload?.[0]?.payload as { at: number }).at)
+              }
+            />
+          }
+        />
+        <ChartLegend content={<ChartLegendContent />} />
+        {STACK_ORDER.map((state) => (
+          <Area
+            key={state}
+            dataKey={state}
+            stackId="fleet"
+            type="monotone"
+            stroke={`var(--color-${state})`}
+            fill={`var(--color-${state})`}
+            fillOpacity={0.35}
+            strokeWidth={2}
+            isAnimationActive={false}
+            connectNulls={false}
+          />
+        ))}
+      </AreaChart>
+    </ChartContainer>
+  );
+}
diff --git a/packages/console/src/features/overview/components/FleetOverview.tsx b/packages/console/src/features/overview/components/FleetOverview.tsx
deleted file mode 100644
index a2cfdc8..0000000
--- a/packages/console/src/features/overview/components/FleetOverview.tsx
+++ /dev/null
@@ -1,332 +0,0 @@
-import type { GetFleetTimelineResponse, SandboxState } from '@dormice/shared';
-import {
-  Activity01Icon,
-  ArrowUpRight01Icon,
-  PackageIcon,
-} from '@hugeicons/core-free-icons';
-import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
-import { Link } from '@tanstack/react-router';
-import { useState } from 'react';
-import { Area, AreaChart, CartesianGrid, XAxis, YAxis } from 'recharts';
-import { Alert, AlertDescription } from '@/components/ui/alert';
-import {
-  Card,
-  CardAction,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from '@/components/ui/card';
-import {
-  type ChartConfig,
-  ChartContainer,
-  ChartLegend,
-  ChartLegendContent,
-  ChartTooltip,
-  ChartTooltipContent,
-} from '@/components/ui/chart';
-import {
-  Empty,
-  EmptyDescription,
-  EmptyHeader,
-  EmptyTitle,
-} from '@/components/ui/empty';
-import { Skeleton } from '@/components/ui/skeleton';
-import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
-import { STATE_COLORS, STATE_LABELS } from '@/features/sandboxes/format';
-import { withGapBreaks } from '@/lib/chart-gaps';
-import { pctOf } from '@/lib/format';
-import { cn } from '@/lib/utils';
-import {
-  TIMELINE_RANGES,
-  type TimelineRangeKey,
-  useFleetTimeline,
-} from '../hooks/useFleetTimeline';
-import { useHostMetrics } from '../hooks/useHostMetrics';
-
-/**
- * 堆叠顺序:活跃垫底(它是主角,贴着基线最好读),往上依次是越来越冷
- * 的状态 — 面积图从下往上就是"从热到冷",与生命周期同向。
- */
-const STACK_ORDER: SandboxState[] = [
-  'active',
-  'frozen',
-  'stopped',
-  'archived',
-  'restoring',
-];
-
-const chartConfig = Object.fromEntries(
-  STACK_ORDER.map((state) => [
-    state,
-    { label: STATE_LABELS[state], theme: STATE_COLORS[state].chart },
-  ]),
-) satisfies ChartConfig;
-
-type ChartRow = { at: number } & Record<SandboxState, number | null>;
-
-/**
- * 时间线点 → 图表行;断档处由 withGapBreaks 插一行全 null,daemon
- * 停机的时段曲线如实断开(connectNulls 关着)。
- */
-function toChartRows(
-  points: GetFleetTimelineResponse['points'],
-  bucketSeconds: number | null,
-): ChartRow[] {
-  const rows: ChartRow[] = points.map((p) => ({
-    at: Date.parse(p.at),
-    ...p.byState,
-  }));
-  return withGapBreaks(
-    rows,
-    bucketSeconds,
-    (row) => row.at,
-    (at) => ({
-      at,
-      active: null,
-      frozen: null,
-      stopped: null,
-      archived: null,
-      restoring: null,
-    }),
-  );
-}
-
-/** 长窗口给日期,短窗口给钟点 — 刻度只说这个窗口内有区分度的部分。 */
-function tickFormatter(range: TimelineRangeKey): (ms: number) => string {
-  if (range === '7d' || range === '30d') {
-    return (ms) => {
-      const d = new Date(ms);
-      return `${d.getMonth() + 1}/${d.getDate()}`;
-    };
-  }
-  return (ms) =>
-    new Date(ms).toLocaleTimeString('zh-CN', {
-      hour12: false,
-      hour: '2-digit',
-      minute: '2-digit',
-    });
-}
-
-/** tooltip 与峰值注脚共用的完整时刻写法。 */
-function fullClock(ms: number): string {
-  return new Date(ms).toLocaleString('zh-CN', {
-    hour12: false,
-    month: 'numeric',
-    day: 'numeric',
-    hour: '2-digit',
-    minute: '2-digit',
-  });
-}
-
-function StatCard({
-  icon,
-  label,
-  value,
-  hint,
-  to,
-}: {
-  icon: NonNullable<HugeiconsProps['icon']>;
-  label: string;
-  value: string;
-  hint: string;
-  to?: string;
-}) {
-  const card = (
-    <Card size="sm">
-      <CardContent className="flex flex-col gap-2">
-        <div className="flex items-center gap-1.5 text-sm text-muted-foreground">
-          <HugeiconsIcon icon={icon} className="size-4" strokeWidth={1.8} />
-          {label}
-        </div>
-        <div className="text-2xl font-semibold tabular-nums">{value}</div>
-        <div className="text-xs text-muted-foreground">{hint}</div>
-      </CardContent>
-    </Card>
-  );
-  if (!to) return card;
-  return (
-    <Link
-      to={to}
-      className="block rounded-[min(var(--radius-4xl),24px)] transition-shadow hover:ring-2 hover:ring-primary/30"
-    >
-      {card}
-    </Link>
-  );
-}
-
-/**
- * 舰队并发一览:三张统计卡(当前活跃 5 秒一刷、窗口峰值与总数)加一张
- * 按状态堆叠的走势图。当前值来自 /getHostMetrics 快照;历史与峰值来自
- * /getFleetTimeline — daemon 的采样器 30 秒落一行,窗口峰值由原始行现算,
- * 分桶抹不掉它。
- */
-export function FleetOverview() {
-  const [range, setRange] = useState<TimelineRangeKey>('24h');
-  const host = useHostMetrics();
-  const timeline = useFleetTimeline(range);
-  const rangeLabel =
-    TIMELINE_RANGES.find((r) => r.key === range)?.label ?? range;
-
-  if (host.isError || timeline.isError) {
-    const message = host.isError
-      ? host.error.message
-      : (timeline.error?.message ?? '');
-    return (
-      <Alert variant="destructive">
-        <AlertDescription>{message}</AlertDescription>
-      </Alert>
-    );
-  }
-
-  if (!host.data || !timeline.data) {
-    // 骨架镜像真实结构:三张统计卡 + 一张图表卡,高度与加载完成后一致。
-    return (
-      <section className="flex flex-col gap-4">
-        <div className="grid gap-4 sm:grid-cols-3">
-          {['active', 'peak', 'total'].map((slot) => (
-            <Card key={slot} size="sm">
-              <CardContent className="flex flex-col gap-2">
-                <Skeleton className="h-5 w-16" />
-                <Skeleton className="h-8 w-24" />
-                <Skeleton className="h-4 w-32" />
-              </CardContent>
-            </Card>
-          ))}
-        </div>
-        <Card>
-          <CardHeader>
-            <Skeleton className="h-5 w-32" />
-            <Skeleton className="h-4 w-48" />
-          </CardHeader>
-          <CardContent>
-            <Skeleton className="h-[280px] w-full" />
-          </CardContent>
-        </Card>
-      </section>
-    );
-  }
-
-  const { sandboxes } = host.data;
-  const { points, bucketSeconds, peak } = timeline.data;
-  const rows = toChartRows(points, bucketSeconds);
-
-  return (
-    <section className="flex flex-col gap-4">
-      <div className="grid gap-4 sm:grid-cols-3">
-        <StatCard
-          icon={Activity01Icon}
-          label="当前活跃"
-          value={String(sandboxes.byState.active)}
-          hint="此刻正在运行的沙箱 — 其余状态都不占 CPU"
-        />
-        <StatCard
-          icon={ArrowUpRight01Icon}
-          label={`${rangeLabel}内峰值`}
-          value={peak === null ? '—' : String(peak.active)}
-          hint={
-            peak === null
-              ? '窗口内还没有采样'
-              : `活跃并发最高点,出现于 ${fullClock(Date.parse(peak.at))}`
-          }
-        />
-        <StatCard
-          icon={PackageIcon}
-          label="沙箱总数"
-          value={`${sandboxes.total} / ${sandboxes.maxSandboxes}`}
-          hint={`容量上限 ${sandboxes.maxSandboxes},已用 ${Math.round(pctOf(sandboxes.total, sandboxes.maxSandboxes))}%`}
-          to="/sandboxes"
-        />
-      </div>
-
-      <Card>
-        <CardHeader>
-          <CardTitle>沙箱并发走势</CardTitle>
-          <CardDescription>
-            各状态沙箱数量随时间的变化 — 活跃掉下去、冻结涨上来,就是
-            「空闲即免费」在发生。
-          </CardDescription>
-          <CardAction>
-            <ToggleGroup
-              value={[range]}
-              onValueChange={(value: unknown[]) => {
-                // base-ui 允许再点一下取消选中(空数组)— 档位必须常有,忽略。
-                const next = value[0];
-                if (typeof next === 'string') {
-                  setRange(next as TimelineRangeKey);
-                }
-              }}
-              variant="outline"
-              size="sm"
-            >
-              {TIMELINE_RANGES.map((r) => (
-                <ToggleGroupItem key={r.key} value={r.key}>
-                  {r.label}
-                </ToggleGroupItem>
-              ))}
-            </ToggleGroup>
-          </CardAction>
-        </CardHeader>
-        <CardContent>
-          {rows.length < 2 ? (
-            <Empty className={cn('border border-dashed', 'h-[280px]')}>
-              <EmptyHeader>
-                <EmptyTitle>窗口内还没有走势可画</EmptyTitle>
-                <EmptyDescription>
-                  daemon 定期落采样(默认每 30 秒),攒够两个点就开始画; daemon
-                  停机的时段没有采样,曲线会如实断开。
-                </EmptyDescription>
-              </EmptyHeader>
-            </Empty>
-          ) : (
-            <ChartContainer config={chartConfig} className="h-[280px] w-full">
-              <AreaChart data={rows} margin={{ left: 4, right: 12, top: 4 }}>
-                <CartesianGrid vertical={false} />
-                <XAxis
-                  dataKey="at"
-                  type="number"
-                  domain={['dataMin', 'dataMax']}
-                  tickFormatter={tickFormatter(range)}
-                  tickLine={false}
-                  axisLine={false}
-                  minTickGap={48}
-                />
-                <YAxis
-                  width={36}
-                  allowDecimals={false}
-                  tickLine={false}
-                  axisLine={false}
-                  tickCount={4}
-                />
-                <ChartTooltip
-                  content={
-                    <ChartTooltipContent
-                      labelFormatter={(_, payload) =>
-                        fullClock((payload?.[0]?.payload as { at: number }).at)
-                      }
-                    />
-                  }
-                />
-                <ChartLegend content={<ChartLegendContent />} />
-                {STACK_ORDER.map((state) => (
-                  <Area
-                    key={state}
-                    dataKey={state}
-                    stackId="fleet"
-                    type="monotone"
-                    stroke={`var(--color-${state})`}
-                    fill={`var(--color-${state})`}
-                    fillOpacity={0.35}
-                    strokeWidth={2}
-                    isAnimationActive={false}
-                    connectNulls={false}
-                  />
-                ))}
-              </AreaChart>
-            </ChartContainer>
-          )}
-        </CardContent>
-      </Card>
-    </section>
-  );
-}
diff --git a/packages/console/src/features/overview/components/FleetStatCards.tsx b/packages/console/src/features/overview/components/FleetStatCards.tsx
new file mode 100644
index 0000000..2342abe
--- /dev/null
+++ b/packages/console/src/features/overview/components/FleetStatCards.tsx
@@ -0,0 +1,92 @@
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { pctOf } from '@/lib/format';
+import { fullClock } from '../format';
+import {
+  TIMELINE_RANGES,
+  type TimelineRangeKey,
+  useFleetTimeline,
+} from '../hooks/useFleetTimeline';
+import { useHostMetrics } from '../hooks/useHostMetrics';
+import { Meter } from './Meter';
+import { Sparkline } from './Sparkline';
+import { StatCard, StatCardSkeleton } from './StatCard';
+
+/**
+ * 舰队三卡:当前活跃(5 秒一刷的快照 + 窗口内活跃数 sparkline)、窗口
+ * 峰值、总数/容量。当前值来自 /getHostMetrics;峰值与 sparkline 来自
+ * /getFleetTimeline — daemon 采样器 30 秒落一行,峰值由原始行现算,
+ * 分桶抹不掉它。档位由页头的全局切换器驱动。
+ */
+export function FleetStatCards({ range }: { range: TimelineRangeKey }) {
+  const host = useHostMetrics();
+  const timeline = useFleetTimeline(range);
+  const rangeLabel =
+    TIMELINE_RANGES.find((r) => r.key === range)?.label ?? range;
+
+  if (host.isError || timeline.isError) {
+    const message = host.isError
+      ? host.error.message
+      : (timeline.error?.message ?? '');
+    return (
+      <Alert variant="destructive">
+        <AlertDescription>{message}</AlertDescription>
+      </Alert>
+    );
+  }
+
+  if (!host.data || !timeline.data) {
+    return (
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+        {['active', 'peak', 'total'].map((slot) => (
+          <StatCardSkeleton key={slot} />
+        ))}
+      </div>
+    );
+  }
+
+  const { sandboxes } = host.data;
+  const { points, peak } = timeline.data;
+  const activeSeries = points.map((p) => p.byState.active);
+  const capacityPct = Math.round(
+    pctOf(sandboxes.total, sandboxes.maxSandboxes),
+  );
+
+  return (
+    <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+      <StatCard
+        label="当前活跃"
+        value={String(sandboxes.byState.active)}
+        hint="此刻正在运行的沙箱"
+        sub="其余状态都不占 CPU"
+        corner={
+          <Sparkline
+            data={activeSeries}
+            className="w-20 shrink-0 @[250px]/card:w-24"
+          />
+        }
+      />
+      <StatCard
+        label={`${rangeLabel}内峰值`}
+        value={peak === null ? '—' : String(peak.active)}
+        hint="活跃并发最高点"
+        sub={
+          peak === null
+            ? '窗口内还没有采样'
+            : `出现于 ${fullClock(Date.parse(peak.at))}`
+        }
+      />
+      <StatCard
+        label="沙箱总数"
+        value={`${sandboxes.total} / ${sandboxes.maxSandboxes}`}
+        hint={`容量上限 ${sandboxes.maxSandboxes}`}
+        sub={`已用 ${capacityPct}%`}
+        corner={
+          <div className="w-20 shrink-0 pb-1.5 @[250px]/card:w-24">
+            <Meter pct={capacityPct} />
+          </div>
+        }
+        to="/sandboxes"
+      />
+    </div>
+  );
+}
diff --git a/packages/console/src/features/overview/components/HostHealthCard.tsx b/packages/console/src/features/overview/components/HostHealthCard.tsx
new file mode 100644
index 0000000..5567f09
--- /dev/null
+++ b/packages/console/src/features/overview/components/HostHealthCard.tsx
@@ -0,0 +1,180 @@
+import {
+  CpuIcon,
+  HardDriveIcon,
+  RamMemoryIcon,
+  SnowIcon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
+import type { ReactNode } from 'react';
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import { Skeleton } from '@/components/ui/skeleton';
+import { formatBytes, pctOf } from '@/lib/format';
+import { cn } from '@/lib/utils';
+import { useHostMetrics } from '../hooks/useHostMetrics';
+import { Meter } from './Meter';
+
+function HostRow({
+  icon,
+  label,
+  value,
+  hint,
+  pct,
+}: {
+  icon: NonNullable<HugeiconsProps['icon']>;
+  label: string;
+  value: string;
+  hint: ReactNode;
+  /** Meter percentage; null renders an empty track, undefined no meter. */
+  pct?: number | null;
+}) {
+  return (
+    <div className="flex flex-col gap-1.5">
+      <div className="flex items-center justify-between gap-2">
+        <span className="flex items-center gap-1.5 text-sm font-medium">
+          <HugeiconsIcon
+            icon={icon}
+            className="size-4 text-muted-foreground"
+            strokeWidth={1.8}
+          />
+          {label}
+        </span>
+        <span className="text-sm text-muted-foreground tabular-nums">
+          {value}
+        </span>
+      </div>
+      {pct !== undefined && <Meter pct={pct} />}
+      <div className="text-xs text-muted-foreground">{hint}</div>
+    </div>
+  );
+}
+
+/**
+ * 宿主健康竖卡:主图旁边的机器体征列(对位 openasi 的 ModelStatus 卡)。
+ * Swap 和数据盘与 CPU、内存平起平坐,因为在这个平台上它们才是要命的
+ * 两个:swap 满了「空闲即免费」就完了,数据盘满了连创建都完了。沙箱
+ * 磁盘的账单在页面底部一行 — 这张卡只讲机器本身。
+ */
+export function HostHealthCard({ className }: { className?: string }) {
+  const query = useHostMetrics();
+
+  return (
+    <Card size="sm" className={cn('flex flex-col', className)}>
+      <CardHeader>
+        <CardTitle>宿主健康</CardTitle>
+        <CardDescription>这台机器的资源水位</CardDescription>
+      </CardHeader>
+      <CardContent className="flex flex-1 flex-col justify-between gap-5">
+        <HostHealthRows query={query} />
+      </CardContent>
+    </Card>
+  );
+}
+
+function HostHealthRows({
+  query,
+}: {
+  query: ReturnType<typeof useHostMetrics>;
+}) {
+  if (query.isError) {
+    return (
+      <div className="flex flex-1 items-center justify-center text-sm text-destructive">
+        {query.error.message}
+      </div>
+    );
+  }
+
+  if (!query.data) {
+    // 骨架镜像真实行解剖(标签+数值 / 量表 / 说明),四行等高不跳动。
+    return (
+      <>
+        {['cpu', 'memory', 'swap', 'data-disk'].map((slot) => (
+          <div key={slot} className="flex flex-col gap-1.5">
+            <div className="flex items-center justify-between gap-2">
+              <Skeleton className="h-5 w-16" />
+              <Skeleton className="h-5 w-12" />
+            </div>
+            <Skeleton className="h-1.5 w-full rounded-full" />
+            <Skeleton className="h-4 w-28" />
+          </div>
+        ))}
+      </>
+    );
+  }
+
+  const { host, dataDisk } = query.data;
+  const memUsed = host.memTotalBytes - host.memAvailableBytes;
+
+  return (
+    <>
+      <HostRow
+        icon={CpuIcon}
+        label="CPU"
+        value={
+          host.cpuUsedPct === null ? '—' : `${Math.round(host.cpuUsedPct)}%`
+        }
+        hint={`${host.cpuCount} 核`}
+        pct={host.cpuUsedPct}
+      />
+      <HostRow
+        icon={RamMemoryIcon}
+        label="内存"
+        value={formatBytes(memUsed)}
+        hint={`共 ${formatBytes(host.memTotalBytes)} · 可用 ${formatBytes(host.memAvailableBytes)}`}
+        pct={pctOf(memUsed, host.memTotalBytes)}
+      />
+      {host.swap === null ? (
+        <HostRow
+          icon={SnowIcon}
+          label="Swap"
+          value="—"
+          hint="此平台读不到 swap"
+        />
+      ) : host.swap.totalBytes === 0 ? (
+        <HostRow
+          icon={SnowIcon}
+          label="Swap"
+          value="未配置"
+          hint={
+            <span className="text-amber-600 dark:text-amber-500">
+              冻结依赖 swap — 见 dor doctor
+            </span>
+          }
+        />
+      ) : (
+        <HostRow
+          icon={SnowIcon}
+          label="Swap"
+          value={formatBytes(host.swap.usedBytes)}
+          hint={`共 ${formatBytes(host.swap.totalBytes)} · 冻结的沙箱住在这里`}
+          pct={pctOf(host.swap.usedBytes, host.swap.totalBytes)}
+        />
+      )}
+      {dataDisk === null ? (
+        <HostRow
+          icon={HardDriveIcon}
+          label="数据盘"
+          value="—"
+          hint="这台主机没有数据目录"
+        />
+      ) : (
+        <HostRow
+          icon={HardDriveIcon}
+          label="数据盘"
+          value={formatBytes(dataDisk.usedBytes)}
+          hint={
+            <span title={dataDisk.path}>
+              {`共 ${formatBytes(dataDisk.totalBytes)} · 剩 ${formatBytes(dataDisk.availableBytes)}`}
+            </span>
+          }
+          pct={pctOf(dataDisk.usedBytes, dataDisk.totalBytes)}
+        />
+      )}
+    </>
+  );
+}
diff --git a/packages/console/src/features/overview/components/Meter.tsx b/packages/console/src/features/overview/components/Meter.tsx
new file mode 100644
index 0000000..e630ee1
--- /dev/null
+++ b/packages/console/src/features/overview/components/Meter.tsx
@@ -0,0 +1,25 @@
+import { cn } from '@/lib/utils';
+
+/**
+ * Usage meter: the fill carries severity (quiet below 75%, amber to 90%,
+ * red past it) and the unfilled track is a lighter step of the same color,
+ * so state reads across the whole bar. Null means "no reading yet" — an
+ * empty quiet track, never a fake zero fill.
+ */
+export function Meter({ pct }: { pct: number | null }) {
+  const clamped = pct === null ? 0 : Math.min(100, Math.max(0, pct));
+  const [fill, track] =
+    clamped >= 90
+      ? ['bg-red-500', 'bg-red-500/15']
+      : clamped >= 75
+        ? ['bg-amber-500', 'bg-amber-500/15']
+        : ['bg-primary', 'bg-primary/10'];
+  return (
+    <div className={cn('h-1.5 w-full overflow-hidden rounded-full', track)}>
+      <div
+        className={cn('h-full rounded-full transition-[width]', fill)}
+        style={{ width: `${clamped}%` }}
+      />
+    </div>
+  );
+}
diff --git a/packages/console/src/features/overview/components/OverviewCards.tsx b/packages/console/src/features/overview/components/OverviewCards.tsx
deleted file mode 100644
index 619b683..0000000
--- a/packages/console/src/features/overview/components/OverviewCards.tsx
+++ /dev/null
@@ -1,217 +0,0 @@
-import {
-  CpuIcon,
-  Database01Icon,
-  HardDriveIcon,
-  RamMemoryIcon,
-  SnowIcon,
-} from '@hugeicons/core-free-icons';
-import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
-import { Link } from '@tanstack/react-router';
-import type { ReactNode } from 'react';
-import { Alert, AlertDescription } from '@/components/ui/alert';
-import { Card, CardContent } from '@/components/ui/card';
-import { Skeleton } from '@/components/ui/skeleton';
-import { formatBytes, pctOf } from '@/lib/format';
-import { cn } from '@/lib/utils';
-import { useHostMetrics } from '../hooks/useHostMetrics';
-import { QuickConnectCard } from './QuickConnectCard';
-
-/**
- * Usage meter: the fill carries severity (quiet below 75%, amber to 90%,
- * red past it) and the unfilled track is a lighter step of the same color,
- * so state reads across the whole bar. Null means "no reading yet" — an
- * empty quiet track, never a fake zero fill.
- */
-function Meter({ pct }: { pct: number | null }) {
-  const clamped = pct === null ? 0 : Math.min(100, Math.max(0, pct));
-  const [fill, track] =
-    clamped >= 90
-      ? ['bg-red-500', 'bg-red-500/15']
-      : clamped >= 75
-        ? ['bg-amber-500', 'bg-amber-500/15']
-        : ['bg-primary', 'bg-primary/10'];
-  return (
-    <div className={cn('h-1.5 w-full overflow-hidden rounded-full', track)}>
-      <div
-        className={cn('h-full rounded-full transition-[width]', fill)}
-        style={{ width: `${clamped}%` }}
-      />
-    </div>
-  );
-}
-
-function StatCard({
-  icon,
-  label,
-  value,
-  hint,
-  pct,
-  to,
-}: {
-  icon: NonNullable<HugeiconsProps['icon']>;
-  label: string;
-  value: string;
-  hint: ReactNode;
-  /** Meter percentage; null renders an empty track, undefined no meter. */
-  pct?: number | null;
-  /** Route this card drills into; only cards with a real destination get one. */
-  to?: string;
-}) {
-  const card = (
-    <Card size="sm">
-      <CardContent className="flex flex-col gap-2">
-        <div className="flex items-center gap-1.5 text-sm text-muted-foreground">
-          <HugeiconsIcon icon={icon} className="size-4" strokeWidth={1.8} />
-          {label}
-        </div>
-        <div className="text-2xl font-semibold">{value}</div>
-        <div className="text-xs text-muted-foreground">{hint}</div>
-        {pct !== undefined && <Meter pct={pct} />}
-      </CardContent>
-    </Card>
-  );
-  if (!to) return card;
-  // Radius mirrors the Card's own, so the focus/hover ring hugs the shape.
-  return (
-    <Link
-      to={to}
-      className="block rounded-[min(var(--radius-4xl),24px)] transition-shadow hover:ring-2 hover:ring-primary/30"
-    >
-      {card}
-    </Link>
-  );
-}
-
-/**
- * The dashboard's host rows: is the machine healthy, and what do the
- * sandbox disks cost it? Swap and the data disk get equal billing with CPU
- * and memory because on this platform they are the two that kill: full
- * swap ends "idle is free", a full data disk ends creation entirely. The
- * fleet's own numbers (counts, states, the concurrency curve) live in
- * FleetOverview above — this section is the machine's story. The quick
- * connect card is static and shares the bottom row, so loading and loaded
- * states keep the same shape.
- */
-export function OverviewCards() {
-  const query = useHostMetrics();
-
-  if (query.isError) {
-    return (
-      <Alert variant="destructive">
-        <AlertDescription>{query.error.message}</AlertDescription>
-      </Alert>
-    );
-  }
-
-  if (!query.data) {
-    // Skeletons mirror the real card anatomy (label / value / hint / meter)
-    // and both rows, block heights matched to the text line heights — the
-    // loading and loaded states are the same height, so nothing jumps.
-    const bones = (slot: string) => (
-      <Card key={slot} size="sm">
-        <CardContent className="flex flex-col gap-2">
-          <Skeleton className="h-5 w-16" />
-          <Skeleton className="h-8 w-24" />
-          <Skeleton className="h-4 w-32" />
-          <Skeleton className="h-1.5 w-full rounded-full" />
-        </CardContent>
-      </Card>
-    );
-    return (
-      <section className="flex flex-col gap-4">
-        <div className="grid gap-4 sm:grid-cols-2 xl:grid-cols-4">
-          {['cpu', 'memory', 'swap', 'data-disk'].map(bones)}
-        </div>
-        <div className="grid gap-4 md:grid-cols-2">
-          {bones('sandbox-disks')}
-          <QuickConnectCard />
-        </div>
-      </section>
-    );
-  }
-
-  const { host, dataDisk, sandboxDisks } = query.data;
-  const memUsed = host.memTotalBytes - host.memAvailableBytes;
-
-  return (
-    <section className="flex flex-col gap-4">
-      <div className="grid gap-4 sm:grid-cols-2 xl:grid-cols-4">
-        <StatCard
-          icon={CpuIcon}
-          label="CPU"
-          value={
-            host.cpuUsedPct === null ? '—' : `${Math.round(host.cpuUsedPct)}%`
-          }
-          hint={`${host.cpuCount} 核`}
-          pct={host.cpuUsedPct}
-        />
-        <StatCard
-          icon={RamMemoryIcon}
-          label="内存"
-          value={formatBytes(memUsed)}
-          hint={`共 ${formatBytes(host.memTotalBytes)} · 可用 ${formatBytes(host.memAvailableBytes)}`}
-          pct={pctOf(memUsed, host.memTotalBytes)}
-        />
-        {host.swap === null ? (
-          <StatCard
-            icon={SnowIcon}
-            label="Swap"
-            value="—"
-            hint="此平台读不到 swap"
-          />
-        ) : host.swap.totalBytes === 0 ? (
-          <StatCard
-            icon={SnowIcon}
-            label="Swap"
-            value="未配置"
-            hint={
-              <span className="text-amber-600 dark:text-amber-500">
-                冻结依赖 swap — 见 dor doctor
-              </span>
-            }
-          />
-        ) : (
-          <StatCard
-            icon={SnowIcon}
-            label="Swap"
-            value={formatBytes(host.swap.usedBytes)}
-            hint={`共 ${formatBytes(host.swap.totalBytes)} · 冻结的沙箱住在这里`}
-            pct={pctOf(host.swap.usedBytes, host.swap.totalBytes)}
-          />
-        )}
-        {dataDisk === null ? (
-          <StatCard
-            icon={HardDriveIcon}
-            label="数据盘"
-            value="—"
-            hint="这台主机没有数据目录"
-          />
-        ) : (
-          <StatCard
-            icon={HardDriveIcon}
-            label="数据盘"
-            value={formatBytes(dataDisk.usedBytes)}
-            hint={
-              <span title={dataDisk.path}>
-                {`共 ${formatBytes(dataDisk.totalBytes)} · 剩 ${formatBytes(dataDisk.availableBytes)}`}
-              </span>
-            }
-            pct={pctOf(dataDisk.usedBytes, dataDisk.totalBytes)}
-          />
-        )}
-      </div>
-
-      <div className="grid gap-4 md:grid-cols-2">
-        <StatCard
-          icon={Database01Icon}
-          label="沙箱磁盘"
-          value={formatBytes(sandboxDisks.actualBytes)}
-          hint={`${sandboxDisks.count} 块盘共许诺 ${formatBytes(sandboxDisks.nominalBytes)} — 稀疏镜像只为真实内容付费`}
-          pct={pctOf(sandboxDisks.actualBytes, sandboxDisks.nominalBytes)}
-          to="/sandboxes"
-        />
-        <QuickConnectCard />
-      </div>
-    </section>
-  );
-}
diff --git a/packages/console/src/features/overview/components/RangeSwitcher.tsx b/packages/console/src/features/overview/components/RangeSwitcher.tsx
new file mode 100644
index 0000000..73df6b7
--- /dev/null
+++ b/packages/console/src/features/overview/components/RangeSwitcher.tsx
@@ -0,0 +1,71 @@
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
+import {
+  TIMELINE_RANGES,
+  type TimelineRangeKey,
+} from '../hooks/useFleetTimeline';
+
+// base-ui Select 的已知坑:value ≠ 展示文案时必须传 items,否则触发器
+// 显示不了选中项文案(RULES/前端.md)。
+const RANGE_ITEMS = TIMELINE_RANGES.map((r) => ({
+  value: r.key,
+  label: r.label,
+}));
+
+/**
+ * 全局时间档位切换:放页头右侧,统一驱动统计卡与走势图 — 档位是整页
+ * 的观察窗口,不是某张图的私有旋钮。桌面 ToggleGroup,移动降级 Select。
+ */
+export function RangeSwitcher({
+  range,
+  onChange,
+}: {
+  range: TimelineRangeKey;
+  onChange: (range: TimelineRangeKey) => void;
+}) {
+  return (
+    <>
+      <ToggleGroup
+        value={[range]}
+        onValueChange={(value: unknown[]) => {
+          // base-ui 允许再点一下取消选中(空数组)— 档位必须常有,忽略。
+          const next = value[0];
+          if (typeof next === 'string') onChange(next as TimelineRangeKey);
+        }}
+        variant="outline"
+        size="sm"
+        className="hidden sm:flex"
+      >
+        {TIMELINE_RANGES.map((r) => (
+          <ToggleGroupItem key={r.key} value={r.key}>
+            {r.label}
+          </ToggleGroupItem>
+        ))}
+      </ToggleGroup>
+      <Select
+        items={RANGE_ITEMS}
+        value={range}
+        onValueChange={(value) => {
+          if (typeof value === 'string') onChange(value as TimelineRangeKey);
+        }}
+      >
+        <SelectTrigger size="sm" className="flex w-28 sm:hidden">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent align="end">
+          {TIMELINE_RANGES.map((r) => (
+            <SelectItem key={r.key} value={r.key}>
+              {r.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </>
+  );
+}
diff --git a/packages/console/src/features/overview/components/SandboxDisksCard.tsx b/packages/console/src/features/overview/components/SandboxDisksCard.tsx
new file mode 100644
index 0000000..883f8a8
--- /dev/null
+++ b/packages/console/src/features/overview/components/SandboxDisksCard.tsx
@@ -0,0 +1,44 @@
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { formatBytes, pctOf } from '@/lib/format';
+import { useHostMetrics } from '../hooks/useHostMetrics';
+import { Meter } from './Meter';
+import { StatCard, StatCardSkeleton } from './StatCard';
+
+/**
+ * 沙箱磁盘账单卡:这群沙箱的盘许诺了多少、实际占了多少 — 稀疏镜像
+ * 只为真实内容付费,这两个数的差就是超卖的空间。机器本身的体征在
+ * 宿主健康卡;这张卡讲的是沙箱群欠机器多少。
+ */
+export function SandboxDisksCard() {
+  const query = useHostMetrics();
+
+  if (query.isError) {
+    return (
+      <Alert variant="destructive">
+        <AlertDescription>{query.error.message}</AlertDescription>
+      </Alert>
+    );
+  }
+
+  if (!query.data) return <StatCardSkeleton />;
+
+  const { sandboxDisks } = query.data;
+  const usedPct = Math.round(
+    pctOf(sandboxDisks.actualBytes, sandboxDisks.nominalBytes),
+  );
+
+  return (
+    <StatCard
+      label="沙箱磁盘"
+      value={formatBytes(sandboxDisks.actualBytes)}
+      hint={`${sandboxDisks.count} 块盘共许诺 ${formatBytes(sandboxDisks.nominalBytes)}`}
+      sub={`实占 ${usedPct}% — 稀疏镜像只为真实内容付费`}
+      corner={
+        <div className="w-20 shrink-0 pb-1.5 @[250px]/card:w-24">
+          <Meter pct={usedPct} />
+        </div>
+      }
+      to="/sandboxes"
+    />
+  );
+}
diff --git a/packages/console/src/features/overview/components/Sparkline.tsx b/packages/console/src/features/overview/components/Sparkline.tsx
new file mode 100644
index 0000000..425eb7e
--- /dev/null
+++ b/packages/console/src/features/overview/components/Sparkline.tsx
@@ -0,0 +1,84 @@
+import { useId } from 'react';
+import { cn } from '@/lib/utils';
+
+/**
+ * 迷你走势曲线(sparkline):统计卡右下角用,只表达「窗口内大致走势」,
+ * 不带坐标轴/刻度/交互。纯 SVG path — 比每卡塞一个 recharts 容器轻得多,
+ * viewBox + preserveAspectRatio 让曲线随容器自由拉伸。
+ *
+ * 用中性主色,刻意不做涨绿跌红:openasi 画的是钱,涨跌有好坏;活跃沙箱
+ * 变多没有好坏(业务旺或泄漏都长这样),红绿会撒谎。
+ * 平滑:相邻点取中点做二次贝塞尔,避免折线尖角;面积渐变填充到底,
+ * 弱化为背景陪衬。
+ */
+const VIEW_W = 100;
+const VIEW_H = 32;
+
+export function Sparkline({
+  data,
+  className,
+}: {
+  data: number[];
+  className?: string;
+}) {
+  const gradientId = useId();
+
+  // 少于两点画不出走势;归一化到 viewBox,min→底、max→顶,曲线占 80%
+  // 高度留出上下边距。
+  const first = data[0];
+  if (data.length < 2 || first === undefined) return null;
+
+  const max = Math.max(...data);
+  const min = Math.min(...data);
+  const range = max - min || 1;
+  const pad = VIEW_H * 0.1;
+  const points = data.map((v, i) => {
+    const x = (i / (data.length - 1)) * VIEW_W;
+    const y = VIEW_H - pad - ((v - min) / range) * (VIEW_H - pad * 2);
+    return { x, y };
+  });
+
+  const head = points[0];
+  const tail = points[points.length - 1];
+  if (head === undefined || tail === undefined) return null;
+  let line = `M ${head.x} ${head.y}`;
+  for (let i = 1; i < points.length; i++) {
+    const prev = points[i - 1];
+    const cur = points[i];
+    if (prev === undefined || cur === undefined) continue;
+    const midX = (prev.x + cur.x) / 2;
+    const midY = (prev.y + cur.y) / 2;
+    line += ` Q ${prev.x} ${prev.y} ${midX} ${midY}`;
+  }
+  line += ` L ${tail.x} ${tail.y}`;
+  const area = `${line} L ${VIEW_W} ${VIEW_H} L 0 ${VIEW_H} Z`;
+
+  const stroke = 'var(--primary)';
+
+  return (
+    <svg
+      viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
+      preserveAspectRatio="none"
+      className={cn('h-8 w-full overflow-visible', className)}
+      role="presentation"
+      aria-hidden="true"
+    >
+      <defs>
+        <linearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
+          <stop offset="0%" stopColor={stroke} stopOpacity={0.25} />
+          <stop offset="100%" stopColor={stroke} stopOpacity={0} />
+        </linearGradient>
+      </defs>
+      <path d={area} fill={`url(#${gradientId})`} stroke="none" />
+      <path
+        d={line}
+        fill="none"
+        stroke={stroke}
+        strokeWidth={1.5}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        vectorEffect="non-scaling-stroke"
+      />
+    </svg>
+  );
+}
diff --git a/packages/console/src/features/overview/components/StatCard.tsx b/packages/console/src/features/overview/components/StatCard.tsx
new file mode 100644
index 0000000..19ecf34
--- /dev/null
+++ b/packages/console/src/features/overview/components/StatCard.tsx
@@ -0,0 +1,88 @@
+import { Link } from '@tanstack/react-router';
+import type { ReactNode } from 'react';
+import {
+  Card,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from '@/components/ui/card';
+import { Skeleton } from '@/components/ui/skeleton';
+
+/**
+ * 统计卡解剖(参考 openasi SectionCards):小标签 + 大数字(容器查询下
+ * 响应式放大)+ footer 左侧两行说明、右下角一个陪衬件(sparkline 或
+ * 容量量表)。刻意没有环比百分比 — 「活跃比上窗口多 30%」没有行动
+ * 含义,是装饰性精确。
+ */
+export function StatCard({
+  label,
+  value,
+  hint,
+  sub,
+  corner,
+  to,
+}: {
+  label: string;
+  value: string;
+  hint: string;
+  sub: ReactNode;
+  /** footer 右下角的陪衬件:sparkline、量表 — 没有就留白。 */
+  corner?: ReactNode;
+  /** 这张卡下钻的路由;只有真有去处的卡才给。 */
+  to?: string;
+}) {
+  const card = (
+    <Card size="sm" className="@container/card">
+      <CardHeader>
+        <CardDescription>{label}</CardDescription>
+        <CardTitle className="text-2xl font-semibold tabular-nums @[250px]/card:text-3xl">
+          {value}
+        </CardTitle>
+      </CardHeader>
+      <CardFooter className="flex items-end justify-between gap-3 text-sm">
+        <div className="flex min-w-0 flex-col gap-1">
+          <div className="line-clamp-1 font-medium">{hint}</div>
+          <div className="text-muted-foreground">{sub}</div>
+        </div>
+        {corner}
+      </CardFooter>
+    </Card>
+  );
+  if (!to) return card;
+  // Radius mirrors the Card's own, so the focus/hover ring hugs the shape.
+  return (
+    <Link
+      to={to}
+      className="block rounded-[min(var(--radius-4xl),24px)] transition-shadow hover:ring-2 hover:ring-primary/30"
+    >
+      {card}
+    </Link>
+  );
+}
+
+/**
+ * 骨架镜像真实解剖:header 标签 + 大数字,footer 两行说明 + 右下角
+ * 陪衬件,块高对齐文字行高 — loading 与 loaded 等高不跳动。
+ */
+export function StatCardSkeleton() {
+  return (
+    <Card size="sm" className="@container/card">
+      <CardHeader>
+        <CardDescription>
+          <Skeleton className="h-5 w-20" />
+        </CardDescription>
+        <CardTitle className="text-2xl font-semibold @[250px]/card:text-3xl">
+          <Skeleton className="h-8 w-24 @[250px]/card:h-9" />
+        </CardTitle>
+      </CardHeader>
+      <CardFooter className="flex items-end justify-between gap-3 text-sm">
+        <div className="flex flex-col gap-1">
+          <Skeleton className="h-5 w-28" />
+          <Skeleton className="h-5 w-20" />
+        </div>
+        <Skeleton className="h-8 w-20 rounded-md" />
+      </CardFooter>
+    </Card>
+  );
+}
diff --git a/packages/console/src/features/overview/format.ts b/packages/console/src/features/overview/format.ts
new file mode 100644
index 0000000..3692f26
--- /dev/null
+++ b/packages/console/src/features/overview/format.ts
@@ -0,0 +1,28 @@
+import type { TimelineRangeKey } from './hooks/useFleetTimeline';
+
+/** tooltip 与峰值注脚共用的完整时刻写法。 */
+export function fullClock(ms: number): string {
+  return new Date(ms).toLocaleString('zh-CN', {
+    hour12: false,
+    month: 'numeric',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+/** 长窗口给日期,短窗口给钟点 — 刻度只说这个窗口内有区分度的部分。 */
+export function tickFormatter(range: TimelineRangeKey): (ms: number) => string {
+  if (range === '7d' || range === '30d') {
+    return (ms) => {
+      const d = new Date(ms);
+      return `${d.getMonth() + 1}/${d.getDate()}`;
+    };
+  }
+  return (ms) =>
+    new Date(ms).toLocaleTimeString('zh-CN', {
+      hour12: false,
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+}
diff --git a/packages/console/src/features/overview/pages/OverviewPage.tsx b/packages/console/src/features/overview/pages/OverviewPage.tsx
index d51be0f..61a48b1 100644
--- a/packages/console/src/features/overview/pages/OverviewPage.tsx
+++ b/packages/console/src/features/overview/pages/OverviewPage.tsx
@@ -1,23 +1,42 @@
-import { FleetOverview } from '../components/FleetOverview';
-import { OverviewCards } from '../components/OverviewCards';
+import { useState } from 'react';
+import { FleetChart } from '../components/FleetChart';
+import { FleetStatCards } from '../components/FleetStatCards';
+import { HostHealthCard } from '../components/HostHealthCard';
+import { QuickConnectCard } from '../components/QuickConnectCard';
+import { RangeSwitcher } from '../components/RangeSwitcher';
+import { SandboxDisksCard } from '../components/SandboxDisksCard';
+import type { TimelineRangeKey } from '../hooks/useFleetTimeline';
 
 /**
- * 回答三个问题:沙箱群现在多忙、一段时间以来多忙(daemon 采样器落库的
- * 舰队时间线,含窗口峰值)、这台机器还好吗。当前值来自 /getHostMetrics
- * 快照,走势来自 /getFleetTimeline 历史;快速接入卡把「换两个 URL 直连」
- * 放上第一屏。
+ * 回答三个问题:沙箱群现在多忙、一段时间以来多忙(daemon 采样器落库
+ * 的舰队时间线,含窗口峰值)、这台机器还好吗。版式参考 openasi 仪表盘:
+ * 页头右侧的全局档位切换统一驱动统计卡与主图,主图区 3:1(走势图配
+ * 宿主健康竖卡),底部一行沙箱磁盘账单 + 快速接入(「换两个 URL 直连」
+ * 放上第一屏)。
  */
 export function OverviewPage() {
+  const [range, setRange] = useState<TimelineRangeKey>('24h');
+
   return (
     <>
-      <div>
-        <h1 className="text-2xl font-semibold">仪表盘</h1>
-        <p className="text-sm text-muted-foreground">
-          沙箱群的并发走势,与这台机器的健康状况。
-        </p>
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div>
+          <h1 className="text-2xl font-semibold">仪表盘</h1>
+          <p className="text-sm text-muted-foreground">
+            沙箱群的并发走势,与这台机器的健康状况。
+          </p>
+        </div>
+        <RangeSwitcher range={range} onChange={setRange} />
+      </div>
+      <FleetStatCards range={range} />
+      <div className="grid grid-cols-1 gap-4 lg:grid-cols-4">
+        <FleetChart range={range} className="min-h-[420px] lg:col-span-3" />
+        <HostHealthCard className="min-h-[420px] lg:col-span-1" />
+      </div>
+      <div className="grid gap-4 md:grid-cols-2">
+        <SandboxDisksCard />
+        <QuickConnectCard />
       </div>
-      <FleetOverview />
-      <OverviewCards />
     </>
   );
 }

From 81a8f3a0241e45f43f4849bca4b7c7bc2d1cde01 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 04:43:46 +0800
Subject: [PATCH 090/133] =?UTF-8?q?Credentials=20learn=20to=20rotate=20wit?=
 =?UTF-8?q?hout=20a=20restart:=20an=20api=5Fkeys=20ledger=20table=20mints?=
 =?UTF-8?q?=20full-power=20peers=20of=20DORMICE=5FAPI=5FTOKEN=20=E2=80=94?=
 =?UTF-8?q?=20createApiKey=20answers=20with=20a=2064-hex=20token=20exactly?=
 =?UTF-8?q?=20once=20(pure=20hex=20because=20the=20Python=20E2B=20SDK=20re?=
 =?UTF-8?q?fuses=20anything=20else=20client-side)=20and=20stores=20only=20?=
 =?UTF-8?q?its=20sha256,=20listApiKeys=20keeps=20revoked=20rows=20as=20rot?=
 =?UTF-8?q?ation=20history,=20revokeApiKey=20soft-kills=20a=20credential?=
 =?UTF-8?q?=20on=20its=20very=20next=20request.=20One=20verifyCredential?=
 =?UTF-8?q?=20closure=20adjudicates=20both=20faces=20=E2=80=94=20native=20?=
 =?UTF-8?q?Bearer=20and=20E2B=20X-API-KEY=20=E2=80=94=20accepting=20the=20?=
 =?UTF-8?q?env=20token=20(now=20the=20bootstrap/recovery=20credential)=20o?=
 =?UTF-8?q?r=20any=20active=20key,=20judged=20per=20request;=20console=20s?=
 =?UTF-8?q?etup=20deliberately=20stays=20env-token-only=20so=20a=20leaked?=
 =?UTF-8?q?=20machine=20credential=20can=20never=20take=20over=20the=20hum?=
 =?UTF-8?q?an=20account.=20lastUsedAt=20lands=20at=2060-second=20granulari?=
 =?UTF-8?q?ty=20to=20spare=20the=20WAL=20from=20hot=20pollers,=20dor=20api?=
 =?UTF-8?q?key=20create/ls/revoke=20speaks=20it=20from=20the=20shell,=20an?=
 =?UTF-8?q?d=20the=20console=20grows=20an=20API=20keys=20page=20whose=20cr?=
 =?UTF-8?q?eate=20dialog=20plays=20two=20acts:=20the=20form,=20then=20the?=
 =?UTF-8?q?=20token's=20only=20appearance=20with=20a=20copy=20button=20and?=
 =?UTF-8?q?=20no=20second=20chance.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 e2e/src/cli.test.ts                           |  40 ++
 e2e/src/e2b.test.ts                           |  29 +
 e2e/src/native.test.ts                        |  28 +
 packages/cli/src/commands.test.ts             |  33 +-
 packages/cli/src/commands.ts                  |  54 ++
 packages/cli/src/main.ts                      |  34 ++
 .../console/src/components/AppSidebar.tsx     |   2 +
 .../console/src/features/activity/kinds.ts    |   6 +
 .../src/features/api-keys/hooks/useApiKeys.ts |  32 ++
 .../features/api-keys/pages/ApiKeysPage.tsx   | 375 +++++++++++++
 packages/console/src/lib/api.ts               |  14 +
 packages/console/src/routeTree.gen.ts         |  21 +
 packages/console/src/routes/_app/api-keys.tsx |   6 +
 packages/console/vite.config.ts               |   3 +
 packages/sdk/src/client.test.ts               |  34 ++
 packages/sdk/src/client.ts                    |  34 ++
 packages/server/drizzle/0009_api-keys.sql     |  12 +
 .../server/drizzle/meta/0009_snapshot.json    | 531 ++++++++++++++++++
 packages/server/drizzle/meta/_journal.json    |  14 +
 packages/server/src/app.test.ts               | 133 +++++
 packages/server/src/app.ts                    |  17 +-
 packages/server/src/auth.ts                   |  19 +-
 packages/server/src/db/api-keys.ts            | 122 ++++
 packages/server/src/db/schema.ts              |  47 ++
 packages/server/src/e2b/compat.test.ts        |  35 ++
 packages/server/src/e2b/control.ts            |   3 +-
 packages/server/src/e2b/deps.ts               |   6 +
 packages/server/src/e2b/protocol.ts           |  11 +-
 packages/server/src/routes/api-keys.ts        |  92 +++
 packages/server/src/routes/console.ts         |   5 +
 packages/shared/src/activity.ts               |   4 +
 packages/shared/src/api-keys.ts               |  85 +++
 packages/shared/src/index.ts                  |   1 +
 skills/dormice/SKILL.md                       |   5 +
 website/content/docs/cli.mdx                  |  16 +
 website/content/docs/configuration.mdx        |   2 +-
 website/content/docs/console.mdx              |  16 +-
 website/content/docs/e2b-sdks.mdx             |   4 +
 website/content/docs/http-api.mdx             |  27 +-
 39 files changed, 1935 insertions(+), 17 deletions(-)
 create mode 100644 packages/console/src/features/api-keys/hooks/useApiKeys.ts
 create mode 100644 packages/console/src/features/api-keys/pages/ApiKeysPage.tsx
 create mode 100644 packages/console/src/routes/_app/api-keys.tsx
 create mode 100644 packages/server/drizzle/0009_api-keys.sql
 create mode 100644 packages/server/drizzle/meta/0009_snapshot.json
 create mode 100644 packages/server/src/db/api-keys.ts
 create mode 100644 packages/server/src/routes/api-keys.ts
 create mode 100644 packages/shared/src/api-keys.ts

diff --git a/e2e/src/cli.test.ts b/e2e/src/cli.test.ts
index 267cce2..8ffb835 100644
--- a/e2e/src/cli.test.ts
+++ b/e2e/src/cli.test.ts
@@ -142,6 +142,46 @@ describe('dor CLI against a real daemon', () => {
     expect(again.stdout).toContain('nothing to remove');
   });
 
+  it('apikey create, ls and revoke run the rotation life through the real binary', async () => {
+    const created = await cli('apikey', 'create', 'cli-key');
+    const lines = created.stdout.trim().split('\n');
+    expect(lines[0]).toMatch(
+      /^Created API key "cli-key" \(prefix [0-9a-f]{8}\)\./,
+    );
+    const token = lines[1] ?? '';
+    expect(token).toMatch(/^[0-9a-f]{64}$/);
+    expect(lines[2]).toContain('never be shown again');
+
+    // The minted key IS a DORMICE_API_TOKEN — same variable, new value:
+    // exactly what rotation looks like from a client's shell.
+    const keyed = await run('node', [CLI, 'sandbox', 'ls'], {
+      env: {
+        ...process.env,
+        DORMICE_ENDPOINT: inject('dormiceEndpoint'),
+        DORMICE_API_TOKEN: token,
+      },
+    });
+    expect(keyed.stdout).toBeDefined();
+
+    const listed = await cli('apikey', 'ls');
+    expect(listed.stdout).toMatch(/NAME\s{2,}PREFIX\s{2,}CREATED/);
+    expect(listed.stdout).toMatch(/cli-key\s{2,}[0-9a-f]{8}.*active/);
+
+    const revoked = await cli('apikey', 'revoke', 'cli-key');
+    expect(revoked.stdout).toContain('Revoked API key "cli-key"');
+    await expect(
+      run('node', [CLI, 'sandbox', 'ls'], {
+        env: {
+          ...process.env,
+          DORMICE_ENDPOINT: inject('dormiceEndpoint'),
+          DORMICE_API_TOKEN: token,
+        },
+      }),
+    ).rejects.toMatchObject({ code: 1 });
+    const again = await cli('apikey', 'revoke', 'cli-key');
+    expect(again.stdout).toContain('nothing to revoke');
+  });
+
   it('fails honestly when the environment is missing', async () => {
     await expect(
       run('node', [CLI, 'sandbox', 'ls'], {
diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 10d05c5..3495bf4 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -72,6 +72,35 @@ describe('official e2b SDK against the daemon', () => {
     }
   });
 
+  it('a ledger API key drives the official SDK exactly like the env token', async () => {
+    // Minted over the native face; the E2B face accepts it as e2b_<key> —
+    // pure hex by construction, so even the Python SDK's client-side
+    // e2b_[0-9a-f]+ validation would let it through.
+    const dormice = new Dormice({
+      endpoint: inject('dormiceEndpoint'),
+      token: inject('dormiceToken'),
+    });
+    const { token } = await dormice.createApiKey('e2b-face');
+    try {
+      const sbx = await Sandbox.create({
+        ...connection(),
+        apiKey: `e2b_${token}`,
+      });
+      try {
+        const result = await sbx.commands.run('echo keyed');
+        expect(result.stdout).toBe('keyed\n');
+      } finally {
+        await sbx.kill();
+      }
+    } finally {
+      await dormice.revokeApiKey('e2b-face');
+    }
+    // Revoked: the same key is refused at the control-plane door.
+    await expect(
+      Sandbox.create({ ...connection(), apiKey: `e2b_${token}` }),
+    ).rejects.toThrow(/invalid API key/);
+  });
+
   it('throws CommandExitError on a nonzero exit — the SDK’s own contract', async () => {
     const sbx = await Sandbox.create(connection());
     try {
diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index e7a3dd4..495cd72 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -419,6 +419,34 @@ describe('native API over a real daemon', () => {
     });
   });
 
+  it('API keys: the rolling-rotation story — mint, work, revoke, the env token survives', async () => {
+    const { apiKey, token } = await client().createApiKey('rotation');
+    expect(token).toMatch(/^[0-9a-f]{64}$/);
+    expect(apiKey.prefix).toBe(token.slice(0, 8));
+
+    // A fresh client on the minted key does real work — rotation means the
+    // new credential is live before the old one dies.
+    const keyed = client(token);
+    const created = await keyed.acquireSandbox('rotation-key');
+    expect(created.sandbox.externalId).toBe('rotation-key');
+    await keyed.destroySandbox('rotation-key');
+
+    const listed = await client().listApiKeys();
+    const mine = listed.find((k) => k.name === 'rotation');
+    expect(mine?.lastUsedAt).not.toBeNull();
+
+    expect(await client().revokeApiKey('rotation')).toEqual({ revoked: true });
+    await expect(keyed.listSandboxes()).rejects.toMatchObject({
+      name: 'DormiceApiError',
+      status: 401,
+    });
+    // The env token is the bootstrap credential: revocation never touches it.
+    expect(await client().listSandboxes()).toBeDefined();
+    expect(await client().revokeApiKey('rotation')).toEqual({
+      revoked: false,
+    });
+  });
+
   it('listSandboxImages tracks a template upgrade; rebuild closes the gap', async () => {
     // The daemon's base image doubles as the template image (real in docker
     // mode, an arbitrary string for the fake). The "upgrade" points the name
diff --git a/packages/cli/src/commands.test.ts b/packages/cli/src/commands.test.ts
index 6f4ecd4..b63f3fb 100644
--- a/packages/cli/src/commands.test.ts
+++ b/packages/cli/src/commands.test.ts
@@ -10,6 +10,9 @@ import {
 } from '@dormice/server';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import {
+  apikeyCreate,
+  apikeyLs,
+  apikeyRevoke,
   clientFromEnv,
   parseLabels,
   pullSavedMessage,
@@ -220,6 +223,32 @@ describe('parseLabels', () => {
   });
 });
 
+describe('apikey commands over real HTTP', () => {
+  it('create, ls and revoke walk the rotation life end to end', async () => {
+    expect(await apikeyLs(client)).toBe('No API keys.');
+
+    const created = await apikeyCreate(client, 'ci');
+    const lines = created.split('\n');
+    expect(lines[0]).toMatch(/^Created API key "ci" \(prefix [0-9a-f]{8}\)\.$/);
+    expect(lines[1]).toMatch(/^[0-9a-f]{64}$/);
+    expect(lines[2]).toBe('Store it now — it will never be shown again.');
+
+    const output = await apikeyLs(client);
+    expect(output.split('\n')[0]).toMatch(
+      /^NAME\s{2,}PREFIX\s{2,}CREATED\s{2,}LAST USED\s{2,}STATUS$/,
+    );
+    expect(output).toMatch(/ci\s{2,}[0-9a-f]{8}.*never\s{2,}active/);
+
+    expect(await apikeyRevoke(client, 'ci')).toBe(
+      'Revoked API key "ci" — it stops working immediately.',
+    );
+    expect(await apikeyRevoke(client, 'ci')).toBe(
+      'No active API key named "ci" — nothing to revoke.',
+    );
+    expect(await apikeyLs(client)).toMatch(/ci\s{2,}.*revoked/);
+  });
+});
+
 describe('template commands over real HTTP', () => {
   it('add, ls and rm walk the registration life end to end', async () => {
     expect(await templateLs(client)).toBe('No templates.');
@@ -228,7 +257,9 @@ describe('template commands over real HTTP', () => {
       'Registered template "py311" -> img:py311.',
     );
     const output = await templateLs(client);
-    expect(output.split('\n')[0]).toMatch(/^NAME\s{2,}IMAGE\s{2,}CREATED$/);
+    expect(output.split('\n')[0]).toMatch(
+      /^NAME\s{2,}IMAGE\s{2,}CREATED\s{2,}UPDATED$/,
+    );
     expect(output).toMatch(/py311\s{2,}img:py311/);
 
     expect(await templateRm(client, 'py311')).toBe('Removed template "py311".');
diff --git a/packages/cli/src/commands.ts b/packages/cli/src/commands.ts
index 249e8d8..615acda 100644
--- a/packages/cli/src/commands.ts
+++ b/packages/cli/src/commands.ts
@@ -1,4 +1,5 @@
 import {
+  type ApiKey,
   Dormice,
   type ReadFileResult,
   type Sandbox,
@@ -250,6 +251,8 @@ export async function templateLs(client: Dormice): Promise<string> {
     { header: 'NAME', value: (t) => t.name },
     { header: 'IMAGE', value: (t) => t.image },
     { header: 'CREATED', value: (t) => t.createdAt },
+    // Moves only on a real image change; equal to CREATED = never upgraded.
+    { header: 'UPDATED', value: (t) => t.updatedAt },
   ];
   return renderTable(
     columns.map((column) => column.header),
@@ -267,3 +270,54 @@ export async function templateRm(
     ? `Removed template "${printable(name)}".`
     : `No template named "${printable(name)}" — nothing to remove.`;
 }
+
+/**
+ * `dor apikey create <name>`: mint an API key. The token line is the one
+ * and only time the key material exists outside the daemon's hash — the
+ * warning is part of the output, not decoration.
+ */
+export async function apikeyCreate(
+  client: Dormice,
+  name: string,
+): Promise<string> {
+  const { apiKey, token } = await client.createApiKey(name);
+  return (
+    `Created API key "${printable(apiKey.name)}" (prefix ${apiKey.prefix}).\n` +
+    `${token}\n` +
+    'Store it now — it will never be shown again.'
+  );
+}
+
+/** `dor apikey ls`: every key ever minted, revoked ones included, as plain columns. */
+export async function apikeyLs(client: Dormice): Promise<string> {
+  const keys = await client.listApiKeys();
+  if (keys.length === 0) {
+    return 'No API keys.';
+  }
+  const columns: { header: string; value: (k: ApiKey) => string }[] = [
+    { header: 'NAME', value: (k) => k.name },
+    { header: 'PREFIX', value: (k) => k.prefix },
+    { header: 'CREATED', value: (k) => k.createdAt },
+    { header: 'LAST USED', value: (k) => k.lastUsedAt ?? 'never' },
+    { header: 'STATUS', value: (k) => (k.revokedAt ? 'revoked' : 'active') },
+  ];
+  return renderTable(
+    columns.map((column) => column.header),
+    keys.map((k) => columns.map((column) => printable(column.value(k)))),
+  );
+}
+
+/**
+ * `dor apikey revoke <name>`: kill the active key under a name. The false
+ * branch is said out loud — a silent miss here would leave a leaked key
+ * alive behind a typo.
+ */
+export async function apikeyRevoke(
+  client: Dormice,
+  name: string,
+): Promise<string> {
+  const { revoked } = await client.revokeApiKey(name);
+  return revoked
+    ? `Revoked API key "${printable(name)}" — it stops working immediately.`
+    : `No active API key named "${printable(name)}" — nothing to revoke.`;
+}
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index 1cd2c62..cb00ed4 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -7,6 +7,9 @@ import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { Command } from 'commander';
 import {
+  apikeyCreate,
+  apikeyLs,
+  apikeyRevoke,
   clientFromEnv,
   parseLabels,
   pullSavedMessage,
@@ -203,6 +206,37 @@ template
     console.log(await templateRm(clientFromEnv(process.env), name));
   });
 
+const apikey = program
+  .command('apikey')
+  .description(
+    'Manage API keys — rotatable peers of DORMICE_API_TOKEN, revocable without a restart',
+  );
+
+apikey
+  .command('create')
+  .description('Mint an API key; the token is printed once and never again')
+  .argument('<name>', 'a human handle for the key, e.g. ci or laptop')
+  .action(async (name: string) => {
+    console.log(await apikeyCreate(clientFromEnv(process.env), name));
+  });
+
+apikey
+  .command('ls')
+  .description('List every API key ever minted, revoked ones included')
+  .action(async () => {
+    console.log(await apikeyLs(clientFromEnv(process.env)));
+  });
+
+apikey
+  .command('revoke')
+  .description(
+    'Revoke the active API key under a name — it stops working on the next request',
+  )
+  .argument('<name>', 'name of the key to revoke')
+  .action(async (name: string) => {
+    console.log(await apikeyRevoke(clientFromEnv(process.env), name));
+  });
+
 try {
   await program.parseAsync();
 } catch (error) {
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index 55224a2..bd27520 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -2,6 +2,7 @@ import {
   Activity01Icon,
   DashboardSquare01Icon,
   Globe02Icon,
+  Key01Icon,
   Layers01Icon,
   Logout01Icon,
   Moon02Icon,
@@ -55,6 +56,7 @@ export const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
     label: '运维',
     items: [
       { to: '/activity', label: '活动', icon: Activity01Icon },
+      { to: '/api-keys', label: 'API 密钥', icon: Key01Icon },
       { to: '/domains', label: '域名', icon: Globe02Icon },
       { to: '/doctor', label: '体检', icon: StethoscopeIcon, mock: true },
       { to: '/settings', label: '设置', icon: Settings01Icon },
diff --git a/packages/console/src/features/activity/kinds.ts b/packages/console/src/features/activity/kinds.ts
index ea55da7..be72eaa 100644
--- a/packages/console/src/features/activity/kinds.ts
+++ b/packages/console/src/features/activity/kinds.ts
@@ -21,6 +21,8 @@ export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
   'metadata-changed': '标签调整',
   'daemon-started': 'daemon 启动',
   'ingress-updated': '域名配置',
+  'apikey-created': '密钥创建',
+  'apikey-revoked': '密钥吊销',
   'upgrade-started': '发起升级',
 };
 
@@ -55,6 +57,10 @@ export const ACTIVITY_KIND_STYLES: Record<ActivityKind, string> = {
   'daemon-started': 'border-border bg-muted text-muted-foreground',
   'ingress-updated':
     'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  'apikey-created':
+    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  'apikey-revoked':
+    'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
   'upgrade-started':
     'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
 };
diff --git a/packages/console/src/features/api-keys/hooks/useApiKeys.ts b/packages/console/src/features/api-keys/hooks/useApiKeys.ts
new file mode 100644
index 0000000..da9b056
--- /dev/null
+++ b/packages/console/src/features/api-keys/hooks/useApiKeys.ts
@@ -0,0 +1,32 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { createApiKey, listApiKeys, revokeApiKey } from '@/lib/api';
+
+/**
+ * API 密钥实体的数据层,一个文件聚合。密钥变化在操作员速度(铸造/吊销
+ * 都在眼前发生,mutation 自己失效缓存),不需要像沙箱那样轮询。
+ */
+export function useApiKeys() {
+  return useQuery({
+    queryKey: ['apiKeys'],
+    queryFn: listApiKeys,
+    retry: false,
+  });
+}
+
+/** 铸造:响应里的 token 只出现这一次 — 展示与复制归调用方,这里只管数据。 */
+export function useCreateApiKey() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (name: string) => createApiKey(name),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['apiKeys'] }),
+  });
+}
+
+/** 软吊销:行留作轮换历史,凭证下一个请求就失效。 */
+export function useRevokeApiKey() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (name: string) => revokeApiKey(name),
+    onSettled: () => queryClient.invalidateQueries({ queryKey: ['apiKeys'] }),
+  });
+}
diff --git a/packages/console/src/features/api-keys/pages/ApiKeysPage.tsx b/packages/console/src/features/api-keys/pages/ApiKeysPage.tsx
new file mode 100644
index 0000000..c7ee05b
--- /dev/null
+++ b/packages/console/src/features/api-keys/pages/ApiKeysPage.tsx
@@ -0,0 +1,375 @@
+import type { ApiKey } from '@dormice/shared';
+import {
+  Add01Icon,
+  Copy01Icon,
+  Delete02Icon,
+  Key01Icon,
+  MoreVerticalIcon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { DataTable } from '@/components/DataTable';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@/components/ui/alert-dialog';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@/components/ui/dialog';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+} from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import {
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table';
+import { since } from '@/features/sandboxes/format';
+import { copyText } from '@/lib/copy';
+import {
+  useApiKeys,
+  useCreateApiKey,
+  useRevokeApiKey,
+} from '../hooks/useApiKeys';
+
+/**
+ * 铸造对话框演两幕:表单幕收名字,成功幕展示 token — daemon 只存哈希,
+ * 这是 token 在世上唯一一次露面,所以成功后不自动关窗,复制按钮和
+ * 「只显示这一次」的警告都长在这一幕里。关窗即翻篇,token 随之消失。
+ */
+function CreateApiKeyDialog() {
+  const [open, setOpen] = useState(false);
+  const [name, setName] = useState('');
+  const [minted, setMinted] = useState<{ name: string; token: string } | null>(
+    null,
+  );
+  const mutation = useCreateApiKey();
+
+  const onOpenChange = (next: boolean) => {
+    setOpen(next);
+    if (next) {
+      setName('');
+      setMinted(null);
+      mutation.reset();
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogTrigger
+        render={
+          <Button size="sm">
+            <HugeiconsIcon icon={Add01Icon} />
+            创建密钥
+          </Button>
+        }
+      />
+      <DialogContent className="sm:max-w-md">
+        {minted === null ? (
+          <>
+            <DialogHeader>
+              <DialogTitle>创建 API 密钥</DialogTitle>
+              <DialogDescription>
+                密钥与 DORMICE_API_TOKEN 等效通行(SDK、CLI、E2B 包都认),
+                区别是可以在这里随时吊销,不用改服务器配置、不用重启。
+              </DialogDescription>
+            </DialogHeader>
+            <form
+              onSubmit={(event) => {
+                event.preventDefault();
+                mutation.mutate(name, {
+                  onSuccess: ({ apiKey, token }) =>
+                    setMinted({ name: apiKey.name, token }),
+                });
+              }}
+            >
+              <FieldGroup>
+                <Field>
+                  <FieldLabel htmlFor="apikey-name">名字</FieldLabel>
+                  <Input
+                    id="apikey-name"
+                    value={name}
+                    onChange={(event) => setName(event.target.value)}
+                    placeholder="ci"
+                    className="font-mono"
+                  />
+                  <FieldDescription>
+                    给人看的把手,比如 ci、laptop。
+                    同名同时只能有一把活跃密钥,吊销后名字可以再用。
+                  </FieldDescription>
+                </Field>
+                {mutation.isError && (
+                  <FieldError>{mutation.error.message}</FieldError>
+                )}
+              </FieldGroup>
+              <DialogFooter className="mt-6">
+                <Button
+                  type="submit"
+                  disabled={name.trim() === '' || mutation.isPending}
+                >
+                  {mutation.isPending && <Spinner />}
+                  创建
+                </Button>
+              </DialogFooter>
+            </form>
+          </>
+        ) : (
+          <>
+            <DialogHeader>
+              <DialogTitle>「{minted.name}」已创建</DialogTitle>
+              <DialogDescription>
+                这是密钥唯一一次显示 — daemon 只存哈希,关掉这个窗口就再也
+                取不回来了。现在复制并存好。
+              </DialogDescription>
+            </DialogHeader>
+            <div className="flex items-center gap-2">
+              <code className="min-w-0 flex-1 break-all rounded-md bg-muted px-3 py-2 font-mono text-xs">
+                {minted.token}
+              </code>
+              <Button
+                variant="outline"
+                size="icon-sm"
+                aria-label="复制密钥"
+                onClick={() =>
+                  copyText(minted.token).then(
+                    () => toast.success('密钥已复制'),
+                    () => toast.error('复制失败 — 请手动选中复制'),
+                  )
+                }
+              >
+                <HugeiconsIcon icon={Copy01Icon} />
+              </Button>
+            </div>
+            <DialogFooter>
+              <Button onClick={() => onOpenChange(false)}>我已存好</Button>
+            </DialogFooter>
+          </>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function RevokeApiKeyDialog({
+  name,
+  open,
+  onOpenChange,
+}: {
+  name: string;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const mutation = useRevokeApiKey();
+
+  const revoke = () =>
+    mutation.mutate(name, {
+      // false 要说响亮:漏杀一把泄露的密钥比报错更糟。
+      onSuccess: ({ revoked }) =>
+        revoked
+          ? toast.success(`已吊销「${name}」— 下一个请求就失效`)
+          : toast.error(`「${name}」名下没有活跃密钥 — 没有吊销任何东西`),
+      onError: (error) => toast.error(error.message),
+    });
+
+  return (
+    <AlertDialog open={open} onOpenChange={onOpenChange}>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>吊销密钥「{name}」?</AlertDialogTitle>
+          <AlertDialogDescription>
+            立即生效,不可恢复 — 还在用它的客户端下一个请求就会 401。
+            记录会留在列表里作轮换历史,名字可以再用。
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>先留着</AlertDialogCancel>
+          <AlertDialogAction variant="destructive" onClick={revoke}>
+            吊销
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
+
+/** 行操作收进「⋯」菜单;吊销弹窗挂菜单外 — 菜单关闭即卸载,放里面会跟着消失。 */
+function ApiKeyRowMenu({ apiKey }: { apiKey: ApiKey }) {
+  const [revokeOpen, setRevokeOpen] = useState(false);
+
+  return (
+    <>
+      <DropdownMenu>
+        <DropdownMenuTrigger
+          render={
+            <Button
+              variant="ghost"
+              size="icon-sm"
+              aria-label={`${apiKey.name} 的操作`}
+            >
+              <HugeiconsIcon icon={MoreVerticalIcon} />
+            </Button>
+          }
+        />
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem
+            variant="destructive"
+            onClick={() => setRevokeOpen(true)}
+          >
+            <HugeiconsIcon icon={Delete02Icon} />
+            吊销
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      <RevokeApiKeyDialog
+        name={apiKey.name}
+        open={revokeOpen}
+        onOpenChange={setRevokeOpen}
+      />
+    </>
+  );
+}
+
+/**
+ * API 密钥账本:铸造、吊销、看谁还活着。密钥本体永不再现(daemon 只存
+ * 哈希),所以表格只有前缀可看;已吊销的行留着 — 那是轮换历史,不是垃圾。
+ * DORMICE_API_TOKEN 不在这张表里:它是引导/恢复凭证,吊销它 = 改服务器
+ * 配置文件。
+ */
+export function ApiKeysPage() {
+  const query = useApiKeys();
+  const keys = query.data?.apiKeys ?? [];
+
+  return (
+    // 六列窄表,同模板页限宽居中 — 宽屏上不摊大饼。
+    <div className="mx-auto flex w-full max-w-4xl flex-col gap-4">
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div>
+          <h1 className="text-2xl font-semibold">API 密钥</h1>
+          <p className="text-sm text-muted-foreground">
+            与 DORMICE_API_TOKEN 等效的可吊销凭证 — 轮换不停机,泄露即止损。
+          </p>
+        </div>
+        <CreateApiKeyDialog />
+      </div>
+
+      {query.isError && (
+        <Alert variant="destructive">
+          <AlertDescription>{query.error.message}</AlertDescription>
+        </Alert>
+      )}
+
+      {query.isSuccess && keys.length === 0 && (
+        <Empty className="border border-dashed">
+          <EmptyHeader>
+            <EmptyMedia variant="icon">
+              <HugeiconsIcon icon={Key01Icon} />
+            </EmptyMedia>
+            <EmptyTitle>还没有 API 密钥</EmptyTitle>
+            <EmptyDescription>
+              现在全靠 DORMICE_API_TOKEN 一枚凭证。创建一把密钥给每个
+              客户端,泄露时吊销那一把就够,不用全局换钥匙。
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      )}
+
+      {keys.length > 0 && (
+        <DataTable>
+          <TableHeader>
+            <TableRow>
+              <TableHead>名字</TableHead>
+              <TableHead>前缀</TableHead>
+              <TableHead>创建</TableHead>
+              <TableHead>最后使用</TableHead>
+              <TableHead>状态</TableHead>
+              <TableHead className="text-right">操作</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {keys.map((apiKey) => {
+              const revoked = apiKey.revokedAt !== null;
+              return (
+                <TableRow
+                  key={apiKey.id}
+                  className={revoked ? 'text-muted-foreground' : undefined}
+                >
+                  <TableCell className="font-mono font-medium">
+                    {apiKey.name}
+                  </TableCell>
+                  <TableCell className="font-mono text-muted-foreground">
+                    {apiKey.prefix}…
+                  </TableCell>
+                  <TableCell
+                    className="tabular-nums text-muted-foreground"
+                    title={new Date(apiKey.createdAt).toLocaleString()}
+                  >
+                    {since(apiKey.createdAt)}前
+                  </TableCell>
+                  <TableCell
+                    className="tabular-nums text-muted-foreground"
+                    title={
+                      apiKey.lastUsedAt
+                        ? new Date(apiKey.lastUsedAt).toLocaleString()
+                        : undefined
+                    }
+                  >
+                    {apiKey.lastUsedAt
+                      ? `${since(apiKey.lastUsedAt)}前`
+                      : '从未'}
+                  </TableCell>
+                  <TableCell>
+                    {revoked ? (
+                      <Badge variant="secondary">已吊销</Badge>
+                    ) : (
+                      <Badge variant="outline">活跃</Badge>
+                    )}
+                  </TableCell>
+                  <TableCell className="text-right">
+                    {!revoked && <ApiKeyRowMenu apiKey={apiKey} />}
+                  </TableCell>
+                </TableRow>
+              );
+            })}
+          </TableBody>
+        </DataTable>
+      )}
+    </div>
+  );
+}
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 6b574b5..c711625 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -1,8 +1,10 @@
 import type {
   AcquireRequest,
   AcquireResponse,
+  ApiKey,
   ApplyUpgradeResponse,
   CheckUpgradeResponse,
+  CreateApiKeyResponse,
   GetConfigResponse,
   GetFleetTimelineResponse,
   GetIngressResponse,
@@ -196,6 +198,18 @@ export const setIngress = (domains: string[]) =>
 export const listTemplates = () =>
   rpc<{ templates: Template[] }>('/listTemplates');
 
+export const listApiKeys = () => rpc<{ apiKeys: ApiKey[] }>('/listApiKeys');
+
+// The response's `token` is the key material's ONE appearance — the daemon
+// stores only its hash. Show it, offer copy, never ask for it back.
+export const createApiKey = (name: string) =>
+  rpc<CreateApiKeyResponse>('/createApiKey', { name });
+
+// Soft revoke: the row stays listed as rotation history; the credential
+// stops working on its next request. False = no active key had that name.
+export const revokeApiKey = (name: string) =>
+  rpc<{ revoked: boolean }>('/revokeApiKey', { name });
+
 // An upsert: re-registering a name points it at a new image — that IS the
 // template upgrade front door (then rebuild the sandboxes that should move).
 export const registerTemplate = (name: string, image: string) =>
diff --git a/packages/console/src/routeTree.gen.ts b/packages/console/src/routeTree.gen.ts
index 8eff25b..15d9a4a 100644
--- a/packages/console/src/routeTree.gen.ts
+++ b/packages/console/src/routeTree.gen.ts
@@ -17,6 +17,7 @@ import { Route as AppSettingsRouteImport } from './routes/_app/settings'
 import { Route as AppDomainsRouteImport } from './routes/_app/domains'
 import { Route as AppDoctorRouteImport } from './routes/_app/doctor'
 import { Route as AppConnectRouteImport } from './routes/_app/connect'
+import { Route as AppApiKeysRouteImport } from './routes/_app/api-keys'
 import { Route as AppActivityRouteImport } from './routes/_app/activity'
 import { Route as AppSandboxesIndexRouteImport } from './routes/_app/sandboxes/index'
 import { Route as AppSandboxesExternalIdRouteImport } from './routes/_app/sandboxes/$externalId'
@@ -60,6 +61,11 @@ const AppConnectRoute = AppConnectRouteImport.update({
   path: '/connect',
   getParentRoute: () => AppRoute,
 } as any)
+const AppApiKeysRoute = AppApiKeysRouteImport.update({
+  id: '/api-keys',
+  path: '/api-keys',
+  getParentRoute: () => AppRoute,
+} as any)
 const AppActivityRoute = AppActivityRouteImport.update({
   id: '/activity',
   path: '/activity',
@@ -80,6 +86,7 @@ export interface FileRoutesByFullPath {
   '/': typeof AppIndexRoute
   '/login': typeof LoginRoute
   '/activity': typeof AppActivityRoute
+  '/api-keys': typeof AppApiKeysRoute
   '/connect': typeof AppConnectRoute
   '/doctor': typeof AppDoctorRoute
   '/domains': typeof AppDomainsRoute
@@ -91,6 +98,7 @@ export interface FileRoutesByFullPath {
 export interface FileRoutesByTo {
   '/login': typeof LoginRoute
   '/activity': typeof AppActivityRoute
+  '/api-keys': typeof AppApiKeysRoute
   '/connect': typeof AppConnectRoute
   '/doctor': typeof AppDoctorRoute
   '/domains': typeof AppDomainsRoute
@@ -105,6 +113,7 @@ export interface FileRoutesById {
   '/_app': typeof AppRouteWithChildren
   '/login': typeof LoginRoute
   '/_app/activity': typeof AppActivityRoute
+  '/_app/api-keys': typeof AppApiKeysRoute
   '/_app/connect': typeof AppConnectRoute
   '/_app/doctor': typeof AppDoctorRoute
   '/_app/domains': typeof AppDomainsRoute
@@ -120,6 +129,7 @@ export interface FileRouteTypes {
     | '/'
     | '/login'
     | '/activity'
+    | '/api-keys'
     | '/connect'
     | '/doctor'
     | '/domains'
@@ -131,6 +141,7 @@ export interface FileRouteTypes {
   to:
     | '/login'
     | '/activity'
+    | '/api-keys'
     | '/connect'
     | '/doctor'
     | '/domains'
@@ -144,6 +155,7 @@ export interface FileRouteTypes {
     | '/_app'
     | '/login'
     | '/_app/activity'
+    | '/_app/api-keys'
     | '/_app/connect'
     | '/_app/doctor'
     | '/_app/domains'
@@ -217,6 +229,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AppConnectRouteImport
       parentRoute: typeof AppRoute
     }
+    '/_app/api-keys': {
+      id: '/_app/api-keys'
+      path: '/api-keys'
+      fullPath: '/api-keys'
+      preLoaderRoute: typeof AppApiKeysRouteImport
+      parentRoute: typeof AppRoute
+    }
     '/_app/activity': {
       id: '/_app/activity'
       path: '/activity'
@@ -243,6 +262,7 @@ declare module '@tanstack/react-router' {
 
 interface AppRouteChildren {
   AppActivityRoute: typeof AppActivityRoute
+  AppApiKeysRoute: typeof AppApiKeysRoute
   AppConnectRoute: typeof AppConnectRoute
   AppDoctorRoute: typeof AppDoctorRoute
   AppDomainsRoute: typeof AppDomainsRoute
@@ -255,6 +275,7 @@ interface AppRouteChildren {
 
 const AppRouteChildren: AppRouteChildren = {
   AppActivityRoute: AppActivityRoute,
+  AppApiKeysRoute: AppApiKeysRoute,
   AppConnectRoute: AppConnectRoute,
   AppDoctorRoute: AppDoctorRoute,
   AppDomainsRoute: AppDomainsRoute,
diff --git a/packages/console/src/routes/_app/api-keys.tsx b/packages/console/src/routes/_app/api-keys.tsx
new file mode 100644
index 0000000..1b2b2fc
--- /dev/null
+++ b/packages/console/src/routes/_app/api-keys.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { ApiKeysPage } from '@/features/api-keys/pages/ApiKeysPage';
+
+export const Route = createFileRoute('/_app/api-keys')({
+  component: ApiKeysPage,
+});
diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index 0b86c36..e8ebf86 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -33,6 +33,9 @@ export default defineConfig({
       '/listTemplates': 'http://127.0.0.1:3676',
       '/registerTemplate': 'http://127.0.0.1:3676',
       '/removeTemplate': 'http://127.0.0.1:3676',
+      '/listApiKeys': 'http://127.0.0.1:3676',
+      '/createApiKey': 'http://127.0.0.1:3676',
+      '/revokeApiKey': 'http://127.0.0.1:3676',
       '/getHostMetrics': 'http://127.0.0.1:3676',
       '/getSandboxMetrics': 'http://127.0.0.1:3676',
       '/listSandboxMetrics': 'http://127.0.0.1:3676',
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 46ec075..cf34f7c 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -358,6 +358,40 @@ describe('templates over real HTTP', () => {
   });
 });
 
+describe('API keys over real HTTP', () => {
+  it('mints a key a fresh client can use, revokes it, and the door closes', async () => {
+    const { apiKey, token } = await client.createApiKey('sdk-rotation');
+    expect(token).toMatch(/^[0-9a-f]{64}$/);
+    expect(apiKey.prefix).toBe(token.slice(0, 8));
+
+    // The rotation story: a new client on the minted key does real work.
+    const keyed = new Dormice({ endpoint, token });
+    await keyed.acquireSandbox('keyed-user');
+    await keyed.destroySandbox('keyed-user');
+
+    const listed = await client.listApiKeys();
+    const mine = listed.find((k) => k.name === 'sdk-rotation');
+    expect(mine?.lastUsedAt).not.toBeNull();
+
+    expect(await client.revokeApiKey('sdk-rotation')).toEqual({
+      revoked: true,
+    });
+    await expect(keyed.listSandboxes()).rejects.toMatchObject({ status: 401 });
+    expect(await client.revokeApiKey('sdk-rotation')).toEqual({
+      revoked: false,
+    });
+  });
+
+  it("surfaces the server's 409 for a duplicate active name", async () => {
+    await client.createApiKey('sdk-dup');
+    await expect(client.createApiKey('sdk-dup')).rejects.toMatchObject({
+      status: 409,
+      message: expect.stringMatching(/sdk-dup/),
+    });
+    await client.revokeApiKey('sdk-dup');
+  });
+});
+
 describe('the observability verbs over real HTTP', () => {
   it('getConfig reports the knobs and withholds the token', async () => {
     // Source attribution is asserted server-side with injected sources;
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 6815bd5..44e65fd 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -1,11 +1,14 @@
 import {
   type AcquireResponse,
   type ActivityEvent,
+  type ApiKey,
   type ApplyUpgradeResponse,
   acquireResponseSchema,
   applyUpgradeResponseSchema,
   type CheckUpgradeResponse,
+  type CreateApiKeyResponse,
   checkUpgradeResponseSchema,
+  createApiKeyResponseSchema,
   DEFAULT_EXEC_TIMEOUT_SECONDS,
   type DestroySandboxResponse,
   destroySandboxResponseSchema,
@@ -28,6 +31,7 @@ import {
   type ListSandboxImagesResponse,
   type ListSandboxMetricsResponse,
   listActivityResponseSchema,
+  listApiKeysResponseSchema,
   listSandboxesResponseSchema,
   listSandboxImagesResponseSchema,
   listSandboxMetricsResponseSchema,
@@ -35,11 +39,13 @@ import {
   type RebuildSandboxResponse,
   type RegisterTemplateResponse,
   type RemoveTemplateResponse,
+  type RevokeApiKeyResponse,
   readFileResponseSchema,
   readFilesResponseSchema,
   rebuildSandboxResponseSchema,
   registerTemplateResponseSchema,
   removeTemplateResponseSchema,
+  revokeApiKeyResponseSchema,
   type Sandbox,
   type SandboxMetadata,
   type SandboxMetricsSample,
@@ -427,6 +433,34 @@ export class Dormice {
     return removeTemplateResponseSchema.parse(data);
   }
 
+  /**
+   * Mints an API key — a full-power peer of the daemon's env token that can
+   * be revoked without touching the server. The returned `token` (64 hex
+   * chars) is shown here EXACTLY ONCE: the daemon stores only its hash, so
+   * no later call can retrieve it. Refused with a 409 while an active key
+   * already answers to this name.
+   */
+  async createApiKey(name: string): Promise<CreateApiKeyResponse> {
+    const data = await this.rpc('createApiKey', { name });
+    return createApiKeyResponseSchema.parse(data);
+  }
+
+  /** Every key ever minted, revoked ones included, newest first. No secrets. */
+  async listApiKeys(): Promise<ApiKey[]> {
+    const data = await this.rpc('listApiKeys', {});
+    return listApiKeysResponseSchema.parse(data).apiKeys;
+  }
+
+  /**
+   * Revokes the active key under a name — the credential stops working on
+   * the very next request; the row stays listed as rotation history.
+   * Idempotent: an unknown or already-revoked name answers `revoked: false`.
+   */
+  async revokeApiKey(name: string): Promise<RevokeApiKeyResponse> {
+    const data = await this.rpc('revokeApiKey', { name });
+    return revokeApiKeyResponseSchema.parse(data);
+  }
+
   /**
    * Runs a shell command inside the sandbox behind an external id and returns
    * the buffered result: honest exit code (a nonzero exit is a result, not
diff --git a/packages/server/drizzle/0009_api-keys.sql b/packages/server/drizzle/0009_api-keys.sql
new file mode 100644
index 0000000..546a553
--- /dev/null
+++ b/packages/server/drizzle/0009_api-keys.sql
@@ -0,0 +1,12 @@
+CREATE TABLE `api_keys` (
+	`id` text PRIMARY KEY NOT NULL,
+	`name` text NOT NULL,
+	`key_hash` text NOT NULL,
+	`prefix` text NOT NULL,
+	`created_at` text NOT NULL,
+	`last_used_at` text,
+	`revoked_at` text
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `api_keys_key_hash_unique` ON `api_keys` (`key_hash`);--> statement-breakpoint
+CREATE UNIQUE INDEX `api_keys_active_name_idx` ON `api_keys` (`name`) WHERE "api_keys"."revoked_at" IS NULL;
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/0009_snapshot.json b/packages/server/drizzle/meta/0009_snapshot.json
new file mode 100644
index 0000000..27ba709
--- /dev/null
+++ b/packages/server/drizzle/meta/0009_snapshot.json
@@ -0,0 +1,531 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "1d311aa2-3a7c-48e6-babd-226c86ce4e8c",
+  "prevId": "3eb1672c-b687-49d5-8830-e89294ffc780",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_id": {
+          "name": "external_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "api_keys": {
+      "name": "api_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "prefix": {
+          "name": "prefix",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "api_keys_key_hash_unique": {
+          "name": "api_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        },
+        "api_keys_active_name_idx": {
+          "name": "api_keys_active_name_idx",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true,
+          "where": "\"api_keys\".\"revoked_at\" IS NULL"
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "daemon_secrets": {
+      "name": "daemon_secrets",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "envd_signing_secret": {
+          "name": "envd_signing_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "fleet_snapshots": {
+      "name": "fleet_snapshots",
+      "columns": {
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active": {
+          "name": "active",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "frozen": {
+          "name": "frozen",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stopped": {
+          "name": "stopped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archived": {
+          "name": "archived",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "restoring": {
+          "name": "restoring",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "total": {
+          "name": "total",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandbox_metrics_samples": {
+      "name": "sandbox_metrics_samples",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_count": {
+          "name": "cpu_count",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_used_pct": {
+          "name": "cpu_used_pct",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_used_bytes": {
+          "name": "mem_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_total_bytes": {
+          "name": "mem_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_cache_bytes": {
+          "name": "mem_cache_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_used_bytes": {
+          "name": "disk_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_total_bytes": {
+          "name": "disk_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "sandbox_metrics_samples_sandbox_at_idx": {
+          "name": "sandbox_metrics_samples_sandbox_at_idx",
+          "columns": [
+            "sandbox_id",
+            "at"
+          ],
+          "isUnique": false
+        },
+        "sandbox_metrics_samples_at_idx": {
+          "name": "sandbox_metrics_samples_at_idx",
+          "columns": [
+            "at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_id": {
+          "name": "external_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_external_id_unique": {
+          "name": "sandboxes_external_id_unique",
+          "columns": [
+            "external_id"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index 51c55d6..a6296eb 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -64,6 +64,20 @@
       "when": 1784127595513,
       "tag": "0008_daemon-secrets",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1784141853788,
+      "tag": "0009_api-keys",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "6",
+      "when": 1784146840196,
+      "tag": "0010_template-updated-at",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index e2090ae..1438f18 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -1357,11 +1357,24 @@ describe('templates', () => {
     const first = (
       await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' })
     ).json().template;
+    // Born un-upgraded: the upgrade timestamp starts at the birth date.
+    expect(first.updatedAt).toBe(first.createdAt);
+    // Millisecond timestamps need real time to pass to tell apart.
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    // Same image again: idempotent, and updatedAt must not claim an upgrade.
+    const same = (
+      await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' })
+    ).json().template;
+    expect(same.updatedAt).toBe(first.updatedAt);
     const second = (
       await rpc(app, '/registerTemplate', { name: 'py', image: 'img-b' })
     ).json().template;
     expect(second.image).toBe('img-b');
     expect(second.createdAt).toBe(first.createdAt);
+    // A real image change stamps the upgrade time.
+    expect(Date.parse(second.updatedAt)).toBeGreaterThan(
+      Date.parse(first.updatedAt),
+    );
     expect((await rpc(app, '/listTemplates')).json().templates).toHaveLength(1);
   });
 
@@ -1539,3 +1552,123 @@ describe('POST /getHostMetrics', () => {
     expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
   });
 });
+
+describe('API keys', () => {
+  it('mints a 64-hex token, shown once and never stored in the view', async () => {
+    const { app } = testApp();
+    const res = await rpc(app, '/createApiKey', { name: 'ci' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.token).toMatch(/^[0-9a-f]{64}$/);
+    expect(body.apiKey).toMatchObject({
+      name: 'ci',
+      prefix: body.token.slice(0, 8),
+      lastUsedAt: null,
+      revokedAt: null,
+    });
+    // The view carries no secret — not the token, not its hash.
+    expect(JSON.stringify(body.apiKey)).not.toContain(body.token);
+    expect(Object.keys(body.apiKey)).not.toContain('keyHash');
+  });
+
+  it('a minted key opens the Bearer door; revoking closes it on the next request', async () => {
+    const { app } = testApp();
+    const { token } = (await rpc(app, '/createApiKey', { name: 'ci' })).json();
+    const asKey = { authorization: `Bearer ${token}` };
+
+    const before = await app.inject({
+      method: 'POST',
+      url: '/listSandboxes',
+      headers: asKey,
+      payload: {},
+    });
+    expect(before.statusCode).toBe(200);
+
+    expect((await rpc(app, '/revokeApiKey', { name: 'ci' })).json()).toEqual({
+      revoked: true,
+    });
+    const afterRevoke = await app.inject({
+      method: 'POST',
+      url: '/listSandboxes',
+      headers: asKey,
+      payload: {},
+    });
+    expect(afterRevoke.statusCode).toBe(401);
+
+    // The env token is the bootstrap credential: revocation never touches it.
+    expect((await rpc(app, '/listSandboxes')).statusCode).toBe(200);
+  });
+
+  it('refuses a second active key under the same name with a 409, and frees the name after revoke', async () => {
+    const { app } = testApp();
+    await rpc(app, '/createApiKey', { name: 'ci' });
+    const dup = await rpc(app, '/createApiKey', { name: 'ci' });
+    expect(dup.statusCode).toBe(409);
+    expect(dup.json().message).toMatch(/'ci' already exists/);
+
+    await rpc(app, '/revokeApiKey', { name: 'ci' });
+    expect((await rpc(app, '/createApiKey', { name: 'ci' })).statusCode).toBe(
+      200,
+    );
+  });
+
+  it('revoke is idempotent: an unknown or already-revoked name answers { revoked: false }', async () => {
+    const { app } = testApp();
+    expect((await rpc(app, '/revokeApiKey', { name: 'ghost' })).json()).toEqual(
+      { revoked: false },
+    );
+    await rpc(app, '/createApiKey', { name: 'ci' });
+    await rpc(app, '/revokeApiKey', { name: 'ci' });
+    expect((await rpc(app, '/revokeApiKey', { name: 'ci' })).json()).toEqual({
+      revoked: false,
+    });
+  });
+
+  it('lists every key ever minted, revoked rows included, newest first', async () => {
+    const { app } = testApp();
+    await rpc(app, '/createApiKey', { name: 'old' });
+    await rpc(app, '/revokeApiKey', { name: 'old' });
+    await rpc(app, '/createApiKey', { name: 'new' });
+
+    const keys = (await rpc(app, '/listApiKeys')).json().apiKeys;
+    expect(keys).toHaveLength(2);
+    expect(keys[0].name).toBe('new');
+    expect(keys[0].revokedAt).toBeNull();
+    expect(keys[1].name).toBe('old');
+    expect(keys[1].revokedAt).not.toBeNull();
+  });
+
+  it('stamps lastUsedAt on first use and throttles the write to 60s granularity', async () => {
+    const { app } = testApp();
+    const { token } = (await rpc(app, '/createApiKey', { name: 'ci' })).json();
+    const asKey = { authorization: `Bearer ${token}` };
+    const use = () =>
+      app.inject({
+        method: 'POST',
+        url: '/listSandboxes',
+        headers: asKey,
+        payload: {},
+      });
+
+    await use();
+    const first = (await rpc(app, '/listApiKeys')).json().apiKeys[0];
+    expect(first.lastUsedAt).not.toBeNull();
+
+    // A second use inside the 60s window must not move the stamp.
+    await use();
+    const second = (await rpc(app, '/listApiKeys')).json().apiKeys[0];
+    expect(second.lastUsedAt).toBe(first.lastUsedAt);
+  });
+
+  it('records mint and revoke in the activity ring, token nowhere in sight', async () => {
+    const { app } = testApp();
+    const { token } = (await rpc(app, '/createApiKey', { name: 'ci' })).json();
+    await rpc(app, '/revokeApiKey', { name: 'ci' });
+
+    const events = (await rpc(app, '/listActivity')).json().events;
+    const kinds = events.map((e: { kind: string }) => e.kind);
+    expect(kinds).toContain('apikey-created');
+    expect(kinds).toContain('apikey-revoked');
+    expect(JSON.stringify(events)).not.toContain(token);
+  });
+});
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 1b4f399..f552c06 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -10,9 +10,10 @@ import {
 import { type Logger, pino } from 'pino';
 import { z } from 'zod';
 import type { Archiver } from './archive/archiver';
-import { requireApiAuth } from './auth';
+import { requireApiAuth, tokensEqual } from './auth';
 import { type Config, type ConfigSources, configSources } from './config';
 import { getConsoleAccount } from './db/account';
+import { verifyApiKeyToken } from './db/api-keys';
 import type { Db } from './db/db';
 import { getOrCreateSigningSecret } from './db/secrets';
 import { registerE2bCompat } from './e2b';
@@ -23,6 +24,7 @@ import type { Ingress } from './ingress';
 import type { KeyedQueue } from './keyed-queue';
 import { ARCHIVE_DEFAULT_SECONDS } from './policy';
 import { activityRoutes } from './routes/activity';
+import { apiKeyRoutes } from './routes/api-keys';
 import { configRoutes } from './routes/config';
 import { consoleRoutes } from './routes/console';
 import { hostRoutes } from './routes/host';
@@ -185,12 +187,21 @@ export function buildApp({
   // cookie on the native routes, the /console surface mints and clears it.
   app.register(fastifyCookie);
 
+  // The one adjudication of "does this bare credential open the door":
+  // the env token (constant-time compare — the bootstrap credential, always
+  // valid) or any active ledger API key (sha256 indexed lookup, judged per
+  // request so a mint or revoke takes effect on the very next call). Both
+  // faces — the native Bearer header and the E2B X-API-KEY hook — feed this
+  // same closure: one truth, two dialects.
+  const verifyCredential = (bare: string): boolean =>
+    tokensEqual(bare, config.DORMICE_API_TOKEN) || verifyApiKeyToken(db, bare);
+
   // Built once, used by every guarded surface. The secret getter reads the
   // ledger per request because setup can replace the account (and void its
   // sessions) while the daemon runs — a captured value would keep dead
   // sessions alive until restart.
   const apiAuth = requireApiAuth(
-    config.DORMICE_API_TOKEN,
+    verifyCredential,
     () => getConsoleAccount(db)?.sessionSecret ?? null,
   );
 
@@ -210,6 +221,7 @@ export function buildApp({
       archiveDefaultSeconds,
     });
     await api.register(templateRoutes, { db });
+    await api.register(apiKeyRoutes, { db });
     await api.register(hostRoutes, { config, db, executor });
     await api.register(activityRoutes, { db });
     await api.register(ingressRoutes, { db, ingress });
@@ -251,6 +263,7 @@ export function buildApp({
       archiver,
       archiveDefaultSeconds,
       envdSigningSecret,
+      verifyCredential,
     });
   });
 
diff --git a/packages/server/src/auth.ts b/packages/server/src/auth.ts
index e37cae3..fc625b6 100644
--- a/packages/server/src/auth.ts
+++ b/packages/server/src/auth.ts
@@ -136,9 +136,16 @@ export function verifySession(
 /**
  * The single arbiter of who may call the API (/healthz stays open —
  * liveness probes have no secrets). Two credentials open the same door:
- * the Bearer token (SDK, CLI, curl) and the web console's session cookie
- * (which additionally requires the console header, see above). A second
- * route surface with its own auth would be a second truth.
+ * a Bearer credential (SDK, CLI, curl — the env token or any active API
+ * key, adjudicated by verifyCredential) and the web console's session
+ * cookie (which additionally requires the console header, see above). A
+ * second route surface with its own auth would be a second truth.
+ *
+ * verifyCredential judges bare tokens, so both faces (this Bearer header
+ * and the E2B X-API-KEY hook) feed it the same canonical form — one
+ * closure, one truth, two dialects. The 'Bearer ' prefix is public
+ * framing, not a secret, so stripping it needs no constant time; the
+ * secret comparisons live inside verifyCredential.
  *
  * The session secret is fetched per request, not captured at startup: setup
  * can replace the account (and its secret) while the daemon runs, and the
@@ -146,11 +153,13 @@ export function verifySession(
  * yet — no cookie can be valid.
  */
 export function requireApiAuth(
-  token: string,
+  verifyCredential: (bareToken: string) => boolean,
   getSessionSecret: () => string | null,
 ): onRequestAsyncHookHandler {
   return async (request, reply) => {
-    if (tokensEqual(request.headers.authorization ?? '', `Bearer ${token}`)) {
+    const header = request.headers.authorization;
+    const bare = header?.startsWith('Bearer ') ? header.slice(7) : null;
+    if (bare !== null && verifyCredential(bare)) {
       return;
     }
     const cookie = request.cookies?.[SESSION_COOKIE];
diff --git a/packages/server/src/db/api-keys.ts b/packages/server/src/db/api-keys.ts
new file mode 100644
index 0000000..01bacdd
--- /dev/null
+++ b/packages/server/src/db/api-keys.ts
@@ -0,0 +1,122 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { and, desc, eq, isNull, lt, or } from 'drizzle-orm';
+import { recordActivity } from './activity';
+import type { Db } from './db';
+import { type ApiKeyRow, apiKeys } from './schema';
+
+/**
+ * lastUsedAt write granularity. A hot-polling client authenticates many
+ * times a second; writing the ledger on every hit would turn the WAL into
+ * an EKG for zero information. One write a minute answers the only question
+ * the column exists for — "is this key still alive, roughly since when".
+ */
+const LAST_USED_GRANULARITY_MS = 60_000;
+
+/** sha256 hex of the bare key material — the only form the ledger stores. */
+export function hashApiKeyToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+/**
+ * Mints a key and returns the material exactly once — the row keeps only
+ * the hash, so this return value is the caller's single chance to see it.
+ * Pure hex, no brand prefix: the official Python E2B SDK validates
+ * `e2b_[0-9a-f]+` client-side, so anything non-hex could never be used on
+ * the X-API-KEY face at all.
+ *
+ * The caller (route) has already refused a duplicate active name with a
+ * 409; the partial unique index backstops that check as a schema fact.
+ */
+export function createApiKey(
+  db: Db,
+  name: string,
+): { row: ApiKeyRow; token: string } {
+  const token = randomBytes(32).toString('hex');
+  const row: ApiKeyRow = {
+    id: randomUUID(),
+    name,
+    keyHash: hashApiKeyToken(token),
+    prefix: token.slice(0, 8),
+    createdAt: new Date().toISOString(),
+    lastUsedAt: null,
+    revokedAt: null,
+  };
+  db.insert(apiKeys).values(row).run();
+  recordActivity(db, {
+    kind: 'apikey-created',
+    detail: `API key "${name}" (prefix ${row.prefix}) minted`,
+  });
+  return { row, token };
+}
+
+export function findActiveApiKeyByName(
+  db: Db,
+  name: string,
+): ApiKeyRow | undefined {
+  return db
+    .select()
+    .from(apiKeys)
+    .where(and(eq(apiKeys.name, name), isNull(apiKeys.revokedAt)))
+    .get();
+}
+
+/** Every key ever minted, revoked ones included — the rotation history. */
+export function listApiKeys(db: Db): ApiKeyRow[] {
+  return db.select().from(apiKeys).orderBy(desc(apiKeys.createdAt)).all();
+}
+
+/**
+ * Soft-revokes the active key under this name. Returns false when none was
+ * active — the desired end state was already true. The row survives as
+ * history; the name is immediately free for a new key.
+ */
+export function revokeApiKey(db: Db, name: string): boolean {
+  const result = db
+    .update(apiKeys)
+    .set({ revokedAt: new Date().toISOString() })
+    .where(and(eq(apiKeys.name, name), isNull(apiKeys.revokedAt)))
+    .run();
+  const revoked = result.changes > 0;
+  if (revoked) {
+    recordActivity(db, {
+      kind: 'apikey-revoked',
+      detail: `API key "${name}" revoked`,
+    });
+  }
+  return revoked;
+}
+
+/**
+ * The ledger leg of credential verification: does this bare token match an
+ * active key? An indexed exact-match lookup on sha256(token) — not a
+ * timing-safe scan, deliberately: the comparison can at worst leak bytes of
+ * sha256(key), which preimage resistance makes worthless to an attacker
+ * (the argument GitHub token storage rests on).
+ *
+ * A hit also stamps lastUsedAt, throttled to LAST_USED_GRANULARITY_MS so a
+ * polling client does not write the ledger per request. ISO strings compare
+ * lexicographically as timestamps, so the cutoff is a plain string <.
+ */
+export function verifyApiKeyToken(db: Db, bareToken: string): boolean {
+  const hash = hashApiKeyToken(bareToken);
+  const row = db
+    .select({ id: apiKeys.id, lastUsedAt: apiKeys.lastUsedAt })
+    .from(apiKeys)
+    .where(and(eq(apiKeys.keyHash, hash), isNull(apiKeys.revokedAt)))
+    .get();
+  if (!row) {
+    return false;
+  }
+  const now = Date.now();
+  const cutoff = new Date(now - LAST_USED_GRANULARITY_MS).toISOString();
+  db.update(apiKeys)
+    .set({ lastUsedAt: new Date(now).toISOString() })
+    .where(
+      and(
+        eq(apiKeys.id, row.id),
+        or(isNull(apiKeys.lastUsedAt), lt(apiKeys.lastUsedAt, cutoff)),
+      ),
+    )
+    .run();
+  return true;
+}
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index 3922541..9746867 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -1,10 +1,12 @@
 import { ACTIVITY_KINDS, SANDBOX_STATES } from '@dormice/shared';
+import { sql } from 'drizzle-orm';
 import {
   index,
   integer,
   real,
   sqliteTable,
   text,
+  uniqueIndex,
 } from 'drizzle-orm/sqlite-core';
 
 /**
@@ -73,6 +75,8 @@ export const templates = sqliteTable('templates', {
   name: text('name').primaryKey(),
   image: text('image').notNull(),
   createdAt: text('created_at').notNull(),
+  /** Bumped only when the image actually changes — see registerTemplate. */
+  updatedAt: text('updated_at').notNull(),
 });
 
 export type TemplateRow = typeof templates.$inferSelect;
@@ -210,3 +214,46 @@ export const daemonSecrets = sqliteTable('daemon_secrets', {
 });
 
 export type DaemonSecretsRow = typeof daemonSecrets.$inferSelect;
+
+/**
+ * Ledger-minted API keys: full-power peers of DORMICE_API_TOKEN that exist
+ * so credentials can rotate without an env edit and a restart. The env
+ * token itself never lives here — it stays the bootstrap/recovery
+ * credential, checked from config.
+ *
+ * keyHash is sha256 of the key material, not scrypt: a key is 256 random
+ * bits, not a human password, so offline brute force is moot and a slow
+ * KDF would only tax every authenticated request. Verification is an
+ * indexed exact-match lookup on the hash; the timing of that comparison
+ * can at worst leak sha256(key) bytes, which preimage resistance makes
+ * worthless (the same argument GitHub tokens rest on).
+ *
+ * Revocation is soft (revokedAt) — the row stays as rotation history and
+ * keeps lastUsedAt readable after the credential dies. "At most one ACTIVE
+ * key per name" is a schema fact via the partial unique index below (the
+ * console_account fixed-id philosophy); a revoked name is free for reuse.
+ */
+export const apiKeys = sqliteTable(
+  'api_keys',
+  {
+    /** UUID, never an autoincrement — ids must stay unique across machines. */
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+    /** sha256 hex of the bare 64-hex key material. The key itself is never stored. */
+    keyHash: text('key_hash').notNull().unique(),
+    /** First 8 hex chars of the key, for display — 32 bits, no meaningful entropy. */
+    prefix: text('prefix').notNull(),
+    createdAt: text('created_at').notNull(),
+    /** Null = never used. Written with 60s granularity, not per request. */
+    lastUsedAt: text('last_used_at'),
+    /** Null = active. Set once by revokeApiKey; never cleared. */
+    revokedAt: text('revoked_at'),
+  },
+  (table) => [
+    uniqueIndex('api_keys_active_name_idx')
+      .on(table.name)
+      .where(sql`${table.revokedAt} IS NULL`),
+  ],
+);
+
+export type ApiKeyRow = typeof apiKeys.$inferSelect;
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 022895b..4a21893 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -211,6 +211,41 @@ describe('E2B control plane', () => {
     expect(bare.statusCode).toBe(201);
   });
 
+  it('a ledger API key opens the X-API-KEY door too, until revoked', async () => {
+    const t = testApp();
+    // Minted over the native face — the same credential truth serves both.
+    const minted = await t.app.inject({
+      method: 'POST',
+      url: '/createApiKey',
+      headers: { authorization: `Bearer ${TOKEN}` },
+      payload: { name: 'e2b-client' },
+    });
+    const { token } = minted.json();
+
+    const prefixed = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/api/sandboxes',
+      headers: { 'x-api-key': `e2b_${token}` },
+      payload: {},
+    });
+    expect(prefixed.statusCode).toBe(201);
+
+    await t.app.inject({
+      method: 'POST',
+      url: '/revokeApiKey',
+      headers: { authorization: `Bearer ${TOKEN}` },
+      payload: { name: 'e2b-client' },
+    });
+    const revoked = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/api/sandboxes',
+      headers: { 'x-api-key': `e2b_${token}` },
+      payload: {},
+    });
+    expect(revoked.statusCode).toBe(401);
+    expect(revoked.json()).toEqual({ code: 401, message: 'invalid API key' });
+  });
+
   it('creates a fresh sandbox per call — E2B semantics, no key given', async () => {
     const t = testApp();
     const first = await createSandbox(t);
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index 1fb8dc4..e3e69be 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -100,6 +100,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     archiver,
     archiveDefaultSeconds,
     envdSigningSecret,
+    verifyCredential,
   },
 ) => {
   /**
@@ -131,7 +132,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   app.addHook('onRequest', async (request, reply) => {
     const presented = request.headers['x-api-key'];
     const key = Array.isArray(presented) ? presented[0] : presented;
-    if (!verifyApiKey(config.DORMICE_API_TOKEN, key)) {
+    if (!verifyApiKey(verifyCredential, key)) {
       await reply.code(401).send({ code: 401, message: 'invalid API key' });
     }
   });
diff --git a/packages/server/src/e2b/deps.ts b/packages/server/src/e2b/deps.ts
index 9e5e1b6..473f6a4 100644
--- a/packages/server/src/e2b/deps.ts
+++ b/packages/server/src/e2b/deps.ts
@@ -31,4 +31,10 @@ export interface E2bDeps {
    * signing secret, never the API token (they rotate independently).
    */
   envdSigningSecret: string;
+  /**
+   * buildApp's one adjudication of "does this bare credential open the
+   * door" (env token or any active ledger API key) — the same closure the
+   * native Bearer face uses, consulted here by the X-API-KEY hook.
+   */
+  verifyCredential: (bareToken: string) => boolean;
 }
diff --git a/packages/server/src/e2b/protocol.ts b/packages/server/src/e2b/protocol.ts
index 0755b81..e8b1f26 100644
--- a/packages/server/src/e2b/protocol.ts
+++ b/packages/server/src/e2b/protocol.ts
@@ -84,15 +84,18 @@ export function verifyEnvdToken(
 
 /**
  * X-API-KEY check. The official SDK formats keys as `e2b_<hex>` and our
- * hex API token is compliant as `e2b_<token>`; the bare token is accepted
- * too — the prefix is the SDK's convention, not a secret.
+ * hex credentials are compliant as `e2b_<token>`; the bare token is
+ * accepted too — the prefix is the SDK's convention, not a secret. What
+ * opens the door is adjudicated by verifyCredential (buildApp's closure:
+ * env token or any active ledger API key), the same truth the native
+ * Bearer face consults.
  */
 export function verifyApiKey(
-  apiToken: string,
+  verifyCredential: (bareToken: string) => boolean,
   presented: string | undefined,
 ): boolean {
   const bare = presented?.startsWith('e2b_') ? presented.slice(4) : presented;
-  return timingSafeEqual(sha256(bare ?? ''), sha256(apiToken));
+  return bare !== undefined && verifyCredential(bare);
 }
 
 /** Connect streaming envelope flags: 0x00 = message, 0x02 = end of stream. */
diff --git a/packages/server/src/routes/api-keys.ts b/packages/server/src/routes/api-keys.ts
new file mode 100644
index 0000000..3ecf9db
--- /dev/null
+++ b/packages/server/src/routes/api-keys.ts
@@ -0,0 +1,92 @@
+import {
+  type ApiKey,
+  createApiKeyRequestSchema,
+  createApiKeyResponseSchema,
+  listApiKeysResponseSchema,
+  revokeApiKeyRequestSchema,
+  revokeApiKeyResponseSchema,
+} from '@dormice/shared';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import {
+  createApiKey,
+  findActiveApiKeyByName,
+  listApiKeys,
+  revokeApiKey,
+} from '../db/api-keys';
+import type { Db } from '../db/db';
+import type { ApiKeyRow } from '../db/schema';
+import { httpError } from '../http-error';
+
+export interface ApiKeyRoutesOptions {
+  db: Db;
+}
+
+/** The wire view: everything but the hash — no secret ever leaves the row. */
+function view(row: ApiKeyRow): ApiKey {
+  return {
+    id: row.id,
+    name: row.name,
+    prefix: row.prefix,
+    createdAt: row.createdAt,
+    lastUsedAt: row.lastUsedAt,
+    revokedAt: row.revokedAt,
+  };
+}
+
+/**
+ * API key management: mint, list, revoke. Pure ledger verbs — no executor,
+ * no locks — sitting behind the same auth they extend: the first key is
+ * minted with the env token (or a console session), later ones with any
+ * live key. Verification itself lives in db/api-keys.ts and is consulted
+ * by buildApp's verifyCredential closure, not here.
+ */
+export const apiKeyRoutes: FastifyPluginAsyncZod<ApiKeyRoutesOptions> = async (
+  app,
+  { db },
+) => {
+  app.post(
+    '/createApiKey',
+    {
+      schema: {
+        body: createApiKeyRequestSchema,
+        response: { 200: createApiKeyResponseSchema },
+      },
+    },
+    async (request) => {
+      const { name } = request.body;
+      // Two live credentials answering to one name is a rotation mistake,
+      // not a goal — refused by name, like removeTemplate's 409. The
+      // partial unique index backstops this check as a schema fact; no
+      // await sits between check and insert, so they cannot race.
+      if (findActiveApiKeyByName(db, name)) {
+        throw httpError(
+          409,
+          `an active API key named '${name}' already exists — revoke it first or pick another name`,
+        );
+      }
+      const { row, token } = createApiKey(db, name);
+      return { apiKey: view(row), token };
+    },
+  );
+
+  app.post(
+    '/listApiKeys',
+    {
+      schema: {
+        response: { 200: listApiKeysResponseSchema },
+      },
+    },
+    async () => ({ apiKeys: listApiKeys(db).map(view) }),
+  );
+
+  app.post(
+    '/revokeApiKey',
+    {
+      schema: {
+        body: revokeApiKeyRequestSchema,
+        response: { 200: revokeApiKeyResponseSchema },
+      },
+    },
+    async (request) => ({ revoked: revokeApiKey(db, request.body.name) }),
+  );
+};
diff --git a/packages/server/src/routes/console.ts b/packages/server/src/routes/console.ts
index 23c8ae8..ffbdb91 100644
--- a/packages/server/src/routes/console.ts
+++ b/packages/server/src/routes/console.ts
@@ -110,6 +110,11 @@ export const consoleRoutes: FastifyPluginAsyncZod<
           message: `too many failed attempts — retry in ${wait}s`,
         });
       }
+      // Deliberately the env token only, never a ledger API key: this verb
+      // resets the human account, and a leaked machine credential must not
+      // escalate into a console takeover. The token's root of trust is
+      // filesystem access to /etc/dormice/env — exactly what a recovery
+      // path should require.
       if (!tokensEqual(request.body.token, config.DORMICE_API_TOKEN)) {
         throttle.recordFailure(request.ip);
         return reply.code(401).send({ message: 'invalid API token' });
diff --git a/packages/shared/src/activity.ts b/packages/shared/src/activity.ts
index d7e6d68..ae04595 100644
--- a/packages/shared/src/activity.ts
+++ b/packages/shared/src/activity.ts
@@ -31,6 +31,10 @@ export const ACTIVITY_KINDS = [
   'daemon-started',
   /** An operator bound or cleared the console domain through setIngress. */
   'ingress-updated',
+  /** An operator minted an API key (createApiKey). The token itself is never logged. */
+  'apikey-created',
+  /** An operator revoked an API key (revokeApiKey) — the credential died here. */
+  'apikey-revoked',
   /**
    * An operator launched the one-click self-upgrade (applyUpgrade). Only
    * the launch is recorded — the outcome lives in getUpgradeStatus, and
diff --git a/packages/shared/src/api-keys.ts b/packages/shared/src/api-keys.ts
new file mode 100644
index 0000000..f7a268d
--- /dev/null
+++ b/packages/shared/src/api-keys.ts
@@ -0,0 +1,85 @@
+import { z } from 'zod';
+
+/**
+ * API keys: ledger-minted credentials that open the same doors as
+ * DORMICE_API_TOKEN — the native Bearer face and the E2B X-API-KEY face
+ * alike. They exist so the operator can rotate credentials without touching
+ * /etc/dormice/env or restarting the daemon: mint a new key, move clients
+ * over, revoke the old one. The env token stays valid forever as the
+ * bootstrap/recovery credential (and the console-setup root of trust — a
+ * key can NOT reset the console password).
+ *
+ * Every key is full-power. There is no per-key authorization scoping —
+ * that would be a multi-tenant model, and Dormice is single-operator.
+ *
+ * The key material is 64 hex chars, no brand prefix: the official Python
+ * E2B SDK validates `e2b_[0-9a-f]+` client-side, so anything non-hex could
+ * never be used on the E2B face at all.
+ */
+export const apiKeyNameSchema = z.string().trim().min(1).max(64);
+
+export const apiKeySchema = z.object({
+  /** Row identity (UUID). The name is the human handle; this never changes. */
+  id: z.string(),
+  name: apiKeyNameSchema,
+  /**
+   * First 8 hex chars of the key — enough to match a leaked credential to
+   * its row without giving away meaningful entropy (32 of 256 bits).
+   */
+  prefix: z.string(),
+  createdAt: z.iso.datetime(),
+  /** Null = never used. Written with 60s granularity, not per request. */
+  lastUsedAt: z.iso.datetime().nullable(),
+  /** Null = active. Revoked rows stay listed — they are the rotation history. */
+  revokedAt: z.iso.datetime().nullable(),
+});
+
+export type ApiKey = z.infer<typeof apiKeySchema>;
+
+/**
+ * createApiKey(name) — mints a key and returns the token exactly once. The
+ * ledger stores only its sha256, so no later call can ever reveal it again.
+ * A second active key under the same name is refused with a 409: two live
+ * credentials answering to one name is a rotation mistake, not a goal.
+ */
+export const createApiKeyRequestSchema = z.object({
+  name: apiKeyNameSchema,
+});
+
+export type CreateApiKeyRequest = z.infer<typeof createApiKeyRequestSchema>;
+
+export const createApiKeyResponseSchema = z.object({
+  apiKey: apiKeySchema,
+  /** The 64-hex key material. Shown here once; never retrievable again. */
+  token: z.string(),
+});
+
+export type CreateApiKeyResponse = z.infer<typeof createApiKeyResponseSchema>;
+
+/** listApiKeys() — every key ever minted, revoked ones included, newest first. */
+export const listApiKeysResponseSchema = z.object({
+  apiKeys: z.array(apiKeySchema),
+});
+
+export type ListApiKeysResponse = z.infer<typeof listApiKeysResponseSchema>;
+
+/**
+ * revokeApiKey(name) — soft-revokes the active key under this name: the row
+ * stays as history, the credential stops opening doors on the next request.
+ * Idempotent like destroySandbox: "no active key under this name" is the
+ * desired end state, so an unknown or already-revoked name answers
+ * { revoked: false } rather than an error. Callers should say that false
+ * out loud — a typo here would leave a leaked key alive.
+ */
+export const revokeApiKeyRequestSchema = z.object({
+  name: apiKeyNameSchema,
+});
+
+export type RevokeApiKeyRequest = z.infer<typeof revokeApiKeyRequestSchema>;
+
+export const revokeApiKeyResponseSchema = z.object({
+  /** True when an active key existed and was revoked; false when none did. */
+  revoked: z.boolean(),
+});
+
+export type RevokeApiKeyResponse = z.infer<typeof revokeApiKeyResponseSchema>;
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index fd2025d..e1c9477 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -1,5 +1,6 @@
 export * from './acquire';
 export * from './activity';
+export * from './api-keys';
 export * from './config';
 export * from './destroy';
 export * from './exec';
diff --git a/skills/dormice/SKILL.md b/skills/dormice/SKILL.md
index c471d1a..97a82c4 100644
--- a/skills/dormice/SKILL.md
+++ b/skills/dormice/SKILL.md
@@ -28,6 +28,8 @@ the operator has either an SSH tunnel
 or a reverse-proxy domain (then use `https://their-domain`). Auth is one
 API token (created by the installer, hex): ask the user for the endpoint
 and token, conventionally held in `DORMICE_ENDPOINT` / `DORMICE_API_TOKEN`.
+API keys minted in the console (or with `dor apikey create <name>`) work
+everywhere the token does — same variables, revocable per client.
 
 ## Pick an entry path
 
@@ -116,6 +118,8 @@ an existing sandbox's lifecycle policy in place — no wake, no destroy),
 `execCommand`, `writeFiles` / `writeFile`, `readFile` / `readFiles`,
 `rebuildSandbox` (fresh container, `/home/user` kept), `destroySandbox`,
 `registerTemplate` / `listTemplates` / `removeTemplate`,
+`createApiKey` / `listApiKeys` / `revokeApiKey` (revocable peers of the
+API token; the create response shows the key once, never again),
 `getHostMetrics`, `getSandboxMetrics` / `listSandboxMetrics` (live
 resource samples; never wake anything), `listSandboxImages` (who still
 runs an old template image), `listActivity` (recent daemon history),
@@ -138,6 +142,7 @@ dor sandbox pull my-agent notes.txt
 dor sandbox rebuild my-agent          # fresh container, /home/user kept
 dor sandbox meta my-agent app=crawler # replace labels (no args = show)
 dor sandbox destroy my-agent
+dor apikey create ci                  # mint a revocable key (printed once)
 dor doctor                            # can this machine run sandboxes?
 ```
 
diff --git a/website/content/docs/cli.mdx b/website/content/docs/cli.mdx
index 3943c3f..3aed83c 100644
--- a/website/content/docs/cli.mdx
+++ b/website/content/docs/cli.mdx
@@ -90,6 +90,22 @@ A template is a name for a Docker image already on the daemon's host.
 sandboxes named) while any sandbox still uses the template, and never
 removes the image itself.
 
+## dor apikey
+
+```sh
+dor apikey create <name>   # prints the key once — store it immediately
+dor apikey ls
+dor apikey revoke <name>
+```
+
+API keys are revocable peers of `DORMICE_API_TOKEN` — same power, but
+killable without touching the server ([details](/docs/http-api#api-keys)).
+`create` prints the 64-hex token exactly once; the daemon keeps only its
+hash. The minted key goes wherever the token goes, including this CLI's
+own `DORMICE_API_TOKEN` variable. `revoke` takes effect on the key's
+next request; revoking a name that has no active key says so honestly —
+check the spelling before assuming the leak is plugged.
+
 ## dor doctor
 
 ```sh
diff --git a/website/content/docs/configuration.mdx b/website/content/docs/configuration.mdx
index 203e1e4..4796447 100644
--- a/website/content/docs/configuration.mdx
+++ b/website/content/docs/configuration.mdx
@@ -27,7 +27,7 @@ Unfamiliar terms in the tables below are covered in
 
 | Variable | Default | What it does |
 | --- | --- | --- |
-| `DORMICE_API_TOKEN` | — **(required)** | Bearer token for the native API, and (with an `e2b_` prefix) the E2B API key. At least 32 characters; generate with `openssl rand -hex 32`. Keep it hex: the official Python e2b SDK validates `e2b_[0-9a-f]+` client-side. |
+| `DORMICE_API_TOKEN` | — **(required)** | Bearer token for the native API, and (with an `e2b_` prefix) the E2B API key. At least 32 characters; generate with `openssl rand -hex 32`. Keep it hex: the official Python e2b SDK validates `e2b_[0-9a-f]+` client-side. This is the bootstrap credential — for day-to-day clients, mint revocable [API keys](/docs/http-api#api-keys) instead and keep this one for recovery. |
 | `DORMICE_PORT` | `3676` | The one port everything is served on: native API, E2B surface, web console. Always bound to 127.0.0.1 — there is deliberately no host setting. |
 | `DORMICE_DB_PATH` | `data/dormice.db` | Where the SQLite database lives. Must be an **absolute path** in docker mode — a relative path depends on the start directory, and a wrong start directory means an empty database facing real sandboxes. |
 | `DORMICE_NODE_ID` | `node-1` | Identifies this machine in the database. Single-machine today; the field keeps the schema shardable later. |
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
index e25834b..bfa2054 100644
--- a/website/content/docs/console.mdx
+++ b/website/content/docs/console.mdx
@@ -80,13 +80,25 @@ form is the same [upgrade front door](/docs/templates) as
 `dor template add`. Deleting a template a sandbox still uses is refused
 with the daemon's own message naming the sandboxes.
 
+## API keys
+
+Mint revocable credentials without leaving the browser
+([what they are](/docs/http-api#api-keys)). The create dialog shows the
+key **exactly once** — the daemon stores only a hash — with a copy
+button and no second chance. The table keeps every key ever minted,
+revoked ones included, as your rotation history: name, prefix, creation
+time, last use, status. Revoking takes effect on the key's next request.
+`DORMICE_API_TOKEN` itself never appears here — it is the bootstrap
+credential, and retiring it means editing `/etc/dormice/env`.
+
 ## Activity, domains, and settings
 
 Three more pages round out the operator view:
 
 - **Activity** — the daemon's recent history (who was created, frozen,
-  destroyed, what the reconciler repaired), filterable by event kind
-  and sandbox key. A bounded window, not an audit log.
+  destroyed, what the reconciler repaired, which API key was minted or
+  revoked), filterable by event kind and sandbox key. A bounded window,
+  not an audit log.
 - **Domains** — bind domains to the daemon's front door (the managed
   reverse proxy), with a copyable DNS record guide and a live per-domain
   probe that shows DNS and certificate progress until each one turns
diff --git a/website/content/docs/e2b-sdks.mdx b/website/content/docs/e2b-sdks.mdx
index bdd7868..f188db5 100644
--- a/website/content/docs/e2b-sdks.mdx
+++ b/website/content/docs/e2b-sdks.mdx
@@ -55,6 +55,10 @@ against `e2b_[0-9a-f]+` on the client side, before any request leaves
 the machine — a token with other characters fails in the SDK, not on the
 wire.
 
+[API keys](/docs/http-api#api-keys) minted through the daemon work here
+too — `e2b_<key>` anywhere the token goes, and they are pure hex by
+construction, so the Python SDK's validation never bites.
+
 ## Reuse the same sandbox across creates
 
 A Dormice extension: pass `metadata: { externalId: '...' }` and
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
index 5472086..6332bc4 100644
--- a/website/content/docs/http-api.mdx
+++ b/website/content/docs/http-api.mdx
@@ -18,7 +18,9 @@ Two rules cover the whole surface:
 
 - **Auth** is `Authorization: Bearer <token>` on every route except
   `GET /healthz`, the open liveness probe (it answers
-  `{"status":"ok"}`).
+  `{"status":"ok"}`). The token is `DORMICE_API_TOKEN` — or any active
+  [API key](#api-keys), the revocable credentials minted through
+  `createApiKey` or the console.
 - **Every non-2xx body is `{ "message": "..." }`** — one error shape,
   whoever produced the error. 4xx name your mistake; 5xx are the
   daemon's.
@@ -44,6 +46,9 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | `POST /registerTemplate` | upsert name → image | 400 `'base'` is reserved |
 | `POST /listTemplates` | every registered template | — |
 | `POST /removeTemplate` | unregister; idempotent | 409 while sandboxes still use it (names them) |
+| `POST /createApiKey` | mint an [API key](#api-keys); the token appears in this response once, never again | 409 while an active key already has this name |
+| `POST /listApiKeys` | every key ever minted, revoked ones included, newest first — no secrets | — |
+| `POST /revokeApiKey` | soft-revoke the active key under a name; idempotent (`revoked: false` when none was) | — |
 | `POST /getHostMetrics` | host snapshot; never wakes anything | — |
 | `POST /getSandboxMetrics` | one sandbox's live CPU/memory/disk sample; `sample` is `null` when nothing is running | 404 unknown key |
 | `POST /listSandboxMetrics` | every measurable sandbox's sample in one answer | — |
@@ -89,6 +94,26 @@ coming back from S3 —
 poll acquire until it flips to `ready` (see
 [Archiving](/docs/archiving)).
 
+## API keys
+
+`DORMICE_API_TOKEN` works forever, but rotating it means editing
+`/etc/dormice/env` and restarting the daemon. API keys are its
+full-power, revocable peers: mint one per client with
+`POST /createApiKey {"name": "ci"}`, hand out the returned 64-hex
+`token`, and when a key leaks, `POST /revokeApiKey {"name": "ci"}` kills
+exactly that credential on its next request — no config edit, no
+restart, no other client disturbed.
+
+The token appears in the create response **once**. The daemon stores
+only its hash, so nothing can ever show it again — copy it then. Keys
+open every door the env token does, the
+[E2B surface](/docs/e2b-sdks) included (`e2b_<key>` works as an E2B API
+key); the one exception is console account setup/reset, which accepts
+only the env token — a leaked machine credential must not be able to
+take over the human account. Each key row carries `lastUsedAt` (written
+with 60-second granularity), and revoked rows stay in `listApiKeys` as
+your rotation history.
+
 ## Commands and files on the wire
 
 `execCommand` takes `{ externalId, command, timeoutSeconds?, cwd?, env? }`

From 9b8f1c06774d4a22d077482c0a1a1fbf88f63d74 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 04:49:25 +0800
Subject: [PATCH 091/133] =?UTF-8?q?Templates=20learn=20when=20they=20were?=
 =?UTF-8?q?=20last=20upgraded:=20updatedAt=20stamps=20only=20a=20real=20im?=
 =?UTF-8?q?age=20change=20=E2=80=94=20an=20idempotent=20re-register=20writ?=
 =?UTF-8?q?es=20nothing,=20so=20the=20timestamp=20can=20never=20claim=20an?=
 =?UTF-8?q?=20upgrade=20that=20didn't=20happen=20=E2=80=94=20the=20migrati?=
 =?UTF-8?q?on=20backfills=20stock=20rows=20to=20their=20birth=20date,=20th?=
 =?UTF-8?q?e=20console=20says=20=E8=BF=98=E6=B2=A1=E5=8D=87=E7=BA=A7=20out?=
 =?UTF-8?q?=20loud=20instead=20of=20echoing=20the=20registration=20time,?=
 =?UTF-8?q?=20and=20dor=20template=20ls=20grows=20an=20UPDATED=20column?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../templates/pages/TemplatesPage.tsx         |  13 +-
 .../drizzle/0010_template-updated-at.sql      |   2 +
 .../server/drizzle/meta/0010_snapshot.json    | 538 ++++++++++++++++++
 packages/server/src/db/templates.ts           |  42 +-
 packages/shared/src/templates.ts              |   8 +
 5 files changed, 584 insertions(+), 19 deletions(-)
 create mode 100644 packages/server/drizzle/0010_template-updated-at.sql
 create mode 100644 packages/server/drizzle/meta/0010_snapshot.json

diff --git a/packages/console/src/features/templates/pages/TemplatesPage.tsx b/packages/console/src/features/templates/pages/TemplatesPage.tsx
index aa9750f..9d6c7ca 100644
--- a/packages/console/src/features/templates/pages/TemplatesPage.tsx
+++ b/packages/console/src/features/templates/pages/TemplatesPage.tsx
@@ -286,7 +286,7 @@ export function TemplatesPage() {
     sandboxes.filter((sandbox) => sandbox.template === name).length;
 
   return (
-    // 五列窄表,同设置页限宽居中 — 宽屏上不摊大饼。
+    // 六列窄表,同设置页限宽居中 — 宽屏上不摊大饼。
     <div className="mx-auto flex w-full max-w-4xl flex-col gap-4">
       <div className="flex flex-wrap items-center justify-between gap-3">
         <div>
@@ -335,6 +335,7 @@ export function TemplatesPage() {
               <TableHead>镜像</TableHead>
               <TableHead className="text-right">引用沙箱</TableHead>
               <TableHead>注册于</TableHead>
+              <TableHead>更新于</TableHead>
               <TableHead className="text-right">操作</TableHead>
             </TableRow>
           </TableHeader>
@@ -364,6 +365,16 @@ export function TemplatesPage() {
                   <TableCell className="tabular-nums text-muted-foreground">
                     {since(template.createdAt)}前
                   </TableCell>
+                  {/* updatedAt 只在镜像真的换过时才走动;等于 createdAt
+                      = 从没升级过,直说比重复注册时间更诚实。 */}
+                  <TableCell
+                    className="tabular-nums text-muted-foreground"
+                    title={new Date(template.updatedAt).toLocaleString()}
+                  >
+                    {template.updatedAt === template.createdAt
+                      ? '还没升级'
+                      : `${since(template.updatedAt)}前`}
+                  </TableCell>
                   <TableCell className="text-right">
                     <TemplateRowMenu template={template} />
                   </TableCell>
diff --git a/packages/server/drizzle/0010_template-updated-at.sql b/packages/server/drizzle/0010_template-updated-at.sql
new file mode 100644
index 0000000..4086683
--- /dev/null
+++ b/packages/server/drizzle/0010_template-updated-at.sql
@@ -0,0 +1,2 @@
+ALTER TABLE `templates` ADD `updated_at` text NOT NULL DEFAULT '';--> statement-breakpoint
+UPDATE `templates` SET `updated_at` = `created_at`;
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/0010_snapshot.json b/packages/server/drizzle/meta/0010_snapshot.json
new file mode 100644
index 0000000..08c7fb3
--- /dev/null
+++ b/packages/server/drizzle/meta/0010_snapshot.json
@@ -0,0 +1,538 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "e5b578b5-b58c-4285-b78a-6fd10040e2e7",
+  "prevId": "1d311aa2-3a7c-48e6-babd-226c86ce4e8c",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_id": {
+          "name": "external_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "api_keys": {
+      "name": "api_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "prefix": {
+          "name": "prefix",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "api_keys_key_hash_unique": {
+          "name": "api_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        },
+        "api_keys_active_name_idx": {
+          "name": "api_keys_active_name_idx",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true,
+          "where": "\"api_keys\".\"revoked_at\" IS NULL"
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "daemon_secrets": {
+      "name": "daemon_secrets",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "envd_signing_secret": {
+          "name": "envd_signing_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "fleet_snapshots": {
+      "name": "fleet_snapshots",
+      "columns": {
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active": {
+          "name": "active",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "frozen": {
+          "name": "frozen",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stopped": {
+          "name": "stopped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archived": {
+          "name": "archived",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "restoring": {
+          "name": "restoring",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "total": {
+          "name": "total",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandbox_metrics_samples": {
+      "name": "sandbox_metrics_samples",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_count": {
+          "name": "cpu_count",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_used_pct": {
+          "name": "cpu_used_pct",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_used_bytes": {
+          "name": "mem_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_total_bytes": {
+          "name": "mem_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_cache_bytes": {
+          "name": "mem_cache_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_used_bytes": {
+          "name": "disk_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_total_bytes": {
+          "name": "disk_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "sandbox_metrics_samples_sandbox_at_idx": {
+          "name": "sandbox_metrics_samples_sandbox_at_idx",
+          "columns": [
+            "sandbox_id",
+            "at"
+          ],
+          "isUnique": false
+        },
+        "sandbox_metrics_samples_at_idx": {
+          "name": "sandbox_metrics_samples_at_idx",
+          "columns": [
+            "at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_id": {
+          "name": "external_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_external_id_unique": {
+          "name": "sandboxes_external_id_unique",
+          "columns": [
+            "external_id"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/src/db/templates.ts b/packages/server/src/db/templates.ts
index 6d9d658..0b34f83 100644
--- a/packages/server/src/db/templates.ts
+++ b/packages/server/src/db/templates.ts
@@ -6,30 +6,36 @@ import { sandboxes, type TemplateRow, templates } from './schema';
  * Upsert: registering an existing name re-points it at the new image. That
  * is the template upgrade front door — build a new image, re-register the
  * name, then rebuildSandbox the stock that should move onto it.
+ *
+ * updatedAt is the upgrade timestamp: stamped only when the image actually
+ * changes. A re-register of the same image writes nothing at all — the
+ * timestamp must not claim an upgrade that didn't happen. Read-then-write
+ * needs no lock: better-sqlite3 is synchronous, there is no await between.
  */
 export function registerTemplate(
   db: Db,
   input: { name: string; image: string },
 ): TemplateRow {
-  const row: TemplateRow = {
-    name: input.name,
-    image: input.image,
-    createdAt: new Date().toISOString(),
-  };
-  db.insert(templates)
-    .values(row)
-    .onConflictDoUpdate({
-      target: templates.name,
-      set: { image: input.image },
-    })
-    .run();
-  // Re-read instead of returning the literal: an upsert on an existing name
-  // keeps its original createdAt.
-  const stored = findTemplate(db, input.name);
-  if (!stored) {
-    throw new Error(`template ${input.name} vanished mid-register`);
+  const now = new Date().toISOString();
+  const existing = findTemplate(db, input.name);
+  if (!existing) {
+    const row: TemplateRow = {
+      name: input.name,
+      image: input.image,
+      createdAt: now,
+      updatedAt: now,
+    };
+    db.insert(templates).values(row).run();
+    return row;
+  }
+  if (existing.image === input.image) {
+    return existing;
   }
-  return stored;
+  db.update(templates)
+    .set({ image: input.image, updatedAt: now })
+    .where(eq(templates.name, input.name))
+    .run();
+  return { ...existing, image: input.image, updatedAt: now };
 }
 
 export function listTemplates(db: Db): TemplateRow[] {
diff --git a/packages/shared/src/templates.ts b/packages/shared/src/templates.ts
index 0dbc3c5..bafc0d1 100644
--- a/packages/shared/src/templates.ts
+++ b/packages/shared/src/templates.ts
@@ -25,6 +25,14 @@ export const templateSchema = z.object({
   /** Docker image reference on the daemon's host, e.g. my-python:3.11. */
   image: z.string().min(1),
   createdAt: z.iso.datetime(),
+  /**
+   * When the name was last re-pointed at a *different* image — the upgrade
+   * timestamp, the ledger half of the "upgradable" verdict on sandboxes.
+   * Equals createdAt until the first upgrade; an idempotent re-register of
+   * the same image deliberately does not bump it (nothing changed, so the
+   * timestamp must not claim otherwise).
+   */
+  updatedAt: z.iso.datetime(),
 });
 
 export type Template = z.infer<typeof templateSchema>;

From 15c630137eae0846b4695556813e9853ab255c79 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 14:07:32 +0800
Subject: [PATCH 092/133] =?UTF-8?q?A=20sandbox=20learns=20its=20two=20name?=
 =?UTF-8?q?s:=20the=20caller-chosen=20address=20is=20now=20simply=20`name`?=
 =?UTF-8?q?=20(was=20externalId=20=E2=80=94=20a=20daemon's-eye=20word=20fo?=
 =?UTF-8?q?r=20what=20the=20user=20rightly=20reads=20as=20"the=20name=20I?=
 =?UTF-8?q?=20gave=20it";=20the=20column's=20third=20christening=20after?=
 =?UTF-8?q?=20user=5Fkey=20and=20external=5Fid),=20and=20the=20platform's?=
 =?UTF-8?q?=20per-incarnation=20UUID=20is=20`id`=20(was=20sandboxId=20?=
 =?UTF-8?q?=E2=80=94=20a=20resource's=20own=20id=20needs=20no=20prefix).?=
 =?UTF-8?q?=20References=20that=20leave=20the=20sandbox=20object=20keep=20?=
 =?UTF-8?q?the=20prefix=20=E2=80=94=20activity,=20image-lineage=20and=20fl?=
 =?UTF-8?q?eet-metric=20rows=20now=20carry=20sandboxName/sandboxId,=20beca?=
 =?UTF-8?q?use=20a=20bare=20name=20on=20an=20image=20row=20reads=20as=20an?=
 =?UTF-8?q?=20image=20name.=20The=20uniqueness=20that=20never=20errors=20b?=
 =?UTF-8?q?ecomes=20observable:=20acquire=20answers=20`created`=20so=20a?=
 =?UTF-8?q?=20caller=20finally=20sees=20whether=20the=20name=20minted=20a?=
 =?UTF-8?q?=20sandbox=20or=20converged=20on=20one=20(and=20that=20its=20po?=
 =?UTF-8?q?licy/template/metadata=20were=20therefore=20ignored),=20the=20c?=
 =?UTF-8?q?onsole's=20create=20dialog=20probes=20the=20fleet=20as=20you=20?=
 =?UTF-8?q?type=20and=20says=20"this=20name=20already=20has=20a=20sandbox?=
 =?UTF-8?q?=20=E2=80=94=20submitting=20takes=20it=20back"=20before=20the?=
 =?UTF-8?q?=20trigger=20is=20pulled,=20and=20the=20E2B=20extension=20key?=
 =?UTF-8?q?=20follows=20suit=20(metadata.name).=20Migration=200011=20renam?=
 =?UTF-8?q?es=20the=20columns=20in=20place=20=E2=80=94=20verified=20agains?=
 =?UTF-8?q?t=20a=20populated=20pre-rename=20ledger,=20unique=20index=20reb?=
 =?UTF-8?q?uilt,=20duplicates=20still=20refused;=20SDK/CLI/console/docs/sk?=
 =?UTF-8?q?ill/examples=20all=20speak=20the=20new=20tongue,=20and=20core-c?=
 =?UTF-8?q?oncepts=20gains=20the=20two-identities=20paragraph=20(name=20is?=
 =?UTF-8?q?=20the=20address=20across=20lifetimes,=20id=20is=20this=20incar?=
 =?UTF-8?q?nation=20=E2=80=94=20rebuild=20keeps=20it,=20destroy-and-reacqu?=
 =?UTF-8?q?ire=20mints=20anew).?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/python/test_e2b_sync.py                   |   4 +-
 e2e/src/archive.test.ts                       |  10 +-
 e2e/src/cli.test.ts                           |   4 +-
 e2e/src/e2b.test.ts                           |  18 +-
 e2e/src/native.test.ts                        |  46 +-
 examples/e2b-compat.mjs                       |   2 +-
 examples/native-lifecycle.mjs                 |   6 +-
 examples/resident-agent.mjs                   |   4 +-
 packages/cli/src/commands.test.ts             |  18 +-
 packages/cli/src/commands.ts                  |  58 +-
 packages/cli/src/main.ts                      | 126 ++--
 packages/console/src/components/AppShell.tsx  |   2 +-
 .../console/src/components/CommandMenu.tsx    |  18 +-
 .../features/activity/hooks/useActivity.ts    |   2 +-
 .../features/activity/pages/ActivityPage.tsx  |  14 +-
 .../console/src/features/connect/snippets.ts  |   4 +-
 .../components/CreateSandboxDialog.tsx        |  43 +-
 .../components/DestroySandboxButton.tsx       |  20 +-
 .../sandboxes/components/EditPolicyDialog.tsx |   6 +-
 .../sandboxes/components/FilesPanel.tsx       |   2 +-
 .../sandboxes/components/HistoryPanel.tsx     |   6 +-
 .../sandboxes/components/MetricsPanel.tsx     |   4 +-
 .../sandboxes/components/ProcessesPanel.tsx   |   2 +-
 .../components/RebuildSandboxButton.tsx       |   8 +-
 .../sandboxes/components/RestoreCard.tsx      |   6 +-
 .../features/sandboxes/hooks/useSandboxes.ts  |  26 +-
 .../sandboxes/pages/SandboxDetailPage.tsx     |  28 +-
 .../sandboxes/pages/SandboxesPage.tsx         |  88 ++-
 .../templates/pages/TemplatesPage.tsx         |   2 +-
 packages/console/src/lib/api.ts               |  22 +-
 packages/console/src/routeTree.gen.ts         |  34 +-
 .../sandboxes/{$externalId.tsx => $name.tsx}  |   2 +-
 packages/sdk/src/client.test.ts               |  36 +-
 packages/sdk/src/client.ts                    |  67 ++-
 .../server/drizzle/0011_sandbox-name-id.sql   |   5 +
 .../server/drizzle/meta/0011_snapshot.json    | 538 ++++++++++++++++++
 packages/server/drizzle/meta/_journal.json    |   7 +
 packages/server/src/app.test.ts               | 404 +++++++------
 packages/server/src/archive/archiver.test.ts  | 114 ++--
 packages/server/src/archive/archiver.ts       |  65 +--
 packages/server/src/db/activity.ts            |   5 +-
 packages/server/src/db/ledger.test.ts         |  24 +-
 packages/server/src/db/ledger.ts              | 117 ++--
 packages/server/src/db/metrics.ts             |   4 +-
 packages/server/src/db/schema.ts              |  17 +-
 packages/server/src/db/templates.ts           |   8 +-
 packages/server/src/e2b/compat.test.ts        |  74 +--
 packages/server/src/e2b/control.ts            |  93 ++-
 packages/server/src/e2b/envd/files.ts         |  22 +-
 packages/server/src/e2b/envd/filesystem.ts    |  16 +-
 packages/server/src/e2b/envd/index.ts         |   4 +-
 packages/server/src/e2b/envd/process.ts       |  18 +-
 packages/server/src/e2b/envd/shared.ts        |  14 +-
 packages/server/src/e2b/envd/watch.ts         |   8 +-
 packages/server/src/e2b/signed-files.ts       |   4 +-
 packages/server/src/e2b/signing.ts            |   2 +-
 packages/server/src/e2b/view.test.ts          |   4 +-
 packages/server/src/lifecycle.ts              |  34 +-
 packages/server/src/metrics-sampler.test.ts   |  24 +-
 packages/server/src/metrics-sampler.ts        |   4 +-
 packages/server/src/reconciler.test.ts        | 180 +++---
 packages/server/src/reconciler.ts             |  44 +-
 .../server/src/routes/observability.test.ts   |  93 ++-
 packages/server/src/routes/sandboxes.ts       | 195 +++----
 packages/server/src/routes/templates.ts       |   4 +-
 packages/server/src/sandbox-proxy.test.ts     |   4 +-
 packages/server/src/sandbox-proxy.ts          |  23 +-
 packages/server/src/scanner.test.ts           | 129 ++---
 packages/server/src/scanner.ts                |  22 +-
 packages/shared/src/acquire.ts                |  17 +-
 packages/shared/src/activity.ts               |   8 +-
 packages/shared/src/destroy.ts                |  14 +-
 packages/shared/src/exec.ts                   |   8 +-
 packages/shared/src/files.ts                  |  20 +-
 packages/shared/src/images.ts                 |   4 +-
 packages/shared/src/metrics.ts                |  14 +-
 packages/shared/src/rebuild.ts                |   8 +-
 packages/shared/src/sandbox.ts                |  28 +-
 packages/shared/src/update-metadata.ts        |   6 +-
 packages/shared/src/update-policy.ts          |   6 +-
 skills/dormice/SKILL.md                       |  12 +-
 website/content/docs/cli.mdx                  |  16 +-
 website/content/docs/commands.mdx             |   2 +-
 website/content/docs/console.mdx              |   2 +-
 website/content/docs/core-concepts.mdx        |  13 +
 website/content/docs/e2b-differences.mdx      |   2 +-
 website/content/docs/e2b-sdks.mdx             |   6 +-
 website/content/docs/http-api.mdx             |  43 +-
 website/content/docs/index.mdx                |   2 +-
 website/content/docs/metrics.mdx              |   2 +-
 website/content/docs/persistence.mdx          |   2 +-
 website/content/docs/quickstart.mdx           |   2 +-
 website/content/docs/resident-agents.mdx      |   2 +-
 website/content/docs/templates.mdx            |   2 +-
 website/content/docs/upgrading.mdx            |   2 +-
 website/src/components/sections/Features.tsx  |   6 +-
 96 files changed, 1891 insertions(+), 1419 deletions(-)
 rename packages/console/src/routes/_app/sandboxes/{$externalId.tsx => $name.tsx} (87%)
 create mode 100644 packages/server/drizzle/0011_sandbox-name-id.sql
 create mode 100644 packages/server/drizzle/meta/0011_snapshot.json

diff --git a/e2e/python/test_e2b_sync.py b/e2e/python/test_e2b_sync.py
index db83aa2..3d45ec3 100644
--- a/e2e/python/test_e2b_sync.py
+++ b/e2e/python/test_e2b_sync.py
@@ -99,8 +99,8 @@ def test_list_filters(conn, make_sandbox):
 
 
 def test_userkey_extension_is_idempotent(conn, make_sandbox):
-    first = make_sandbox(metadata={"externalId": "py-idem"})
-    second = Sandbox.create(metadata={"externalId": "py-idem"}, **conn)
+    first = make_sandbox(metadata={"name": "py-idem"})
+    second = Sandbox.create(metadata={"name": "py-idem"}, **conn)
     # Same key, same sandbox — the Dormice extension speaks Python too.
     assert second.sandbox_id == first.sandbox_id
 
diff --git a/e2e/src/archive.test.ts b/e2e/src/archive.test.ts
index cc989b9..3feb9c3 100644
--- a/e2e/src/archive.test.ts
+++ b/e2e/src/archive.test.ts
@@ -28,7 +28,7 @@ describe('the archive lifecycle over a real daemon', () => {
         archiveAfterSeconds: 3,
       },
     });
-    const id = first.sandbox.sandboxId;
+    const id = first.sandbox.id;
     await dormice.writeFiles('archive-key', [
       { path: 'kept.txt', content: 'survived the bucket' },
     ]);
@@ -38,7 +38,7 @@ describe('the archive lifecycle over a real daemon', () => {
     const deadline = Date.now() + 15_000;
     for (;;) {
       const sandboxes = await dormice.listSandboxes();
-      const mine = sandboxes.find((s) => s.externalId === 'archive-key');
+      const mine = sandboxes.find((s) => s.name === 'archive-key');
       if (mine?.state === 'archived') break;
       if (Date.now() > deadline) {
         throw new Error(`never archived; last observed: ${mine?.state}`);
@@ -63,7 +63,7 @@ describe('the archive lifecycle over a real daemon', () => {
       outcome = await dormice.acquireSandbox('archive-key');
     }
 
-    expect(outcome.sandbox.sandboxId).toBe(id);
+    expect(outcome.sandbox.id).toBe(id);
     expect(outcome.sandbox.state).toBe('active');
     const read = await dormice.readFile('archive-key', 'kept.txt');
     expect(Buffer.from(read.content).toString()).toBe('survived the bucket');
@@ -83,9 +83,7 @@ describe('the archive lifecycle over a real daemon', () => {
     const deadline = Date.now() + 15_000;
     for (;;) {
       const sandboxes = await dormice.listSandboxes();
-      const mine = sandboxes.find(
-        (s) => s.externalId === 'archive-destroy-key',
-      );
+      const mine = sandboxes.find((s) => s.name === 'archive-destroy-key');
       if (mine?.state === 'archived') break;
       if (Date.now() > deadline) {
         throw new Error(`never archived; last observed: ${mine?.state}`);
diff --git a/e2e/src/cli.test.ts b/e2e/src/cli.test.ts
index 8ffb835..8f5db5c 100644
--- a/e2e/src/cli.test.ts
+++ b/e2e/src/cli.test.ts
@@ -39,9 +39,9 @@ describe('dor CLI against a real daemon', () => {
     const created = await sdk.acquireSandbox('cli-ls-key');
 
     const { stdout } = await cli('sandbox', 'ls');
-    expect(stdout).toMatch(/USER KEY\s{2,}STATE\s{2,}SANDBOX ID/);
+    expect(stdout).toMatch(/NAME\s{2,}STATE\s{2,}ID/);
     expect(stdout).toMatch(/cli-ls-key\s{2,}active/);
-    expect(stdout).toContain(created.sandbox.sandboxId);
+    expect(stdout).toContain(created.sandbox.id);
   });
 
   it('sandbox meta shows, replaces and clears labels through the real binary', async () => {
diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 3495bf4..6c3d0b4 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -561,15 +561,15 @@ describe('official e2b SDK against the daemon', () => {
       endpoint: inject('dormiceEndpoint'),
       token: inject('dormiceToken'),
     });
-    const externalId = `watch-freeze-${Date.now()}`;
+    const name = `watch-freeze-${Date.now()}`;
     // Native acquire sets the second-scale policy; the e2b face then joins
-    // the same sandbox through the externalId extension.
-    await dormice.acquireSandbox(externalId, {
+    // the same sandbox through the metadata.name extension.
+    await dormice.acquireSandbox(name, {
       policy: { freezeAfterSeconds: 1, stopAfterSeconds: null },
     });
     const sbx = await Sandbox.create({
       ...connection(),
-      metadata: { externalId },
+      metadata: { name },
     });
     try {
       const events: Array<{ name: string; type: string }> = [];
@@ -583,7 +583,7 @@ describe('official e2b SDK against the daemon', () => {
       // The real wall-clock scanner freezes the sandbox under the open watch.
       const frozen = async () => {
         const sandboxes = await dormice.listSandboxes();
-        return sandboxes.find((s) => s.externalId === externalId)?.state;
+        return sandboxes.find((s) => s.name === name)?.state;
       };
       const deadline = Date.now() + 15_000;
       while ((await frozen()) !== 'frozen') {
@@ -599,7 +599,7 @@ describe('official e2b SDK against the daemon', () => {
       );
       await handle.stop();
     } finally {
-      await dormice.destroySandbox(externalId);
+      await dormice.destroySandbox(name);
     }
   });
 
@@ -673,16 +673,16 @@ describe('official e2b SDK against the daemon', () => {
     }
   });
 
-  it('the Dormice extension: metadata.externalId makes create idempotent, data persists', async () => {
+  it('the Dormice extension: metadata.name makes create idempotent, data persists', async () => {
     const first = await Sandbox.create({
       ...connection(),
-      metadata: { externalId: 'e2e-agent-key' },
+      metadata: { name: 'e2e-agent-key' },
     });
     try {
       await first.files.write('persistent.txt', 'same sandbox every time');
       const second = await Sandbox.create({
         ...connection(),
-        metadata: { externalId: 'e2e-agent-key' },
+        metadata: { name: 'e2e-agent-key' },
       });
       expect(second.sandboxId).toBe(first.sandboxId);
       expect(await second.files.read('persistent.txt')).toBe(
diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index 495cd72..ce614cc 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -30,7 +30,7 @@ describe('native API over a real daemon', () => {
     const res = await client().acquireSandbox('fresh-key');
     expect(res.status).toBe('ready');
     expect(res.sandbox.state).toBe('active');
-    expect(res.sandbox.externalId).toBe('fresh-key');
+    expect(res.sandbox.name).toBe('fresh-key');
     // The exam daemon runs with S3 configured (see setup/daemon.ts), so the
     // archive default is live: a week from stopped to archived.
     expect(res.sandbox.policy).toEqual({
@@ -43,7 +43,7 @@ describe('native API over a real daemon', () => {
   it('is idempotent: the same key always returns the same sandbox', async () => {
     const first = await client().acquireSandbox('idem-key');
     const second = await client().acquireSandbox('idem-key');
-    expect(second.sandbox.sandboxId).toBe(first.sandbox.sandboxId);
+    expect(second.sandbox.id).toBe(first.sandbox.id);
   });
 
   it('stores a policy override, including null for never-archive', async () => {
@@ -76,7 +76,7 @@ describe('native API over a real daemon', () => {
     expect(updated.sandbox.metadata).toEqual({ app: 'assistant' });
 
     const listed = await client().listSandboxes();
-    expect(listed.find((s) => s.externalId === 'meta-key')?.metadata).toEqual({
+    expect(listed.find((s) => s.name === 'meta-key')?.metadata).toEqual({
       app: 'assistant',
     });
 
@@ -118,16 +118,14 @@ describe('native API over a real daemon', () => {
       destroyed: true,
     });
     const listed = await client().listSandboxes();
-    expect(listed.some((s) => s.sandboxId === created.sandbox.sandboxId)).toBe(
-      false,
-    );
+    expect(listed.some((s) => s.id === created.sandbox.id)).toBe(false);
     expect(await client().destroySandbox('destroy-key')).toEqual({
       destroyed: false,
     });
 
     // The key is free again: the next acquire builds a brand-new sandbox.
     const again = await client().acquireSandbox('destroy-key');
-    expect(again.sandbox.sandboxId).not.toBe(created.sandbox.sandboxId);
+    expect(again.sandbox.id).not.toBe(created.sandbox.id);
   });
 
   it('rebuilds a sandbox: shell swapped, /home/user kept, same key wakes it', async () => {
@@ -137,13 +135,13 @@ describe('native API over a real daemon', () => {
     ]);
 
     const { sandbox } = await client().rebuildSandbox('rebuild-key');
-    expect(sandbox.sandboxId).toBe(created.sandbox.sandboxId);
+    expect(sandbox.id).toBe(created.sandbox.id);
     expect(sandbox.state).toBe('stopped');
 
     // The wake after a rebuild is a cold start into a fresh container; the
     // disk — and with it the file — must have survived the swap.
     const again = await client().acquireSandbox('rebuild-key');
-    expect(again.sandbox.sandboxId).toBe(created.sandbox.sandboxId);
+    expect(again.sandbox.id).toBe(created.sandbox.id);
     const read = await client().readFile('rebuild-key', 'keep.txt');
     expect(new TextDecoder().decode(read.content)).toBe('still here');
 
@@ -163,7 +161,7 @@ describe('native API over a real daemon', () => {
       stopAfterSeconds: null,
       archiveAfterSeconds: null,
     });
-    expect(sandbox.sandboxId).toBe(created.sandbox.sandboxId);
+    expect(sandbox.id).toBe(created.sandbox.id);
     expect(sandbox.policy.stopAfterSeconds).toBeNull();
     expect(sandbox.policy.archiveAfterSeconds).toBeNull();
     // Ledger-only: the sandbox itself was not woken or touched.
@@ -226,7 +224,7 @@ describe('native API over a real daemon', () => {
     ).rejects.toMatchObject({
       name: 'DormiceApiError',
       status: 404,
-      message: expect.stringMatching(/no sandbox for key/),
+      message: expect.stringMatching(/no sandbox named/),
     });
   });
 
@@ -245,7 +243,7 @@ describe('native API over a real daemon', () => {
     const result = await client().execCommand('exec-busy-key', 'sleep 3');
     expect(result.exitCode).toBe(0);
     const observed = (await client().listSandboxes()).find(
-      (s) => s.externalId === 'exec-busy-key',
+      (s) => s.name === 'exec-busy-key',
     );
     expect(observed?.state).toBe('active');
   });
@@ -262,7 +260,7 @@ describe('native API over a real daemon', () => {
     const deadline = Date.now() + 15_000;
     for (;;) {
       const cold = (await client().listSandboxes()).find(
-        (s) => s.externalId === 'exec-wake-key',
+        (s) => s.name === 'exec-wake-key',
       );
       if (cold?.state === 'frozen') break;
       if (Date.now() > deadline) {
@@ -279,7 +277,7 @@ describe('native API over a real daemon', () => {
     expect(result.exitCode).toBe(0);
     expect(result.stdout).toBe('woke\n');
     const observed = (await client().listSandboxes()).find(
-      (s) => s.externalId === 'exec-wake-key',
+      (s) => s.name === 'exec-wake-key',
     );
     expect(observed?.state).toBe('active');
   });
@@ -303,7 +301,7 @@ describe('native API over a real daemon', () => {
     const deadline = Date.now() + 15_000;
     for (;;) {
       const asleep = (await client().listSandboxes()).find(
-        (s) => s.externalId === 'sleeper-key',
+        (s) => s.name === 'sleeper-key',
       );
       if (asleep?.state === 'stopped') break;
       if (Date.now() > deadline) {
@@ -316,7 +314,7 @@ describe('native API over a real daemon', () => {
 
     const woken = await client().acquireSandbox('sleeper-key');
     expect(woken.status).toBe('ready');
-    expect(woken.sandbox.sandboxId).toBe(created.sandbox.sandboxId);
+    expect(woken.sandbox.id).toBe(created.sandbox.id);
     expect(woken.sandbox.state).toBe('active');
   });
 
@@ -404,7 +402,7 @@ describe('native API over a real daemon', () => {
     });
     expect(created.sandbox.template).toBe('native-tpl');
     const listed = (await client().listSandboxes()).find(
-      (s) => s.externalId === 'tpl-key',
+      (s) => s.name === 'tpl-key',
     );
     expect(listed?.template).toBe('native-tpl');
 
@@ -428,7 +426,7 @@ describe('native API over a real daemon', () => {
     // new credential is live before the old one dies.
     const keyed = client(token);
     const created = await keyed.acquireSandbox('rotation-key');
-    expect(created.sandbox.externalId).toBe('rotation-key');
+    expect(created.sandbox.name).toBe('rotation-key');
     await keyed.destroySandbox('rotation-key');
 
     const listed = await client().listApiKeys();
@@ -459,13 +457,13 @@ describe('native API over a real daemon', () => {
     });
     const mine = async () =>
       (await client().listSandboxImages()).find(
-        (e) => e.externalId === 'lineage-key',
+        (e) => e.sandboxName === 'lineage-key',
       );
 
     // Fresh: born from the template's current image, nothing to upgrade.
     expect(await mine()).toEqual({
-      externalId: 'lineage-key',
-      sandboxId: created.sandbox.sandboxId,
+      sandboxName: 'lineage-key',
+      sandboxId: created.sandbox.id,
       image,
       nextImage: image,
       upgradable: false,
@@ -541,7 +539,7 @@ describe('native API over a real daemon', () => {
     const deadline = Date.now() + 15_000;
     for (;;) {
       const cold = (await client().listSandboxes()).find(
-        (s) => s.externalId === 'files-wake-key',
+        (s) => s.name === 'files-wake-key',
       );
       if (cold?.state === 'frozen') break;
       if (Date.now() > deadline) {
@@ -555,7 +553,7 @@ describe('native API over a real daemon', () => {
     const read = await client().readFile('files-wake-key', 'keep.txt');
     expect(new TextDecoder().decode(read.content)).toBe('still here');
     const observed = (await client().listSandboxes()).find(
-      (s) => s.externalId === 'files-wake-key',
+      (s) => s.name === 'files-wake-key',
     );
     expect(observed?.state).toBe('active');
   });
@@ -612,7 +610,7 @@ describe('the observability verbs over a real daemon', () => {
     await client().acquireSandbox('obs-story-key');
     await client().destroySandbox('obs-story-key');
     const events = await client().listActivity({ limit: 500 });
-    const mine = events.filter((e) => e.externalId === 'obs-story-key');
+    const mine = events.filter((e) => e.sandboxName === 'obs-story-key');
     expect(mine.map((e) => e.kind)).toEqual(['destroyed', 'created']);
     expect(mine[1]?.detail).toContain('acquireSandbox');
   });
diff --git a/examples/e2b-compat.mjs b/examples/e2b-compat.mjs
index c1cf1c6..a567ec4 100644
--- a/examples/e2b-compat.mjs
+++ b/examples/e2b-compat.mjs
@@ -41,7 +41,7 @@ try {
   console.log('killed');
 }
 
-// Dormice extension worth knowing: Sandbox.create({ metadata: { externalId } })
+// Dormice extension worth knowing: Sandbox.create({ metadata: { name } })
 // makes create idempotent — the same key returns the same sandbox instead of
 // a new one, which is how an E2B application picks up permanent sandboxes
 // without leaving the e2b package.
diff --git a/examples/native-lifecycle.mjs b/examples/native-lifecycle.mjs
index 4f495d1..25a5f6c 100644
--- a/examples/native-lifecycle.mjs
+++ b/examples/native-lifecycle.mjs
@@ -20,7 +20,7 @@ const key = 'example-lifecycle';
 // acquire() is the single entry point, idempotent on a key you choose:
 // no sandbox → create, frozen → wake, stopped → restart, archived → restore.
 const { sandbox } = await client.acquireSandbox(key);
-console.log(`acquired ${sandbox.sandboxId} (${sandbox.state})`);
+console.log(`acquired ${sandbox.id} (${sandbox.state})`);
 
 // Real code execution. `uname -r` names gVisor's userspace kernel — proof
 // the command did not run on your host.
@@ -43,9 +43,7 @@ console.log(`read back: ${new TextDecoder().decode(file.content).trimEnd()}`);
 
 // The same key always answers with the same sandbox.
 const again = await client.acquireSandbox(key);
-console.log(
-  `same sandbox on re-acquire: ${again.sandbox.sandboxId === sandbox.sandboxId}`,
-);
+console.log(`same sandbox on re-acquire: ${again.sandbox.id === sandbox.id}`);
 
 // release() destroys container and disk — the only verb that loses data.
 await client.destroySandbox(key);
diff --git a/examples/resident-agent.mjs b/examples/resident-agent.mjs
index 4f6e80e..9a52c2c 100644
--- a/examples/resident-agent.mjs
+++ b/examples/resident-agent.mjs
@@ -26,9 +26,7 @@ const key = 'example-resident-agent';
 const { sandbox } = await client.acquireSandbox(key, {
   policy: { stopAfterSeconds: null },
 });
-console.log(
-  `${sandbox.sandboxId} — ${sandbox.state}, created ${sandbox.createdAt}`,
-);
+console.log(`${sandbox.id} — ${sandbox.state}, created ${sandbox.createdAt}`);
 
 // State lives on the sandbox's disk, not in this script: every visit appends
 // to the same journal.
diff --git a/packages/cli/src/commands.test.ts b/packages/cli/src/commands.test.ts
index b63f3fb..6281b92 100644
--- a/packages/cli/src/commands.test.ts
+++ b/packages/cli/src/commands.test.ts
@@ -109,11 +109,11 @@ describe('sandbox commands over real HTTP', () => {
     const output = await sandboxLs(client);
     const lines = output.split('\n');
     expect(lines[0]).toMatch(
-      /^USER KEY\s{2,}STATE\s{2,}SANDBOX ID\s{2,}LAST ACTIVE\s{2,}METADATA$/,
+      /^NAME\s{2,}STATE\s{2,}ID\s{2,}LAST ACTIVE\s{2,}METADATA$/,
     );
     expect(output).toMatch(/alice\s{2,}active/);
     expect(output).toMatch(/bob\s{2,}active/);
-    expect(output).toContain(alice.sandbox.sandboxId);
+    expect(output).toContain(alice.sandbox.id);
     expect(output).toContain('app=demo');
   });
 
@@ -125,10 +125,10 @@ describe('sandbox commands over real HTTP', () => {
       'app=demo,env=prod',
     );
     expect(await sandboxMeta(client, 'labeled', { app: 'ci' })).toBe(
-      'Metadata for key "labeled" is now app=ci.',
+      'Metadata of "labeled" is now app=ci.',
     );
     expect(await sandboxMeta(client, 'labeled', {})).toBe(
-      'Cleared metadata for key "labeled".',
+      'Cleared metadata of "labeled".',
     );
     expect(await sandboxMeta(client, 'labeled', null)).toBe('No metadata.');
     await expect(sandboxMeta(client, 'nobody', null)).rejects.toThrow(
@@ -137,8 +137,8 @@ describe('sandbox commands over real HTTP', () => {
     await client.destroySandbox('labeled');
   });
 
-  it('neutralizes control characters a hostile external id smuggles in', async () => {
-    // The protocol keeps externalId opaque, so an ESC sequence is a legal key;
+  it('neutralizes control characters a hostile name smuggles in', async () => {
+    // The protocol keeps name opaque, so an ESC sequence is a legal key;
     // printed raw it would rewrite the operator's terminal.
     await client.acquireSandbox('evil\u001b[31mkey');
     const output = await sandboxLs(client);
@@ -189,7 +189,7 @@ describe('sandbox commands over real HTTP', () => {
   it('rebuild reports the swap and surfaces the 404 for an unknown key', async () => {
     await client.acquireSandbox('rebuilder');
     expect(await sandboxRebuild(client, 'rebuilder')).toBe(
-      'Rebuilt the sandbox for key "rebuilder" — /home/user kept, now stopped; ' +
+      'Rebuilt the sandbox "rebuilder" — /home/user kept, now stopped; ' +
         'its next use starts on the current base image.',
     );
     await expect(sandboxRebuild(client, 'nobody')).rejects.toThrow(
@@ -201,10 +201,10 @@ describe('sandbox commands over real HTTP', () => {
   it('destroy reports both outcomes of the idempotent destroy', async () => {
     await client.acquireSandbox('carol');
     expect(await sandboxDestroy(client, 'carol')).toBe(
-      'Destroyed the sandbox for key "carol".',
+      'Destroyed the sandbox "carol".',
     );
     expect(await sandboxDestroy(client, 'carol')).toBe(
-      'No sandbox for key "carol" — nothing to destroy.',
+      'No sandbox named "carol" — nothing to destroy.',
     );
   });
 });
diff --git a/packages/cli/src/commands.ts b/packages/cli/src/commands.ts
index 615acda..c264fdd 100644
--- a/packages/cli/src/commands.ts
+++ b/packages/cli/src/commands.ts
@@ -40,15 +40,15 @@ function formatMetadata(metadata: Record<string, string>): string {
 }
 
 const COLUMNS: { header: string; value: (s: Sandbox) => string }[] = [
-  { header: 'USER KEY', value: (s) => s.externalId },
+  { header: 'NAME', value: (s) => s.name },
   { header: 'STATE', value: (s) => s.state },
-  { header: 'SANDBOX ID', value: (s) => s.sandboxId },
+  { header: 'ID', value: (s) => s.id },
   { header: 'LAST ACTIVE', value: (s) => s.lastActiveAt },
   { header: 'METADATA', value: (s) => formatMetadata(s.metadata) },
 ];
 
 /**
- * The protocol keeps externalId opaque, so a hostile key can carry control
+ * The protocol keeps name opaque, so a hostile key can carry control
  * characters — printed raw, ESC sequences would let one sandbox's name
  * rewrite the operator's terminal. Neutralized here, at the output layer,
  * where the terminal risk lives.
@@ -101,31 +101,29 @@ export function parseLabels(args: string[]): Record<string, string> {
 }
 
 /**
- * `dor sandbox meta <externalId> [key=value ...]`: no labels = show the
+ * `dor sandbox meta <name> [key=value ...]`: no labels = show the
  * current set; labels (or --clear) = full replacement, the verb's wire
  * semantics stated plainly. A pure ledger write — nothing is woken.
  */
 export async function sandboxMeta(
   client: Dormice,
-  externalId: string,
+  name: string,
   labels: Record<string, string> | null,
 ): Promise<string> {
   if (labels === null) {
     // Read path: the native list is the one read the daemon offers.
-    const sandbox = (await client.listSandboxes()).find(
-      (s) => s.externalId === externalId,
-    );
+    const sandbox = (await client.listSandboxes()).find((s) => s.name === name);
     if (!sandbox) {
-      throw new Error(`no sandbox for key "${externalId}" — acquire it first`);
+      throw new Error(`no sandbox named "${name}" — acquire it first`);
     }
     const line = formatMetadata(sandbox.metadata);
     return line ? printable(line) : 'No metadata.';
   }
-  const { sandbox } = await client.updateMetadata(externalId, labels);
+  const { sandbox } = await client.updateMetadata(name, labels);
   const line = formatMetadata(sandbox.metadata);
   return line
-    ? `Metadata for key "${printable(externalId)}" is now ${printable(line)}.`
-    : `Cleared metadata for key "${printable(externalId)}".`;
+    ? `Metadata of "${printable(name)}" is now ${printable(line)}.`
+    : `Cleared metadata of "${printable(name)}".`;
 }
 
 export interface ExecOutput {
@@ -135,7 +133,7 @@ export interface ExecOutput {
 }
 
 /**
- * `dor sandbox exec <externalId> <command>`: run a shell command in the
+ * `dor sandbox exec <name> <command>`: run a shell command in the
  * sandbox, buffered. Three channels instead of one string: the command's
  * stdout and stderr must reach the operator's matching streams untouched
  * (this is their own command's output, like ssh — unlike the ls table,
@@ -144,11 +142,11 @@ export interface ExecOutput {
  */
 export async function sandboxExec(
   client: Dormice,
-  externalId: string,
+  name: string,
   command: string,
   timeoutSeconds?: number,
 ): Promise<ExecOutput> {
-  const result = await client.execCommand(externalId, command, {
+  const result = await client.execCommand(name, command, {
     timeoutSeconds,
   });
   let stderr = result.stderr;
@@ -158,17 +156,17 @@ export async function sandboxExec(
 }
 
 /**
- * `dor sandbox push <externalId> <localPath> [remotePath]`: one local file into
+ * `dor sandbox push <name> <localPath> [remotePath]`: one local file into
  * the sandbox. The bytes arrive here already read — main.ts owns the
  * filesystem, this function owns the API call and the message.
  */
 export async function sandboxPush(
   client: Dormice,
-  externalId: string,
+  name: string,
   content: Uint8Array,
   remotePath: string,
 ): Promise<string> {
-  const { files } = await client.writeFiles(externalId, [
+  const { files } = await client.writeFiles(name, [
     { path: remotePath, content },
   ]);
   const written = files[0]?.path ?? remotePath;
@@ -176,17 +174,17 @@ export async function sandboxPush(
 }
 
 /**
- * `dor sandbox pull <externalId> <remotePath> [localPath]`: one file out of the
+ * `dor sandbox pull <name> <remotePath> [localPath]`: one file out of the
  * sandbox. Returns the exact bytes; main.ts decides between a local file and
  * raw stdout — raw on purpose, the same rule as exec output: these are the
  * operator's own bytes, not a place to strip control characters.
  */
 export async function sandboxPull(
   client: Dormice,
-  externalId: string,
+  name: string,
   remotePath: string,
 ): Promise<ReadFileResult> {
-  return client.readFile(externalId, remotePath);
+  return client.readFile(name, remotePath);
 }
 
 /** The message printed instead of raw bytes when pull saves to a local file. */
@@ -198,33 +196,33 @@ export function pullSavedMessage(
 }
 
 /**
- * `dor sandbox rebuild <externalId>`: swap the sandbox's container, keep its
+ * `dor sandbox rebuild <name>`: swap the sandbox's container, keep its
  * disk. /home/user survives; everything else resets onto the current image
  * of the sandbox's template (or the base image) at the next use.
  */
 export async function sandboxRebuild(
   client: Dormice,
-  externalId: string,
+  name: string,
 ): Promise<string> {
-  const { sandbox } = await client.rebuildSandbox(externalId);
+  const { sandbox } = await client.rebuildSandbox(name);
   const target = sandbox.template
     ? `template "${printable(sandbox.template)}"'s current image`
     : 'the current base image';
   return (
-    `Rebuilt the sandbox for key "${printable(externalId)}" — /home/user kept, ` +
+    `Rebuilt the sandbox "${printable(name)}" — /home/user kept, ` +
     `now ${sandbox.state}; its next use starts on ${target}.`
   );
 }
 
-/** `dor sandbox destroy <externalId>`: destroy the sandbox behind a key, idempotently. */
+/** `dor sandbox destroy <name>`: destroy the sandbox behind a key, idempotently. */
 export async function sandboxDestroy(
   client: Dormice,
-  externalId: string,
+  name: string,
 ): Promise<string> {
-  const { destroyed } = await client.destroySandbox(externalId);
+  const { destroyed } = await client.destroySandbox(name);
   return destroyed
-    ? `Destroyed the sandbox for key "${printable(externalId)}".`
-    : `No sandbox for key "${printable(externalId)}" — nothing to destroy.`;
+    ? `Destroyed the sandbox "${printable(name)}".`
+    : `No sandbox named "${printable(name)}" — nothing to destroy.`;
 }
 
 /**
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index cb00ed4..712077a 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -58,7 +58,7 @@ sandbox
   .description(
     'Run a shell command inside the sandbox behind a key (wakes it first)',
   )
-  .argument('<externalId>', 'the external id whose sandbox runs the command')
+  .argument('<name>', 'the sandbox name to run the command in')
   .argument(
     '<command>',
     'shell command, quoted as one argument (runs as bash -c)',
@@ -68,110 +68,102 @@ sandbox
     'kill the command after this many seconds',
     (value: string) => Number(value),
   )
-  .action(
-    async (externalId: string, command: string, opts: { timeout?: number }) => {
-      const result = await sandboxExec(
-        clientFromEnv(process.env),
-        externalId,
-        command,
-        opts.timeout,
-      );
-      process.stdout.write(result.stdout);
-      process.stderr.write(result.stderr);
-      process.exitCode = result.exitCode;
-    },
-  );
+  .action(async (name: string, command: string, opts: { timeout?: number }) => {
+    const result = await sandboxExec(
+      clientFromEnv(process.env),
+      name,
+      command,
+      opts.timeout,
+    );
+    process.stdout.write(result.stdout);
+    process.stderr.write(result.stderr);
+    process.exitCode = result.exitCode;
+  });
 
 sandbox
   .command('push')
   .description(
     'Copy a local file into the sandbox behind a key (wakes it first)',
   )
-  .argument('<externalId>', 'the external id whose sandbox receives the file')
+  .argument('<name>', 'the sandbox name to push the file into')
   .argument('<localPath>', 'local file to send')
   .argument(
     '[remotePath]',
     'destination inside the sandbox; relative paths land under /home/user (default: the local file name)',
   )
-  .action(
-    async (externalId: string, localPath: string, remotePath?: string) => {
-      const content = await readFile(localPath);
-      console.log(
-        await sandboxPush(
-          clientFromEnv(process.env),
-          externalId,
-          content,
-          remotePath ?? path.basename(localPath),
-        ),
-      );
-    },
-  );
+  .action(async (name: string, localPath: string, remotePath?: string) => {
+    const content = await readFile(localPath);
+    console.log(
+      await sandboxPush(
+        clientFromEnv(process.env),
+        name,
+        content,
+        remotePath ?? path.basename(localPath),
+      ),
+    );
+  });
 
 sandbox
   .command('pull')
   .description('Copy a file out of the sandbox behind a key (wakes it first)')
-  .argument('<externalId>', 'the external id whose sandbox holds the file')
+  .argument('<name>', 'the sandbox name to pull the file from')
   .argument('<remotePath>', 'file inside the sandbox; relative to /home/user')
   .argument('[localPath]', 'where to save it; omitted = raw bytes to stdout')
-  .action(
-    async (externalId: string, remotePath: string, localPath?: string) => {
-      const result = await sandboxPull(
-        clientFromEnv(process.env),
-        externalId,
-        remotePath,
-      );
-      if (localPath === undefined) {
-        // Raw on purpose, like exec output: the operator's own file's bytes.
-        process.stdout.write(result.content);
-        return;
-      }
-      await writeFile(localPath, result.content);
-      console.log(pullSavedMessage(result, localPath));
-    },
-  );
+  .action(async (name: string, remotePath: string, localPath?: string) => {
+    const result = await sandboxPull(
+      clientFromEnv(process.env),
+      name,
+      remotePath,
+    );
+    if (localPath === undefined) {
+      // Raw on purpose, like exec output: the operator's own file's bytes.
+      process.stdout.write(result.content);
+      return;
+    }
+    await writeFile(localPath, result.content);
+    console.log(pullSavedMessage(result, localPath));
+  });
 
 sandbox
   .command('meta')
   .description(
     'Show or replace the labels on the sandbox behind a key (replacement is total; a pure ledger write, nothing is woken)',
   )
-  .argument('<externalId>', 'the external id whose sandbox to label')
+  .argument('<name>', 'the sandbox name to label')
   .argument(
     '[labels...]',
     'key=value pairs forming the NEW complete label set; omitted = show the current one',
   )
   .option('--clear', 'remove every label')
-  .action(
-    async (externalId: string, labels: string[], opts: { clear?: boolean }) => {
-      if (opts.clear && labels.length > 0) {
-        throw new Error('--clear and key=value labels are mutually exclusive');
-      }
-      console.log(
-        await sandboxMeta(
-          clientFromEnv(process.env),
-          externalId,
-          opts.clear ? {} : labels.length > 0 ? parseLabels(labels) : null,
-        ),
-      );
-    },
-  );
+  .action(async (name: string, labels: string[], opts: { clear?: boolean }) => {
+    if (opts.clear && labels.length > 0) {
+      throw new Error('--clear and key=value labels are mutually exclusive');
+    }
+    console.log(
+      await sandboxMeta(
+        clientFromEnv(process.env),
+        name,
+        opts.clear ? {} : labels.length > 0 ? parseLabels(labels) : null,
+      ),
+    );
+  });
 
 sandbox
   .command('rebuild')
   .description(
     "Swap the container, keep /home/user — next use starts on the template's current image (or the base image)",
   )
-  .argument('<externalId>', 'the external id whose sandbox to rebuild')
-  .action(async (externalId: string) => {
-    console.log(await sandboxRebuild(clientFromEnv(process.env), externalId));
+  .argument('<name>', 'the sandbox name to rebuild')
+  .action(async (name: string) => {
+    console.log(await sandboxRebuild(clientFromEnv(process.env), name));
   });
 
 sandbox
   .command('destroy')
-  .description('Destroy the sandbox behind an external id (idempotent)')
-  .argument('<externalId>', 'the external id whose sandbox to destroy')
-  .action(async (externalId: string) => {
-    console.log(await sandboxDestroy(clientFromEnv(process.env), externalId));
+  .description('Destroy the sandbox behind a name (idempotent)')
+  .argument('<name>', 'the sandbox name to destroy')
+  .action(async (name: string) => {
+    console.log(await sandboxDestroy(clientFromEnv(process.env), name));
   });
 
 const template = program
diff --git a/packages/console/src/components/AppShell.tsx b/packages/console/src/components/AppShell.tsx
index b843d95..1530262 100644
--- a/packages/console/src/components/AppShell.tsx
+++ b/packages/console/src/components/AppShell.tsx
@@ -16,7 +16,7 @@ import {
   SidebarTrigger,
 } from '@/components/ui/sidebar';
 
-// 路径段 → 中文名。没在表里的段(比如 externalId)原样展示 — 它就是名字本身。
+// 路径段 → 中文名。没在表里的段(比如 name)原样展示 — 它就是名字本身。
 const SEGMENT_LABELS: Record<string, string> = {
   sandboxes: '沙箱',
   templates: '模板',
diff --git a/packages/console/src/components/CommandMenu.tsx b/packages/console/src/components/CommandMenu.tsx
index 4a0614b..c7717bb 100644
--- a/packages/console/src/components/CommandMenu.tsx
+++ b/packages/console/src/components/CommandMenu.tsx
@@ -26,7 +26,7 @@ import { MOCK_PAGES_ENABLED } from '@/lib/mock';
  * hook 不能条件调用,但组件可以条件挂载。缓存和列表页共享同一个 key,
  * 打开面板时多半直接命中。
  */
-function SandboxItems({ onGo }: { onGo: (externalId: string) => void }) {
+function SandboxItems({ onGo }: { onGo: (name: string) => void }) {
   const query = useSandboxes();
   const sandboxes = query.data?.sandboxes ?? [];
   if (sandboxes.length === 0) return null;
@@ -34,12 +34,12 @@ function SandboxItems({ onGo }: { onGo: (externalId: string) => void }) {
     <CommandGroup heading="沙箱">
       {sandboxes.map((sandbox) => (
         <CommandItem
-          key={sandbox.sandboxId}
-          value={`sandbox ${sandbox.externalId}`}
-          onSelect={() => onGo(sandbox.externalId)}
+          key={sandbox.id}
+          value={`sandbox ${sandbox.name}`}
+          onSelect={() => onGo(sandbox.name)}
         >
           <HugeiconsIcon icon={PackageIcon} strokeWidth={1.8} />
-          <span className="font-mono">{sandbox.externalId}</span>
+          <span className="font-mono">{sandbox.name}</span>
           <span className="ml-auto text-xs text-muted-foreground">
             {STATE_LABELS[sandbox.state]}
           </span>
@@ -50,7 +50,7 @@ function SandboxItems({ onGo }: { onGo: (externalId: string) => void }) {
 }
 
 /**
- * ⌘K / Ctrl+K 命令面板:跳页面、按 externalId 跳沙箱。挂在 AppShell 上,
+ * ⌘K / Ctrl+K 命令面板:跳页面、按 name 跳沙箱。挂在 AppShell 上,
  * 登录后全站可用;它只做导航 — 动作(销毁/重建)留在各自页面的确认
  * 流程里,快捷键不该绕过"删了就没有了"的那道闸。
  */
@@ -73,11 +73,11 @@ export function CommandMenu() {
     setOpen(false);
     void navigate({ to });
   };
-  const goSandbox = (externalId: string) => {
+  const goSandbox = (name: string) => {
     setOpen(false);
     void navigate({
-      to: '/sandboxes/$externalId',
-      params: { externalId },
+      to: '/sandboxes/$name',
+      params: { name },
       search: { tab: 'overview' },
     });
   };
diff --git a/packages/console/src/features/activity/hooks/useActivity.ts b/packages/console/src/features/activity/hooks/useActivity.ts
index e6fd931..89c714d 100644
--- a/packages/console/src/features/activity/hooks/useActivity.ts
+++ b/packages/console/src/features/activity/hooks/useActivity.ts
@@ -5,7 +5,7 @@ import { listActivity } from '@/lib/api';
  * 活动流是观察窗:5 秒轮询即可 — 事件写在动作发生处,读只是翻账本,
  * 比沙箱列表的 2 秒松一档(历史不像状态那样急着看)。
  *
- * limit 缺省用 wire 默认(200);详情页历史 tab 要按 externalId 过滤,
+ * limit 缺省用 wire 默认(200);详情页历史 tab 要按 name 过滤,
  * 传环形表上限(1000)把一个沙箱的事件尽量捞全。
  */
 export function useActivity(limit?: number) {
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index 1c1ab1c..587bad5 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -48,7 +48,7 @@ export function ActivityPage() {
         (event) =>
           (kindFilter === 'all' || event.kind === kindFilter) &&
           (search === '' ||
-            (event.externalId ?? '')
+            (event.sandboxName ?? '')
               .toLowerCase()
               .includes(search.toLowerCase())),
       ),
@@ -76,7 +76,7 @@ export function ActivityPage() {
           <InputGroupInput
             value={search}
             onChange={(event) => setSearch(event.target.value)}
-            placeholder="按 externalId 搜索"
+            placeholder="按名称搜索"
           />
         </InputGroup>
         <FilterMenu
@@ -130,7 +130,7 @@ export function ActivityPage() {
             <TableRow>
               <TableHead className="w-28">时间</TableHead>
               <TableHead className="w-28">事件</TableHead>
-              <TableHead className="w-40">externalId</TableHead>
+              <TableHead className="w-40">名称</TableHead>
               <TableHead>详情</TableHead>
             </TableRow>
           </TableHeader>
@@ -156,14 +156,14 @@ export function ActivityPage() {
                   </Badge>
                 </TableCell>
                 <TableCell>
-                  {event.externalId ? (
+                  {event.sandboxName ? (
                     <Link
-                      to="/sandboxes/$externalId"
-                      params={{ externalId: event.externalId }}
+                      to="/sandboxes/$name"
+                      params={{ name: event.sandboxName }}
                       search={{ tab: 'overview' as const }}
                       className="font-mono hover:underline"
                     >
-                      {event.externalId}
+                      {event.sandboxName}
                     </Link>
                   ) : (
                     <span className="text-muted-foreground">—</span>
diff --git a/packages/console/src/features/connect/snippets.ts b/packages/console/src/features/connect/snippets.ts
index ae3a428..d67ac47 100644
--- a/packages/console/src/features/connect/snippets.ts
+++ b/packages/console/src/features/connect/snippets.ts
@@ -10,8 +10,8 @@ const sandbox = await Sandbox.create({
   apiKey: 'e2b_<your API token>',
   apiUrl: '${origin}/e2b/api',
   sandboxUrl: '${origin}/e2b/envd',
-  // Dormice 扩展:同一个 externalId 永远回到同一个沙箱。
-  metadata: { externalId: 'my-project' },
+  // Dormice 扩展:同一个 name 永远回到同一个沙箱。
+  metadata: { name: 'my-project' },
 });
 
 const result = await sandbox.commands.run('echo hello from dormice');`;
diff --git a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
index 8aeb314..1b9c2f1 100644
--- a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
+++ b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
@@ -29,8 +29,8 @@ import { Spinner } from '@/components/ui/spinner';
 import { Switch } from '@/components/ui/switch';
 import { useConfig } from '@/features/settings/hooks/useConfig';
 import { useTemplates } from '@/features/templates/hooks/useTemplates';
-import { durationHint } from '../format';
-import { useAcquireSandbox } from '../hooks/useSandboxes';
+import { durationHint, STATE_LABELS } from '../format';
+import { useAcquireSandbox, useSandboxes } from '../hooks/useSandboxes';
 
 /**
  * The console speaks the same verb as everyone else: acquire. Same key,
@@ -45,7 +45,7 @@ import { useAcquireSandbox } from '../hooks/useSandboxes';
  */
 export function CreateSandboxDialog() {
   const [open, setOpen] = useState(false);
-  const [externalId, setExternalId] = useState('');
+  const [name, setName] = useState('');
   const [template, setTemplate] = useState('');
   const [freezeAfter, setFreezeAfter] = useState('');
   const [neverStop, setNeverStop] = useState(false);
@@ -55,9 +55,12 @@ export function CreateSandboxDialog() {
   const mutation = useAcquireSandbox();
   const templates = useTemplates().data?.templates ?? [];
   const archive = useConfig().data?.archive;
+  // 名字撞车不报错而是拿回旧沙箱 — 没有 duplicate 报错来教这件事,
+  // 所以在扣扳机前一秒把真相亮出来:列表缓存本来就 2 秒一刷,免费。
+  const existing = useSandboxes().data?.sandboxes.find((s) => s.name === name);
 
   const reset = () => {
-    setExternalId('');
+    setName('');
     setTemplate('');
     setFreezeAfter('');
     setNeverStop(false);
@@ -80,13 +83,18 @@ export function CreateSandboxDialog() {
 
     mutation.mutate(
       {
-        externalId,
+        name,
         ...(template !== '' ? { template } : {}),
         ...(Object.keys(policy).length > 0 ? { policy } : {}),
       },
       {
-        onSuccess: ({ sandbox }) => {
-          toast.success(`「${sandbox.externalId}」的沙箱已就绪`);
+        onSuccess: ({ created, sandbox }) => {
+          // created 让幂等可见:拿回旧沙箱时不许谎报"已创建"。
+          toast.success(
+            created
+              ? `「${sandbox.name}」的沙箱已创建`
+              : `拿回了已有的沙箱「${sandbox.name}」`,
+          );
           setOpen(false);
           reset();
         },
@@ -114,8 +122,8 @@ export function CreateSandboxDialog() {
         <DialogHeader>
           <DialogTitle>创建沙箱</DialogTitle>
           <DialogDescription>
-            acquire 是幂等的:这个 key 已经有沙箱时,拿回的是原来那个,
-            下面的策略会被忽略。
+            acquire 是幂等的:名字已经有沙箱时,拿回的是原来那个,
+            下面的模板和策略不会应用。
           </DialogDescription>
         </DialogHeader>
         <form
@@ -126,18 +134,19 @@ export function CreateSandboxDialog() {
         >
           <FieldGroup>
             <Field>
-              <FieldLabel htmlFor="create-user-key">externalId</FieldLabel>
+              <FieldLabel htmlFor="create-sandbox-name">名称</FieldLabel>
               <Input
-                id="create-user-key"
-                value={externalId}
-                onChange={(event) => setExternalId(event.target.value)}
+                id="create-sandbox-name"
+                value={name}
+                onChange={(event) => setName(event.target.value)}
                 placeholder="my-agent"
                 maxLength={128}
                 className="font-mono"
               />
               <FieldDescription>
-                调用方自选的身份,acquire 对它幂等 — 同一个 key 永远回到
-                同一个沙箱。
+                {existing
+                  ? `这个名字已有沙箱(${STATE_LABELS[existing.state]})— 提交会直接拿回它,下面的模板和策略不会应用。`
+                  : '你起的唯一名字,acquire 对它幂等 — 同一个名字永远回到同一个沙箱。'}
               </FieldDescription>
             </Field>
             {templates.length > 0 && (
@@ -249,10 +258,10 @@ export function CreateSandboxDialog() {
           <DialogFooter className="mt-6">
             <Button
               type="submit"
-              disabled={externalId.length === 0 || mutation.isPending}
+              disabled={name.length === 0 || mutation.isPending}
             >
               {mutation.isPending && <Spinner />}
-              创建
+              {existing ? '拿回已有沙箱' : '创建'}
             </Button>
           </DialogFooter>
         </form>
diff --git a/packages/console/src/features/sandboxes/components/DestroySandboxButton.tsx b/packages/console/src/features/sandboxes/components/DestroySandboxButton.tsx
index 5f9835e..cde9b24 100644
--- a/packages/console/src/features/sandboxes/components/DestroySandboxButton.tsx
+++ b/packages/console/src/features/sandboxes/components/DestroySandboxButton.tsx
@@ -21,12 +21,12 @@ import { useDestroySandbox } from '../hooks/useSandboxes';
  * so the dialog must live outside it — a trigger inside would vanish).
  */
 export function DestroySandboxDialog({
-  externalId,
+  name,
   open,
   onOpenChange,
   onDestroyed,
 }: {
-  externalId: string;
+  name: string;
   open: boolean;
   onOpenChange: (open: boolean) => void;
   onDestroyed?: () => void;
@@ -34,11 +34,9 @@ export function DestroySandboxDialog({
   const mutation = useDestroySandbox();
 
   const destroy = () =>
-    mutation.mutate(externalId, {
+    mutation.mutate(name, {
       onSuccess: ({ destroyed }) => {
-        toast.success(
-          destroyed ? `已销毁 ${externalId}` : `${externalId} 本来就不存在`,
-        );
+        toast.success(destroyed ? `已销毁 ${name}` : `${name} 本来就不存在`);
         onDestroyed?.();
       },
       onError: (error) => toast.error(error.message),
@@ -48,9 +46,9 @@ export function DestroySandboxDialog({
     <AlertDialog open={open} onOpenChange={onOpenChange}>
       <AlertDialogContent>
         <AlertDialogHeader>
-          <AlertDialogTitle>销毁「{externalId}」?</AlertDialogTitle>
+          <AlertDialogTitle>销毁「{name}」?</AlertDialogTitle>
           <AlertDialogDescription>
-            沙箱连同磁盘一起销毁,不可恢复。key 依然有效 — 下次 acquire
+            沙箱连同磁盘一起销毁,不可恢复。名字依然可用 — 下次同名 acquire
             会得到一个全新的空白沙箱。
           </AlertDialogDescription>
         </AlertDialogHeader>
@@ -66,10 +64,10 @@ export function DestroySandboxDialog({
 }
 
 export function DestroySandboxButton({
-  externalId,
+  name,
   onDestroyed,
 }: {
-  externalId: string;
+  name: string;
   onDestroyed?: () => void;
 }) {
   const [open, setOpen] = useState(false);
@@ -80,7 +78,7 @@ export function DestroySandboxButton({
         销毁
       </Button>
       <DestroySandboxDialog
-        externalId={externalId}
+        name={name}
         open={open}
         onOpenChange={setOpen}
         onDestroyed={onDestroyed}
diff --git a/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx b/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
index 3897197..1a16084 100644
--- a/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
+++ b/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
@@ -63,7 +63,7 @@ export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
   const submit = () => {
     mutation.mutate(
       {
-        externalId: sandbox.externalId,
+        name: sandbox.name,
         policy: {
           freezeAfterSeconds: Number(freezeAfter),
           stopAfterSeconds: neverStop ? null : Number(stopAfter),
@@ -79,7 +79,7 @@ export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
       },
       {
         onSuccess: () => {
-          toast.success(`「${sandbox.externalId}」的策略已更新`);
+          toast.success(`「${sandbox.name}」的策略已更新`);
           setOpen(false);
         },
       },
@@ -110,7 +110,7 @@ export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
       />
       <DialogContent className="sm:max-w-md">
         <DialogHeader>
-          <DialogTitle>调整「{sandbox.externalId}」的生命周期策略</DialogTitle>
+          <DialogTitle>调整「{sandbox.name}」的生命周期策略</DialogTitle>
           <DialogDescription>
             立即生效,只改账本 — 沉睡的沙箱不会被吵醒,空闲计时也不重置
             (新阈值按已累积的空闲时间判定)。
diff --git a/packages/console/src/features/sandboxes/components/FilesPanel.tsx b/packages/console/src/features/sandboxes/components/FilesPanel.tsx
index 7970560..433c9ec 100644
--- a/packages/console/src/features/sandboxes/components/FilesPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/FilesPanel.tsx
@@ -104,7 +104,7 @@ function sortEntries(entries: EnvdEntry[]): EnvdEntry[] {
 export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
   const [unlocked, setUnlocked] = useState(sandbox.state === 'active');
   const [path, setPath] = useState(HOME);
-  const auth = useEnvdAuth(sandbox.sandboxId);
+  const auth = useEnvdAuth(sandbox.id);
   const directory = useDirectory(auth.data, path, unlocked);
   // 沙箱里(agent、终端)动了文件,这张表 2 秒内自己跟上 — 不用手点刷新。
   useDirectoryWatch(auth.data, path, {
diff --git a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
index a810025..a07602f 100644
--- a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
@@ -27,13 +27,13 @@ import { since } from '../format';
 
 /**
  * 「我的沙箱昨晚为什么停了」— 活动环里只属于这个沙箱的那几行。纯前端
- * 过滤:活动事件本来就带 externalId,不发明新端点;按环形表上限(1000)
+ * 过滤:活动事件本来就带 name,不发明新端点;按环形表上限(1000)
  * 拉取,把这个沙箱的事件尽量捞全,再老的已经滚出环了。
  */
-export function HistoryPanel({ externalId }: { externalId: string }) {
+export function HistoryPanel({ name }: { name: string }) {
   const { data, isPending, isError, error } = useActivity(1000);
   const events = (data?.events ?? []).filter(
-    (event) => event.externalId === externalId,
+    (event) => event.sandboxName === name,
   );
 
   if (isPending) {
diff --git a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
index d5d14cd..c04e3a0 100644
--- a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
@@ -217,10 +217,10 @@ function HistoryChart({
  */
 export function MetricsPanel({ sandbox }: { sandbox: Sandbox }) {
   const [range, setRange] = useState<HistoryRangeKey>('1h');
-  const live = useSandboxMetrics(sandbox.externalId);
+  const live = useSandboxMetrics(sandbox.name);
   const spanMs =
     HISTORY_RANGES.find((r) => r.key === range)?.spanMs ?? 3600_000;
-  const history = useSandboxMetricsHistory(sandbox.externalId, spanMs);
+  const history = useSandboxMetricsHistory(sandbox.name, spanMs);
 
   if (live.isPending) {
     return (
diff --git a/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx b/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
index 2cf791c..2526e38 100644
--- a/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
@@ -36,7 +36,7 @@ import { useEnvdAuth, useKillProcess, useProcesses } from '../hooks/useEnvd';
 export function ProcessesPanel({ sandbox }: { sandbox: Sandbox }) {
   // 只有物理容器在(active/frozen)才有进程表;停机沙箱只剩磁盘。
   const hasContainer = sandbox.state === 'active' || sandbox.state === 'frozen';
-  const auth = useEnvdAuth(sandbox.sandboxId);
+  const auth = useEnvdAuth(sandbox.id);
   const processes = useProcesses(auth.data, hasContainer);
   const kill = useKillProcess(auth.data);
 
diff --git a/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx b/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx
index 90976a6..a23745e 100644
--- a/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx
+++ b/packages/console/src/features/sandboxes/components/RebuildSandboxButton.tsx
@@ -19,14 +19,14 @@ import { useRebuildSandbox } from '../hooks/useSandboxes';
  * does kill everything running inside and resets anything installed outside
  * the home directory, so it still asks first.
  */
-export function RebuildSandboxButton({ externalId }: { externalId: string }) {
+export function RebuildSandboxButton({ name }: { name: string }) {
   const mutation = useRebuildSandbox();
 
   const rebuild = () =>
-    mutation.mutate(externalId, {
+    mutation.mutate(name, {
       onSuccess: () =>
         toast.success(
-          `已重建 ${externalId} — /home/user 保留,下次使用跑在当前镜像上`,
+          `已重建 ${name} — /home/user 保留,下次使用跑在当前镜像上`,
         ),
       onError: (error) => toast.error(error.message),
     });
@@ -43,7 +43,7 @@ export function RebuildSandboxButton({ externalId }: { externalId: string }) {
       />
       <AlertDialogContent>
         <AlertDialogHeader>
-          <AlertDialogTitle>重建「{externalId}」?</AlertDialogTitle>
+          <AlertDialogTitle>重建「{name}」?</AlertDialogTitle>
           <AlertDialogDescription>
             换壳保盘:下次使用跑在 daemon 当前的镜像上。/home/user 一字节
             不丢;正在跑的进程和家目录之外的改动随旧壳蒸发。
diff --git a/packages/console/src/features/sandboxes/components/RestoreCard.tsx b/packages/console/src/features/sandboxes/components/RestoreCard.tsx
index 705f4e7..d7339d8 100644
--- a/packages/console/src/features/sandboxes/components/RestoreCard.tsx
+++ b/packages/console/src/features/sandboxes/components/RestoreCard.tsx
@@ -21,14 +21,14 @@ export function RestoreCard({ sandbox }: { sandbox: Sandbox }) {
   const restoring = sandbox.state === 'restoring';
 
   const progressQuery = useQuery({
-    queryKey: ['restore-progress', sandbox.externalId],
-    queryFn: () => acquireSandbox({ externalId: sandbox.externalId }),
+    queryKey: ['restore-progress', sandbox.name],
+    queryFn: () => acquireSandbox({ name: sandbox.name }),
     enabled: restoring,
     refetchInterval: 1500,
     retry: false,
   });
   const begin = useMutation({
-    mutationFn: () => acquireSandbox({ externalId: sandbox.externalId }),
+    mutationFn: () => acquireSandbox({ name: sandbox.name }),
     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
     onError: (error) => toast.error(`恢复没能开始:${error.message}`),
   });
diff --git a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
index ebfb735..96980d4 100644
--- a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
+++ b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
@@ -34,11 +34,11 @@ export function useSandboxes() {
   });
 }
 
-export function useSandbox(externalId: string) {
+export function useSandbox(name: string) {
   const query = useSandboxes();
   return {
     ...query,
-    sandbox: query.data?.sandboxes.find((s) => s.externalId === externalId),
+    sandbox: query.data?.sandboxes.find((s) => s.name === name),
   };
 }
 
@@ -46,10 +46,10 @@ export function useSandbox(externalId: string) {
  * 单沙箱指标,5 秒一拍。观察不唤醒:停着的沙箱答 sample: null,面板
  * 据此出空态而不是把沙箱吵醒。只在指标 tab 挂载时才跑(面板卸载即停)。
  */
-export function useSandboxMetrics(externalId: string) {
+export function useSandboxMetrics(name: string) {
   return useQuery({
-    queryKey: ['sandbox-metrics', externalId],
-    queryFn: () => getSandboxMetrics(externalId),
+    queryKey: ['sandbox-metrics', name],
+    queryFn: () => getSandboxMetrics(name),
     refetchInterval: 5000,
     retry: false,
   });
@@ -61,13 +61,13 @@ export function useSandboxMetrics(externalId: string) {
  * 历史键在 sandboxId 上,换壳(rebuild)不断线。切换档位时沿用上一档
  * 的数据顶住新答案到来(keepPreviousData),图表不塌回空态。
  */
-export function useSandboxMetricsHistory(externalId: string, spanMs: number) {
+export function useSandboxMetricsHistory(name: string, spanMs: number) {
   return useQuery({
-    queryKey: ['sandbox-metrics-history', externalId, spanMs],
+    queryKey: ['sandbox-metrics-history', name, spanMs],
     queryFn: () => {
       const end = Date.now();
       return getSandboxMetricsHistory(
-        externalId,
+        name,
         new Date(end - spanMs).toISOString(),
         new Date(end).toISOString(),
       );
@@ -118,10 +118,8 @@ export function useAcquireSandbox() {
 export function useUpdatePolicy() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: (args: {
-      externalId: string;
-      policy: LifecyclePolicyOverride;
-    }) => updatePolicy(args.externalId, args.policy),
+    mutationFn: (args: { name: string; policy: LifecyclePolicyOverride }) =>
+      updatePolicy(args.name, args.policy),
     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
   });
 }
@@ -129,7 +127,7 @@ export function useUpdatePolicy() {
 export function useRebuildSandbox() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: (externalId: string) => rebuildSandbox(externalId),
+    mutationFn: (name: string) => rebuildSandbox(name),
     onSettled: () => {
       queryClient.invalidateQueries({ queryKey: ['sandboxes'] });
       // 换壳直接改变镜像血统(可升级标记要立即消失),不等下一拍。
@@ -141,7 +139,7 @@ export function useRebuildSandbox() {
 export function useDestroySandbox() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: (externalId: string) => destroySandbox(externalId),
+    mutationFn: (name: string) => destroySandbox(name),
     onSettled: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
   });
 }
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index 2a09447..18bdbeb 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -56,21 +56,21 @@ function Row({ label, children }: { label: string; children: ReactNode }) {
  * SDK 同一条 wire。tab 记在 URL 里,刷新与分享都停在原面板。
  */
 export function SandboxDetailPage() {
-  const { externalId } = useParams({ from: '/_app/sandboxes/$externalId' });
-  const { tab } = useSearch({ from: '/_app/sandboxes/$externalId' });
-  const navigate = useNavigate({ from: '/sandboxes/$externalId' });
-  const { sandbox, isSuccess } = useSandbox(externalId);
+  const { name } = useParams({ from: '/_app/sandboxes/$name' });
+  const { tab } = useSearch({ from: '/_app/sandboxes/$name' });
+  const navigate = useNavigate({ from: '/sandboxes/$name' });
+  const { sandbox, isSuccess } = useSandbox(name);
   // 镜像血统与列表页同一份 5 秒缓存;拿不到就不显示,不挡页面。
   const images = useSandboxImages();
-  const lineage = images.data?.images.find((e) => e.externalId === externalId);
+  const lineage = images.data?.images.find((e) => e.sandboxName === name);
 
   if (!sandbox) {
     return isSuccess ? (
       <Empty className="border border-dashed">
         <EmptyHeader>
-          <EmptyTitle>没有叫「{externalId}」的沙箱</EmptyTitle>
+          <EmptyTitle>没有叫「{name}」的沙箱</EmptyTitle>
           <EmptyDescription>
-            可能已被销毁 — 这个 key 依然有效,下次 acquire 会得到一个
+            可能已被销毁 — 这个名字依然可用,下次同名 acquire 会得到一个
             全新的沙箱。
           </EmptyDescription>
         </EmptyHeader>
@@ -92,17 +92,15 @@ export function SandboxDetailPage() {
     <>
       <div className="flex flex-wrap items-center justify-between gap-3">
         <div className="flex items-center gap-3">
-          <h1 className="font-mono text-2xl font-semibold">
-            {sandbox.externalId}
-          </h1>
+          <h1 className="font-mono text-2xl font-semibold">{sandbox.name}</h1>
           <SandboxStateBadge state={sandbox.state} />
           <LifecycleCountdown sandbox={sandbox} />
         </div>
         <div className="flex items-center gap-2">
           <EditPolicyDialog sandbox={sandbox} />
-          <RebuildSandboxButton externalId={sandbox.externalId} />
+          <RebuildSandboxButton name={sandbox.name} />
           <DestroySandboxButton
-            externalId={sandbox.externalId}
+            name={sandbox.name}
             onDestroyed={() => navigate({ to: '/sandboxes' })}
           />
         </div>
@@ -134,7 +132,7 @@ export function SandboxDetailPage() {
           <Card>
             <CardContent>
               <dl>
-                <Row label="沙箱 ID">{sandbox.sandboxId}</Row>
+                <Row label="沙箱 ID">{sandbox.id}</Row>
                 <Row label="模板">
                   <span className="inline-flex items-center gap-1.5">
                     {sandbox.template ?? '基础镜像'}
@@ -192,7 +190,7 @@ export function SandboxDetailPage() {
         </TabsContent>
 
         <TabsContent value="terminal">
-          <SandboxTerminalCard sandboxId={sandbox.sandboxId} />
+          <SandboxTerminalCard sandboxId={sandbox.id} />
         </TabsContent>
 
         <TabsContent value="files">
@@ -208,7 +206,7 @@ export function SandboxDetailPage() {
         </TabsContent>
 
         <TabsContent value="history">
-          <HistoryPanel externalId={sandbox.externalId} />
+          <HistoryPanel name={sandbox.name} />
         </TabsContent>
       </Tabs>
     </>
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index baa3550..cbc503b 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -78,8 +78,8 @@ const STATE_FILTERS: Array<SandboxState> = [
   'restoring',
 ];
 
-/** 可排序的列:字符串比较对 externalId 和 ISO 时间戳同样成立。 */
-type SortKey = 'externalId' | 'lastActiveAt' | 'createdAt';
+/** 可排序的列:字符串比较对 name 和 ISO 时间戳同样成立。 */
+type SortKey = 'name' | 'lastActiveAt' | 'createdAt';
 type Sort = { key: SortKey; dir: 1 | -1 };
 
 /** 一个沙箱的标签摊平成 "key=value" 串 — 筛选项与展示共用同一拼法。 */
@@ -182,7 +182,7 @@ function SortableHead({
  * 安静的 ghost 图标,不是一排常驻按钮。销毁的确认弹窗挂在菜单外 —
  * 菜单关闭即卸载,弹窗放里面会跟着消失。
  */
-function SandboxRowMenu({ externalId }: { externalId: string }) {
+function SandboxRowMenu({ name }: { name: string }) {
   const [confirmOpen, setConfirmOpen] = useState(false);
 
   return (
@@ -193,7 +193,7 @@ function SandboxRowMenu({ externalId }: { externalId: string }) {
             <Button
               variant="ghost"
               size="icon-sm"
-              aria-label={`${externalId} 的操作`}
+              aria-label={`${name} 的操作`}
             >
               <HugeiconsIcon icon={MoreVerticalIcon} />
             </Button>
@@ -202,12 +202,12 @@ function SandboxRowMenu({ externalId }: { externalId: string }) {
         <DropdownMenuContent align="end">
           <DropdownMenuItem
             onClick={async () => {
-              await navigator.clipboard.writeText(externalId);
-              toast.success('externalId 已复制');
+              await navigator.clipboard.writeText(name);
+              toast.success('名称已复制');
             }}
           >
             <HugeiconsIcon icon={Copy01Icon} />
-            复制 externalId
+            复制名称
           </DropdownMenuItem>
           <DropdownMenuItem
             variant="destructive"
@@ -219,7 +219,7 @@ function SandboxRowMenu({ externalId }: { externalId: string }) {
         </DropdownMenuContent>
       </DropdownMenu>
       <DestroySandboxDialog
-        externalId={externalId}
+        name={name}
         open={confirmOpen}
         onOpenChange={setConfirmOpen}
       />
@@ -232,10 +232,10 @@ function SandboxRowMenu({ externalId }: { externalId: string }) {
  * 裁决的,并发只是把失败搅在一起),结束后一次性汇报成败。
  */
 function BulkDestroyButton({
-  externalIds,
+  names,
   onDone,
 }: {
-  externalIds: string[];
+  names: string[];
   onDone: () => void;
 }) {
   const [pending, setPending] = useState(false);
@@ -243,17 +243,17 @@ function BulkDestroyButton({
   const destroyAll = async () => {
     setPending(true);
     const failures: string[] = [];
-    for (const externalId of externalIds) {
+    for (const name of names) {
       try {
-        await destroySandbox(externalId);
+        await destroySandbox(name);
       } catch {
-        failures.push(externalId);
+        failures.push(name);
       }
     }
     setPending(false);
     void queryClient.invalidateQueries({ queryKey: ['sandboxes'] });
     if (failures.length === 0) {
-      toast.success(`已销毁 ${externalIds.length} 个沙箱`);
+      toast.success(`已销毁 ${names.length} 个沙箱`);
     } else {
       toast.error(`${failures.length} 个销毁失败:${failures.join('、')}`);
     }
@@ -266,15 +266,15 @@ function BulkDestroyButton({
         render={
           <Button variant="destructive" size="sm" disabled={pending}>
             {pending && <Spinner />}
-            销毁选中({externalIds.length})
+            销毁选中({names.length})
           </Button>
         }
       />
       <AlertDialogContent>
         <AlertDialogHeader>
-          <AlertDialogTitle>销毁 {externalIds.length} 个沙箱?</AlertDialogTitle>
+          <AlertDialogTitle>销毁 {names.length} 个沙箱?</AlertDialogTitle>
           <AlertDialogDescription>
-            沙箱连同磁盘一起销毁,不可恢复。key 依然有效 — 下次 acquire
+            沙箱连同磁盘一起销毁,不可恢复。名字依然可用 — 下次用同名 acquire
             会得到一个全新的空白沙箱。
           </AlertDialogDescription>
         </AlertDialogHeader>
@@ -296,13 +296,15 @@ export function SandboxesPage() {
   const fleet = useFleetMetrics();
   const metricsOf = useMemo(
     () =>
-      new Map((fleet.data?.samples ?? []).map((s) => [s.externalId, s.sample])),
+      new Map(
+        (fleet.data?.samples ?? []).map((s) => [s.sandboxName, s.sample]),
+      ),
     [fleet.data],
   );
   // 镜像血统批量拉,同一口径:拉不到就不出标记,不挡列表。
   const images = useSandboxImages();
   const lineageOf = useMemo(
-    () => new Map((images.data?.images ?? []).map((e) => [e.externalId, e])),
+    () => new Map((images.data?.images ?? []).map((e) => [e.sandboxName, e])),
     [images.data],
   );
   const [search, setSearch] = useState('');
@@ -332,7 +334,7 @@ export function SandboxesPage() {
         (metadataFilter === '' ||
           labelPairs(sandbox).includes(metadataFilter)) &&
         (search === '' ||
-          sandbox.externalId.toLowerCase().includes(search.toLowerCase())),
+          sandbox.name.toLowerCase().includes(search.toLowerCase())),
     );
     if (!sort) return matched;
     return [...matched].sort(
@@ -341,22 +343,20 @@ export function SandboxesPage() {
   }, [sandboxes, stateFilter, metadataFilter, search, sort]);
 
   // 选中集随现实收敛:被别处销毁的沙箱不该留在选中里撑数字。
-  const selectedVisible = filtered.filter((s) => selected.has(s.externalId));
+  const selectedVisible = filtered.filter((s) => selected.has(s.name));
   const allVisibleSelected =
     filtered.length > 0 && selectedVisible.length === filtered.length;
 
   const toggleAll = () => {
     setSelected(
-      allVisibleSelected
-        ? new Set()
-        : new Set(filtered.map((s) => s.externalId)),
+      allVisibleSelected ? new Set() : new Set(filtered.map((s) => s.name)),
     );
   };
-  const toggleOne = (externalId: string) => {
+  const toggleOne = (name: string) => {
     setSelected((prev) => {
       const next = new Set(prev);
-      if (next.has(externalId)) next.delete(externalId);
-      else next.add(externalId);
+      if (next.has(name)) next.delete(name);
+      else next.add(name);
       return next;
     });
   };
@@ -384,7 +384,7 @@ export function SandboxesPage() {
           <InputGroupInput
             value={search}
             onChange={(event) => setSearch(event.target.value)}
-            placeholder="按 externalId 搜索"
+            placeholder="按 name 搜索"
           />
         </InputGroup>
         <FilterMenu
@@ -412,7 +412,7 @@ export function SandboxesPage() {
         {selectedVisible.length > 0 && (
           <div className="ml-auto">
             <BulkDestroyButton
-              externalIds={selectedVisible.map((s) => s.externalId)}
+              names={selectedVisible.map((s) => s.name)}
               onDone={() => setSelected(new Set())}
             />
           </div>
@@ -462,8 +462,8 @@ export function SandboxesPage() {
               </TableHead>
               <TableHead>
                 <SortableHead
-                  label="externalId"
-                  sortKey="externalId"
+                  label="名称"
+                  sortKey="name"
                   sort={sort}
                   onSort={toggleSort}
                 />
@@ -498,26 +498,24 @@ export function SandboxesPage() {
           <TableBody>
             {filtered.map((sandbox: Sandbox) => (
               <TableRow
-                key={sandbox.sandboxId}
-                data-state={
-                  selected.has(sandbox.externalId) ? 'selected' : undefined
-                }
+                key={sandbox.id}
+                data-state={selected.has(sandbox.name) ? 'selected' : undefined}
               >
                 <TableCell>
                   <Checkbox
-                    aria-label={`选中 ${sandbox.externalId}`}
-                    checked={selected.has(sandbox.externalId)}
-                    onCheckedChange={() => toggleOne(sandbox.externalId)}
+                    aria-label={`选中 ${sandbox.name}`}
+                    checked={selected.has(sandbox.name)}
+                    onCheckedChange={() => toggleOne(sandbox.name)}
                   />
                 </TableCell>
                 <TableCell>
                   <Link
-                    to="/sandboxes/$externalId"
-                    params={{ externalId: sandbox.externalId }}
+                    to="/sandboxes/$name"
+                    params={{ name: sandbox.name }}
                     search={{ tab: 'overview' }}
                     className="font-mono font-medium hover:underline"
                   >
-                    {sandbox.externalId}
+                    {sandbox.name}
                   </Link>
                 </TableCell>
                 <TableCell>
@@ -526,16 +524,14 @@ export function SandboxesPage() {
                 <TableCell className="text-muted-foreground">
                   <span className="inline-flex items-center gap-1.5">
                     {sandbox.template ?? '基础镜像'}
-                    <UpgradableBadge
-                      lineage={lineageOf.get(sandbox.externalId)}
-                    />
+                    <UpgradableBadge lineage={lineageOf.get(sandbox.name)} />
                   </span>
                 </TableCell>
                 <TableCell>
                   <MetadataChips sandbox={sandbox} />
                 </TableCell>
                 {(() => {
-                  const m = metricsOf.get(sandbox.externalId);
+                  const m = metricsOf.get(sandbox.name);
                   if (!m) {
                     return (
                       <>
@@ -581,7 +577,7 @@ export function SandboxesPage() {
                   {since(sandbox.createdAt)}
                 </TableCell>
                 <TableCell className="text-right">
-                  <SandboxRowMenu externalId={sandbox.externalId} />
+                  <SandboxRowMenu name={sandbox.name} />
                 </TableCell>
               </TableRow>
             ))}
diff --git a/packages/console/src/features/templates/pages/TemplatesPage.tsx b/packages/console/src/features/templates/pages/TemplatesPage.tsx
index 9d6c7ca..555139b 100644
--- a/packages/console/src/features/templates/pages/TemplatesPage.tsx
+++ b/packages/console/src/features/templates/pages/TemplatesPage.tsx
@@ -199,7 +199,7 @@ function RemoveTemplateDialog({
         toast.success(
           removed ? `已删除「${name}」` : `「${name}」本来就不存在`,
         ),
-      // 还有沙箱引用时 daemon 回 409 并点名 externalId — 原文转达。
+      // 还有沙箱引用时 daemon 回 409 并点名 name — 原文转达。
       onError: (error) => toast.error(error.message),
     });
 
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index c711625..1b1f6d4 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -123,8 +123,8 @@ export const getHostMetrics = () => rpc<HostMetricsResponse>('/getHostMetrics');
 
 // One sandbox's point-in-time reading. Same principle: a frozen sandbox is
 // measured as it sleeps, a stopped one answers sample: null — never woken.
-export const getSandboxMetrics = (externalId: string) =>
-  rpc<GetSandboxMetricsResponse>('/getSandboxMetrics', { externalId });
+export const getSandboxMetrics = (name: string) =>
+  rpc<GetSandboxMetricsResponse>('/getSandboxMetrics', { name });
 
 // Every measurable sandbox in one answer — the list view's food. Presence
 // means measured: colder states are simply absent.
@@ -135,12 +135,12 @@ export const listSandboxMetrics = () =>
 // daemon buckets the answer (per-field maxima — spikes survive); a window
 // the daemon was down for shows the gap, never an interpolation.
 export const getSandboxMetricsHistory = (
-  externalId: string,
+  name: string,
   start: string,
   end: string,
 ) =>
   rpc<GetSandboxMetricsHistoryResponse>('/getSandboxMetricsHistory', {
-    externalId,
+    name,
     start,
     end,
   });
@@ -223,20 +223,18 @@ export const removeTemplate = (name: string) =>
 export const acquireSandbox = (request: AcquireRequest) =>
   rpc<AcquireResponse>('/acquireSandbox', request);
 
-export const destroySandbox = (externalId: string) =>
-  rpc<{ destroyed: boolean }>('/destroySandbox', { externalId });
+export const destroySandbox = (name: string) =>
+  rpc<{ destroyed: boolean }>('/destroySandbox', { name });
 
 // Swap the container, keep /home/user: the next use starts on the daemon's
 // current base image.
-export const rebuildSandbox = (externalId: string) =>
-  rpc<{ sandbox: Sandbox }>('/rebuildSandbox', { externalId });
+export const rebuildSandbox = (name: string) =>
+  rpc<{ sandbox: Sandbox }>('/rebuildSandbox', { name });
 
 // Patch the stored lifecycle policy in place — the update verb acquire is
 // not. Ledger-only: nothing wakes, the idle clock keeps running.
-export const updatePolicy = (
-  externalId: string,
-  policy: LifecyclePolicyOverride,
-) => rpc<{ sandbox: Sandbox }>('/updatePolicy', { externalId, policy });
+export const updatePolicy = (name: string, policy: LifecyclePolicyOverride) =>
+  rpc<{ sandbox: Sandbox }>('/updatePolicy', { name, policy });
 
 // The terminal's key: trades the session cookie for one sandbox's envd
 // access token, so the browser can speak to the envd surface directly.
diff --git a/packages/console/src/routeTree.gen.ts b/packages/console/src/routeTree.gen.ts
index 15d9a4a..74fb4ab 100644
--- a/packages/console/src/routeTree.gen.ts
+++ b/packages/console/src/routeTree.gen.ts
@@ -20,7 +20,7 @@ import { Route as AppConnectRouteImport } from './routes/_app/connect'
 import { Route as AppApiKeysRouteImport } from './routes/_app/api-keys'
 import { Route as AppActivityRouteImport } from './routes/_app/activity'
 import { Route as AppSandboxesIndexRouteImport } from './routes/_app/sandboxes/index'
-import { Route as AppSandboxesExternalIdRouteImport } from './routes/_app/sandboxes/$externalId'
+import { Route as AppSandboxesNameRouteImport } from './routes/_app/sandboxes/$name'
 
 const LoginRoute = LoginRouteImport.update({
   id: '/login',
@@ -76,9 +76,9 @@ const AppSandboxesIndexRoute = AppSandboxesIndexRouteImport.update({
   path: '/sandboxes/',
   getParentRoute: () => AppRoute,
 } as any)
-const AppSandboxesExternalIdRoute = AppSandboxesExternalIdRouteImport.update({
-  id: '/sandboxes/$externalId',
-  path: '/sandboxes/$externalId',
+const AppSandboxesNameRoute = AppSandboxesNameRouteImport.update({
+  id: '/sandboxes/$name',
+  path: '/sandboxes/$name',
   getParentRoute: () => AppRoute,
 } as any)
 
@@ -92,7 +92,7 @@ export interface FileRoutesByFullPath {
   '/domains': typeof AppDomainsRoute
   '/settings': typeof AppSettingsRoute
   '/templates': typeof AppTemplatesRoute
-  '/sandboxes/$externalId': typeof AppSandboxesExternalIdRoute
+  '/sandboxes/$name': typeof AppSandboxesNameRoute
   '/sandboxes/': typeof AppSandboxesIndexRoute
 }
 export interface FileRoutesByTo {
@@ -105,7 +105,7 @@ export interface FileRoutesByTo {
   '/settings': typeof AppSettingsRoute
   '/templates': typeof AppTemplatesRoute
   '/': typeof AppIndexRoute
-  '/sandboxes/$externalId': typeof AppSandboxesExternalIdRoute
+  '/sandboxes/$name': typeof AppSandboxesNameRoute
   '/sandboxes': typeof AppSandboxesIndexRoute
 }
 export interface FileRoutesById {
@@ -120,7 +120,7 @@ export interface FileRoutesById {
   '/_app/settings': typeof AppSettingsRoute
   '/_app/templates': typeof AppTemplatesRoute
   '/_app/': typeof AppIndexRoute
-  '/_app/sandboxes/$externalId': typeof AppSandboxesExternalIdRoute
+  '/_app/sandboxes/$name': typeof AppSandboxesNameRoute
   '/_app/sandboxes/': typeof AppSandboxesIndexRoute
 }
 export interface FileRouteTypes {
@@ -135,7 +135,7 @@ export interface FileRouteTypes {
     | '/domains'
     | '/settings'
     | '/templates'
-    | '/sandboxes/$externalId'
+    | '/sandboxes/$name'
     | '/sandboxes/'
   fileRoutesByTo: FileRoutesByTo
   to:
@@ -148,7 +148,7 @@ export interface FileRouteTypes {
     | '/settings'
     | '/templates'
     | '/'
-    | '/sandboxes/$externalId'
+    | '/sandboxes/$name'
     | '/sandboxes'
   id:
     | '__root__'
@@ -162,7 +162,7 @@ export interface FileRouteTypes {
     | '/_app/settings'
     | '/_app/templates'
     | '/_app/'
-    | '/_app/sandboxes/$externalId'
+    | '/_app/sandboxes/$name'
     | '/_app/sandboxes/'
   fileRoutesById: FileRoutesById
 }
@@ -250,11 +250,11 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AppSandboxesIndexRouteImport
       parentRoute: typeof AppRoute
     }
-    '/_app/sandboxes/$externalId': {
-      id: '/_app/sandboxes/$externalId'
-      path: '/sandboxes/$externalId'
-      fullPath: '/sandboxes/$externalId'
-      preLoaderRoute: typeof AppSandboxesExternalIdRouteImport
+    '/_app/sandboxes/$name': {
+      id: '/_app/sandboxes/$name'
+      path: '/sandboxes/$name'
+      fullPath: '/sandboxes/$name'
+      preLoaderRoute: typeof AppSandboxesNameRouteImport
       parentRoute: typeof AppRoute
     }
   }
@@ -269,7 +269,7 @@ interface AppRouteChildren {
   AppSettingsRoute: typeof AppSettingsRoute
   AppTemplatesRoute: typeof AppTemplatesRoute
   AppIndexRoute: typeof AppIndexRoute
-  AppSandboxesExternalIdRoute: typeof AppSandboxesExternalIdRoute
+  AppSandboxesNameRoute: typeof AppSandboxesNameRoute
   AppSandboxesIndexRoute: typeof AppSandboxesIndexRoute
 }
 
@@ -282,7 +282,7 @@ const AppRouteChildren: AppRouteChildren = {
   AppSettingsRoute: AppSettingsRoute,
   AppTemplatesRoute: AppTemplatesRoute,
   AppIndexRoute: AppIndexRoute,
-  AppSandboxesExternalIdRoute: AppSandboxesExternalIdRoute,
+  AppSandboxesNameRoute: AppSandboxesNameRoute,
   AppSandboxesIndexRoute: AppSandboxesIndexRoute,
 }
 
diff --git a/packages/console/src/routes/_app/sandboxes/$externalId.tsx b/packages/console/src/routes/_app/sandboxes/$name.tsx
similarity index 87%
rename from packages/console/src/routes/_app/sandboxes/$externalId.tsx
rename to packages/console/src/routes/_app/sandboxes/$name.tsx
index 6e2092b..928aed2 100644
--- a/packages/console/src/routes/_app/sandboxes/$externalId.tsx
+++ b/packages/console/src/routes/_app/sandboxes/$name.tsx
@@ -6,7 +6,7 @@ import {
 } from '@/features/sandboxes/pages/SandboxDetailPage';
 
 // tab 进 URL:刷新、分享、返回键都停在同一个工作区面板上。
-export const Route = createFileRoute('/_app/sandboxes/$externalId')({
+export const Route = createFileRoute('/_app/sandboxes/$name')({
   validateSearch: (search: Record<string, unknown>): { tab: DetailTab } => ({
     tab: DETAIL_TABS.includes(search.tab as DetailTab)
       ? (search.tab as DetailTab)
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index cf34f7c..8aeebd1 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -73,7 +73,7 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
   it('is idempotent: the same key returns the same sandbox', async () => {
     const first = await client.acquireSandbox('alice');
     const second = await client.acquireSandbox('alice');
-    expect(second.sandbox.sandboxId).toBe(first.sandbox.sandboxId);
+    expect(second.sandbox.id).toBe(first.sandbox.id);
   });
 
   it('passes a policy override through', async () => {
@@ -154,19 +154,19 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
         DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds * 1000,
     );
     await scanOnce(db, executor, locks, frozenAt);
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+    expect(executor.stateOf(created.sandbox.id)).toBe('paused');
 
     const woken = await client.acquireSandbox('dave');
     expect(woken.status).toBe('ready');
-    expect(woken.sandbox.sandboxId).toBe(created.sandbox.sandboxId);
+    expect(woken.sandbox.id).toBe(created.sandbox.id);
     expect(woken.sandbox.state).toBe('active');
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('running');
+    expect(executor.stateOf(created.sandbox.id)).toBe('running');
   });
 
   it('lists sandboxes with their lifecycle states', async () => {
     await client.acquireSandbox('erin');
     const sandboxes = await client.listSandboxes();
-    const erin = sandboxes.find((s) => s.externalId === 'erin');
+    const erin = sandboxes.find((s) => s.name === 'erin');
     expect(erin?.state).toBe('active');
   });
 
@@ -216,7 +216,7 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
             authorization: `Bearer ${TOKEN}`,
             'content-type': 'application/json',
           },
-          body: JSON.stringify({ externalId: 'henry', command: 'sleep 1' }),
+          body: JSON.stringify({ name: 'henry', command: 'sleep 1' }),
         }),
       ).rejects.toThrow(/fetch failed/);
       // The SDK carries its own dispatcher, so the same call sails through.
@@ -232,7 +232,7 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
       {
         name: 'DormiceApiError',
         status: 404,
-        message: expect.stringMatching(/no sandbox for key/),
+        message: expect.stringMatching(/no sandbox named/),
       },
     );
   });
@@ -273,16 +273,16 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
 
   it('rebuilds a sandbox: same id, state stopped, data intact after re-acquire', async () => {
     const created = await client.acquireSandbox('grace');
-    const id = created.sandbox.sandboxId;
+    const id = created.sandbox.id;
     await client.writeFiles('grace', [{ path: 'keep.txt', content: 'body' }]);
 
     const { sandbox } = await client.rebuildSandbox('grace');
-    expect(sandbox.sandboxId).toBe(id);
+    expect(sandbox.id).toBe(id);
     expect(sandbox.state).toBe('stopped');
     expect(executor.stateOf(id)).toBeUndefined();
 
     const again = await client.acquireSandbox('grace');
-    expect(again.sandbox.sandboxId).toBe(id);
+    expect(again.sandbox.id).toBe(id);
     const read = await client.readFile('grace', 'keep.txt');
     expect(new TextDecoder().decode(read.content)).toBe('body');
 
@@ -297,7 +297,7 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
     const { sandbox } = await client.updatePolicy('policy-key', {
       stopAfterSeconds: null,
     });
-    expect(sandbox.sandboxId).toBe(created.sandbox.sandboxId);
+    expect(sandbox.id).toBe(created.sandbox.id);
     expect(sandbox.policy).toEqual({
       ...DEFAULT_LIFECYCLE_POLICY,
       stopAfterSeconds: null,
@@ -315,11 +315,11 @@ describe('Dormice.acquireSandbox over real HTTP', () => {
   it('releases a sandbox and reports idempotently', async () => {
     const created = await client.acquireSandbox('frank');
     expect(await client.destroySandbox('frank')).toEqual({ destroyed: true });
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBeUndefined();
+    expect(executor.stateOf(created.sandbox.id)).toBeUndefined();
     expect(await client.destroySandbox('frank')).toEqual({ destroyed: false });
 
     const again = await client.acquireSandbox('frank');
-    expect(again.sandbox.sandboxId).not.toBe(created.sandbox.sandboxId);
+    expect(again.sandbox.id).not.toBe(created.sandbox.id);
   });
 });
 
@@ -334,7 +334,7 @@ describe('templates over real HTTP', () => {
       template: 'tpl-sdk',
     });
     expect(res.sandbox.template).toBe('tpl-sdk');
-    expect(await executor.imageOf(res.sandbox.sandboxId)).toBe('img-sdk');
+    expect(await executor.imageOf(res.sandbox.id)).toBe('img-sdk');
 
     // In use: removal is refused, naming the key that holds it.
     await expect(client.removeTemplate('tpl-sdk')).rejects.toMatchObject({
@@ -422,8 +422,8 @@ describe('the observability verbs over real HTTP', () => {
     await client.acquireSandbox('fleet-a');
     await client.acquireSandbox('fleet-b');
     const samples = await client.listSandboxMetrics();
-    const mine = samples.filter((s) => s.externalId.startsWith('fleet-'));
-    expect(mine.map((s) => s.externalId).sort()).toEqual([
+    const mine = samples.filter((s) => s.sandboxName.startsWith('fleet-'));
+    expect(mine.map((s) => s.sandboxName).sort()).toEqual([
       'fleet-a',
       'fleet-b',
     ]);
@@ -434,14 +434,14 @@ describe('the observability verbs over real HTTP', () => {
     await client.destroySandbox('fleet-b');
     // Released means gone from the measurable set, not null-stuffed.
     const after = await client.listSandboxMetrics();
-    expect(after.filter((s) => s.externalId.startsWith('fleet-'))).toEqual([]);
+    expect(after.filter((s) => s.sandboxName.startsWith('fleet-'))).toEqual([]);
   });
 
   it('listActivity tells the story just written, newest first', async () => {
     await client.acquireSandbox('story-sdk');
     await client.destroySandbox('story-sdk');
     const log = await client.listActivity({ limit: 10 });
-    const mine = log.filter((e) => e.externalId === 'story-sdk');
+    const mine = log.filter((e) => e.sandboxName === 'story-sdk');
     expect(mine.map((e) => e.kind)).toEqual(['destroyed', 'created']);
   });
 });
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 44e65fd..e90a133 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -149,17 +149,19 @@ export class Dormice {
   }
 
   /**
-   * acquire(externalId): the platform's single entry point, idempotent — the
-   * same key always comes back to the same sandbox, whatever state it was
-   * in. A `restoring` status means the sandbox is being pulled back from
+   * acquire(name): the platform's single entry point, idempotent — the
+   * same name always comes back to the same sandbox, whatever state it was
+   * in (names converge, they never error as duplicates); the response's
+   * `created` flag says whether this call minted the sandbox or found it.
+   * A `restoring` status means the sandbox is being pulled back from
    * the archive; poll until it flips to `ready`.
    */
   async acquireSandbox(
-    externalId: string,
+    name: string,
     options?: AcquireSandboxOptions,
   ): Promise<AcquireResponse> {
     const data = await this.rpc('acquireSandbox', {
-      externalId,
+      name,
       policy: options?.policy,
       template: options?.template,
       metadata: options?.metadata,
@@ -193,10 +195,8 @@ export class Dormice {
    * and with no running container (stopped, archived, restoring) the
    * sample is null. For the past, see getSandboxMetricsHistory.
    */
-  async getSandboxMetrics(
-    externalId: string,
-  ): Promise<SandboxMetricsSample | null> {
-    const data = await this.rpc('getSandboxMetrics', { externalId });
+  async getSandboxMetrics(name: string): Promise<SandboxMetricsSample | null> {
+    const data = await this.rpc('getSandboxMetrics', { name });
     return getSandboxMetricsResponseSchema.parse(data).sample;
   }
 
@@ -209,11 +209,11 @@ export class Dormice {
    * for shows the gap.
    */
   async getSandboxMetricsHistory(
-    externalId: string,
+    name: string,
     options?: { start?: string; end?: string },
   ): Promise<GetSandboxMetricsHistoryResponse> {
     const data = await this.rpc('getSandboxMetricsHistory', {
-      externalId,
+      name,
       start: options?.start,
       end: options?.end,
     });
@@ -360,8 +360,8 @@ export class Dormice {
    * or exec wakes it, paying one cold start. Unknown key: 404 — rebuild is
    * not a creator.
    */
-  async rebuildSandbox(externalId: string): Promise<RebuildSandboxResponse> {
-    const data = await this.rpc('rebuildSandbox', { externalId });
+  async rebuildSandbox(name: string): Promise<RebuildSandboxResponse> {
+    const data = await this.rpc('rebuildSandbox', { name });
     return rebuildSandboxResponseSchema.parse(data);
   }
 
@@ -374,10 +374,10 @@ export class Dormice {
    * the idle clock is not refreshed. Unknown key: 404 — not a creator.
    */
   async updatePolicy(
-    externalId: string,
+    name: string,
     policy: LifecyclePolicyOverride,
   ): Promise<UpdatePolicyResponse> {
-    const data = await this.rpc('updatePolicy', { externalId, policy });
+    const data = await this.rpc('updatePolicy', { name, policy });
     return updatePolicyResponseSchema.parse(data);
   }
 
@@ -387,20 +387,20 @@ export class Dormice {
    * idle clock is not refreshed. Unknown key: 404 — not a creator.
    */
   async updateMetadata(
-    externalId: string,
+    name: string,
     metadata: SandboxMetadata,
   ): Promise<UpdateMetadataResponse> {
-    const data = await this.rpc('updateMetadata', { externalId, metadata });
+    const data = await this.rpc('updateMetadata', { name, metadata });
     return updateMetadataResponseSchema.parse(data);
   }
 
   /**
-   * Destroys the sandbox behind an external id — container and disk are gone
+   * Destroys the sandbox behind a name — container and disk are gone
    * for good. Idempotent like acquire: a key that has no sandbox is not an
    * error, the response just says `destroyed: false`.
    */
-  async destroySandbox(externalId: string): Promise<DestroySandboxResponse> {
-    const data = await this.rpc('destroySandbox', { externalId });
+  async destroySandbox(name: string): Promise<DestroySandboxResponse> {
+    const data = await this.rpc('destroySandbox', { name });
     return destroySandboxResponseSchema.parse(data);
   }
 
@@ -462,14 +462,14 @@ export class Dormice {
   }
 
   /**
-   * Runs a shell command inside the sandbox behind an external id and returns
+   * Runs a shell command inside the sandbox behind a name and returns
    * the buffered result: honest exit code (a nonzero exit is a result, not
    * an error), stdout/stderr capped at 1 MiB per stream. Wakes a cold
    * sandbox first, and counts as activity for the whole run — the idle
    * scanner never freezes a sandbox mid-command.
    */
   async execCommand(
-    externalId: string,
+    name: string,
     command: string,
     options?: ExecCommandOptions,
   ): Promise<ExecCommandResponse> {
@@ -481,7 +481,7 @@ export class Dormice {
     const data = await this.rpc(
       'execCommand',
       {
-        externalId,
+        name,
         command,
         timeoutSeconds,
         cwd: options?.cwd,
@@ -494,17 +494,17 @@ export class Dormice {
   }
 
   /**
-   * Writes a batch of files into the sandbox behind an external id, waking a
+   * Writes a batch of files into the sandbox behind a name, waking a
    * cold sandbox first. Parents are created, existing files overwritten.
    * Per-file cap is 16 MiB — content travels as base64 inside JSON; a big
    * batch on a slow link may need a larger client `timeoutMs`.
    */
   async writeFiles(
-    externalId: string,
+    name: string,
     files: FileToWrite[],
   ): Promise<WriteFilesResponse> {
     const data = await this.rpc('writeFiles', {
-      externalId,
+      name,
       files: files.map((file) => ({
         path: file.path,
         contentBase64: Buffer.from(
@@ -522,12 +522,12 @@ export class Dormice {
    * same rules (parents created, existing file overwritten, 16 MiB cap).
    */
   async writeFile(
-    externalId: string,
+    name: string,
     path: string,
     content: string | Uint8Array,
   ): Promise<WriteFileResponse> {
     const data = await this.rpc('writeFile', {
-      externalId,
+      name,
       path,
       contentBase64: Buffer.from(
         typeof content === 'string'
@@ -542,8 +542,8 @@ export class Dormice {
    * Reads one file's bytes out of the sandbox. A file over the 16 MiB cap
    * is refused by the daemon (413), never truncated.
    */
-  async readFile(externalId: string, path: string): Promise<ReadFileResult> {
-    const data = await this.rpc('readFile', { externalId, path });
+  async readFile(name: string, path: string): Promise<ReadFileResult> {
+    const data = await this.rpc('readFile', { name, path });
     const parsed = readFileResponseSchema.parse(data);
     return {
       path: parsed.path,
@@ -557,11 +557,8 @@ export class Dormice {
    * file by file. Files come back in request order; the batch total is
    * capped at 48 MiB by the daemon (413).
    */
-  async readFiles(
-    externalId: string,
-    paths: string[],
-  ): Promise<ReadFileResult[]> {
-    const data = await this.rpc('readFiles', { externalId, paths });
+  async readFiles(name: string, paths: string[]): Promise<ReadFileResult[]> {
+    const data = await this.rpc('readFiles', { name, paths });
     return readFilesResponseSchema.parse(data).files.map((file) => ({
       path: file.path,
       content: new Uint8Array(Buffer.from(file.contentBase64, 'base64')),
diff --git a/packages/server/drizzle/0011_sandbox-name-id.sql b/packages/server/drizzle/0011_sandbox-name-id.sql
new file mode 100644
index 0000000..55b4f37
--- /dev/null
+++ b/packages/server/drizzle/0011_sandbox-name-id.sql
@@ -0,0 +1,5 @@
+ALTER TABLE `sandboxes` RENAME COLUMN `sandbox_id` TO `id`;--> statement-breakpoint
+ALTER TABLE `sandboxes` RENAME COLUMN `external_id` TO `name`;--> statement-breakpoint
+DROP INDEX `sandboxes_external_id_unique`;--> statement-breakpoint
+CREATE UNIQUE INDEX `sandboxes_name_unique` ON `sandboxes` (`name`);--> statement-breakpoint
+ALTER TABLE `activity` RENAME COLUMN `external_id` TO `sandbox_name`;
diff --git a/packages/server/drizzle/meta/0011_snapshot.json b/packages/server/drizzle/meta/0011_snapshot.json
new file mode 100644
index 0000000..a92af2f
--- /dev/null
+++ b/packages/server/drizzle/meta/0011_snapshot.json
@@ -0,0 +1,538 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "3de8f547-6677-4f7b-a4fb-03d8e45c2c88",
+  "prevId": "e5b578b5-b58c-4285-b78a-6fd10040e2e7",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_name": {
+          "name": "sandbox_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "api_keys": {
+      "name": "api_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "prefix": {
+          "name": "prefix",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "api_keys_key_hash_unique": {
+          "name": "api_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        },
+        "api_keys_active_name_idx": {
+          "name": "api_keys_active_name_idx",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true,
+          "where": "\"api_keys\".\"revoked_at\" IS NULL"
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "daemon_secrets": {
+      "name": "daemon_secrets",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "envd_signing_secret": {
+          "name": "envd_signing_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "fleet_snapshots": {
+      "name": "fleet_snapshots",
+      "columns": {
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active": {
+          "name": "active",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "frozen": {
+          "name": "frozen",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stopped": {
+          "name": "stopped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archived": {
+          "name": "archived",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "restoring": {
+          "name": "restoring",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "total": {
+          "name": "total",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandbox_metrics_samples": {
+      "name": "sandbox_metrics_samples",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_count": {
+          "name": "cpu_count",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_used_pct": {
+          "name": "cpu_used_pct",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_used_bytes": {
+          "name": "mem_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_total_bytes": {
+          "name": "mem_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_cache_bytes": {
+          "name": "mem_cache_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_used_bytes": {
+          "name": "disk_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_total_bytes": {
+          "name": "disk_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "sandbox_metrics_samples_sandbox_at_idx": {
+          "name": "sandbox_metrics_samples_sandbox_at_idx",
+          "columns": [
+            "sandbox_id",
+            "at"
+          ],
+          "isUnique": false
+        },
+        "sandbox_metrics_samples_at_idx": {
+          "name": "sandbox_metrics_samples_at_idx",
+          "columns": [
+            "at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_name_unique": {
+          "name": "sandboxes_name_unique",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index a6296eb..af19379 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -78,6 +78,13 @@
       "when": 1784146840196,
       "tag": "0010_template-updated-at",
       "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "6",
+      "when": 1784149139146,
+      "tag": "0011_sandbox-name-id",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index 1438f18..bc5791f 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -78,14 +78,14 @@ describe('auth', () => {
   });
 
   it('rejects API calls without a token', async () => {
-    const res = await acquire(testApp().app, { externalId: 'u' }, {});
+    const res = await acquire(testApp().app, { name: 'u' }, {});
     expect(res.statusCode).toBe(401);
   });
 
   it('rejects API calls with a wrong token', async () => {
     const res = await acquire(
       testApp().app,
-      { externalId: 'u' },
+      { name: 'u' },
       { authorization: 'Bearer wrong-token-wrong-token-wrong-token' },
     );
     expect(res.statusCode).toBe(401);
@@ -95,35 +95,35 @@ describe('auth', () => {
 describe('POST /acquireSandbox', () => {
   it('creates a sandbox on first acquire, with default policy', async () => {
     const { app, executor } = testApp();
-    const res = await acquire(app, { externalId: 'alice' });
+    const res = await acquire(app, { name: 'alice' });
     expect(res.statusCode).toBe(200);
     const body = res.json();
     expect(body.status).toBe('ready');
     expect(body.sandbox.state).toBe('active');
-    expect(body.sandbox.externalId).toBe('alice');
+    expect(body.sandbox.name).toBe('alice');
     expect(body.sandbox.policy).toEqual(DEFAULT_LIFECYCLE_POLICY);
     expect(body.sandbox.endpoint).toBe('http://127.0.0.1:3676');
     // The ledger and reality agree: the container is actually running.
-    expect(executor.stateOf(body.sandbox.sandboxId)).toBe('running');
+    expect(executor.stateOf(body.sandbox.id)).toBe('running');
   });
 
   it('is idempotent: same external id returns the same sandbox', async () => {
     const { app } = testApp();
-    const first = (await acquire(app, { externalId: 'alice' })).json();
-    const second = (await acquire(app, { externalId: 'alice' })).json();
-    expect(second.sandbox.sandboxId).toBe(first.sandbox.sandboxId);
+    const first = (await acquire(app, { name: 'alice' })).json();
+    const second = (await acquire(app, { name: 'alice' })).json();
+    expect(second.sandbox.id).toBe(first.sandbox.id);
   });
 
   it('gives different external ids different sandboxes', async () => {
     const { app } = testApp();
-    const alice = (await acquire(app, { externalId: 'alice' })).json();
-    const bob = (await acquire(app, { externalId: 'bob' })).json();
-    expect(bob.sandbox.sandboxId).not.toBe(alice.sandbox.sandboxId);
+    const alice = (await acquire(app, { name: 'alice' })).json();
+    const bob = (await acquire(app, { name: 'bob' })).json();
+    expect(bob.sandbox.id).not.toBe(alice.sandbox.id);
   });
 
   it('stores a policy override, including explicit null for archive', async () => {
     const res = await acquire(testApp().app, {
-      externalId: 'alice',
+      name: 'alice',
       policy: { freezeAfterSeconds: 60, archiveAfterSeconds: null },
     });
     expect(res.json().sandbox.policy).toEqual({
@@ -135,7 +135,7 @@ describe('POST /acquireSandbox', () => {
 
   it('rejects an override whose merged result breaks the ordering rule', async () => {
     const res = await acquire(testApp().app, {
-      externalId: 'alice',
+      name: 'alice',
       policy: { freezeAfterSeconds: 61, stopAfterSeconds: 60 },
     });
     expect(res.statusCode).toBe(400);
@@ -146,7 +146,7 @@ describe('POST /acquireSandbox', () => {
     // Without an archiver a stored archive threshold would be a standing
     // lie; the daemon refuses rather than nodding along.
     const res = await acquire(testApp().app, {
-      externalId: 'alice',
+      name: 'alice',
       policy: { archiveAfterSeconds: 3600 },
     });
     expect(res.statusCode).toBe(400);
@@ -162,7 +162,7 @@ describe('POST /acquireSandbox', () => {
 
   it('stores stopAfterSeconds: null — the never-stop resident policy', async () => {
     const res = await acquire(testApp().app, {
-      externalId: 'resident',
+      name: 'resident',
       policy: { stopAfterSeconds: null },
     });
     expect(res.statusCode).toBe(200);
@@ -171,11 +171,11 @@ describe('POST /acquireSandbox', () => {
 
   it('rejects an invalid override even when the sandbox already exists', async () => {
     const { app } = testApp();
-    await acquire(app, { externalId: 'alice' });
+    await acquire(app, { name: 'alice' });
     // The override would not apply (the sandbox exists), but it is still
     // the caller's mistake — a 400, never a silent ignore.
     const res = await acquire(app, {
-      externalId: 'alice',
+      name: 'alice',
       policy: { archiveAfterSeconds: 1 },
     });
     expect(res.statusCode).toBe(400);
@@ -184,33 +184,33 @@ describe('POST /acquireSandbox', () => {
   it('stores metadata at creation and echoes {} when none was given', async () => {
     const { app } = testApp();
     const labeled = await acquire(app, {
-      externalId: 'alice',
+      name: 'alice',
       metadata: { app: 'crawler', env: 'prod' },
     });
     expect(labeled.json().sandbox.metadata).toEqual({
       app: 'crawler',
       env: 'prod',
     });
-    const bare = await acquire(app, { externalId: 'bob' });
+    const bare = await acquire(app, { name: 'bob' });
     expect(bare.json().sandbox.metadata).toEqual({});
   });
 
   it('keeps stored metadata on the idempotent path, but a malformed value is still a 400', async () => {
     const { app } = testApp();
     await acquire(app, {
-      externalId: 'alice',
+      name: 'alice',
       metadata: { app: 'crawler' },
     });
     // Same rule as policy/template: creation-time only, never an update.
     const again = await acquire(app, {
-      externalId: 'alice',
+      name: 'alice',
       metadata: { app: 'other' },
     });
     expect(again.json().sandbox.metadata).toEqual({ app: 'crawler' });
     // Non-string values are outside the label contract — the caller's
     // mistake even though it would not have applied.
     const bad = await acquire(app, {
-      externalId: 'alice',
+      name: 'alice',
       metadata: { app: 42 },
     });
     expect(bad.statusCode).toBe(400);
@@ -236,17 +236,17 @@ describe('error shape', () => {
 describe('sandbox capacity', () => {
   it('caps creation at DORMICE_MAX_SANDBOXES with an honest 429', async () => {
     const { app } = testApp(undefined, { DORMICE_MAX_SANDBOXES: '1' });
-    expect((await acquire(app, { externalId: 'alice' })).statusCode).toBe(200);
+    expect((await acquire(app, { name: 'alice' })).statusCode).toBe(200);
 
-    const capped = await acquire(app, { externalId: 'bob' });
+    const capped = await acquire(app, { name: 'bob' });
     expect(capped.statusCode).toBe(429);
     expect(capped.json().message).toMatch(/DORMICE_MAX_SANDBOXES/);
 
     // Existing sandboxes always wake — the cap only guards creation.
-    expect((await acquire(app, { externalId: 'alice' })).statusCode).toBe(200);
+    expect((await acquire(app, { name: 'alice' })).statusCode).toBe(200);
     // Releasing frees the slot.
-    await rpc(app, '/destroySandbox', { externalId: 'alice' });
-    expect((await acquire(app, { externalId: 'bob' })).statusCode).toBe(200);
+    await rpc(app, '/destroySandbox', { name: 'alice' });
+    expect((await acquire(app, { name: 'bob' })).statusCode).toBe(200);
   });
 });
 
@@ -264,14 +264,12 @@ describe('concurrent acquires', () => {
     const executor = new SlowCreateExecutor();
     const { app } = testApp(executor);
     const [first, second] = await Promise.all([
-      acquire(app, { externalId: 'alice' }),
-      acquire(app, { externalId: 'alice' }),
+      acquire(app, { name: 'alice' }),
+      acquire(app, { name: 'alice' }),
     ]);
     expect(first.statusCode).toBe(200);
     expect(second.statusCode).toBe(200);
-    expect(second.json().sandbox.sandboxId).toBe(
-      first.json().sandbox.sandboxId,
-    );
+    expect(second.json().sandbox.id).toBe(first.json().sandbox.id);
     // Exactly one container: the second request queued behind the first's
     // slot and found its row instead of racing it and leaking an orphan.
     expect((await executor.listContainers()).size).toBe(1);
@@ -281,12 +279,10 @@ describe('concurrent acquires', () => {
     const executor = new SlowCreateExecutor();
     const { app } = testApp(executor);
     const [alice, bob] = await Promise.all([
-      acquire(app, { externalId: 'alice' }),
-      acquire(app, { externalId: 'bob' }),
+      acquire(app, { name: 'alice' }),
+      acquire(app, { name: 'bob' }),
     ]);
-    expect(bob.json().sandbox.sandboxId).not.toBe(
-      alice.json().sandbox.sandboxId,
-    );
+    expect(bob.json().sandbox.id).not.toBe(alice.json().sandbox.id);
     expect((await executor.listContainers()).size).toBe(2);
   });
 });
@@ -294,8 +290,8 @@ describe('concurrent acquires', () => {
 describe('acquire wakes cold sandboxes', () => {
   it('unfreezes a frozen sandbox back to active', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
-    const id = created.sandbox.sandboxId;
+    const created = (await acquire(app, { name: 'alice' })).json();
+    const id = created.sandbox.id;
 
     await scanOnce(
       db,
@@ -308,8 +304,8 @@ describe('acquire wakes cold sandboxes', () => {
     );
     expect(executor.stateOf(id)).toBe('paused');
 
-    const woken = (await acquire(app, { externalId: 'alice' })).json();
-    expect(woken.sandbox.sandboxId).toBe(id);
+    const woken = (await acquire(app, { name: 'alice' })).json();
+    expect(woken.sandbox.id).toBe(id);
     expect(woken.sandbox.state).toBe('active');
     expect(executor.stateOf(id)).toBe('running');
   });
@@ -318,26 +314,26 @@ describe('acquire wakes cold sandboxes', () => {
     const { app, db, executor, locks } = testApp();
     const created = (
       await acquire(app, {
-        externalId: 'alice',
+        name: 'alice',
         policy: { freezeAfterSeconds: 60, stopAfterSeconds: 120 },
       })
     ).json();
-    const id = created.sandbox.sandboxId;
+    const id = created.sandbox.id;
 
     const lastActiveAt = created.sandbox.lastActiveAt;
     await scanOnce(db, executor, locks, after(lastActiveAt, 60));
     await scanOnce(db, executor, locks, after(lastActiveAt, 120));
     expect(executor.stateOf(id)).toBe('stopped');
 
-    const woken = (await acquire(app, { externalId: 'alice' })).json();
-    expect(woken.sandbox.sandboxId).toBe(id);
+    const woken = (await acquire(app, { name: 'alice' })).json();
+    expect(woken.sandbox.id).toBe(id);
     expect(woken.sandbox.state).toBe('active');
     expect(executor.stateOf(id)).toBe('running');
   });
 
   it('waking refreshes the idle clock', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
+    const created = (await acquire(app, { name: 'alice' })).json();
 
     await scanOnce(
       db,
@@ -350,7 +346,7 @@ describe('acquire wakes cold sandboxes', () => {
     );
     // touch() stamps real wall-clock time, so give it a distinct millisecond.
     await new Promise((resolve) => setTimeout(resolve, 5));
-    const woken = (await acquire(app, { externalId: 'alice' })).json();
+    const woken = (await acquire(app, { name: 'alice' })).json();
     expect(Date.parse(woken.sandbox.lastActiveAt)).toBeGreaterThan(
       Date.parse(created.sandbox.lastActiveAt),
     );
@@ -369,8 +365,8 @@ describe('scanner vs acquire on the same key', () => {
   it('an acquire during a freeze waits its turn and gets a running sandbox', async () => {
     const executor = new SlowFreezeExecutor();
     const { app, db, locks } = testApp(executor);
-    const created = (await acquire(app, { externalId: 'alice' })).json();
-    const id = created.sandbox.sandboxId;
+    const created = (await acquire(app, { name: 'alice' })).json();
+    const id = created.sandbox.id;
 
     // The scanner decides to freeze; the acquire lands mid-freeze.
     // Unserialized, the acquire read `active` from the ledger, answered
@@ -385,7 +381,7 @@ describe('scanner vs acquire on the same key', () => {
         DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
       ),
     );
-    const woken = acquire(app, { externalId: 'alice' });
+    const woken = acquire(app, { name: 'alice' });
     const [sweepResult, res] = await Promise.all([sweep, woken]);
 
     expect(sweepResult.frozen).toBe(1);
@@ -407,11 +403,11 @@ describe('concurrent releases of the same key', () => {
   it('one reports released, the other reports the goal state — no 500', async () => {
     const executor = new SlowDestroyExecutor();
     const { app } = testApp(executor);
-    await acquire(app, { externalId: 'alice' });
+    await acquire(app, { name: 'alice' });
 
     const [a, b] = await Promise.all([
-      rpc(app, '/destroySandbox', { externalId: 'alice' }),
-      rpc(app, '/destroySandbox', { externalId: 'alice' }),
+      rpc(app, '/destroySandbox', { name: 'alice' }),
+      rpc(app, '/destroySandbox', { name: 'alice' }),
     ]);
     expect(a.statusCode).toBe(200);
     expect(b.statusCode).toBe(200);
@@ -423,20 +419,20 @@ describe('concurrent releases of the same key', () => {
 describe('acquire after reality moved behind the ledger', () => {
   it('returns a fresh sandbox when container and disk are truly gone', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
+    const created = (await acquire(app, { name: 'alice' })).json();
     // Container and disk wiped behind the daemon's back — the end state of
     // a release that crashed after the executor's work, before the ledger's.
-    await executor.destroy(created.sandbox.sandboxId);
+    await executor.destroy(created.sandbox.id);
 
     // The heartbeat reconciles before every scan; the dead row is deleted
     // within one interval, freeing the key.
     await reconcile(db, executor, locks, new Set());
 
-    const again = (await acquire(app, { externalId: 'alice' })).json();
+    const again = (await acquire(app, { name: 'alice' })).json();
     expect(again.status).toBe('ready');
-    expect(again.sandbox.sandboxId).not.toBe(created.sandbox.sandboxId);
+    expect(again.sandbox.id).not.toBe(created.sandbox.id);
     // This time the sandbox is real.
-    expect(executor.stateOf(again.sandbox.sandboxId)).toBe('running');
+    expect(executor.stateOf(again.sandbox.id)).toBe('running');
   });
 
   it('returns the same sandbox after its exited container was pruned', async () => {
@@ -448,11 +444,11 @@ describe('acquire after reality moved behind the ledger', () => {
     const { app, db, executor, locks } = testApp();
     const created = (
       await acquire(app, {
-        externalId: 'alice',
+        name: 'alice',
         policy: { freezeAfterSeconds: 60, stopAfterSeconds: 120 },
       })
     ).json();
-    const id = created.sandbox.sandboxId;
+    const id = created.sandbox.id;
     const lastActiveAt = created.sandbox.lastActiveAt;
     await scanOnce(db, executor, locks, after(lastActiveAt, 60));
     await scanOnce(db, executor, locks, after(lastActiveAt, 120));
@@ -460,8 +456,8 @@ describe('acquire after reality moved behind the ledger', () => {
 
     await reconcile(db, executor, locks, new Set());
 
-    const again = (await acquire(app, { externalId: 'alice' })).json();
-    expect(again.sandbox.sandboxId).toBe(id);
+    const again = (await acquire(app, { name: 'alice' })).json();
+    expect(again.sandbox.id).toBe(id);
     expect(again.sandbox.state).toBe('active');
     expect(executor.stateOf(id)).toBe('running');
   });
@@ -470,10 +466,10 @@ describe('acquire after reality moved behind the ledger', () => {
 describe('POST /execCommand', () => {
   it('runs a command in the sandbox and returns the buffered result', async () => {
     const { app } = testApp();
-    await acquire(app, { externalId: 'alice' });
+    await acquire(app, { name: 'alice' });
     // No timeoutSeconds sent: the schema default fills it in server-side.
     const res = await rpc(app, '/execCommand', {
-      externalId: 'alice',
+      name: 'alice',
       command: 'echo hi',
     });
     expect(res.statusCode).toBe(200);
@@ -488,17 +484,17 @@ describe('POST /execCommand', () => {
 
   it('answers an unknown key with a 404, never a silent create', async () => {
     const res = await rpc(testApp().app, '/execCommand', {
-      externalId: 'nobody',
+      name: 'nobody',
       command: 'echo hi',
     });
     expect(res.statusCode).toBe(404);
-    expect(res.json().message).toMatch(/no sandbox for key/);
+    expect(res.json().message).toMatch(/no sandbox named/);
   });
 
   it('wakes a frozen sandbox before running the command', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
-    const id = created.sandbox.sandboxId;
+    const created = (await acquire(app, { name: 'alice' })).json();
+    const id = created.sandbox.id;
     await scanOnce(
       db,
       executor,
@@ -513,7 +509,7 @@ describe('POST /execCommand', () => {
     // A paused container cannot even receive an exec (Docker refuses); the
     // route must wake it first, exactly like acquire does.
     const res = await rpc(app, '/execCommand', {
-      externalId: 'alice',
+      name: 'alice',
       command: 'echo woke',
     });
     expect(res.statusCode).toBe(200);
@@ -527,18 +523,18 @@ describe('POST /execCommand', () => {
     const { app, db, executor, locks } = testApp();
     const created = (
       await acquire(app, {
-        externalId: 'alice',
+        name: 'alice',
         policy: { freezeAfterSeconds: 1 },
       })
     ).json();
-    const id = created.sandbox.sandboxId;
+    const id = created.sandbox.id;
 
     // freeze:1 → heartbeat every 500ms. Sweep at real 700ms with a clock
     // reading 1.2s past the original lastActiveAt: exec's own start-of-exec
     // touch (~0ms) is stale against that clock — only the 500ms heartbeat
     // touch keeps the idle under the threshold.
     const execPromise = rpc(app, '/execCommand', {
-      externalId: 'alice',
+      name: 'alice',
       command: 'sleep 1',
     });
     await new Promise((resolve) => setTimeout(resolve, 700));
@@ -563,17 +559,17 @@ describe('POST /execCommand', () => {
     // Reverse-verified: without the heartbeat's try/catch this crashes.
     const { app } = testApp();
     await acquire(app, {
-      externalId: 'alice',
+      name: 'alice',
       policy: { freezeAfterSeconds: 1 },
     });
 
     const execPromise = rpc(app, '/execCommand', {
-      externalId: 'alice',
+      name: 'alice',
       command: 'sleep 1',
     });
     await new Promise((resolve) => setTimeout(resolve, 100));
     const releaseRes = await rpc(app, '/destroySandbox', {
-      externalId: 'alice',
+      name: 'alice',
     });
     expect(releaseRes.json()).toEqual({ destroyed: true });
 
@@ -589,15 +585,15 @@ describe('POST /execCommand', () => {
 
   it('rejects malformed requests with the protocol {message} shape', async () => {
     const { app } = testApp();
-    await acquire(app, { externalId: 'alice' });
+    await acquire(app, { name: 'alice' });
     const bad = [
-      { externalId: 'alice' }, // no command
-      { externalId: 'alice', command: '' },
-      { externalId: 'alice', command: 'echo hi', timeoutSeconds: 0 },
-      { externalId: 'alice', command: 'echo hi', timeoutSeconds: -5 },
-      { externalId: 'alice', command: 'echo hi', timeoutSeconds: 1.5 },
-      { externalId: 'alice', command: 'echo hi', timeoutSeconds: 86_401 },
-      { externalId: 'alice', command: 'echo hi', env: { PATH: 42 } },
+      { name: 'alice' }, // no command
+      { name: 'alice', command: '' },
+      { name: 'alice', command: 'echo hi', timeoutSeconds: 0 },
+      { name: 'alice', command: 'echo hi', timeoutSeconds: -5 },
+      { name: 'alice', command: 'echo hi', timeoutSeconds: 1.5 },
+      { name: 'alice', command: 'echo hi', timeoutSeconds: 86_401 },
+      { name: 'alice', command: 'echo hi', env: { PATH: 42 } },
     ];
     for (const payload of bad) {
       const res = await rpc(app, '/execCommand', payload);
@@ -610,13 +606,13 @@ describe('POST /execCommand', () => {
 describe('POST /writeFiles and /readFile', () => {
   it('round-trips content through base64, resolving paths to absolute', async () => {
     const { app } = testApp();
-    await acquire(app, { externalId: 'alice' });
+    await acquire(app, { name: 'alice' });
     // Every byte value: any utf8 coercion or base64 sloppiness breaks this.
     const bytes = Buffer.alloc(256);
     for (let i = 0; i < 256; i++) bytes[i] = i;
 
     const write = await rpc(app, '/writeFiles', {
-      externalId: 'alice',
+      name: 'alice',
       files: [
         {
           path: 'notes.txt',
@@ -637,7 +633,7 @@ describe('POST /writeFiles and /readFile', () => {
     });
 
     const read = await rpc(app, '/readFile', {
-      externalId: 'alice',
+      name: 'alice',
       path: 'blob.bin',
     });
     expect(read.statusCode).toBe(200);
@@ -650,21 +646,21 @@ describe('POST /writeFiles and /readFile', () => {
   it('answers an unknown key with a 404 on both verbs, never a silent create', async () => {
     const { app } = testApp();
     const write = await rpc(app, '/writeFiles', {
-      externalId: 'nobody',
+      name: 'nobody',
       files: [{ path: 'x', contentBase64: 'eA==' }],
     });
     expect(write.statusCode).toBe(404);
     const read = await rpc(app, '/readFile', {
-      externalId: 'nobody',
+      name: 'nobody',
       path: 'x',
     });
     expect(read.statusCode).toBe(404);
-    expect(read.json().message).toMatch(/no sandbox for key/);
+    expect(read.json().message).toMatch(/no sandbox named/);
   });
 
   it('wakes a frozen sandbox before touching files', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
+    const created = (await acquire(app, { name: 'alice' })).json();
     await scanOnce(
       db,
       executor,
@@ -674,29 +670,29 @@ describe('POST /writeFiles and /readFile', () => {
         DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
       ),
     );
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+    expect(executor.stateOf(created.sandbox.id)).toBe('paused');
 
     const res = await rpc(app, '/writeFiles', {
-      externalId: 'alice',
+      name: 'alice',
       files: [{ path: 'woke.txt', contentBase64: 'eA==' }],
     });
     expect(res.statusCode).toBe(200);
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('running');
+    expect(executor.stateOf(created.sandbox.id)).toBe('running');
   });
 
   it('maps the typed file errors onto 404, 400 and 413', async () => {
     const { app, executor } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
+    const created = (await acquire(app, { name: 'alice' })).json();
 
     const missing = await rpc(app, '/readFile', {
-      externalId: 'alice',
+      name: 'alice',
       path: 'absent.txt',
     });
     expect(missing.statusCode).toBe(404);
     expect(missing.json().message).toBe('no such file: /home/user/absent.txt');
 
     const directory = await rpc(app, '/readFile', {
-      externalId: 'alice',
+      name: 'alice',
       path: '/home/user',
     });
     expect(directory.statusCode).toBe(400);
@@ -706,11 +702,11 @@ describe('POST /writeFiles and /readFile', () => {
     // uncapped (the schema is the write-cap adjudicator), which is what
     // lets an over-limit file exist to be read.
     const size = FILE_SIZE_LIMIT_BYTES + 1;
-    await executor.writeFiles(created.sandbox.sandboxId, [
+    await executor.writeFiles(created.sandbox.id, [
       { path: 'big.bin', content: Buffer.alloc(size) },
     ]);
     const big = await rpc(app, '/readFile', {
-      externalId: 'alice',
+      name: 'alice',
       path: 'big.bin',
     });
     expect(big.statusCode).toBe(413);
@@ -724,9 +720,9 @@ describe('POST /writeFiles and /readFile', () => {
     // bodyLimit and failing the per-file refine proves both gates sit where
     // they should: total bytes at the body limit, per-file size in the schema.
     const { app } = testApp();
-    await acquire(app, { externalId: 'alice' });
+    await acquire(app, { name: 'alice' });
     const res = await rpc(app, '/writeFiles', {
-      externalId: 'alice',
+      name: 'alice',
       files: [
         {
           path: 'big.bin',
@@ -742,30 +738,30 @@ describe('POST /writeFiles and /readFile', () => {
 
   it('rejects malformed requests with the protocol {message} shape', async () => {
     const { app } = testApp();
-    await acquire(app, { externalId: 'alice' });
+    await acquire(app, { name: 'alice' });
     const bad = [
-      ['/writeFiles', { externalId: 'alice', files: [] }],
-      ['/writeFiles', { externalId: 'alice' }],
+      ['/writeFiles', { name: 'alice', files: [] }],
+      ['/writeFiles', { name: 'alice' }],
       [
         '/writeFiles',
-        { externalId: 'alice', files: [{ path: '', contentBase64: 'eA==' }] },
+        { name: 'alice', files: [{ path: '', contentBase64: 'eA==' }] },
       ],
       [
         '/writeFiles',
         {
-          externalId: 'alice',
+          name: 'alice',
           files: [{ path: 'a\0b', contentBase64: 'eA==' }],
         },
       ],
       [
         '/writeFiles',
         {
-          externalId: 'alice',
+          name: 'alice',
           files: [{ path: 'x', contentBase64: '!!not-b64' }],
         },
       ],
-      ['/readFile', { externalId: 'alice' }],
-      ['/readFile', { externalId: 'alice', path: '' }],
+      ['/readFile', { name: 'alice' }],
+      ['/readFile', { name: 'alice', path: '' }],
     ] as const;
     for (const [url, payload] of bad) {
       const res = await rpc(app, url, payload as Record<string, unknown>);
@@ -790,11 +786,11 @@ describe('POST /listSandboxes', () => {
     // Give alice a shorter freeze threshold so one sweep freezes only her.
     const alice = (
       await acquire(app, {
-        externalId: 'alice',
+        name: 'alice',
         policy: { freezeAfterSeconds: 60 },
       })
     ).json();
-    await acquire(app, { externalId: 'bob' });
+    await acquire(app, { name: 'bob' });
     await scanOnce(db, executor, locks, after(alice.sandbox.lastActiveAt, 60));
 
     const res = await rpc(app, '/listSandboxes');
@@ -802,8 +798,8 @@ describe('POST /listSandboxes', () => {
     const states = Object.fromEntries(
       res
         .json()
-        .sandboxes.map((s: { externalId: string; state: string }) => [
-          s.externalId,
+        .sandboxes.map((s: { name: string; state: string }) => [
+          s.name,
           s.state,
         ]),
     );
@@ -814,10 +810,10 @@ describe('POST /listSandboxes', () => {
 describe('POST /rebuildSandbox', () => {
   it('swaps the container, keeps the disk, and the same key wakes with its data', async () => {
     const { app, executor } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
-    const id = created.sandbox.sandboxId;
+    const created = (await acquire(app, { name: 'alice' })).json();
+    const id = created.sandbox.id;
     await rpc(app, '/writeFiles', {
-      externalId: 'alice',
+      name: 'alice',
       files: [
         {
           path: 'keep.txt',
@@ -826,20 +822,20 @@ describe('POST /rebuildSandbox', () => {
       ],
     });
 
-    const res = await rpc(app, '/rebuildSandbox', { externalId: 'alice' });
+    const res = await rpc(app, '/rebuildSandbox', { name: 'alice' });
     expect(res.statusCode).toBe(200);
     // The shell is gone, the row stays, the state says so honestly.
     expect(res.json().sandbox).toMatchObject({
-      sandboxId: id,
+      id,
       state: 'stopped',
     });
     expect(executor.stateOf(id)).toBeUndefined();
 
     // The same key comes back to the same sandbox — rebuilt shell, same body.
-    const again = (await acquire(app, { externalId: 'alice' })).json();
-    expect(again.sandbox.sandboxId).toBe(id);
+    const again = (await acquire(app, { name: 'alice' })).json();
+    expect(again.sandbox.id).toBe(id);
     const read = await rpc(app, '/readFile', {
-      externalId: 'alice',
+      name: 'alice',
       path: 'keep.txt',
     });
     expect(Buffer.from(read.json().contentBase64, 'base64').toString()).toBe(
@@ -849,7 +845,7 @@ describe('POST /rebuildSandbox', () => {
 
   it('rebuilds a frozen sandbox too, and again while already stopped', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
+    const created = (await acquire(app, { name: 'alice' })).json();
     await scanOnce(
       db,
       executor,
@@ -859,20 +855,20 @@ describe('POST /rebuildSandbox', () => {
         DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
       ),
     );
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+    expect(executor.stateOf(created.sandbox.id)).toBe('paused');
 
-    const res = await rpc(app, '/rebuildSandbox', { externalId: 'alice' });
+    const res = await rpc(app, '/rebuildSandbox', { name: 'alice' });
     expect(res.json().sandbox.state).toBe('stopped');
 
     // A second rebuild finds no container — the goal state, not an error.
-    const again = await rpc(app, '/rebuildSandbox', { externalId: 'alice' });
+    const again = await rpc(app, '/rebuildSandbox', { name: 'alice' });
     expect(again.statusCode).toBe(200);
     expect(again.json().sandbox.state).toBe('stopped');
   });
 
   it('answers 404 for an unknown key — rebuild is not a creator', async () => {
     const res = await rpc(testApp().app, '/rebuildSandbox', {
-      externalId: 'nobody',
+      name: 'nobody',
     });
     expect(res.statusCode).toBe(404);
     expect(res.json().message).toMatch(/acquire it first/);
@@ -882,10 +878,10 @@ describe('POST /rebuildSandbox', () => {
 describe('POST /updatePolicy', () => {
   it('patches one knob, keeps the rest, and does not refresh the idle clock', async () => {
     const { app } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
+    const created = (await acquire(app, { name: 'alice' })).json();
 
     const res = await rpc(app, '/updatePolicy', {
-      externalId: 'alice',
+      name: 'alice',
       policy: { freezeAfterSeconds: 120 },
     });
     expect(res.statusCode).toBe(200);
@@ -899,14 +895,14 @@ describe('POST /updatePolicy', () => {
     const events = (await rpc(app, '/listActivity')).json().events;
     expect(events[0]).toMatchObject({
       kind: 'policy-changed',
-      externalId: 'alice',
+      sandboxName: 'alice',
       detail: 'freeze 600s -> 120s',
     });
   });
 
   it('promotes a frozen sandbox to never-stop without waking it', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
+    const created = (await acquire(app, { name: 'alice' })).json();
     await scanOnce(
       db,
       executor,
@@ -916,25 +912,25 @@ describe('POST /updatePolicy', () => {
         DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
       ),
     );
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+    expect(executor.stateOf(created.sandbox.id)).toBe('paused');
 
     const res = await rpc(app, '/updatePolicy', {
-      externalId: 'alice',
+      name: 'alice',
       policy: { stopAfterSeconds: null },
     });
     expect(res.statusCode).toBe(200);
     expect(res.json().sandbox.policy.stopAfterSeconds).toBeNull();
     // Ledger-only: the sandbox slept through its own promotion.
     expect(res.json().sandbox.state).toBe('frozen');
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+    expect(executor.stateOf(created.sandbox.id)).toBe('paused');
   });
 
   it('rejects a patch whose merged result breaks the ordering rule', async () => {
     const { app } = testApp();
-    await acquire(app, { externalId: 'alice' });
+    await acquire(app, { name: 'alice' });
     // freeze pushed past the stored stop threshold.
     const res = await rpc(app, '/updatePolicy', {
-      externalId: 'alice',
+      name: 'alice',
       policy: {
         freezeAfterSeconds:
           (DEFAULT_LIFECYCLE_POLICY.stopAfterSeconds ?? 0) + 1,
@@ -946,9 +942,9 @@ describe('POST /updatePolicy', () => {
 
   it('refuses to promise archiving on a daemon without S3', async () => {
     const { app } = testApp();
-    await acquire(app, { externalId: 'alice' });
+    await acquire(app, { name: 'alice' });
     const res = await rpc(app, '/updatePolicy', {
-      externalId: 'alice',
+      name: 'alice',
       policy: { archiveAfterSeconds: 30 * 24 * 60 * 60 },
     });
     expect(res.statusCode).toBe(400);
@@ -957,7 +953,7 @@ describe('POST /updatePolicy', () => {
 
   it('answers 404 for an unknown key — updatePolicy is not a creator', async () => {
     const res = await rpc(testApp().app, '/updatePolicy', {
-      externalId: 'nobody',
+      name: 'nobody',
       policy: { freezeAfterSeconds: 60 },
     });
     expect(res.statusCode).toBe(404);
@@ -966,9 +962,9 @@ describe('POST /updatePolicy', () => {
 
   it('treats a no-change patch as the goal state and writes no history', async () => {
     const { app } = testApp();
-    await acquire(app, { externalId: 'alice' });
+    await acquire(app, { name: 'alice' });
     const res = await rpc(app, '/updatePolicy', {
-      externalId: 'alice',
+      name: 'alice',
       policy: {
         freezeAfterSeconds: DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
       },
@@ -986,14 +982,14 @@ describe('POST /updateMetadata', () => {
     const { app } = testApp();
     const created = (
       await acquire(app, {
-        externalId: 'alice',
+        name: 'alice',
         metadata: { app: 'crawler', env: 'staging' },
       })
     ).json();
 
     // Full replacement: env is gone, not merged.
     const res = await rpc(app, '/updateMetadata', {
-      externalId: 'alice',
+      name: 'alice',
       metadata: { app: 'assistant' },
     });
     expect(res.statusCode).toBe(200);
@@ -1004,16 +1000,16 @@ describe('POST /updateMetadata', () => {
     const events = (await rpc(app, '/listActivity')).json().events;
     expect(events[0]).toMatchObject({
       kind: 'metadata-changed',
-      externalId: 'alice',
+      sandboxName: 'alice',
       detail: 'app=assistant',
     });
   });
 
   it('clears every label with {} and says so in the history', async () => {
     const { app } = testApp();
-    await acquire(app, { externalId: 'alice', metadata: { app: 'crawler' } });
+    await acquire(app, { name: 'alice', metadata: { app: 'crawler' } });
     const res = await rpc(app, '/updateMetadata', {
-      externalId: 'alice',
+      name: 'alice',
       metadata: {},
     });
     expect(res.statusCode).toBe(200);
@@ -1027,7 +1023,7 @@ describe('POST /updateMetadata', () => {
 
   it('relabels a frozen sandbox without waking it — a pure ledger write', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
+    const created = (await acquire(app, { name: 'alice' })).json();
     await scanOnce(
       db,
       executor,
@@ -1037,20 +1033,20 @@ describe('POST /updateMetadata', () => {
         DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
       ),
     );
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+    expect(executor.stateOf(created.sandbox.id)).toBe('paused');
 
     const res = await rpc(app, '/updateMetadata', {
-      externalId: 'alice',
+      name: 'alice',
       metadata: { team: 'blue' },
     });
     expect(res.statusCode).toBe(200);
     expect(res.json().sandbox.state).toBe('frozen');
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+    expect(executor.stateOf(created.sandbox.id)).toBe('paused');
   });
 
   it('answers 404 for an unknown key — updateMetadata is not a creator', async () => {
     const res = await rpc(testApp().app, '/updateMetadata', {
-      externalId: 'nobody',
+      name: 'nobody',
       metadata: { app: 'x' },
     });
     expect(res.statusCode).toBe(404);
@@ -1059,9 +1055,9 @@ describe('POST /updateMetadata', () => {
 
   it('treats a no-change replacement as the goal state and writes no history', async () => {
     const { app } = testApp();
-    await acquire(app, { externalId: 'alice', metadata: { app: 'crawler' } });
+    await acquire(app, { name: 'alice', metadata: { app: 'crawler' } });
     const res = await rpc(app, '/updateMetadata', {
-      externalId: 'alice',
+      name: 'alice',
       metadata: { app: 'crawler' },
     });
     expect(res.statusCode).toBe(200);
@@ -1075,21 +1071,21 @@ describe('POST /updateMetadata', () => {
 describe('POST /destroySandbox', () => {
   it('destroys the container and forgets the key', async () => {
     const { app, executor } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
-    const id = created.sandbox.sandboxId;
+    const created = (await acquire(app, { name: 'alice' })).json();
+    const id = created.sandbox.id;
 
-    const res = await rpc(app, '/destroySandbox', { externalId: 'alice' });
+    const res = await rpc(app, '/destroySandbox', { name: 'alice' });
     expect(res.json()).toEqual({ destroyed: true });
     // Reality and ledger agree: container gone, key free again — the next
     // acquire builds a brand-new sandbox.
     expect(executor.stateOf(id)).toBeUndefined();
-    const again = (await acquire(app, { externalId: 'alice' })).json();
-    expect(again.sandbox.sandboxId).not.toBe(id);
+    const again = (await acquire(app, { name: 'alice' })).json();
+    expect(again.sandbox.id).not.toBe(id);
   });
 
   it('releases a cold sandbox too', async () => {
     const { app, db, executor, locks } = testApp();
-    const created = (await acquire(app, { externalId: 'alice' })).json();
+    const created = (await acquire(app, { name: 'alice' })).json();
     await scanOnce(
       db,
       executor,
@@ -1099,16 +1095,16 @@ describe('POST /destroySandbox', () => {
         DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
       ),
     );
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+    expect(executor.stateOf(created.sandbox.id)).toBe('paused');
 
-    const res = await rpc(app, '/destroySandbox', { externalId: 'alice' });
+    const res = await rpc(app, '/destroySandbox', { name: 'alice' });
     expect(res.json()).toEqual({ destroyed: true });
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBeUndefined();
+    expect(executor.stateOf(created.sandbox.id)).toBeUndefined();
   });
 
   it('is idempotent: a key with no sandbox reports released false', async () => {
     const res = await rpc(testApp().app, '/destroySandbox', {
-      externalId: 'nobody',
+      name: 'nobody',
     });
     expect(res.statusCode).toBe(200);
     expect(res.json()).toEqual({ destroyed: false });
@@ -1148,11 +1144,11 @@ describe('the archiver through the app', () => {
   /** Polls acquire until the union flips to ready; the whole restore path. */
   async function acquireUntilReady(
     app: ReturnType<typeof testApp>['app'],
-    externalId: string,
+    name: string,
   ) {
     const deadline = Date.now() + 5_000;
     while (true) {
-      const body = (await acquire(app, { externalId })).json();
+      const body = (await acquire(app, { name })).json();
       if (body.status === 'ready') return body;
       expect(body.status).toBe('restoring');
       expect(body.progress.phase).toMatch(/downloading|extracting/);
@@ -1167,7 +1163,7 @@ describe('the archiver through the app', () => {
     const { app, db, executor, locks, store, archiver } = archiverTestApp();
     const created = (
       await acquire(app, {
-        externalId: 'alice',
+        name: 'alice',
         policy: {
           freezeAfterSeconds: 1,
           stopAfterSeconds: 2,
@@ -1175,9 +1171,9 @@ describe('the archiver through the app', () => {
         },
       })
     ).json();
-    const id = created.sandbox.sandboxId;
+    const id = created.sandbox.id;
     await rpc(app, '/writeFiles', {
-      externalId: 'alice',
+      name: 'alice',
       files: [
         {
           path: 'kept.txt',
@@ -1201,10 +1197,10 @@ describe('the archiver through the app', () => {
     // The re-acquire begins the restore and answers restoring immediately;
     // polling lands on ready with the same sandbox and its data intact.
     const ready = await acquireUntilReady(app, 'alice');
-    expect(ready.sandbox.sandboxId).toBe(id);
+    expect(ready.sandbox.id).toBe(id);
     expect(ready.sandbox.state).toBe('active');
     const read = (
-      await rpc(app, '/readFile', { externalId: 'alice', path: 'kept.txt' })
+      await rpc(app, '/readFile', { name: 'alice', path: 'kept.txt' })
     ).json();
     expect(Buffer.from(read.contentBase64, 'base64').toString()).toBe(
       'through the archive',
@@ -1213,7 +1209,7 @@ describe('the archiver through the app', () => {
 
   it('stores the 7-day archive default when S3 is configured', async () => {
     const { app } = archiverTestApp();
-    const res = await acquire(app, { externalId: 'alice' });
+    const res = await acquire(app, { name: 'alice' });
     expect(res.json().sandbox.policy.archiveAfterSeconds).toBe(
       ARCHIVE_DEFAULT_SECONDS,
     );
@@ -1224,14 +1220,14 @@ describe('the archiver through the app', () => {
     // the rows are honest, the restore is impossible, the error names it.
     const executor = new FakeExecutor();
     const { app, db } = testApp(executor);
-    const created = (await acquire(app, { externalId: 'alice' })).json();
-    const id = created.sandbox.sandboxId;
+    const created = (await acquire(app, { name: 'alice' })).json();
+    const id = created.sandbox.id;
     transition(db, id, 'frozen');
     transition(db, id, 'stopped');
     transition(db, id, 'archived');
     await executor.destroy(id);
 
-    const res = await acquire(app, { externalId: 'alice' });
+    const res = await acquire(app, { name: 'alice' });
     expect(res.statusCode).toBe(503);
     expect(res.json().message).toMatch(/no S3 configured \(DORMICE_S3_\*\)/);
   });
@@ -1240,7 +1236,7 @@ describe('the archiver through the app', () => {
     const { app, db, executor, locks, store, archiver } = archiverTestApp();
     const created = (
       await acquire(app, {
-        externalId: 'alice',
+        name: 'alice',
         policy: {
           freezeAfterSeconds: 1,
           stopAfterSeconds: 2,
@@ -1248,14 +1244,14 @@ describe('the archiver through the app', () => {
         },
       })
     ).json();
-    const id = created.sandbox.sandboxId;
+    const id = created.sandbox.id;
     const stamp = created.sandbox.lastActiveAt;
     await scanOnce(db, executor, locks, after(stamp, 1), archiver);
     await scanOnce(db, executor, locks, after(stamp, 2), archiver);
     await scanOnce(db, executor, locks, after(stamp, 3), archiver);
     expect(store.has(objectKey(id))).toBe(true);
 
-    const res = await rpc(app, '/destroySandbox', { externalId: 'alice' });
+    const res = await rpc(app, '/destroySandbox', { name: 'alice' });
     expect(res.json()).toEqual({ destroyed: true });
     expect(store.has(objectKey(id))).toBe(false);
     expect((await rpc(app, '/listSandboxes')).json().sandboxes).toEqual([]);
@@ -1265,7 +1261,7 @@ describe('the archiver through the app', () => {
     const { app, db, executor, locks, store, archiver } = archiverTestApp();
     const created = (
       await acquire(app, {
-        externalId: 'alice',
+        name: 'alice',
         policy: {
           freezeAfterSeconds: 1,
           stopAfterSeconds: 2,
@@ -1288,9 +1284,9 @@ describe('the archiver through the app', () => {
       return innerGet(key, dest, onProgress);
     };
 
-    const restoring = (await acquire(app, { externalId: 'alice' })).json();
+    const restoring = (await acquire(app, { name: 'alice' })).json();
     expect(restoring.status).toBe('restoring');
-    const res = await rpc(app, '/destroySandbox', { externalId: 'alice' });
+    const res = await rpc(app, '/destroySandbox', { name: 'alice' });
     expect(res.statusCode).toBe(409);
     expect(res.json().message).toMatch(/restoring; retry/);
 
@@ -1302,7 +1298,7 @@ describe('the archiver through the app', () => {
     const { app, db, executor, locks, archiver } = archiverTestApp();
     const created = (
       await acquire(app, {
-        externalId: 'alice',
+        name: 'alice',
         policy: {
           freezeAfterSeconds: 1,
           stopAfterSeconds: 2,
@@ -1316,13 +1312,13 @@ describe('the archiver through the app', () => {
     await scanOnce(db, executor, locks, after(stamp, 3), archiver);
 
     const exec = await rpc(app, '/execCommand', {
-      externalId: 'alice',
+      name: 'alice',
       command: 'echo hi',
     });
     expect(exec.statusCode).toBe(409);
     expect(exec.json().message).toMatch(/call acquireSandbox and poll/);
     const read = await rpc(app, '/readFile', {
-      externalId: 'alice',
+      name: 'alice',
       path: 'kept.txt',
     });
     expect(read.statusCode).toBe(409);
@@ -1396,48 +1392,46 @@ describe('templates', () => {
   it('acquire with a template creates the sandbox from its image and records the name', async () => {
     const { app, executor } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' });
-    const res = await acquire(app, { externalId: 'alice', template: 'py' });
+    const res = await acquire(app, { name: 'alice', template: 'py' });
     expect(res.statusCode).toBe(200);
     const sandbox = res.json().sandbox;
     expect(sandbox.template).toBe('py');
     // The physical half: the shell was actually born from the template's image.
-    expect(await executor.imageOf(sandbox.sandboxId)).toBe('img-a');
+    expect(await executor.imageOf(sandbox.id)).toBe('img-a');
     // A template-less acquire stays on the base image, template null.
-    const plain = (await acquire(app, { externalId: 'bob' })).json().sandbox;
+    const plain = (await acquire(app, { name: 'bob' })).json().sandbox;
     expect(plain.template).toBeNull();
   });
 
   it('rejects an unknown template with 400, on the wake path too', async () => {
     const { app } = testApp();
-    const res = await acquire(app, { externalId: 'alice', template: 'ghost' });
+    const res = await acquire(app, { name: 'alice', template: 'ghost' });
     expect(res.statusCode).toBe(400);
     expect(res.json().message).toBe(
       "unknown template 'ghost' — register it first",
     );
     // Same answer when the key already has a sandbox: the caller's mistake
     // deserves a 400 even when the value would not apply.
-    await acquire(app, { externalId: 'bob' });
-    const wake = await acquire(app, { externalId: 'bob', template: 'ghost' });
+    await acquire(app, { name: 'bob' });
+    const wake = await acquire(app, { name: 'bob', template: 'ghost' });
     expect(wake.statusCode).toBe(400);
   });
 
   it('a valid template on an existing key is not applied — creation-time only', async () => {
     const { app } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' });
-    const created = (await acquire(app, { externalId: 'alice' })).json()
-      .sandbox;
+    const created = (await acquire(app, { name: 'alice' })).json().sandbox;
     expect(created.template).toBeNull();
-    const again = (
-      await acquire(app, { externalId: 'alice', template: 'py' })
-    ).json().sandbox;
-    expect(again.sandboxId).toBe(created.sandboxId);
+    const again = (await acquire(app, { name: 'alice', template: 'py' })).json()
+      .sandbox;
+    expect(again.id).toBe(created.id);
     expect(again.template).toBeNull();
   });
 
   it('refuses to remove a template while sandboxes use it, naming the keys', async () => {
     const { app } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-a' });
-    await acquire(app, { externalId: 'alice', template: 'py' });
+    await acquire(app, { name: 'alice', template: 'py' });
 
     const refused = await rpc(app, '/removeTemplate', { name: 'py' });
     expect(refused.statusCode).toBe(409);
@@ -1445,7 +1439,7 @@ describe('templates', () => {
       "template 'py' is used by 1 sandbox(es): alice — destroy them first",
     );
 
-    await rpc(app, '/destroySandbox', { externalId: 'alice' });
+    await rpc(app, '/destroySandbox', { name: 'alice' });
     expect((await rpc(app, '/removeTemplate', { name: 'py' })).json()).toEqual({
       removed: true,
     });
@@ -1459,20 +1453,20 @@ describe('templates', () => {
     const { app, executor } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
     const created = (
-      await acquire(app, { externalId: 'alice', template: 'py' })
+      await acquire(app, { name: 'alice', template: 'py' })
     ).json().sandbox;
-    expect(await executor.imageOf(created.sandboxId)).toBe('img-v1');
+    expect(await executor.imageOf(created.id)).toBe('img-v1');
 
     // Operator builds a new image and re-points the name; the stock moves
     // per sandbox, on its own rebuild — never behind its back.
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });
-    expect(await executor.imageOf(created.sandboxId)).toBe('img-v1');
+    expect(await executor.imageOf(created.id)).toBe('img-v1');
 
-    await rpc(app, '/rebuildSandbox', { externalId: 'alice' });
-    const woken = (await acquire(app, { externalId: 'alice' })).json().sandbox;
-    expect(woken.sandboxId).toBe(created.sandboxId);
+    await rpc(app, '/rebuildSandbox', { name: 'alice' });
+    const woken = (await acquire(app, { name: 'alice' })).json().sandbox;
+    expect(woken.id).toBe(created.id);
     // The rebuilt shell was born from the template's *current* image.
-    expect(await executor.imageOf(created.sandboxId)).toBe('img-v2');
+    expect(await executor.imageOf(created.id)).toBe('img-v2');
   });
 });
 
@@ -1526,11 +1520,11 @@ describe('POST /getHostMetrics', () => {
     // to alice+60 freezes exactly one of them.
     const created = (
       await acquire(app, {
-        externalId: 'alice',
+        name: 'alice',
         policy: { freezeAfterSeconds: 60 },
       })
     ).json();
-    await acquire(app, { externalId: 'bob' });
+    await acquire(app, { name: 'bob' });
 
     let body = (await rpc(app, '/getHostMetrics')).json();
     expect(body.sandboxes.total).toBe(2);
@@ -1549,7 +1543,7 @@ describe('POST /getHostMetrics', () => {
     expect(body.sandboxes.byState.active).toBe(1);
     expect(body.sandboxes.byState.frozen).toBe(1);
     // Observation is not activity: reading metrics woke nothing.
-    expect(executor.stateOf(created.sandbox.sandboxId)).toBe('paused');
+    expect(executor.stateOf(created.sandbox.id)).toBe('paused');
   });
 });
 
diff --git a/packages/server/src/archive/archiver.test.ts b/packages/server/src/archive/archiver.test.ts
index 66b3d71..af6e64d 100644
--- a/packages/server/src/archive/archiver.test.ts
+++ b/packages/server/src/archive/archiver.test.ts
@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { DEFAULT_LIFECYCLE_POLICY } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { type Db, migrateDb, openDb } from '../db/db';
-import { createSandbox, findByExternalId, transition } from '../db/ledger';
+import { createSandbox, findByName, transition } from '../db/ledger';
 import type { SandboxRow } from '../db/schema';
 import { FakeExecutor } from '../executor/fake';
 import { KeyedQueue } from '../keyed-queue';
@@ -31,23 +31,23 @@ function setup() {
 async function seedStopped(
   db: Db,
   executor: FakeExecutor,
-  externalId: string,
+  name: string,
 ): Promise<SandboxRow> {
-  const sandboxId = randomUUID();
-  await executor.create(sandboxId);
-  await executor.writeFiles(sandboxId, [
-    { path: 'kept.txt', content: Buffer.from(`data of ${externalId}`) },
+  const id = randomUUID();
+  await executor.create(id);
+  await executor.writeFiles(id, [
+    { path: 'kept.txt', content: Buffer.from(`data of ${name}`) },
   ]);
   createSandbox(db, {
-    sandboxId,
-    externalId,
+    id,
+    name,
     nodeId: 'node-test',
     policy: DEFAULT_LIFECYCLE_POLICY,
   });
-  await executor.freeze(sandboxId);
-  await executor.stop(sandboxId);
-  transition(db, sandboxId, 'frozen');
-  return transition(db, sandboxId, 'stopped');
+  await executor.freeze(id);
+  await executor.stop(id);
+  transition(db, id, 'frozen');
+  return transition(db, id, 'stopped');
 }
 
 describe('Archiver.archive', () => {
@@ -57,11 +57,11 @@ describe('Archiver.archive', () => {
 
     await archiver.archive(row);
 
-    expect(store.has(objectKey(row.sandboxId))).toBe(true);
-    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
+    expect(store.has(objectKey(row.id))).toBe(true);
+    expect(findByName(db, 'alice')?.state).toBe('archived');
     // "Local copy freed" includes the shell: destroy, not just the disk.
-    expect(executor.stateOf(row.sandboxId)).toBeUndefined();
-    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+    expect(executor.stateOf(row.id)).toBeUndefined();
+    expect(await executor.listDisks()).not.toContain(row.id);
     expect(readdirSync(tmpDir)).toEqual([]);
   });
 
@@ -76,13 +76,13 @@ describe('Archiver.archive', () => {
     const events: string[] = [];
     const watchingStore = new (class extends MemStore {
       override async put(key: string, filePath: string): Promise<void> {
-        events.push(`put while ${findByExternalId(db, 'alice')?.state}`);
+        events.push(`put while ${findByName(db, 'alice')?.state}`);
         await super.put(key, filePath);
       }
     })();
     const watchingExecutor = new (class extends FakeExecutor {
       override async destroy(sandboxId: string): Promise<void> {
-        events.push(`destroy while ${findByExternalId(db, 'alice')?.state}`);
+        events.push(`destroy while ${findByName(db, 'alice')?.state}`);
         await super.destroy(sandboxId);
       }
     })();
@@ -119,23 +119,23 @@ describe('Archiver.archive', () => {
     await expect(archiver.archive(row)).rejects.toThrow('the bucket said no');
     // The invariant as behavior: disk still present <=> upload unconfirmed,
     // so the row stays stopped and the next sweep retries the whole thing.
-    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
-    expect(await executor.listDisks()).toContain(row.sandboxId);
+    expect(findByName(db, 'alice')?.state).toBe('stopped');
+    expect(await executor.listDisks()).toContain(row.id);
     expect(readdirSync(tmpDir)).toEqual([]);
   });
 
   it('refuses a row that is not stopped', async () => {
     const { db, executor, archiver } = setup();
-    const sandboxId = randomUUID();
-    await executor.create(sandboxId);
+    const id = randomUUID();
+    await executor.create(id);
     const row = createSandbox(db, {
-      sandboxId,
-      externalId: 'alice',
+      id,
+      name: 'alice',
       nodeId: 'node-test',
       policy: DEFAULT_LIFECYCLE_POLICY,
     });
     await expect(archiver.archive(row)).rejects.toThrow(
-      `sandbox ${sandboxId} is active, expected stopped`,
+      `sandbox ${id} is active, expected stopped`,
     );
   });
 });
@@ -145,7 +145,7 @@ describe('Archiver.beginRestore', () => {
     const { db, executor, store, tmpDir, archiver } = setup();
     const row = await seedStopped(db, executor, 'alice');
     await archiver.archive(row);
-    const archived = findByExternalId(db, 'alice');
+    const archived = findByName(db, 'alice');
     if (!archived) throw new Error('row vanished');
 
     let entry: ReturnType<Archiver['beginRestore']> | undefined;
@@ -153,21 +153,21 @@ describe('Archiver.beginRestore', () => {
       entry = archiver.beginRestore(archived);
     });
     // Non-blocking: the row is restoring the moment beginRestore returns.
-    expect(findByExternalId(db, 'alice')?.state).toBe('restoring');
-    expect(archiver.hasLiveRestore(row.sandboxId)).toBe(true);
+    expect(findByName(db, 'alice')?.state).toBe('restoring');
+    expect(archiver.hasLiveRestore(row.id)).toBe(true);
     expect(entry?.progress.phase).toBe('downloading');
 
-    await archiver.restoreJoin(row.sandboxId);
+    await archiver.restoreJoin(row.id);
 
-    expect(findByExternalId(db, 'alice')?.state).toBe('active');
-    expect(executor.stateOf(row.sandboxId)).toBe('running');
-    expect(
-      (await executor.readFile(row.sandboxId, 'kept.txt')).toString(),
-    ).toBe('data of alice');
-    expect(archiver.hasLiveRestore(row.sandboxId)).toBe(false);
+    expect(findByName(db, 'alice')?.state).toBe('active');
+    expect(executor.stateOf(row.id)).toBe('running');
+    expect((await executor.readFile(row.id, 'kept.txt')).toString()).toBe(
+      'data of alice',
+    );
+    expect(archiver.hasLiveRestore(row.id)).toBe(false);
     // The object goes with the restore: from here "an object exists" means
     // "the row is archived" — release never chases stale copies.
-    expect(store.has(objectKey(row.sandboxId))).toBe(false);
+    expect(store.has(objectKey(row.id))).toBe(false);
     expect(readdirSync(tmpDir)).toEqual([]);
   });
 
@@ -175,20 +175,20 @@ describe('Archiver.beginRestore', () => {
     const { db, executor, store, tmpDir, archiver } = setup();
     const row = await seedStopped(db, executor, 'alice');
     await archiver.archive(row);
-    await store.delete(objectKey(row.sandboxId));
-    const archived = findByExternalId(db, 'alice');
+    await store.delete(objectKey(row.id));
+    const archived = findByName(db, 'alice');
     if (!archived) throw new Error('row vanished');
 
     archiver.beginRestore(archived);
-    await expect(archiver.restoreJoin(row.sandboxId)).rejects.toThrow(
-      `archive object ${objectKey(row.sandboxId)} is not in bucket`,
+    await expect(archiver.restoreJoin(row.id)).rejects.toThrow(
+      `archive object ${objectKey(row.id)} is not in bucket`,
     );
 
     // The S3 object is the only copy; with it gone the honest state is
     // archived-and-failing, retried on every acquire, loudly.
-    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
-    expect(await executor.listDisks()).not.toContain(row.sandboxId);
-    expect(archiver.hasLiveRestore(row.sandboxId)).toBe(false);
+    expect(findByName(db, 'alice')?.state).toBe('archived');
+    expect(await executor.listDisks()).not.toContain(row.id);
+    expect(archiver.hasLiveRestore(row.id)).toBe(false);
     expect(readdirSync(tmpDir)).toEqual([]);
   });
 
@@ -196,32 +196,30 @@ describe('Archiver.beginRestore', () => {
     const { db, executor, archiver } = setup();
     const row = await seedStopped(db, executor, 'alice');
     await archiver.archive(row);
-    const archived = findByExternalId(db, 'alice');
+    const archived = findByName(db, 'alice');
     if (!archived) throw new Error('row vanished');
 
     const first = archiver.beginRestore(archived);
-    const again = archiver.beginRestore(
-      findByExternalId(db, 'alice') as SandboxRow,
-    );
+    const again = archiver.beginRestore(findByName(db, 'alice') as SandboxRow);
     expect(again).toBe(first);
-    await archiver.restoreJoin(row.sandboxId);
-    expect(findByExternalId(db, 'alice')?.state).toBe('active');
+    await archiver.restoreJoin(row.id);
+    expect(findByName(db, 'alice')?.state).toBe('active');
   });
 });
 
 describe('Archiver.restoreJoin', () => {
   it('is a no-op for a sandbox that is not archived', async () => {
     const { db, executor, archiver } = setup();
-    const sandboxId = randomUUID();
-    await executor.create(sandboxId);
+    const id = randomUUID();
+    await executor.create(id);
     createSandbox(db, {
-      sandboxId,
-      externalId: 'alice',
+      id,
+      name: 'alice',
       nodeId: 'node-test',
       policy: DEFAULT_LIFECYCLE_POLICY,
     });
-    await archiver.restoreJoin(sandboxId);
-    expect(findByExternalId(db, 'alice')?.state).toBe('active');
+    await archiver.restoreJoin(id);
+    expect(findByName(db, 'alice')?.state).toBe('active');
   });
 
   it('starts the restore itself when the row is archived', async () => {
@@ -229,9 +227,9 @@ describe('Archiver.restoreJoin', () => {
     const row = await seedStopped(db, executor, 'alice');
     await archiver.archive(row);
 
-    await archiver.restoreJoin(row.sandboxId);
+    await archiver.restoreJoin(row.id);
 
-    expect(findByExternalId(db, 'alice')?.state).toBe('active');
-    expect(executor.stateOf(row.sandboxId)).toBe('running');
+    expect(findByName(db, 'alice')?.state).toBe('active');
+    expect(executor.stateOf(row.id)).toBe('running');
   });
 });
diff --git a/packages/server/src/archive/archiver.ts b/packages/server/src/archive/archiver.ts
index e4874c7..0d04b78 100644
--- a/packages/server/src/archive/archiver.ts
+++ b/packages/server/src/archive/archiver.ts
@@ -2,12 +2,7 @@ import { mkdir, rm } from 'node:fs/promises';
 import path from 'node:path';
 import { recordActivity } from '../db/activity';
 import type { Db } from '../db/db';
-import {
-  findBySandboxId,
-  setPausedByUser,
-  touch,
-  transition,
-} from '../db/ledger';
+import { findById, setPausedByUser, touch, transition } from '../db/ledger';
 import type { SandboxRow } from '../db/schema';
 import { resolveImage } from '../db/templates';
 import type { Executor } from '../executor/executor';
@@ -97,27 +92,27 @@ export class Archiver {
   async archive(row: SandboxRow): Promise<void> {
     if (row.state !== 'stopped') {
       throw new Error(
-        `sandbox ${row.sandboxId} is ${row.state}, expected stopped — only a stopped sandbox can archive`,
+        `sandbox ${row.id} is ${row.state}, expected stopped — only a stopped sandbox can archive`,
       );
     }
     const startedAt = Date.now();
-    const tmp = path.join(this.tmpDir, `${row.sandboxId}.archive.tar.zst`);
+    const tmp = path.join(this.tmpDir, `${row.id}.archive.tar.zst`);
     try {
-      await this.executor.exportDisk(row.sandboxId, tmp);
-      await this.store.put(objectKey(row.sandboxId), tmp);
-      transition(this.db, row.sandboxId, 'archived');
-      await this.executor.destroy(row.sandboxId);
+      await this.executor.exportDisk(row.id, tmp);
+      await this.store.put(objectKey(row.id), tmp);
+      transition(this.db, row.id, 'archived');
+      await this.executor.destroy(row.id);
     } finally {
       await rm(tmp, { force: true });
     }
     const seconds = ((Date.now() - startedAt) / 1000).toFixed(1);
     recordActivity(this.db, {
       kind: 'archived',
-      externalId: row.externalId,
-      sandboxId: row.sandboxId,
+      sandboxName: row.name,
+      sandboxId: row.id,
       detail: `disk shipped to S3 in ${seconds}s; local copy freed`,
     });
-    this.log(`archived ${row.sandboxId} in ${seconds}s`);
+    this.log(`archived ${row.id} in ${seconds}s`);
   }
 
   /**
@@ -126,34 +121,30 @@ export class Archiver {
    * the key slot. Calling again while a restore runs joins the same task.
    */
   beginRestore(row: SandboxRow): { progress: RestoreProgress } {
-    const existing = this.restores.get(row.sandboxId);
+    const existing = this.restores.get(row.id);
     if (existing) return existing;
     if (row.state !== 'archived') {
       throw new Error(
-        `sandbox ${row.sandboxId} is ${row.state}, expected archived — beginRestore is the move on archived rows`,
+        `sandbox ${row.id} is ${row.state}, expected archived — beginRestore is the move on archived rows`,
       );
     }
-    transition(this.db, row.sandboxId, 'restoring');
+    transition(this.db, row.id, 'restoring');
     recordActivity(this.db, {
       kind: 'restore-started',
-      externalId: row.externalId,
-      sandboxId: row.sandboxId,
+      sandboxName: row.name,
+      sandboxId: row.id,
       detail: 'restore from S3 began',
     });
     const progress: RestoreProgress = { phase: 'downloading', percent: 0 };
-    const done = this.runRestore(
-      row.sandboxId,
-      row.externalId,
-      progress,
-    ).finally(() => {
-      this.restores.delete(row.sandboxId);
+    const done = this.runRestore(row.id, row.name, progress).finally(() => {
+      this.restores.delete(row.id);
     });
     // Native acquire never awaits this — a failure with no joiner must not
     // crash the daemon as an unhandled rejection. Joiners still observe the
     // rejection through the same promise.
     done.catch(() => {});
     const entry: RestoreEntry = { progress, done };
-    this.restores.set(row.sandboxId, entry);
+    this.restores.set(row.id, entry);
     return entry;
   }
 
@@ -176,12 +167,12 @@ export class Archiver {
    * own finish needs the slot.
    */
   async restoreJoin(sandboxId: string): Promise<void> {
-    const row = findBySandboxId(this.db, sandboxId);
+    const row = findById(this.db, sandboxId);
     if (!row || (row.state !== 'archived' && row.state !== 'restoring')) {
       return;
     }
-    const entry = await this.locks.run(row.externalId, async () => {
-      const fresh = findBySandboxId(this.db, sandboxId);
+    const entry = await this.locks.run(row.name, async () => {
+      const fresh = findById(this.db, sandboxId);
       if (fresh?.state === 'archived') {
         return this.beginRestore(fresh) as RestoreEntry;
       }
@@ -204,7 +195,7 @@ export class Archiver {
    */
   private async runRestore(
     sandboxId: string,
-    externalId: string,
+    name: string,
     progress: RestoreProgress,
   ): Promise<void> {
     const tmp = path.join(this.tmpDir, `${sandboxId}.restore.tar.zst`);
@@ -217,8 +208,8 @@ export class Archiver {
       await this.executor.importDisk(sandboxId, tmp, (fraction) => {
         progress.percent = clampPercent(fraction);
       });
-      await this.locks.run(externalId, async () => {
-        const fresh = findBySandboxId(this.db, sandboxId);
+      await this.locks.run(name, async () => {
+        const fresh = findById(this.db, sandboxId);
         if (fresh?.state !== 'restoring') {
           // Nothing legal moves a restoring row but this task; hearing
           // otherwise is a bug report. The disk just built is task-owned.
@@ -240,7 +231,7 @@ export class Archiver {
         touch(this.db, sandboxId);
         recordActivity(this.db, {
           kind: 'restored',
-          externalId,
+          sandboxName: name,
           sandboxId,
           detail: 'disk back from S3, sandbox active; archive object deleted',
         });
@@ -255,13 +246,13 @@ export class Archiver {
         `restore of ${sandboxId} failed: ${err instanceof Error ? err.message : String(err)}`,
       );
       await this.executor.removeDisk(sandboxId).catch(() => {});
-      await this.locks.run(externalId, async () => {
-        const fresh = findBySandboxId(this.db, sandboxId);
+      await this.locks.run(name, async () => {
+        const fresh = findById(this.db, sandboxId);
         if (fresh?.state === 'restoring') {
           transition(this.db, sandboxId, 'archived');
           recordActivity(this.db, {
             kind: 'restore-failed',
-            externalId,
+            sandboxName: name,
             sandboxId,
             detail: `back to archived, S3 object intact — ${
               err instanceof Error ? err.message : String(err)
diff --git a/packages/server/src/db/activity.ts b/packages/server/src/db/activity.ts
index a125d5f..a1cd317 100644
--- a/packages/server/src/db/activity.ts
+++ b/packages/server/src/db/activity.ts
@@ -13,7 +13,8 @@ export const ACTIVITY_KEEP = 1000;
 
 export interface ActivityInput {
   kind: ActivityKind;
-  externalId?: string | null;
+  /** The owning sandbox's name/id — prefixed: they reference another entity. */
+  sandboxName?: string | null;
   sandboxId?: string | null;
   detail: string;
 }
@@ -30,7 +31,7 @@ export function recordActivity(db: Db, input: ActivityInput): void {
     .values({
       at: new Date().toISOString(),
       kind: input.kind,
-      externalId: input.externalId ?? null,
+      sandboxName: input.sandboxName ?? null,
       sandboxId: input.sandboxId ?? null,
       detail: input.detail,
     })
diff --git a/packages/server/src/db/ledger.test.ts b/packages/server/src/db/ledger.test.ts
index bf11633..5908036 100644
--- a/packages/server/src/db/ledger.test.ts
+++ b/packages/server/src/db/ledger.test.ts
@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { DEFAULT_LIFECYCLE_POLICY } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { type Db, migrateDb, openDb } from './db';
-import { createSandbox, findByExternalId, touch, transition } from './ledger';
+import { createSandbox, findByName, touch, transition } from './ledger';
 
 const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
 
@@ -13,10 +13,10 @@ function testDb(): Db {
   return db;
 }
 
-function create(db: Db, externalId = 'user-1') {
+function create(db: Db, name = 'user-1') {
   return createSandbox(db, {
-    sandboxId: randomUUID(),
-    externalId,
+    id: randomUUID(),
+    name,
     nodeId: 'node-1',
     policy: DEFAULT_LIFECYCLE_POLICY,
   });
@@ -27,8 +27,8 @@ describe('ledger', () => {
     const db = testDb();
     const created = create(db);
     expect(created.state).toBe('active');
-    expect(findByExternalId(db, 'user-1')).toEqual(created);
-    expect(findByExternalId(db, 'someone-else')).toBeUndefined();
+    expect(findByName(db, 'user-1')).toEqual(created);
+    expect(findByName(db, 'someone-else')).toBeUndefined();
   });
 
   it('enforces one sandbox per external id at the database level', () => {
@@ -39,7 +39,7 @@ describe('ledger', () => {
 
   it('walks the full lifecycle: active -> frozen -> stopped -> archived -> restoring -> active', () => {
     const db = testDb();
-    const { sandboxId } = create(db);
+    const { id: sandboxId } = create(db);
     for (const to of [
       'frozen',
       'stopped',
@@ -49,19 +49,19 @@ describe('ledger', () => {
     ] as const) {
       expect(transition(db, sandboxId, to).state).toBe(to);
     }
-    expect(findByExternalId(db, 'user-1')?.state).toBe('active');
+    expect(findByName(db, 'user-1')?.state).toBe('active');
   });
 
   it('wakes a frozen sandbox straight back to active', () => {
     const db = testDb();
-    const { sandboxId } = create(db);
+    const { id: sandboxId } = create(db);
     transition(db, sandboxId, 'frozen');
     expect(transition(db, sandboxId, 'active').state).toBe('active');
   });
 
   it('rejects skipping rungs on the way down, except rebuild', () => {
     const db = testDb();
-    const { sandboxId } = create(db);
+    const { id: sandboxId } = create(db);
     expect(() => transition(db, sandboxId, 'archived')).toThrow(
       /illegal transition/,
     );
@@ -72,7 +72,7 @@ describe('ledger', () => {
 
   it('rejects waking an archived sandbox without going through restoring', () => {
     const db = testDb();
-    const { sandboxId } = create(db);
+    const { id: sandboxId } = create(db);
     transition(db, sandboxId, 'frozen');
     transition(db, sandboxId, 'stopped');
     transition(db, sandboxId, 'archived');
@@ -88,7 +88,7 @@ describe('ledger', () => {
 
   it('touch refreshes the idle clock to the injected instant', () => {
     const db = testDb();
-    const { sandboxId, lastActiveAt } = create(db);
+    const { id: sandboxId, lastActiveAt } = create(db);
     const future = new Date(Date.parse(lastActiveAt) + 60_000).toISOString();
     expect(touch(db, sandboxId, future).lastActiveAt).toBe(future);
   });
diff --git a/packages/server/src/db/ledger.ts b/packages/server/src/db/ledger.ts
index 0f87394..4977a1e 100644
--- a/packages/server/src/db/ledger.ts
+++ b/packages/server/src/db/ledger.ts
@@ -34,8 +34,8 @@ export interface CreateSandboxInput {
    * Supplied by the caller, not generated here: reality moves first (the
    * container is created under this id), then the ledger records it.
    */
-  sandboxId: string;
-  externalId: string;
+  id: string;
+  name: string;
   nodeId: string;
   policy: LifecyclePolicy;
   /** Template the sandbox is created from; absent/null means the base image. */
@@ -55,12 +55,12 @@ export interface CreateSandboxInput {
   };
 }
 
-/** Inserts a new sandbox row in `active` state. Throws if the external id is taken. */
+/** Inserts a new sandbox row in `active` state. Throws if the name is taken. */
 export function createSandbox(db: Db, input: CreateSandboxInput): SandboxRow {
   const now = new Date().toISOString();
   const row: SandboxRow = {
-    sandboxId: input.sandboxId,
-    externalId: input.externalId,
+    id: input.id,
+    name: input.name,
     state: 'active',
     nodeId: input.nodeId,
     freezeAfterSeconds: input.policy.freezeAfterSeconds,
@@ -79,8 +79,8 @@ export function createSandbox(db: Db, input: CreateSandboxInput): SandboxRow {
   // The one place every creation passes through, whichever face asked.
   recordActivity(db, {
     kind: 'created',
-    externalId: row.externalId,
-    sandboxId: row.sandboxId,
+    sandboxName: row.name,
+    sandboxId: row.id,
     detail: `${input.e2b ? 'via E2B create' : 'via acquireSandbox'}${
       input.template ? `, template ${input.template}` : ''
     }`,
@@ -95,20 +95,16 @@ export function createSandbox(db: Db, input: CreateSandboxInput): SandboxRow {
  */
 export function touch(
   db: Db,
-  sandboxId: string,
+  id: string,
   now: string = new Date().toISOString(),
 ): SandboxRow {
   db.update(sandboxes)
     .set({ lastActiveAt: now })
-    .where(eq(sandboxes.sandboxId, sandboxId))
+    .where(eq(sandboxes.id, id))
     .run();
-  const row = db
-    .select()
-    .from(sandboxes)
-    .where(eq(sandboxes.sandboxId, sandboxId))
-    .get();
+  const row = db.select().from(sandboxes).where(eq(sandboxes.id, id)).get();
   if (!row) {
-    throw new Error(`sandbox ${sandboxId} not found`);
+    throw new Error(`sandbox ${id} not found`);
   }
   return row;
 }
@@ -140,8 +136,8 @@ export function countSandboxes(db: Db): number {
  * does not go through ALLOWED_TRANSITIONS — that table governs moves between
  * states, not the end of the record.
  */
-export function deleteSandbox(db: Db, sandboxId: string): void {
-  db.delete(sandboxes).where(eq(sandboxes.sandboxId, sandboxId)).run();
+export function deleteSandbox(db: Db, id: string): void {
+  db.delete(sandboxes).where(eq(sandboxes.id, id)).run();
 }
 
 /**
@@ -150,15 +146,8 @@ export function deleteSandbox(db: Db, sandboxId: string): void {
  * reality already did while nobody was watching. Only the reconciler calls
  * this — everything else goes through transition().
  */
-export function overwriteState(
-  db: Db,
-  sandboxId: string,
-  state: SandboxState,
-): void {
-  db.update(sandboxes)
-    .set({ state })
-    .where(eq(sandboxes.sandboxId, sandboxId))
-    .run();
+export function overwriteState(db: Db, id: string, state: SandboxState): void {
+  db.update(sandboxes).set({ state }).where(eq(sandboxes.id, id)).run();
 }
 
 /**
@@ -167,7 +156,7 @@ export function overwriteState(
  */
 export function setDeadline(
   db: Db,
-  sandboxId: string,
+  id: string,
   deadline: { deadlineAt: string; onDeadline: 'kill' | 'pause' } | null,
 ): void {
   db.update(sandboxes)
@@ -175,7 +164,7 @@ export function setDeadline(
       deadlineAt: deadline?.deadlineAt ?? null,
       onDeadline: deadline?.onDeadline ?? null,
     })
-    .where(eq(sandboxes.sandboxId, sandboxId))
+    .where(eq(sandboxes.id, id))
     .run();
 }
 
@@ -186,7 +175,7 @@ export function setDeadline(
  */
 export function updatePolicy(
   db: Db,
-  sandboxId: string,
+  id: string,
   policy: LifecyclePolicy,
 ): SandboxRow {
   db.update(sandboxes)
@@ -195,11 +184,11 @@ export function updatePolicy(
       stopAfterSeconds: policy.stopAfterSeconds,
       archiveAfterSeconds: policy.archiveAfterSeconds,
     })
-    .where(eq(sandboxes.sandboxId, sandboxId))
+    .where(eq(sandboxes.id, id))
     .run();
-  const row = findBySandboxId(db, sandboxId);
+  const row = findById(db, id);
   if (!row) {
-    throw new Error(`sandbox ${sandboxId} not found`);
+    throw new Error(`sandbox ${id} not found`);
   }
   return row;
 }
@@ -211,52 +200,31 @@ export function updatePolicy(
  */
 export function updateMetadata(
   db: Db,
-  sandboxId: string,
+  id: string,
   metadata: string | null,
 ): SandboxRow {
-  db.update(sandboxes)
-    .set({ metadata })
-    .where(eq(sandboxes.sandboxId, sandboxId))
-    .run();
-  const row = findBySandboxId(db, sandboxId);
+  db.update(sandboxes).set({ metadata }).where(eq(sandboxes.id, id)).run();
+  const row = findById(db, id);
   if (!row) {
-    throw new Error(`sandbox ${sandboxId} not found`);
+    throw new Error(`sandbox ${id} not found`);
   }
   return row;
 }
 
 /** Marks an explicit E2B pause; wakes clear it (an awake sandbox is not paused). */
-export function setPausedByUser(
-  db: Db,
-  sandboxId: string,
-  paused: boolean,
-): void {
+export function setPausedByUser(db: Db, id: string, paused: boolean): void {
   db.update(sandboxes)
     .set({ pausedByUser: paused })
-    .where(eq(sandboxes.sandboxId, sandboxId))
+    .where(eq(sandboxes.id, id))
     .run();
 }
 
-export function findByExternalId(
-  db: Db,
-  externalId: string,
-): SandboxRow | undefined {
-  return db
-    .select()
-    .from(sandboxes)
-    .where(eq(sandboxes.externalId, externalId))
-    .get();
+export function findByName(db: Db, name: string): SandboxRow | undefined {
+  return db.select().from(sandboxes).where(eq(sandboxes.name, name)).get();
 }
 
-export function findBySandboxId(
-  db: Db,
-  sandboxId: string,
-): SandboxRow | undefined {
-  return db
-    .select()
-    .from(sandboxes)
-    .where(eq(sandboxes.sandboxId, sandboxId))
-    .get();
+export function findById(db: Db, id: string): SandboxRow | undefined {
+  return db.select().from(sandboxes).where(eq(sandboxes.id, id)).get();
 }
 
 /**
@@ -266,27 +234,14 @@ export function findBySandboxId(
  * No lock needed: better-sqlite3 is synchronous and the daemon is a single
  * process, so there is no await point between the read and the write.
  */
-export function transition(
-  db: Db,
-  sandboxId: string,
-  to: SandboxState,
-): SandboxRow {
-  const row = db
-    .select()
-    .from(sandboxes)
-    .where(eq(sandboxes.sandboxId, sandboxId))
-    .get();
+export function transition(db: Db, id: string, to: SandboxState): SandboxRow {
+  const row = db.select().from(sandboxes).where(eq(sandboxes.id, id)).get();
   if (!row) {
-    throw new Error(`sandbox ${sandboxId} not found`);
+    throw new Error(`sandbox ${id} not found`);
   }
   if (!ALLOWED_TRANSITIONS[row.state].includes(to)) {
-    throw new Error(
-      `illegal transition ${row.state} -> ${to} (sandbox ${sandboxId})`,
-    );
+    throw new Error(`illegal transition ${row.state} -> ${to} (sandbox ${id})`);
   }
-  db.update(sandboxes)
-    .set({ state: to })
-    .where(eq(sandboxes.sandboxId, sandboxId))
-    .run();
+  db.update(sandboxes).set({ state: to }).where(eq(sandboxes.id, id)).run();
   return { ...row, state: to };
 }
diff --git a/packages/server/src/db/metrics.ts b/packages/server/src/db/metrics.ts
index 0f005ce..4361535 100644
--- a/packages/server/src/db/metrics.ts
+++ b/packages/server/src/db/metrics.ts
@@ -70,11 +70,11 @@ export function insertMetricsTick(db: Db, input: MetricsTickInput): void {
     if (input.samples.length > 0) {
       const liveIds = new Set(
         tx
-          .select({ sandboxId: sandboxes.sandboxId })
+          .select({ sandboxId: sandboxes.id })
           .from(sandboxes)
           .where(
             inArray(
-              sandboxes.sandboxId,
+              sandboxes.id,
               input.samples.map((s) => s.sandboxId),
             ),
           )
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index 9746867..ed5eb7e 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -19,9 +19,9 @@ import {
  */
 export const sandboxes = sqliteTable('sandboxes', {
   /** UUID, never an autoincrement — ids must stay unique across machines. */
-  sandboxId: text('sandbox_id').primaryKey(),
-  /** The key acquire() is idempotent on: one sandbox per external id. */
-  externalId: text('external_id').notNull().unique(),
+  id: text('id').primaryKey(),
+  /** The caller-chosen name acquire() is idempotent on: one sandbox per name. */
+  name: text('name').notNull().unique(),
   state: text('state', { enum: SANDBOX_STATES }).notNull(),
   nodeId: text('node_id').notNull(),
   freezeAfterSeconds: integer('freeze_after_seconds').notNull(),
@@ -96,7 +96,7 @@ export const activity = sqliteTable('activity', {
   at: text('at').notNull(),
   kind: text('kind', { enum: ACTIVITY_KINDS }).notNull(),
   /** Null for events with no owning sandbox (orphan sweeps, daemon start). */
-  externalId: text('external_id'),
+  sandboxName: text('sandbox_name'),
   sandboxId: text('sandbox_id'),
   detail: text('detail').notNull(),
 });
@@ -116,10 +116,11 @@ export type ActivityRow = typeof activity.$inferSelect;
  * (DORMICE_METRICS_RETENTION_HOURS vs a fixed 30 days) and deletion path
  * (destroy cascades here, never there).
  *
- * Keyed by sandboxId, not externalId: rebuild replaces the shell but keeps
- * the sandboxId, so history stays continuous across rebuilds; destroy
- * deletes by the same key. No autoincrement id — rows have no "Nth entry"
- * meaning (unlike the activity ring, where id IS the ring position).
+ * Keyed by the sandbox's platform id, not its name: rebuild replaces the
+ * shell but keeps the id, so history stays continuous across rebuilds;
+ * destroy deletes by the same key. No autoincrement id of its own — rows
+ * have no "Nth entry" meaning (unlike the activity ring, where id IS the
+ * ring position).
  */
 export const sandboxMetricsSamples = sqliteTable(
   'sandbox_metrics_samples',
diff --git a/packages/server/src/db/templates.ts b/packages/server/src/db/templates.ts
index 0b34f83..4a22464 100644
--- a/packages/server/src/db/templates.ts
+++ b/packages/server/src/db/templates.ts
@@ -54,16 +54,16 @@ export function removeTemplate(db: Db, name: string): boolean {
 }
 
 /**
- * External ids of sandboxes still created from this template — removal is
+ * Names of sandboxes still created from this template — removal is
  * refused while this is non-empty, so wakes never resolve a dangling name.
  */
-export function externalIdsUsingTemplate(db: Db, name: string): string[] {
+export function sandboxNamesUsingTemplate(db: Db, name: string): string[] {
   return db
-    .select({ externalId: sandboxes.externalId })
+    .select({ name: sandboxes.name })
     .from(sandboxes)
     .where(eq(sandboxes.template, name))
     .all()
-    .map((row) => row.externalId);
+    .map((row) => row.name);
 }
 
 /**
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 4a21893..f089376 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -11,7 +11,7 @@ import { MemStore } from '../archive/mem-store';
 import { objectKey } from '../archive/store';
 import { loadConfig } from '../config';
 import { migrateDb, openDb } from '../db/db';
-import { findBySandboxId, setDeadline } from '../db/ledger';
+import { findById, setDeadline } from '../db/ledger';
 import { getOrCreateSigningSecret } from '../db/secrets';
 import { FAKE_BASE_IMAGE, FakeExecutor } from '../executor/fake';
 import { KeyedQueue } from '../keyed-queue';
@@ -259,13 +259,13 @@ describe('E2B control plane', () => {
     expect(t.executor.stateOf(first.sandboxID)).toBe('running');
   });
 
-  it('metadata.externalId is the Dormice extension: same key, same sandbox', async () => {
+  it('metadata.name is the Dormice extension: same key, same sandbox', async () => {
     const t = testApp();
     const first = await createSandbox(t, {
-      metadata: { externalId: 'agent-7' },
+      metadata: { name: 'agent-7' },
     });
     const second = await createSandbox(t, {
-      metadata: { externalId: 'agent-7' },
+      metadata: { name: 'agent-7' },
     });
     expect(second.sandboxID).toBe(first.sandboxID);
   });
@@ -274,13 +274,13 @@ describe('E2B control plane', () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t, {
       timeout: 600,
-      metadata: { externalId: 'meta-echo', team: 'blue' },
+      metadata: { name: 'meta-echo', team: 'blue' },
     });
     const res = await control(t, 'GET', `/sandboxes/${sandboxID}`);
     expect(res.statusCode).toBe(200);
     const info = res.json();
     expect(info.state).toBe('running');
-    expect(info.metadata).toEqual({ externalId: 'meta-echo', team: 'blue' });
+    expect(info.metadata).toEqual({ name: 'meta-echo', team: 'blue' });
     const endInMs = Date.parse(info.endAt) - Date.now();
     expect(endInMs).toBeGreaterThan(590_000);
     expect(endInMs).toBeLessThan(610_000);
@@ -333,7 +333,7 @@ describe('E2B control plane', () => {
     expect(killed.statusCode).toBe(204);
     expect(t.executor.stateOf(sandboxID)).toBeUndefined();
     expect(await t.executor.listDisks()).not.toContain(sandboxID);
-    expect(findBySandboxId(t.db, sandboxID)).toBeUndefined();
+    expect(findById(t.db, sandboxID)).toBeUndefined();
 
     const again = await control(t, 'DELETE', `/sandboxes/${sandboxID}`);
     expect(again.statusCode).toBe(404);
@@ -344,7 +344,7 @@ describe('E2B control plane', () => {
   it('an expired kill-deadline is protocol-dead immediately, reaped by the scanner after', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t, { timeout: 300 });
-    const row = findBySandboxId(t.db, sandboxID);
+    const row = findById(t.db, sandboxID);
     expect(row?.onDeadline).toBe('kill');
     // Time-travel the deadline into the past instead of sleeping.
     setDeadline(t.db, sandboxID, {
@@ -398,7 +398,7 @@ describe('E2B control plane', () => {
 
     const info = await control(t, 'GET', `/sandboxes/${sandboxID}`);
     expect(info.json().state).toBe('running');
-    const fresh = findBySandboxId(t.db, sandboxID);
+    const fresh = findById(t.db, sandboxID);
     expect(Date.parse(fresh?.deadlineAt ?? '')).toBeGreaterThan(Date.now());
   });
 
@@ -440,7 +440,7 @@ describe('E2B control plane', () => {
     });
     expect(res.statusCode).toBe(204);
     expect(t.executor.stateOf(sandboxID)).toBe('stopped');
-    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('stopped');
+    expect(findById(t.db, sandboxID)?.state).toBe('stopped');
   });
 
   it('metrics with no history takes one live reading, SDK field names', async () => {
@@ -518,7 +518,7 @@ describe('E2B control plane', () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t, { timeout: 86400 });
     // Freeze through the idle scanner, exactly like production.
-    const row = findBySandboxId(t.db, sandboxID);
+    const row = findById(t.db, sandboxID);
     const later = new Date(
       Date.now() + ((row?.freezeAfterSeconds ?? 0) + 60) * 1000,
     );
@@ -607,16 +607,16 @@ describe('E2B control plane', () => {
       method: 'POST',
       url: '/acquireSandbox',
       headers: { authorization: `Bearer ${TOKEN}` },
-      payload: { externalId: 'native-immortal' },
+      payload: { name: 'native-immortal' },
     });
-    const sandboxId = native.json().sandbox.sandboxId;
+    const sandboxId = native.json().sandbox.id;
 
     const res = await control(t, 'POST', `/sandboxes/${sandboxId}/timeout`, {
       timeout: 60,
     });
     expect(res.statusCode).toBe(204);
     // Accepted but not applied: immortality is the owner's choice.
-    expect(findBySandboxId(t.db, sandboxId)?.deadlineAt).toBeNull();
+    expect(findById(t.db, sandboxId)?.deadlineAt).toBeNull();
   });
 });
 
@@ -1248,7 +1248,7 @@ describe('E2B envd surface', () => {
 
     // The idle scanner, told it is an hour later, freezes the sandbox —
     // no heartbeat outlives its stream; only attached streams keep warmth.
-    const row = findBySandboxId(t.db, sandboxID);
+    const row = findById(t.db, sandboxID);
     const later = new Date(
       Date.now() + ((row?.freezeAfterSeconds ?? 0) + 60) * 1000,
     );
@@ -1362,7 +1362,7 @@ describe('E2B envd surface', () => {
     const pending = watchDir(t, sandboxID, { path: '/home/user' }, 600);
     setTimeout(() => {
       void (async () => {
-        const row = findBySandboxId(t.db, sandboxID);
+        const row = findById(t.db, sandboxID);
         const later = new Date(
           Date.now() + ((row?.freezeAfterSeconds ?? 0) + 60) * 1000,
         );
@@ -1684,7 +1684,7 @@ describe('signed file URLs at the daemon root', () => {
       timeout: 86400,
     });
     await putFile(t, sandboxID, 'frozen.txt', 'still here\n');
-    const row = findBySandboxId(t.db, sandboxID);
+    const row = findById(t.db, sandboxID);
     const later = new Date(
       Date.now() + ((row?.freezeAfterSeconds ?? 0) + 60) * 1000,
     );
@@ -1800,20 +1800,20 @@ describe('E2B templates', () => {
     }
   });
 
-  it('externalId reuse keeps the original template; an unknown one still 404s first', async () => {
+  it('name reuse keeps the original template; an unknown one still 404s first', async () => {
     const t = testApp();
     await registerTemplate(t, 'tpl-a', 'img-a');
     await registerTemplate(t, 'tpl-b', 'img-b');
     const first = await createSandbox(t, {
       templateID: 'tpl-a',
-      metadata: { externalId: 'alice' },
+      metadata: { name: 'alice' },
     });
 
     // Same key, different template: the stored one stays — same principle
     // as metadata and envs on the reuse path.
     const again = await control(t, 'POST', '/sandboxes', {
       templateID: 'tpl-b',
-      metadata: { externalId: 'alice' },
+      metadata: { name: 'alice' },
     });
     expect(again.statusCode).toBe(201);
     expect(again.json().sandboxID).toBe(first.sandboxID);
@@ -1822,7 +1822,7 @@ describe('E2B templates', () => {
     // Validation happens before the reuse shortcut: a typo is a typo.
     const typo = await control(t, 'POST', '/sandboxes', {
       templateID: 'ghost',
-      metadata: { externalId: 'alice' },
+      metadata: { name: 'alice' },
     });
     expect(typo.statusCode).toBe(404);
   });
@@ -1832,7 +1832,7 @@ describe('E2B templates', () => {
     await registerTemplate(t, 'py311', 'img-py');
     await createSandbox(t, {
       templateID: 'py311',
-      metadata: { externalId: 'tpl-list' },
+      metadata: { name: 'tpl-list' },
     });
     const res = await control(t, 'GET', '/v2/sandboxes');
     const items = res.json() as Array<{ templateID: string; alias?: string }>;
@@ -1880,7 +1880,7 @@ describe('E2B surface vs the archiver', () => {
     t: ReturnType<typeof archiverTestApp>,
     sandboxID: string,
   ): Promise<void> {
-    const row = findBySandboxId(t.db, sandboxID);
+    const row = findById(t.db, sandboxID);
     if (!row) throw new Error('row missing');
     const at = (s: number) => new Date(Date.parse(row.lastActiveAt) + s * 1000);
     // The scanner sweeps travel in time, but e2bView reads the ledger's
@@ -1895,7 +1895,7 @@ describe('E2B surface vs the archiver', () => {
     await scanOnce(t.db, t.executor, t.locks, at(300), t.archiver);
     await scanOnce(t.db, t.executor, t.locks, at(3 * 86400), t.archiver);
     await scanOnce(t.db, t.executor, t.locks, at(7 * 86400), t.archiver);
-    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('archived');
+    expect(findById(t.db, sandboxID)?.state).toBe('archived');
     expect(t.store.has(objectKey(sandboxID))).toBe(true);
   }
 
@@ -1936,7 +1936,7 @@ describe('E2B surface vs the archiver', () => {
       path: '/home/user',
     });
     expect(stat.statusCode).toBe(502);
-    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('archived');
+    expect(findById(t.db, sandboxID)?.state).toBe('archived');
     expect(t.store.has(objectKey(sandboxID))).toBe(true);
   });
 
@@ -1950,7 +1950,7 @@ describe('E2B surface vs the archiver', () => {
       url: '/acquireSandbox',
       headers: { authorization: `Bearer ${TOKEN}` },
       payload: {
-        externalId: 'native',
+        name: 'native',
         policy: {
           freezeAfterSeconds: 1,
           stopAfterSeconds: 2,
@@ -1958,33 +1958,33 @@ describe('E2B surface vs the archiver', () => {
         },
       },
     });
-    const sandboxID = acquired.json().sandbox.sandboxId as string;
-    const row = findBySandboxId(t.db, sandboxID);
+    const sandboxID = acquired.json().sandbox.id as string;
+    const row = findById(t.db, sandboxID);
     if (!row) throw new Error('row missing');
     const at = (s: number) => new Date(Date.parse(row.lastActiveAt) + s * 1000);
     await scanOnce(t.db, t.executor, t.locks, at(1), t.archiver);
     await scanOnce(t.db, t.executor, t.locks, at(2), t.archiver);
     await scanOnce(t.db, t.executor, t.locks, at(3), t.archiver);
-    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('archived');
+    expect(findById(t.db, sandboxID)?.state).toBe('archived');
 
     const stat = await envdRpc(t, sandboxID, '/filesystem.Filesystem/Stat', {
       path: '/home/user',
     });
     expect(stat.statusCode).toBe(200);
     expect(t.executor.stateOf(sandboxID)).toBe('running');
-    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('active');
+    expect(findById(t.db, sandboxID)?.state).toBe('active');
   });
 
-  it('create with metadata.externalId resumes its archived sandbox', async () => {
+  it('create with metadata.name resumes its archived sandbox', async () => {
     const t = archiverTestApp();
     const first = await createSandbox(t, {
       autoPause: true,
-      metadata: { externalId: 'alice' },
+      metadata: { name: 'alice' },
     });
     await walkToArchived(t, first.sandboxID);
 
     const res = await control(t, 'POST', '/sandboxes', {
-      metadata: { externalId: 'alice' },
+      metadata: { name: 'alice' },
     });
     expect(res.statusCode).toBe(201);
     expect(res.json().sandboxID).toBe(first.sandboxID);
@@ -1999,7 +1999,7 @@ describe('E2B surface vs the archiver', () => {
     const res = await control(t, 'DELETE', `/sandboxes/${sandboxID}`);
     expect(res.statusCode).toBe(204);
     expect(t.store.has(objectKey(sandboxID))).toBe(false);
-    expect(findBySandboxId(t.db, sandboxID)).toBeUndefined();
+    expect(findById(t.db, sandboxID)).toBeUndefined();
   });
 
   it('kill mid-restore joins the task first, then deletes', async () => {
@@ -2016,10 +2016,10 @@ describe('E2B surface vs the archiver', () => {
       await gate;
       return innerGet(key, dest, onProgress);
     };
-    const row = findBySandboxId(t.db, sandboxID);
+    const row = findById(t.db, sandboxID);
     if (!row) throw new Error('row missing');
     t.archiver.beginRestore(row);
-    expect(findBySandboxId(t.db, sandboxID)?.state).toBe('restoring');
+    expect(findById(t.db, sandboxID)?.state).toBe('restoring');
 
     const del = control(t, 'DELETE', `/sandboxes/${sandboxID}`);
     // Let the DELETE reach its join, then release the download.
@@ -2028,6 +2028,6 @@ describe('E2B surface vs the archiver', () => {
     const res = await del;
     expect(res.statusCode).toBe(204);
     expect(t.store.has(objectKey(sandboxID))).toBe(false);
-    expect(findBySandboxId(t.db, sandboxID)).toBeUndefined();
+    expect(findById(t.db, sandboxID)).toBeUndefined();
   });
 });
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index e3e69be..6b9f6f0 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -5,8 +5,8 @@ import { z } from 'zod';
 import {
   countSandboxes,
   createSandbox,
-  findByExternalId,
-  findBySandboxId,
+  findById,
+  findByName,
   listSandboxes,
   setDeadline,
   setPausedByUser,
@@ -41,11 +41,11 @@ import { e2bView } from './view';
  * The E2B control plane: what the official SDK calls api.e2b.app for.
  * Mounted under /e2b/api; the SDK reaches it through its `apiUrl` option.
  * Faithful by default — timeouts kill, kill destroys; Dormice's immortality
- * is opt-in via metadata.externalId (idempotent create) or autoPause.
+ * is opt-in via metadata.name (idempotent create) or autoPause.
  */
 
-/** The Dormice extension key: metadata.externalId makes create idempotent. */
-const EXTERNAL_ID_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/;
+/** The Dormice extension key: metadata.name makes create idempotent. */
+const SANDBOX_NAME_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/;
 
 /** Seconds; E2B's default sandbox TTL. */
 const DEFAULT_TIMEOUT_SECONDS = 300;
@@ -117,15 +117,15 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     if (!archiver) {
       throw apiError(
         502,
-        `sandbox "${row.sandboxId}" is archived but the daemon has no S3 configured (DORMICE_S3_*)`,
+        `sandbox "${row.id}" is archived but the daemon has no S3 configured (DORMICE_S3_*)`,
       );
     }
     try {
-      await archiver.restoreJoin(row.sandboxId);
+      await archiver.restoreJoin(row.id);
     } catch (error) {
       throw apiError(
         502,
-        `restoring sandbox "${row.sandboxId}" failed: ${error instanceof Error ? error.message : String(error)} — retry`,
+        `restoring sandbox "${row.id}" failed: ${error instanceof Error ? error.message : String(error)} — retry`,
       );
     }
   }
@@ -181,7 +181,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   /** What create and connect answer with. */
   function sessionView(row: SandboxRow) {
     return {
-      sandboxID: row.sandboxId,
+      sandboxID: row.id,
       // The node identity. The JS SDK never reads this field, but the
       // Python SDK's generated models hard-require it on every sandbox
       // response — its absence is a KeyError before user code runs
@@ -189,7 +189,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       clientID: row.nodeId,
       ...templateFields(row),
       envdVersion: ENVD_VERSION,
-      envdAccessToken: mintEnvdToken(envdSigningSecret, row.sandboxId),
+      envdAccessToken: mintEnvdToken(envdSigningSecret, row.id),
       ...domainField,
     };
   }
@@ -197,7 +197,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   /** What getInfo and list answer with. */
   function infoView(row: SandboxRow, state: 'running' | 'paused') {
     return {
-      sandboxID: row.sandboxId,
+      sandboxID: row.id,
       // Required by the Python SDK's models, like clientID above.
       clientID: row.nodeId,
       ...templateFields(row),
@@ -227,7 +227,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     row: SandboxRow;
     state: 'running' | 'paused';
   } {
-    const row = findBySandboxId(db, sandboxId);
+    const row = findById(db, sandboxId);
     if (!row) throw notFound(sandboxId);
     const state = e2bView(row, new Date());
     if (state === 'dead') throw notFound(sandboxId);
@@ -245,7 +245,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     const candidate = Date.now() + timeoutSeconds * 1000;
     const current = row.deadlineAt ? Date.parse(row.deadlineAt) : 0;
     if (candidate > current) {
-      setDeadline(db, row.sandboxId, {
+      setDeadline(db, row.id, {
         deadlineAt: new Date(candidate).toISOString(),
         onDeadline: row.onDeadline,
       });
@@ -258,22 +258,22 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     async (request, reply) => {
       const body = request.body;
       const timeoutSeconds = body.timeout ?? DEFAULT_TIMEOUT_SECONDS;
-      const requestedKey = body.metadata?.externalId;
+      const requestedKey = body.metadata?.name;
       if (
         requestedKey !== undefined &&
-        !EXTERNAL_ID_PATTERN.test(requestedKey)
+        !SANDBOX_NAME_PATTERN.test(requestedKey)
       ) {
         throw apiError(
           400,
-          `invalid metadata.externalId "${requestedKey}": expected 1-64 chars of [a-zA-Z0-9._-]`,
+          `invalid metadata.name "${requestedKey}": expected 1-64 chars of [a-zA-Z0-9._-]`,
         );
       }
-      const externalId = requestedKey ?? `e2b-${randomUUID()}`;
+      const name = requestedKey ?? `e2b-${randomUUID()}`;
 
-      // The externalId reuse path may find an archived sandbox; the join
+      // The name-reuse path may find an archived sandbox; the join
       // brings it back before the slot work below wakes it as usual.
       if (requestedKey !== undefined) {
-        await joinRestore(findByExternalId(db, requestedKey));
+        await joinRestore(findByName(db, requestedKey));
       }
 
       // templateID resolution: a registered name wins; 'base', the base
@@ -293,8 +293,8 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         }
       }
 
-      const row = await locks.run(externalId, async () => {
-        const existing = findByExternalId(db, externalId);
+      const row = await locks.run(name, async () => {
+        const existing = findByName(db, name);
         if (existing && e2bView(existing, new Date()) !== 'dead') {
           // The Dormice extension: same key, same sandbox — an acquire in
           // E2B clothes. Stored metadata/envs stay (same principle as the
@@ -302,7 +302,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
           // deadline is extended like a connect.
           const awake = await wakeSandbox(db, executor, existing);
           extendDeadline(awake, timeoutSeconds);
-          return touch(db, awake.sandboxId);
+          return touch(db, awake.id);
         }
         if (existing) {
           // Protocol-dead but not yet reaped: E2B semantics say it is gone,
@@ -310,7 +310,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
           await destroySandbox(
             db,
             executor,
-            existing.sandboxId,
+            existing.id,
             archiver?.store ?? null,
             {
               kind: 'destroyed',
@@ -325,13 +325,13 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
             `sandbox limit reached (DORMICE_MAX_SANDBOXES=${config.DORMICE_MAX_SANDBOXES}) — destroy a sandbox or raise the limit`,
           );
         }
-        const sandboxId = randomUUID();
-        await executor.create(sandboxId, {
+        const id = randomUUID();
+        await executor.create(id, {
           image: resolveImage(db, template),
         });
         return createSandbox(db, {
-          sandboxId,
-          externalId,
+          id,
+          name,
           nodeId: config.DORMICE_NODE_ID,
           policy: resolvePolicy(undefined, archiveDefaultSeconds),
           template,
@@ -367,14 +367,14 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       // then finds it active and the wake below is a no-op. Blocking is the
       // faithful behavior: E2B's connect returns a live sandbox, period.
       await joinRestore(before.row);
-      const row = await locks.run(before.row.externalId, async () => {
-        const fresh = findBySandboxId(db, id);
+      const row = await locks.run(before.row.name, async () => {
+        const fresh = findById(db, id);
         if (!fresh || e2bView(fresh, new Date()) === 'dead') {
           throw notFound(id);
         }
         const awake = await wakeSandbox(db, executor, fresh);
         extendDeadline(awake, request.body.timeout ?? DEFAULT_TIMEOUT_SECONDS);
-        return touch(db, awake.sandboxId);
+        return touch(db, awake.id);
       });
       // 200 = it was already running, 201 = this connect resumed it.
       return reply
@@ -444,7 +444,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         3600_000,
         now,
       );
-      const rows = querySandboxSamples(db, row.sandboxId, startIso, endIso);
+      const rows = querySandboxSamples(db, row.id, startIso, endIso);
       const bucketSeconds = resolveBucketSeconds(rows.length, startMs, endMs);
       const sliced =
         bucketSeconds === null
@@ -474,7 +474,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       const windowIncludesNow =
         now.getTime() >= startMs && now.getTime() <= endMs;
       if (!measurable || !windowIncludesNow) return [];
-      const m = await executor.metrics(row.sandboxId);
+      const m = await executor.metrics(row.id);
       return [
         {
           timestamp: now.toISOString(),
@@ -494,7 +494,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   app.delete('/sandboxes/:id', async (request, reply) => {
     const { id } = request.params as { id: string };
     // kill = destroy, for real: container, disk and row gone. Persistence
-    // on the E2B surface is "don't kill" (autoPause / externalId), never a
+    // on the E2B surface is "don't kill" (autoPause / metadata.name), never a
     // kill that secretly keeps data.
     const { row } = findLive(id);
     if (row.state === 'restoring') {
@@ -504,16 +504,13 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       // whose destroy below deletes the S3 object.
       await archiver?.restoreJoin(id).catch(() => {});
     }
-    await locks.run(row.externalId, async () => {
-      const fresh = findBySandboxId(db, id);
+    await locks.run(row.name, async () => {
+      const fresh = findById(db, id);
       if (!fresh) throw notFound(id);
-      await destroySandbox(
-        db,
-        executor,
-        fresh.sandboxId,
-        archiver?.store ?? null,
-        { kind: 'destroyed', cause: 'via E2B kill' },
-      );
+      await destroySandbox(db, executor, fresh.id, archiver?.store ?? null, {
+        kind: 'destroyed',
+        cause: 'via E2B kill',
+      });
     });
     return reply.code(204).send();
   });
@@ -527,7 +524,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       // setTimeout overwrites in both directions, measured from now — but
       // only for E2B-created sandboxes; native ones stay immortal.
       if (row.onDeadline !== null) {
-        setDeadline(db, row.sandboxId, {
+        setDeadline(db, row.id, {
           deadlineAt: new Date(
             Date.now() + request.body.timeout * 1000,
           ).toISOString(),
@@ -548,15 +545,15 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         // The SDK reads a 409 as "already paused" and answers false.
         throw apiError(409, 'sandbox is already paused');
       }
-      await locks.run(before.row.externalId, async () => {
-        const fresh = findBySandboxId(db, id);
+      await locks.run(before.row.name, async () => {
+        const fresh = findById(db, id);
         if (!fresh) throw notFound(id);
         let current = fresh;
         if (current.state === 'active') {
           current = await freezeSandbox(
             db,
             executor,
-            current.sandboxId,
+            current.id,
             'paused via E2B',
           );
         }
@@ -566,11 +563,11 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
           await stopSandbox(
             db,
             executor,
-            current.sandboxId,
+            current.id,
             'paused via E2B (memory discarded)',
           );
         }
-        setPausedByUser(db, fresh.sandboxId, true);
+        setPausedByUser(db, fresh.id, true);
       });
       return reply.code(204).send();
     },
diff --git a/packages/server/src/e2b/envd/files.ts b/packages/server/src/e2b/envd/files.ts
index 3350404..06353ad 100644
--- a/packages/server/src/e2b/envd/files.ts
+++ b/packages/server/src/e2b/envd/files.ts
@@ -52,15 +52,11 @@ export async function serveFileDownload(
   // vetted before anything wakes.
   const user = vetUsername(query.username);
   const row = await ctx.wakeForUse(sandboxId);
-  const stopHeartbeat = startExecHeartbeat(
-    db,
-    row.sandboxId,
-    row.freezeAfterSeconds,
-  );
+  const stopHeartbeat = startExecHeartbeat(db, row.id, row.freezeAfterSeconds);
   try {
     let entry: SandboxEntry;
     try {
-      entry = await executor.statEntry(row.sandboxId, query.path, user);
+      entry = await executor.statEntry(row.id, query.path, user);
       if (entry.type !== 'file') {
         throw new NotAFileError(`not a regular file: ${entry.path}`);
       }
@@ -81,7 +77,7 @@ export async function serveFileDownload(
       'content-length': String(entry.sizeBytes),
     });
     await executor.readFileStream(
-      row.sandboxId,
+      row.id,
       query.path,
       (chunk) => {
         if (!reply.raw.write(chunk)) {
@@ -107,7 +103,7 @@ export async function serveFileDownload(
   } finally {
     stopHeartbeat();
     try {
-      touch(db, row.sandboxId);
+      touch(db, row.id);
     } catch {
       // Released mid-transfer; the transfer's own error tells the story.
     }
@@ -124,16 +120,12 @@ export async function serveFileUpload(
   const query = request.query as { path?: string; username?: string };
   const user = vetUsername(query.username);
   const row = await ctx.wakeForUse(sandboxId);
-  const stopHeartbeat = startExecHeartbeat(
-    db,
-    row.sandboxId,
-    row.freezeAfterSeconds,
-  );
+  const stopHeartbeat = startExecHeartbeat(db, row.id, row.freezeAfterSeconds);
   try {
     const written: Array<{ name: string; type: 'file'; path: string }> = [];
     const writeOne = async (path: string, content: NodeJS.ReadableStream) => {
       try {
-        await executor.writeFileStream(row.sandboxId, path, content, user);
+        await executor.writeFileStream(row.id, path, content, user);
       } catch (error) {
         if (error instanceof NotAFileError) {
           throw new E2bError(400, 'invalid_argument', error.message);
@@ -187,7 +179,7 @@ export async function serveFileUpload(
   } finally {
     stopHeartbeat();
     try {
-      touch(db, row.sandboxId);
+      touch(db, row.id);
     } catch {
       // Released mid-upload; the upload's own result tells the story.
     }
diff --git a/packages/server/src/e2b/envd/filesystem.ts b/packages/server/src/e2b/envd/filesystem.ts
index c33e366..bc41423 100644
--- a/packages/server/src/e2b/envd/filesystem.ts
+++ b/packages/server/src/e2b/envd/filesystem.ts
@@ -56,7 +56,7 @@ export function registerFilesystemRoutes(
     if (!body.path) throw connectError('invalid_argument', 'missing path');
     const user = vetUsername(usernameOf(request));
     const entry = await ctx.inSlot(sandboxIdOf(request), (row) =>
-      executor.statEntry(row.sandboxId, body.path as string, user),
+      executor.statEntry(row.id, body.path as string, user),
     );
     return { entry: entryInfoJson(entry) };
   });
@@ -70,7 +70,7 @@ export function registerFilesystemRoutes(
     }
     const user = vetUsername(usernameOf(request));
     const entries = await ctx.inSlot(sandboxIdOf(request), (row) =>
-      executor.listDir(row.sandboxId, body.path as string, depth, user),
+      executor.listDir(row.id, body.path as string, depth, user),
     );
     return { entries: entries.map(entryInfoJson) };
   });
@@ -80,11 +80,7 @@ export function registerFilesystemRoutes(
     if (!body.path) throw connectError('invalid_argument', 'missing path');
     const user = vetUsername(usernameOf(request));
     const entry = await ctx.inSlot(sandboxIdOf(request), async (row) => {
-      const created = await executor.makeDir(
-        row.sandboxId,
-        body.path as string,
-        user,
-      );
+      const created = await executor.makeDir(row.id, body.path as string, user);
       if (!created) {
         // The SDK reads already_exists as makeDir() === false.
         throw connectError(
@@ -92,7 +88,7 @@ export function registerFilesystemRoutes(
           `already exists: ${resolveSandboxPath(body.path as string)}`,
         );
       }
-      return executor.statEntry(row.sandboxId, body.path as string, user);
+      return executor.statEntry(row.id, body.path as string, user);
     });
     return { entry: entryInfoJson(entry) };
   });
@@ -105,7 +101,7 @@ export function registerFilesystemRoutes(
     const user = vetUsername(usernameOf(request));
     const entry = await ctx.inSlot(sandboxIdOf(request), (row) =>
       executor.move(
-        row.sandboxId,
+        row.id,
         body.source as string,
         body.destination as string,
         user,
@@ -119,7 +115,7 @@ export function registerFilesystemRoutes(
     if (!body.path) throw connectError('invalid_argument', 'missing path');
     const user = vetUsername(usernameOf(request));
     await ctx.inSlot(sandboxIdOf(request), (row) =>
-      executor.remove(row.sandboxId, body.path as string, user),
+      executor.remove(row.id, body.path as string, user),
     );
     return {};
   });
diff --git a/packages/server/src/e2b/envd/index.ts b/packages/server/src/e2b/envd/index.ts
index d7648c6..6a4cb82 100644
--- a/packages/server/src/e2b/envd/index.ts
+++ b/packages/server/src/e2b/envd/index.ts
@@ -1,6 +1,6 @@
 import multipart from '@fastify/multipart';
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
-import { findBySandboxId } from '../../db/ledger';
+import { findById } from '../../db/ledger';
 import type { E2bDeps } from '../deps';
 import { E2bError, verifyEnvdToken } from '../protocol';
 import { e2bView } from '../view';
@@ -94,7 +94,7 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     // running, the exact signal isRunning() keys on.
     const header = request.headers['e2b-sandbox-id'];
     const id = Array.isArray(header) ? header[0] : header;
-    const row = id ? findBySandboxId(db, id) : undefined;
+    const row = id ? findById(db, id) : undefined;
     if (!row || e2bView(row, new Date()) !== 'running') {
       return reply
         .code(502)
diff --git a/packages/server/src/e2b/envd/process.ts b/packages/server/src/e2b/envd/process.ts
index f4f7751..08e5d56 100644
--- a/packages/server/src/e2b/envd/process.ts
+++ b/packages/server/src/e2b/envd/process.ts
@@ -128,7 +128,7 @@ export function registerProcessRoutes(
     const { request, reply, row, write, done, detach } = args;
     const stopHeartbeat = startExecHeartbeat(
       db,
-      row.sandboxId,
+      row.id,
       row.freezeAfterSeconds,
     );
     // Keepalive events on the interval the SDK asked for — what keeps
@@ -172,7 +172,7 @@ export function registerProcessRoutes(
       try {
         // Watching the command was the activity: the idle countdown starts
         // when the stream detaches, not when it attached.
-        touch(db, row.sandboxId);
+        touch(db, row.id);
       } catch {
         // Released mid-stream; the stream's own ending tells the story.
       }
@@ -193,7 +193,7 @@ export function registerProcessRoutes(
     // Read-only: no wake — looking at the table must not thaw a sandbox.
     const row = ctx.requireRunningRow(sandboxIdOf(request));
     return {
-      processes: processes.list(row.sandboxId).map((record) => ({
+      processes: processes.list(row.id).map((record) => ({
         pid: record.pid,
         // config is echoed verbatim and always complete: the SDK
         // dereferences processes[].config.args unconditionally.
@@ -260,7 +260,7 @@ export function registerProcessRoutes(
     try {
       record = await processes.start({
         executor,
-        sandboxId: row.sandboxId,
+        sandboxId: row.id,
         options: {
           command,
           loginShell,
@@ -315,7 +315,7 @@ export function registerProcessRoutes(
     }
     const row = await ctx.wakeForStream(request, reply);
     if (!row) return;
-    const record = processes.get(row.sandboxId, pid);
+    const record = processes.get(row.id, pid);
     if (!record) {
       return streamError(reply, 'not_found', `process not found: ${pid}`);
     }
@@ -360,7 +360,7 @@ export function registerProcessRoutes(
     };
     const pid = requirePid(body);
     const row = await ctx.wakeForUse(sandboxIdOf(request));
-    const record = requireProcess(row.sandboxId, pid);
+    const record = requireProcess(row.id, pid);
     const stdinB64 = body.input?.stdin;
     const ptyB64 = body.input?.pty;
     if (typeof stdinB64 !== 'string' && typeof ptyB64 !== 'string') {
@@ -392,7 +392,7 @@ export function registerProcessRoutes(
   app.post('/process.Process/CloseStdin', async (request) => {
     const pid = requirePid(request.body);
     const row = await ctx.wakeForUse(sandboxIdOf(request));
-    const record = requireProcess(row.sandboxId, pid);
+    const record = requireProcess(row.id, pid);
     if (!record.stdin) {
       throw connectError(
         'invalid_argument',
@@ -431,7 +431,7 @@ export function registerProcessRoutes(
       );
     }
     const row = await ctx.wakeForUse(sandboxIdOf(request));
-    const record = requireProcess(row.sandboxId, pid);
+    const record = requireProcess(row.id, pid);
     try {
       await record.handle.signal(sig);
     } catch {
@@ -449,7 +449,7 @@ export function registerProcessRoutes(
     };
     const pid = requirePid(body);
     const row = await ctx.wakeForUse(sandboxIdOf(request));
-    const record = requireProcess(row.sandboxId, pid);
+    const record = requireProcess(row.id, pid);
     if (!record.pty) {
       throw connectError('invalid_argument', 'process has no PTY');
     }
diff --git a/packages/server/src/e2b/envd/shared.ts b/packages/server/src/e2b/envd/shared.ts
index d3b89be..c45c4a7 100644
--- a/packages/server/src/e2b/envd/shared.ts
+++ b/packages/server/src/e2b/envd/shared.ts
@@ -1,6 +1,6 @@
 import { Buffer } from 'node:buffer';
 import type { FastifyReply, FastifyRequest } from 'fastify';
-import { findBySandboxId, touch } from '../../db/ledger';
+import { findById, touch } from '../../db/ledger';
 import type { SandboxRow } from '../../db/schema';
 import {
   DiskFullError,
@@ -152,7 +152,7 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
       }
       return;
     }
-    const row = findBySandboxId(db, sandboxId);
+    const row = findById(db, sandboxId);
     if (row && (row.state === 'archived' || row.state === 'restoring')) {
       throw new E2bError(
         502,
@@ -169,7 +169,7 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
    * sandbox feels like.
    */
   function requireRunningRow(sandboxId: string): SandboxRow {
-    const row = findBySandboxId(db, sandboxId);
+    const row = findById(db, sandboxId);
     if (!row) {
       throw new E2bError(502, 'unavailable', 'sandbox not found');
     }
@@ -194,10 +194,10 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
     // will be refused anyway would waste a whole restore.
     const before = requireRunningRow(sandboxId);
     await joinRestore(sandboxId);
-    return locks.run(before.externalId, async () => {
+    return locks.run(before.name, async () => {
       const fresh = requireRunningRow(sandboxId);
       const awake = await wakeSandbox(db, executor, fresh);
-      return touch(db, awake.sandboxId);
+      return touch(db, awake.id);
     });
   }
 
@@ -207,10 +207,10 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
   ): Promise<T> {
     const before = requireRunningRow(sandboxId);
     await joinRestore(sandboxId);
-    return locks.run(before.externalId, async () => {
+    return locks.run(before.name, async () => {
       const fresh = requireRunningRow(sandboxId);
       const awake = await wakeSandbox(db, executor, fresh);
-      const row = touch(db, awake.sandboxId);
+      const row = touch(db, awake.id);
       try {
         return await work(row);
       } catch (error) {
diff --git a/packages/server/src/e2b/envd/watch.ts b/packages/server/src/e2b/envd/watch.ts
index 1d9c842..028bf29 100644
--- a/packages/server/src/e2b/envd/watch.ts
+++ b/packages/server/src/e2b/envd/watch.ts
@@ -95,7 +95,7 @@ export function registerWatchRoutes(
     });
     let watcher: Awaited<ReturnType<typeof executor.watchDir>>;
     try {
-      watcher = await executor.watchDir(row.sandboxId, {
+      watcher = await executor.watchDir(row.id, {
         path: message.path,
         recursive: message.recursive === true,
         onEvent: async (event) => {
@@ -180,7 +180,7 @@ export function registerWatchRoutes(
     try {
       const watcherId = await watchers.create({
         executor,
-        sandboxId: row.sandboxId,
+        sandboxId: row.id,
         path: body.path,
         recursive: body.recursive === true,
       });
@@ -202,7 +202,7 @@ export function registerWatchRoutes(
     // No wake: this reads daemon memory. A frozen sandbox has no new events
     // to report anyway — the disk cannot change while it is frozen.
     const row = ctx.requireRunningRow(sandboxIdOf(request));
-    const events = watchers.drain(row.sandboxId, body.watcherId);
+    const events = watchers.drain(row.id, body.watcherId);
     if (events === undefined) {
       throw connectError(
         'not_found',
@@ -224,7 +224,7 @@ export function registerWatchRoutes(
     }
     // Wakes: stopping the in-container inotifywait needs the container up.
     const row = await ctx.wakeForUse(sandboxIdOf(request));
-    const removed = await watchers.remove(row.sandboxId, body.watcherId);
+    const removed = await watchers.remove(row.id, body.watcherId);
     if (!removed) {
       throw connectError(
         'not_found',
diff --git a/packages/server/src/e2b/signed-files.ts b/packages/server/src/e2b/signed-files.ts
index edc9c51..11985f6 100644
--- a/packages/server/src/e2b/signed-files.ts
+++ b/packages/server/src/e2b/signed-files.ts
@@ -116,11 +116,11 @@ export const signedFileRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
 
   app.get('/files', async (request, reply) => {
     const row = authenticate(request, 'read');
-    return serveFileDownload(ctx, row.sandboxId, request, reply);
+    return serveFileDownload(ctx, row.id, request, reply);
   });
 
   app.post('/files', { bodyLimit: UNLIMITED_BODY_BYTES }, (request, reply) => {
     const row = authenticate(request, 'write');
-    return serveFileUpload(ctx, row.sandboxId, request, reply);
+    return serveFileUpload(ctx, row.id, request, reply);
   });
 };
diff --git a/packages/server/src/e2b/signing.ts b/packages/server/src/e2b/signing.ts
index 1cd73e2..fec3f5d 100644
--- a/packages/server/src/e2b/signing.ts
+++ b/packages/server/src/e2b/signing.ts
@@ -62,7 +62,7 @@ export function findRowBySignature(
   for (const row of listSandboxes(db)) {
     if (e2bView(row, now) === 'dead') continue;
     const expected = fileSignature(
-      mintEnvdToken(signingSecret, row.sandboxId),
+      mintEnvdToken(signingSecret, row.id),
       material,
     );
     if (timingSafeEqual(sha256(expected), sha256(presented))) return row;
diff --git a/packages/server/src/e2b/view.test.ts b/packages/server/src/e2b/view.test.ts
index 208ed03..73583f5 100644
--- a/packages/server/src/e2b/view.test.ts
+++ b/packages/server/src/e2b/view.test.ts
@@ -4,8 +4,8 @@ import { e2bView } from './view';
 
 function row(overrides: Partial<SandboxRow>): SandboxRow {
   return {
-    sandboxId: 'sbx-1',
-    externalId: 'alice',
+    id: 'sbx-1',
+    name: 'alice',
     state: 'active',
     nodeId: 'node-test',
     freezeAfterSeconds: 60,
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index 21f3454..1aa4a95 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -3,7 +3,7 @@ import { recordActivity } from './db/activity';
 import type { Db } from './db/db';
 import {
   deleteSandbox,
-  findBySandboxId,
+  findById,
   setPausedByUser,
   transition,
 } from './db/ledger';
@@ -39,7 +39,7 @@ export async function freezeSandbox(
   const row = transition(db, sandboxId, 'frozen');
   recordActivity(db, {
     kind: 'frozen',
-    externalId: row.externalId,
+    sandboxName: row.name,
     sandboxId,
     detail: cause ?? 'memory squeezed into swap',
   });
@@ -56,7 +56,7 @@ export async function stopSandbox(
   const row = transition(db, sandboxId, 'stopped');
   recordActivity(db, {
     kind: 'stopped',
-    externalId: row.externalId,
+    sandboxName: row.name,
     sandboxId,
     detail: cause ?? 'container torn down, disk kept',
   });
@@ -86,7 +86,7 @@ export async function destroySandbox(
     cause: 'via destroySandbox',
   },
 ): Promise<void> {
-  const row = findBySandboxId(db, sandboxId);
+  const row = findById(db, sandboxId);
   if (row?.state === 'archived') {
     if (store === null) {
       throw new Error(
@@ -100,7 +100,7 @@ export async function destroySandbox(
     deleteSandboxMetricsSamples(db, sandboxId);
     recordActivity(db, {
       kind: activity.kind,
-      externalId: row.externalId,
+      sandboxName: row.name,
       sandboxId,
       detail: `${activity.cause}; archive object deleted`,
     });
@@ -112,7 +112,7 @@ export async function destroySandbox(
   if (row) {
     recordActivity(db, {
       kind: activity.kind,
-      externalId: row.externalId,
+      sandboxName: row.name,
       sandboxId,
       detail: activity.cause,
     });
@@ -134,18 +134,18 @@ export async function rebuildSandbox(
   executor: Executor,
   row: SandboxRow,
 ): Promise<SandboxRow> {
-  await executor.removeContainer(row.sandboxId);
+  await executor.removeContainer(row.id);
   recordActivity(db, {
     kind: 'rebuilt',
-    externalId: row.externalId,
-    sandboxId: row.sandboxId,
+    sandboxName: row.name,
+    sandboxId: row.id,
     detail:
       'shell removed, disk kept — next wake builds from the current image',
   });
   if (row.state === 'stopped') {
     return row;
   }
-  return transition(db, row.sandboxId, 'stopped');
+  return transition(db, row.id, 'stopped');
 }
 
 /** Brings a sandbox in any cold state back to active. No-op when already active. */
@@ -158,12 +158,12 @@ export async function wakeSandbox(
     case 'active':
       return row;
     case 'frozen':
-      await executor.unfreeze(row.sandboxId);
+      await executor.unfreeze(row.id);
       return awaken(db, row, 'from frozen (memory back out of swap)');
     case 'stopped':
       // If the container object was pruned away, start rebuilds the shell —
       // from the template's current image, resolved here at wake time.
-      await executor.start(row.sandboxId, {
+      await executor.start(row.id, {
         image: resolveImage(db, row.template),
       });
       return awaken(db, row, 'cold start from the surviving disk');
@@ -173,7 +173,7 @@ export async function wakeSandbox(
       // (acquire begins a restore, the E2B surface joins one); reaching
       // this arm is a caller bug worth hearing loudly.
       throw new Error(
-        `sandbox ${row.sandboxId} is ${row.state}; restore goes through the archiver — this wake is a caller bug`,
+        `sandbox ${row.id} is ${row.state}; restore goes through the archiver — this wake is a caller bug`,
       );
   }
 }
@@ -185,13 +185,13 @@ export async function wakeSandbox(
  */
 function awaken(db: Db, row: SandboxRow, how: string): SandboxRow {
   if (row.pausedByUser) {
-    setPausedByUser(db, row.sandboxId, false);
+    setPausedByUser(db, row.id, false);
   }
-  const awake = transition(db, row.sandboxId, 'active');
+  const awake = transition(db, row.id, 'active');
   recordActivity(db, {
     kind: 'woken',
-    externalId: row.externalId,
-    sandboxId: row.sandboxId,
+    sandboxName: row.name,
+    sandboxId: row.id,
     detail: how,
   });
   return { ...awake, pausedByUser: false };
diff --git a/packages/server/src/metrics-sampler.test.ts b/packages/server/src/metrics-sampler.test.ts
index 68154ba..6a3fe2c 100644
--- a/packages/server/src/metrics-sampler.test.ts
+++ b/packages/server/src/metrics-sampler.test.ts
@@ -48,15 +48,15 @@ function harness() {
 
 type App = ReturnType<typeof harness>['app'];
 
-async function acquire(app: App, externalId: string) {
+async function acquire(app: App, name: string) {
   const res = await app.inject({
     method: 'POST',
     url: '/acquireSandbox',
     headers: authed,
-    payload: { externalId },
+    payload: { name },
   });
   expect(res.statusCode).toBe(200);
-  return res.json().sandbox as { sandboxId: string };
+  return res.json().sandbox as { id: string };
 }
 
 function sampleRows(db: ReturnType<typeof harness>['db']) {
@@ -72,10 +72,10 @@ describe('sampleOnce', () => {
     const { app, db, executor } = harness();
     await acquire(app, 'hot');
     const napping = await acquire(app, 'napping');
-    await freezeSandbox(db, executor, napping.sandboxId);
+    await freezeSandbox(db, executor, napping.id);
     const cold = await acquire(app, 'cold');
-    await freezeSandbox(db, executor, cold.sandboxId);
-    await stopSandbox(db, executor, cold.sandboxId);
+    await freezeSandbox(db, executor, cold.id);
+    await stopSandbox(db, executor, cold.id);
 
     const now = new Date('2026-07-15T10:00:00.000Z');
     const result = await sampleOnce(db, executor, now, { retentionHours: 168 });
@@ -101,9 +101,7 @@ describe('sampleOnce', () => {
       expect(row.memTotalBytes).toBeGreaterThan(0);
     }
     // Observation is not activity: the frozen sandbox is still frozen.
-    expect((await executor.listContainers()).get(napping.sandboxId)).toBe(
-      'paused',
-    );
+    expect((await executor.listContainers()).get(napping.id)).toBe('paused');
   });
 
   it('skips a vanished container without failing the tick', async () => {
@@ -112,8 +110,8 @@ describe('sampleOnce', () => {
     const doomed = await acquire(app, 'doomed');
     // The container dies physically, past the ledger (gVisor OOM does this
     // for real) — the row still says active, the reading throws.
-    await executor.freeze(doomed.sandboxId);
-    await executor.stop(doomed.sandboxId);
+    await executor.freeze(doomed.id);
+    await executor.stop(doomed.id);
 
     const now = new Date('2026-07-15T10:00:00.000Z');
     const result = await sampleOnce(db, executor, now, { retentionHours: 168 });
@@ -165,13 +163,13 @@ describe('sampleOnce', () => {
       method: 'POST',
       url: '/destroySandbox',
       headers: authed,
-      payload: { externalId: 'victim' },
+      payload: { name: 'victim' },
     });
     expect(res.statusCode).toBe(200);
 
     const remaining = sampleRows(db);
     expect(remaining).toHaveLength(1);
-    expect(remaining[0]?.sandboxId).not.toBe(victim.sandboxId);
+    expect(remaining[0]?.sandboxId).not.toBe(victim.id);
     // Fleet snapshots belong to no sandbox: untouched.
     expect(fleetRows(db)).toHaveLength(1);
   });
diff --git a/packages/server/src/metrics-sampler.ts b/packages/server/src/metrics-sampler.ts
index 5863d0b..33dbc08 100644
--- a/packages/server/src/metrics-sampler.ts
+++ b/packages/server/src/metrics-sampler.ts
@@ -55,8 +55,8 @@ export async function sampleOnce(
       ): Promise<{ sandboxId: string; metrics: SandboxMetrics } | null> => {
         try {
           return {
-            sandboxId: row.sandboxId,
-            metrics: await executor.metrics(row.sandboxId),
+            sandboxId: row.id,
+            metrics: await executor.metrics(row.id),
           };
         } catch {
           return null;
diff --git a/packages/server/src/reconciler.test.ts b/packages/server/src/reconciler.test.ts
index 3862bb5..741bce0 100644
--- a/packages/server/src/reconciler.test.ts
+++ b/packages/server/src/reconciler.test.ts
@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { DEFAULT_LIFECYCLE_POLICY } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { type Db, migrateDb, openDb } from './db/db';
-import { createSandbox, findByExternalId, transition } from './db/ledger';
+import { createSandbox, findByName, transition } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
@@ -34,13 +34,13 @@ function setup() {
 async function seed(
   db: Db,
   executor: FakeExecutor,
-  externalId: string,
+  name: string,
 ): Promise<SandboxRow> {
-  const sandboxId = randomUUID();
-  await executor.create(sandboxId);
+  const id = randomUUID();
+  await executor.create(id);
   return createSandbox(db, {
-    sandboxId,
-    externalId,
+    id,
+    name,
     nodeId: 'node-test',
     policy: DEFAULT_LIFECYCLE_POLICY,
   });
@@ -51,19 +51,19 @@ describe('startup reconcile', () => {
     const { db, executor, locks } = setup();
     const row = await seed(db, executor, 'alice');
     expect(await reconcile(db, executor, locks)).toEqual(NONE);
-    expect(findByExternalId(db, 'alice')?.state).toBe('active');
-    expect(executor.stateOf(row.sandboxId)).toBe('running');
+    expect(findByName(db, 'alice')?.state).toBe('active');
+    expect(executor.stateOf(row.id)).toBe('running');
   });
 
   it('records a freeze the ledger missed', async () => {
     const { db, executor, locks } = setup();
     // Crash between executor.freeze() and transition(): reality moved alone.
     const row = await seed(db, executor, 'alice');
-    await executor.freeze(row.sandboxId);
+    await executor.freeze(row.id);
 
     const result = await reconcile(db, executor, locks);
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByExternalId(db, 'alice')?.state).toBe('frozen');
+    expect(findByName(db, 'alice')?.state).toBe('frozen');
   });
 
   it('repairs across rungs the transition table would forbid', async () => {
@@ -71,12 +71,12 @@ describe('startup reconcile', () => {
     // Ledger says active, container is fully stopped — a two-rung gap that
     // transition() would reject. The reconciler records facts, not moves.
     const row = await seed(db, executor, 'alice');
-    await executor.freeze(row.sandboxId);
-    await executor.stop(row.sandboxId);
+    await executor.freeze(row.id);
+    await executor.stop(row.id);
 
     const result = await reconcile(db, executor, locks);
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
+    expect(findByName(db, 'alice')?.state).toBe('stopped');
   });
 
   it('keeps the row of a pruned container: the disk is the sandbox', async () => {
@@ -85,14 +85,14 @@ describe('startup reconcile', () => {
     // The container object is removed behind the daemon's back (a routine
     // `docker container prune` does this to every exited container) while
     // the disk — the sandbox's actual data — stays.
-    executor.vanishContainer(row.sandboxId);
+    executor.vanishContainer(row.id);
 
     const result = await reconcile(db, executor, locks);
     // Not a death: the sandbox is recorded as stopped, its row keeps the
     // external id, and the next acquire rebuilds the container from the disk.
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
-    expect(await executor.listDisks()).toContain(row.sandboxId);
+    expect(findByName(db, 'alice')?.state).toBe('stopped');
+    expect(await executor.listDisks()).toContain(row.id);
   });
 
   it('deletes the row only when container and disk are both gone', async () => {
@@ -100,12 +100,12 @@ describe('startup reconcile', () => {
     const row = await seed(db, executor, 'alice');
     // The end state of a release that crashed after the executor's work but
     // before the ledger's delete: nothing of the sandbox physically remains.
-    executor.vanishContainer(row.sandboxId);
-    await executor.removeDisk(row.sandboxId);
+    executor.vanishContainer(row.id);
+    await executor.removeDisk(row.id);
 
     const result = await reconcile(db, executor, locks);
     expect(result).toEqual({ ...NONE, deletedRows: 1 });
-    expect(findByExternalId(db, 'alice')).toBeUndefined();
+    expect(findByName(db, 'alice')).toBeUndefined();
   });
 
   it('destroys a container no row points at', async () => {
@@ -125,53 +125,53 @@ describe('startup reconcile', () => {
     // A crash between the archive's ledger write and its local cleanup:
     // the transition to archived IS the upload confirmation, so whatever is
     // still here is a stale copy — the sweep resumes the interrupted job.
-    await executor.freeze(row.sandboxId);
-    await executor.stop(row.sandboxId);
-    transition(db, row.sandboxId, 'frozen');
-    transition(db, row.sandboxId, 'stopped');
-    transition(db, row.sandboxId, 'archived');
+    await executor.freeze(row.id);
+    await executor.stop(row.id);
+    transition(db, row.id, 'frozen');
+    transition(db, row.id, 'stopped');
+    transition(db, row.id, 'archived');
 
     expect(await reconcile(db, executor, locks)).toEqual({
       ...NONE,
       archivedSwept: 1,
     });
-    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
-    expect(executor.stateOf(row.sandboxId)).toBeUndefined();
-    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+    expect(findByName(db, 'alice')?.state).toBe('archived');
+    expect(executor.stateOf(row.id)).toBeUndefined();
+    expect(await executor.listDisks()).not.toContain(row.id);
   });
 
   it('sweeps an archived row whose container is gone but disk remains', async () => {
     const { db, executor, locks } = setup();
     const row = await seed(db, executor, 'alice');
-    await executor.freeze(row.sandboxId);
-    await executor.stop(row.sandboxId);
-    transition(db, row.sandboxId, 'frozen');
-    transition(db, row.sandboxId, 'stopped');
-    transition(db, row.sandboxId, 'archived');
-    executor.vanishContainer(row.sandboxId);
+    await executor.freeze(row.id);
+    await executor.stop(row.id);
+    transition(db, row.id, 'frozen');
+    transition(db, row.id, 'stopped');
+    transition(db, row.id, 'archived');
+    executor.vanishContainer(row.id);
 
     expect(await reconcile(db, executor, locks)).toEqual({
       ...NONE,
       archivedSwept: 1,
     });
-    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
-    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+    expect(findByName(db, 'alice')?.state).toBe('archived');
+    expect(await executor.listDisks()).not.toContain(row.id);
   });
 
   it('leaves a fully-archived row alone — its body is in S3', async () => {
     const { db, executor, locks } = setup();
     const row = await seed(db, executor, 'alice');
-    await executor.freeze(row.sandboxId);
-    await executor.stop(row.sandboxId);
-    transition(db, row.sandboxId, 'frozen');
-    transition(db, row.sandboxId, 'stopped');
-    transition(db, row.sandboxId, 'archived');
-    await executor.destroy(row.sandboxId);
+    await executor.freeze(row.id);
+    await executor.stop(row.id);
+    transition(db, row.id, 'frozen');
+    transition(db, row.id, 'stopped');
+    transition(db, row.id, 'archived');
+    await executor.destroy(row.id);
 
     // Nothing local, and crucially NOT deletedRows: an archived row with no
     // local remains is the normal state, not drift.
     expect(await reconcile(db, executor, locks)).toEqual(NONE);
-    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
+    expect(findByName(db, 'alice')?.state).toBe('archived');
   });
 
   it('reverts a restoring zombie with no live task to archived', async () => {
@@ -179,21 +179,21 @@ describe('startup reconcile', () => {
     const row = await seed(db, executor, 'alice');
     // A crash mid-restore: the row says restoring, a half-extracted disk
     // exists, no container yet — and the tracker (daemon memory) is empty.
-    await executor.freeze(row.sandboxId);
-    await executor.stop(row.sandboxId);
-    transition(db, row.sandboxId, 'frozen');
-    transition(db, row.sandboxId, 'stopped');
-    transition(db, row.sandboxId, 'archived');
-    await executor.destroy(row.sandboxId);
-    executor.plantDiskResidue(row.sandboxId);
-    transition(db, row.sandboxId, 'restoring');
+    await executor.freeze(row.id);
+    await executor.stop(row.id);
+    transition(db, row.id, 'frozen');
+    transition(db, row.id, 'stopped');
+    transition(db, row.id, 'archived');
+    await executor.destroy(row.id);
+    executor.plantDiskResidue(row.id);
+    transition(db, row.id, 'restoring');
 
     const result = await reconcile(db, executor, locks);
     // The disk is the task's garbage; the S3 object is intact, so archived
     // makes the next acquire a clean retry.
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
-    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+    expect(findByName(db, 'alice')?.state).toBe('archived');
+    expect(await executor.listDisks()).not.toContain(row.id);
   });
 
   it('records a restoring zombie whose container runs as active', async () => {
@@ -202,40 +202,40 @@ describe('startup reconcile', () => {
     // A crash between the restore's start() and its ledger write: the
     // restore physically finished. Reality wins — removing the disk under
     // a live container would be the ledger trashing reality.
-    await executor.freeze(row.sandboxId);
-    await executor.stop(row.sandboxId);
-    transition(db, row.sandboxId, 'frozen');
-    transition(db, row.sandboxId, 'stopped');
-    transition(db, row.sandboxId, 'archived');
-    transition(db, row.sandboxId, 'restoring');
-    await executor.start(row.sandboxId);
+    await executor.freeze(row.id);
+    await executor.stop(row.id);
+    transition(db, row.id, 'frozen');
+    transition(db, row.id, 'stopped');
+    transition(db, row.id, 'archived');
+    transition(db, row.id, 'restoring');
+    await executor.start(row.id);
 
     const result = await reconcile(db, executor, locks);
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByExternalId(db, 'alice')?.state).toBe('active');
-    expect(executor.stateOf(row.sandboxId)).toBe('running');
+    expect(findByName(db, 'alice')?.state).toBe('active');
+    expect(executor.stateOf(row.id)).toBe('running');
   });
 
   it('leaves a restoring row with a live task untouched', async () => {
     const { db, executor, locks } = setup();
     const row = await seed(db, executor, 'alice');
-    await executor.freeze(row.sandboxId);
-    await executor.stop(row.sandboxId);
-    transition(db, row.sandboxId, 'frozen');
-    transition(db, row.sandboxId, 'stopped');
-    transition(db, row.sandboxId, 'archived');
-    await executor.destroy(row.sandboxId);
+    await executor.freeze(row.id);
+    await executor.stop(row.id);
+    transition(db, row.id, 'frozen');
+    transition(db, row.id, 'stopped');
+    transition(db, row.id, 'archived');
+    await executor.destroy(row.id);
     // Mid-restore: the task has built half a disk and is still running.
-    executor.plantDiskResidue(row.sandboxId);
-    transition(db, row.sandboxId, 'restoring');
+    executor.plantDiskResidue(row.id);
+    transition(db, row.id, 'restoring');
 
     const result = await reconcile(db, executor, locks, new Set(), {
       hasLiveRestore: () => true,
     });
     expect(result).toEqual(NONE);
-    expect(findByExternalId(db, 'alice')?.state).toBe('restoring');
+    expect(findByName(db, 'alice')?.state).toBe('restoring');
     // The mid-flight disk also dodges the orphan pass: the row owns it.
-    expect(await executor.listDisks()).toContain(row.sandboxId);
+    expect(await executor.listDisks()).toContain(row.id);
   });
 
   it('repairs every sandbox in one pass', async () => {
@@ -244,10 +244,10 @@ describe('startup reconcile', () => {
     const drifted = await seed(db, executor, 'drifted');
     const pruned = await seed(db, executor, 'pruned');
     const dead = await seed(db, executor, 'dead');
-    await executor.freeze(drifted.sandboxId);
-    executor.vanishContainer(pruned.sandboxId);
-    executor.vanishContainer(dead.sandboxId);
-    await executor.removeDisk(dead.sandboxId);
+    await executor.freeze(drifted.id);
+    executor.vanishContainer(pruned.id);
+    executor.vanishContainer(dead.id);
+    await executor.removeDisk(dead.id);
     await executor.create('orphan');
 
     expect(await reconcile(db, executor, locks)).toEqual({
@@ -259,11 +259,11 @@ describe('startup reconcile', () => {
       archivedSwept: 0,
       suspects: [],
     });
-    expect(findByExternalId(db, 'healthy')?.state).toBe('active');
-    expect(findByExternalId(db, 'drifted')?.state).toBe('frozen');
-    expect(findByExternalId(db, 'pruned')?.state).toBe('stopped');
-    expect(findByExternalId(db, 'dead')).toBeUndefined();
-    expect(executor.stateOf(healthy.sandboxId)).toBe('running');
+    expect(findByName(db, 'healthy')?.state).toBe('active');
+    expect(findByName(db, 'drifted')?.state).toBe('frozen');
+    expect(findByName(db, 'pruned')?.state).toBe('stopped');
+    expect(findByName(db, 'dead')).toBeUndefined();
+    expect(executor.stateOf(healthy.id)).toBe('running');
     expect(executor.stateOf('orphan')).toBeUndefined();
   });
 });
@@ -299,8 +299,8 @@ describe('runtime reconcile (two-strike orphans)', () => {
 
     // The acquire finished: the row is in the ledger now.
     createSandbox(db, {
-      sandboxId: 'in-flight',
-      externalId: 'alice',
+      id: 'in-flight',
+      name: 'alice',
       nodeId: 'node-test',
       policy: DEFAULT_LIFECYCLE_POLICY,
     });
@@ -313,25 +313,25 @@ describe('runtime reconcile (two-strike orphans)', () => {
     );
     expect(second).toEqual(NONE);
     expect(executor.stateOf('in-flight')).toBe('running');
-    expect(findByExternalId(db, 'alice')?.state).toBe('active');
+    expect(findByName(db, 'alice')?.state).toBe('active');
   });
 
   it('still repairs and buries on every runtime pass, not only at boot', async () => {
     const { db, executor, locks } = setup();
     const row = await seed(db, executor, 'alice');
-    executor.vanishContainer(row.sandboxId);
-    await executor.removeDisk(row.sandboxId);
+    executor.vanishContainer(row.id);
+    await executor.removeDisk(row.id);
 
     const result = await reconcile(db, executor, locks, new Set());
     expect(result).toEqual({ ...NONE, deletedRows: 1 });
-    expect(findByExternalId(db, 'alice')).toBeUndefined();
+    expect(findByName(db, 'alice')).toBeUndefined();
   });
 
   it('skips a row whose key is busy instead of repairing from a stale view', async () => {
     const { db, executor, locks } = setup();
     const row = await seed(db, executor, 'alice');
     // Reality drifted (paused, ledger says active)...
-    await executor.freeze(row.sandboxId);
+    await executor.freeze(row.id);
     // ...but alice's slot is held — an acquire or release is mid-operation
     // and knows more about this sandbox than our snapshot does.
     let release!: () => void;
@@ -345,14 +345,14 @@ describe('runtime reconcile (two-strike orphans)', () => {
 
     const result = await reconcile(db, executor, locks, new Set());
     expect(result.repairedStates).toBe(0);
-    expect(findByExternalId(db, 'alice')?.state).toBe('active');
+    expect(findByName(db, 'alice')?.state).toBe('active');
 
     release();
     await holder;
     // Next tick, with the key free, the repair lands.
     const next = await reconcile(db, executor, locks, new Set());
     expect(next).toEqual({ ...NONE, repairedStates: 1 });
-    expect(findByExternalId(db, 'alice')?.state).toBe('frozen');
+    expect(findByName(db, 'alice')?.state).toBe('frozen');
   });
 });
 
@@ -361,7 +361,7 @@ describe('disk reconcile', () => {
     const { db, executor, locks } = setup();
     const row = await seed(db, executor, 'alice');
     expect(await reconcile(db, executor, locks, new Set())).toEqual(NONE);
-    expect(await executor.listDisks()).toContain(row.sandboxId);
+    expect(await executor.listDisks()).toContain(row.id);
   });
 
   it('removes a disk nothing owns on two strikes at runtime', async () => {
diff --git a/packages/server/src/reconciler.ts b/packages/server/src/reconciler.ts
index 7e1aeea..5cdfe50 100644
--- a/packages/server/src/reconciler.ts
+++ b/packages/server/src/reconciler.ts
@@ -3,7 +3,7 @@ import { recordActivity } from './db/activity';
 import type { Db } from './db/db';
 import {
   deleteSandbox,
-  findBySandboxId,
+  findById,
   listSandboxes,
   overwriteState,
 } from './db/ledger';
@@ -123,8 +123,8 @@ export async function reconcile(
     row: SandboxRow,
     apply: () => void | Promise<void>,
   ) =>
-    locks.tryRun(row.externalId, async () => {
-      const fresh = findBySandboxId(db, row.sandboxId);
+    locks.tryRun(row.name, async () => {
+      const fresh = findById(db, row.id);
       if (fresh && fresh.state === row.state) {
         await apply();
       }
@@ -135,25 +135,25 @@ export async function reconcile(
   const note = (row: SandboxRow, detail: string) =>
     recordActivity(db, {
       kind: 'reconciled',
-      externalId: row.externalId,
-      sandboxId: row.sandboxId,
+      sandboxName: row.name,
+      sandboxId: row.id,
       detail,
     });
 
   for (const row of rows) {
-    const observed = containers.get(row.sandboxId);
-    containers.delete(row.sandboxId);
+    const observed = containers.get(row.id);
+    containers.delete(row.id);
     if (row.state === 'archived') {
-      owners.add(row.sandboxId);
+      owners.add(row.id);
       if (observed !== undefined) {
         await repairUnderLock(row, async () => {
-          await executor.destroy(row.sandboxId);
+          await executor.destroy(row.id);
           result.archivedSwept += 1;
           note(row, 'leftover container of an archived sandbox destroyed');
         });
-      } else if (disks.has(row.sandboxId)) {
+      } else if (disks.has(row.id)) {
         await repairUnderLock(row, async () => {
-          await executor.removeDisk(row.sandboxId);
+          await executor.removeDisk(row.id);
           result.archivedSwept += 1;
           note(row, 'leftover disk of an archived sandbox removed');
         });
@@ -161,13 +161,13 @@ export async function reconcile(
       continue;
     }
     if (row.state === 'restoring') {
-      owners.add(row.sandboxId);
-      if (archiver?.hasLiveRestore(row.sandboxId)) {
+      owners.add(row.id);
+      if (archiver?.hasLiveRestore(row.id)) {
         continue; // The task owns this row; what we observe is its mid-work.
       }
       if (observed !== undefined) {
         await repairUnderLock(row, () => {
-          overwriteState(db, row.sandboxId, LEDGER_STATE[observed]);
+          overwriteState(db, row.id, LEDGER_STATE[observed]);
           result.repairedStates += 1;
           note(
             row,
@@ -176,8 +176,8 @@ export async function reconcile(
         });
       } else {
         await repairUnderLock(row, async () => {
-          await executor.removeDisk(row.sandboxId);
-          overwriteState(db, row.sandboxId, 'archived');
+          await executor.removeDisk(row.id);
+          overwriteState(db, row.id, 'archived');
           result.repairedStates += 1;
           note(
             row,
@@ -188,10 +188,10 @@ export async function reconcile(
       continue;
     }
     if (observed !== undefined) {
-      owners.add(row.sandboxId);
+      owners.add(row.id);
       if (LEDGER_STATE[observed] !== row.state) {
         await repairUnderLock(row, () => {
-          overwriteState(db, row.sandboxId, LEDGER_STATE[observed]);
+          overwriteState(db, row.id, LEDGER_STATE[observed]);
           result.repairedStates += 1;
           note(
             row,
@@ -199,11 +199,11 @@ export async function reconcile(
           );
         });
       }
-    } else if (disks.has(row.sandboxId)) {
-      owners.add(row.sandboxId);
+    } else if (disks.has(row.id)) {
+      owners.add(row.id);
       if (row.state !== 'stopped') {
         await repairUnderLock(row, () => {
-          overwriteState(db, row.sandboxId, 'stopped');
+          overwriteState(db, row.id, 'stopped');
           result.repairedStates += 1;
           note(
             row,
@@ -213,7 +213,7 @@ export async function reconcile(
       }
     } else {
       await repairUnderLock(row, () => {
-        deleteSandbox(db, row.sandboxId);
+        deleteSandbox(db, row.id);
         result.deletedRows += 1;
         note(row, 'container and disk both gone — row deleted, key freed');
       });
diff --git a/packages/server/src/routes/observability.test.ts b/packages/server/src/routes/observability.test.ts
index c9fd771..503ad1d 100644
--- a/packages/server/src/routes/observability.test.ts
+++ b/packages/server/src/routes/observability.test.ts
@@ -162,7 +162,7 @@ describe('listActivity', () => {
   it('records create, wake, cooling and release, newest first', async () => {
     const { app, db, executor, locks } = testApp();
     const res = await rpc(app, '/acquireSandbox', {
-      externalId: 'story',
+      name: 'story',
       policy: { freezeAfterSeconds: 5, stopAfterSeconds: 10 },
     });
     expect(res.statusCode).toBe(200);
@@ -181,8 +181,8 @@ describe('listActivity', () => {
       locks,
       new Date(Date.parse(created.lastActiveAt) + 11_000),
     );
-    await rpc(app, '/acquireSandbox', { externalId: 'story' });
-    await rpc(app, '/destroySandbox', { externalId: 'story' });
+    await rpc(app, '/acquireSandbox', { name: 'story' });
+    await rpc(app, '/destroySandbox', { name: 'story' });
 
     const log = await events(app);
     expect(log.map((e) => e.kind)).toEqual([
@@ -193,7 +193,7 @@ describe('listActivity', () => {
       'created',
     ]);
     // Every event names its sandbox, and the scanner names its threshold.
-    expect(new Set(log.map((e) => e.externalId))).toEqual(new Set(['story']));
+    expect(new Set(log.map((e) => e.sandboxName))).toEqual(new Set(['story']));
     expect(log.find((e) => e.kind === 'frozen')?.detail).toContain('scanner');
     expect(log.find((e) => e.kind === 'created')?.detail).toContain(
       'acquireSandbox',
@@ -202,14 +202,14 @@ describe('listActivity', () => {
 
   it('records what reconciliation repaired', async () => {
     const { app, db, executor, locks } = testApp();
-    await rpc(app, '/acquireSandbox', { externalId: 'doomed' });
+    await rpc(app, '/acquireSandbox', { name: 'doomed' });
     const { sandboxes } = (await rpc(app, '/listSandboxes')).json();
     // Reality loses both container and disk behind the ledger's back.
-    await executor.destroy(sandboxes[0].sandboxId);
+    await executor.destroy(sandboxes[0].id);
     await reconcile(db, executor, locks);
 
     const log = await events(app);
-    expect(log[0]).toMatchObject({ kind: 'reconciled', externalId: 'doomed' });
+    expect(log[0]).toMatchObject({ kind: 'reconciled', sandboxName: 'doomed' });
     expect(log[0]?.detail).toContain('row deleted');
   });
 
@@ -247,9 +247,9 @@ describe('listActivity', () => {
 describe('getSandboxMetrics', () => {
   it('answers a single sample for a running sandbox', async () => {
     const { app } = testApp();
-    await rpc(app, '/acquireSandbox', { externalId: 'measured' });
+    await rpc(app, '/acquireSandbox', { name: 'measured' });
     const res = await rpc(app, '/getSandboxMetrics', {
-      externalId: 'measured',
+      name: 'measured',
     });
     expect(res.statusCode).toBe(200);
     const { sample } = getSandboxMetricsResponseSchema.parse(res.json());
@@ -260,13 +260,13 @@ describe('getSandboxMetrics', () => {
 
   it('answers null for a stopped sandbox instead of waking it', async () => {
     const { app, db, executor } = testApp();
-    const res = await rpc(app, '/acquireSandbox', { externalId: 'cold' });
-    const { sandboxId } = res.json().sandbox;
+    const res = await rpc(app, '/acquireSandbox', { name: 'cold' });
+    const { id: sandboxId } = res.json().sandbox;
     await freezeSandbox(db, executor, sandboxId);
     await stopSandbox(db, executor, sandboxId);
 
     const metrics = await rpc(app, '/getSandboxMetrics', {
-      externalId: 'cold',
+      name: 'cold',
     });
     expect(getSandboxMetricsResponseSchema.parse(metrics.json()).sample).toBe(
       null,
@@ -278,7 +278,7 @@ describe('getSandboxMetrics', () => {
 
   it('404s an unknown key instead of inventing a sandbox', async () => {
     const { app } = testApp();
-    const res = await rpc(app, '/getSandboxMetrics', { externalId: 'nobody' });
+    const res = await rpc(app, '/getSandboxMetrics', { name: 'nobody' });
     expect(res.statusCode).toBe(404);
   });
 });
@@ -300,19 +300,19 @@ describe('getSandboxMetricsHistory', () => {
   it('404s an unknown key instead of inventing a sandbox', async () => {
     const { app } = testApp();
     const res = await rpc(app, '/getSandboxMetricsHistory', {
-      externalId: 'nobody',
+      name: 'nobody',
     });
     expect(res.statusCode).toBe(404);
   });
 
   it('answers an empty window honestly — never a live fallback', async () => {
     const { app } = testApp();
-    await rpc(app, '/acquireSandbox', { externalId: 'fresh' });
+    await rpc(app, '/acquireSandbox', { name: 'fresh' });
     // The sandbox is running and measurable, but the sampler never ticked:
     // the native face reports silence as silence (the E2B face is the one
     // that takes a live reading, as compatibility politeness).
     const res = await rpc(app, '/getSandboxMetricsHistory', {
-      externalId: 'fresh',
+      name: 'fresh',
     });
     expect(res.statusCode).toBe(200);
     const body = getSandboxMetricsHistoryResponseSchema.parse(res.json());
@@ -321,9 +321,9 @@ describe('getSandboxMetricsHistory', () => {
 
   it('rejects an unparseable timestamp at the door', async () => {
     const { app } = testApp();
-    await rpc(app, '/acquireSandbox', { externalId: 'strict' });
+    await rpc(app, '/acquireSandbox', { name: 'strict' });
     const res = await rpc(app, '/getSandboxMetricsHistory', {
-      externalId: 'strict',
+      name: 'strict',
       start: 'yesterday-ish',
     });
     expect(res.statusCode).toBe(400);
@@ -331,7 +331,7 @@ describe('getSandboxMetricsHistory', () => {
 
   it('slices by start/end, ascending', async () => {
     const { app, db, executor } = testApp();
-    await rpc(app, '/acquireSandbox', { externalId: 'sliced' });
+    await rpc(app, '/acquireSandbox', { name: 'sliced' });
     const t0 = Date.parse('2026-07-15T10:00:00.000Z');
     for (let i = 0; i < 3; i += 1) {
       await sampleOnce(db, executor, new Date(t0 + i * 30_000), {
@@ -339,7 +339,7 @@ describe('getSandboxMetricsHistory', () => {
       });
     }
     const res = await rpc(app, '/getSandboxMetricsHistory', {
-      externalId: 'sliced',
+      name: 'sliced',
       start: new Date(t0 + 15_000).toISOString(),
       end: new Date(t0 + 65_000).toISOString(),
     });
@@ -355,7 +355,7 @@ describe('getSandboxMetricsHistory', () => {
   it('buckets past MAX_POINTS by per-field max — the spike survives', async () => {
     const { app, db } = testApp();
     const created = (
-      await rpc(app, '/acquireSandbox', { externalId: 'spiky' })
+      await rpc(app, '/acquireSandbox', { name: 'spiky' })
     ).json().sandbox;
     const t0 = Date.parse('2026-07-15T00:00:00.000Z');
     const rows = MAX_POINTS + 40;
@@ -373,7 +373,7 @@ describe('getSandboxMetricsHistory', () => {
         // One reading spikes; every neighbor idles. Averaging would bury it.
         samples: [
           {
-            sandboxId: created.sandboxId,
+            sandboxId: created.id,
             metrics: reading(i === 200 ? 95 : 5),
           },
         ],
@@ -381,7 +381,7 @@ describe('getSandboxMetricsHistory', () => {
       });
     }
     const res = await rpc(app, '/getSandboxMetricsHistory', {
-      externalId: 'spiky',
+      name: 'spiky',
       start: new Date(t0).toISOString(),
       end: new Date(t0 + rows * 30_000).toISOString(),
     });
@@ -407,10 +407,10 @@ describe('getFleetTimeline', () => {
 
   it('returns snapshots ascending with byState summing to total', async () => {
     const { app, db, executor } = testApp();
-    await rpc(app, '/acquireSandbox', { externalId: 'one' });
+    await rpc(app, '/acquireSandbox', { name: 'one' });
     const t0 = Date.parse('2026-07-15T10:00:00.000Z');
     await sampleOnce(db, executor, new Date(t0), { retentionHours: 168 });
-    await rpc(app, '/acquireSandbox', { externalId: 'two' });
+    await rpc(app, '/acquireSandbox', { name: 'two' });
     await sampleOnce(db, executor, new Date(t0 + 30_000), {
       retentionHours: 168,
     });
@@ -495,18 +495,18 @@ describe('getFleetTimeline', () => {
 describe('listSandboxMetrics', () => {
   it('measures active and frozen sandboxes; colder states are absent', async () => {
     const { app, db, executor } = testApp();
-    await rpc(app, '/acquireSandbox', { externalId: 'hot' });
-    const frozen = await rpc(app, '/acquireSandbox', { externalId: 'napping' });
-    await freezeSandbox(db, executor, frozen.json().sandbox.sandboxId);
-    const cold = await rpc(app, '/acquireSandbox', { externalId: 'cold' });
-    const coldId = cold.json().sandbox.sandboxId;
+    await rpc(app, '/acquireSandbox', { name: 'hot' });
+    const frozen = await rpc(app, '/acquireSandbox', { name: 'napping' });
+    await freezeSandbox(db, executor, frozen.json().sandbox.id);
+    const cold = await rpc(app, '/acquireSandbox', { name: 'cold' });
+    const coldId = cold.json().sandbox.id;
     await freezeSandbox(db, executor, coldId);
     await stopSandbox(db, executor, coldId);
 
     const res = await rpc(app, '/listSandboxMetrics', {});
     expect(res.statusCode).toBe(200);
     const { samples } = listSandboxMetricsResponseSchema.parse(res.json());
-    const keys = samples.map((s) => s.externalId).sort();
+    const keys = samples.map((s) => s.sandboxName).sort();
     // The frozen sandbox is measured as it sleeps; the stopped one has no
     // container to measure and is honestly absent, not null-stuffed.
     expect(keys).toEqual(['hot', 'napping']);
@@ -517,10 +517,7 @@ describe('listSandboxMetrics', () => {
     // Observation is not activity: nobody woke or cooled further.
     const { sandboxes } = (await rpc(app, '/listSandboxes')).json();
     const byKey = new Map<string, string>(
-      sandboxes.map((s: { externalId: string; state: string }) => [
-        s.externalId,
-        s.state,
-      ]),
+      sandboxes.map((s: { name: string; state: string }) => [s.name, s.state]),
     );
     expect(byKey.get('napping')).toBe('frozen');
     expect(byKey.get('cold')).toBe('stopped');
@@ -528,18 +525,18 @@ describe('listSandboxMetrics', () => {
 
   it('skips a sandbox whose container vanished instead of failing the sweep', async () => {
     const { app, executor } = testApp();
-    await rpc(app, '/acquireSandbox', { externalId: 'alive' });
-    const doomed = await rpc(app, '/acquireSandbox', { externalId: 'doomed' });
+    await rpc(app, '/acquireSandbox', { name: 'alive' });
+    const doomed = await rpc(app, '/acquireSandbox', { name: 'doomed' });
     // The container dies physically, past the ledger (gVisor OOM does this
     // for real) — the row still says active, the reading throws, the sweep
     // reports what it could see.
-    const doomedId = doomed.json().sandbox.sandboxId;
+    const doomedId = doomed.json().sandbox.id;
     await executor.freeze(doomedId);
     await executor.stop(doomedId);
 
     const res = await rpc(app, '/listSandboxMetrics', {});
     const { samples } = listSandboxMetricsResponseSchema.parse(res.json());
-    expect(samples.map((s) => s.externalId)).toEqual(['alive']);
+    expect(samples.map((s) => s.sandboxName)).toEqual(['alive']);
   });
 
   it('answers an empty list on an empty ledger', async () => {
@@ -562,14 +559,14 @@ describe('listSandboxImages', () => {
     const { app } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
     const created = (
-      await rpc(app, '/acquireSandbox', { externalId: 'alice', template: 'py' })
+      await rpc(app, '/acquireSandbox', { name: 'alice', template: 'py' })
     ).json().sandbox;
 
     // Fresh: the shell was born from the template's current image.
     expect(await images(app)).toEqual([
       {
-        externalId: 'alice',
-        sandboxId: created.sandboxId,
+        sandboxName: 'alice',
+        sandboxId: created.id,
         image: 'img-v1',
         nextImage: 'img-v1',
         upgradable: false,
@@ -584,13 +581,13 @@ describe('listSandboxImages', () => {
 
     // Rebuild removes the shell: no image to report, and nothing to upgrade
     // — the next boot resolves the current image by itself.
-    await rpc(app, '/rebuildSandbox', { externalId: 'alice' });
+    await rpc(app, '/rebuildSandbox', { name: 'alice' });
     expect(await images(app)).toMatchObject([
       { image: null, nextImage: 'img-v2', upgradable: false },
     ]);
 
     // Woken: born from the template's current image, in sync again.
-    await rpc(app, '/acquireSandbox', { externalId: 'alice' });
+    await rpc(app, '/acquireSandbox', { name: 'alice' });
     expect(await images(app)).toMatchObject([
       { image: 'img-v2', nextImage: 'img-v2', upgradable: false },
     ]);
@@ -598,7 +595,7 @@ describe('listSandboxImages', () => {
 
   it('compares template-less sandboxes against the executor base image', async () => {
     const { app } = testApp();
-    await rpc(app, '/acquireSandbox', { externalId: 'plain' });
+    await rpc(app, '/acquireSandbox', { name: 'plain' });
     expect(await images(app)).toMatchObject([
       { image: FAKE_BASE_IMAGE, nextImage: FAKE_BASE_IMAGE, upgradable: false },
     ]);
@@ -608,10 +605,10 @@ describe('listSandboxImages', () => {
     const { app, db, executor } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
     const created = (
-      await rpc(app, '/acquireSandbox', { externalId: 'cold', template: 'py' })
+      await rpc(app, '/acquireSandbox', { name: 'cold', template: 'py' })
     ).json().sandbox;
-    await freezeSandbox(db, executor, created.sandboxId);
-    await stopSandbox(db, executor, created.sandboxId);
+    await freezeSandbox(db, executor, created.id);
+    await stopSandbox(db, executor, created.id);
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });
 
     // The exited container is still the shell: waking it would boot the old
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index 7656d8f..8171d23 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -46,7 +46,7 @@ import type { Db } from '../db/db';
 import {
   countSandboxes,
   createSandbox,
-  findByExternalId,
+  findByName,
   listSandboxes,
   touch,
   updateMetadata,
@@ -85,14 +85,15 @@ export interface SandboxRoutesOptions {
 
 /** What acquire's slot work resolves to — the wire union's two arms. */
 type AcquireOutcome =
-  | { status: 'ready'; row: SandboxRow }
+  /** `created` — names converge instead of erroring, so this flag is how a caller sees which happened. */
+  | { status: 'ready'; created: boolean; row: SandboxRow }
   | { status: 'restoring'; row: SandboxRow; progress: RestoreProgress };
 
 /** Ledger row -> wire shape: nest the flat policy columns, attach the endpoint. */
 function toSandbox(row: SandboxRow, endpoint: string): Sandbox {
   return {
-    sandboxId: row.sandboxId,
-    externalId: row.externalId,
+    id: row.id,
+    name: row.name,
     state: row.state,
     nodeId: row.nodeId,
     endpoint,
@@ -139,12 +140,12 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
   // request queues, finds the row the first one wrote, and comes back with
   // the same sandbox instead of racing a duplicate create.
   async function findOrCreate(
-    externalId: string,
+    name: string,
     policy: LifecyclePolicy,
     template: string | null,
     metadata: string | null,
   ): Promise<AcquireOutcome> {
-    const existing = findByExternalId(db, externalId);
+    const existing = findByName(db, name);
     if (existing?.state === 'archived' || existing?.state === 'restoring') {
       // The protocol's promise: acquire never blocks on a slow wake-up. An
       // archived sandbox starts its restore and answers `restoring` with
@@ -152,18 +153,15 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       if (!archiver) {
         throw httpError(
           503,
-          `sandbox for key "${externalId}" is ${existing.state} but the daemon has no S3 configured (DORMICE_S3_*) — restore is impossible until it is`,
+          `sandbox "${name}" is ${existing.state} but the daemon has no S3 configured (DORMICE_S3_*) — restore is impossible until it is`,
         );
       }
       if (existing.state === 'archived') {
         archiver.beginRestore(existing);
       }
-      const restoring = findByExternalId(db, externalId);
+      const restoring = findByName(db, name);
       if (!restoring) {
-        throw httpError(
-          500,
-          `sandbox for key "${externalId}" vanished mid-slot`,
-        );
+        throw httpError(500, `sandbox "${name}" vanished mid-slot`);
       }
       return {
         status: 'restoring',
@@ -171,7 +169,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         // The fallback covers the crash-zombie instant before the next
         // reconcile flips the row back to archived; at runtime a restoring
         // row always has a live task.
-        progress: archiver.progressOf(existing.sandboxId) ?? {
+        progress: archiver.progressOf(existing.id) ?? {
           phase: 'downloading',
           percent: 0,
         },
@@ -184,7 +182,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       // take effect only when this acquire creates the sandbox (metadata
       // has its own update verb, updateMetadata).
       const awake = await wakeSandbox(db, executor, existing);
-      return { status: 'ready', row: touch(db, awake.sandboxId) };
+      return { status: 'ready', created: false, row: touch(db, awake.id) };
     }
 
     // The capacity check lives at the only verb that creates — wakes of
@@ -205,13 +203,14 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     // UUID, never an autoincrement (ids must survive sharding); its
     // alphabet is safe everywhere an id will land — Docker names, file
     // names, DNS labels.
-    const sandboxId = randomUUID();
-    await executor.create(sandboxId, { image: resolveImage(db, template) });
+    const id = randomUUID();
+    await executor.create(id, { image: resolveImage(db, template) });
     return {
       status: 'ready',
+      created: true,
       row: createSandbox(db, {
-        sandboxId,
-        externalId,
+        id,
+        name,
         nodeId: config.DORMICE_NODE_ID,
         policy,
         template,
@@ -225,24 +224,21 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
   // is more likely a typo than an intent to build a sandbox as a side
   // effect — then wake whatever cold state the sandbox is in and refresh
   // its idle clock. Must be called while holding the key's queue slot.
-  async function wakeForUse(externalId: string): Promise<SandboxRow> {
-    const existing = findByExternalId(db, externalId);
+  async function wakeForUse(name: string): Promise<SandboxRow> {
+    const existing = findByName(db, name);
     if (!existing) {
-      throw httpError(
-        404,
-        `no sandbox for key "${externalId}" — acquire it first`,
-      );
+      throw httpError(404, `no sandbox named "${name}" — acquire it first`);
     }
     if (existing.state === 'archived' || existing.state === 'restoring') {
       // The native restore path is acquire's poll loop; a use verb neither
       // blocks for minutes nor starts restores on the side.
       throw httpError(
         409,
-        `sandbox for key "${externalId}" is ${existing.state} — call acquireSandbox and poll until it is ready`,
+        `sandbox "${name}" is ${existing.state} — call acquireSandbox and poll until it is ready`,
       );
     }
     const awake = await wakeSandbox(db, executor, existing);
-    return touch(db, awake.sandboxId);
+    return touch(db, awake.id);
   }
 
   // Native API convention: RPC style — every operation is a POST to a
@@ -261,7 +257,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request, reply) => {
-      const { externalId, policy: override, template, metadata } = request.body;
+      const { name, policy: override, template, metadata } = request.body;
 
       // Validate the policy before taking the key's slot, so a queued
       // rejection can only come from the work itself, never from another
@@ -298,9 +294,9 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         });
       }
 
-      const outcome = await locks.run(externalId, () =>
+      const outcome = await locks.run(name, () =>
         findOrCreate(
-          externalId,
+          name,
           policy,
           template ?? null,
           serializeMetadata(metadata),
@@ -309,12 +305,15 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       if (outcome.status === 'restoring') {
         return {
           status: 'restoring' as const,
+          // Only an already-archived sandbox restores — never a fresh one.
+          created: false,
           sandbox: toSandbox(outcome.row, endpoint),
           progress: outcome.progress,
         };
       }
       return {
         status: 'ready' as const,
+        created: outcome.created,
         sandbox: toSandbox(outcome.row, endpoint),
       };
     },
@@ -349,18 +348,15 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { externalId } = request.body;
-      const row = findByExternalId(db, externalId);
+      const { name } = request.body;
+      const row = findByName(db, name);
       if (!row) {
-        throw httpError(
-          404,
-          `no sandbox for key "${externalId}" — acquire it first`,
-        );
+        throw httpError(404, `no sandbox named "${name}" — acquire it first`);
       }
       if (row.state !== 'active' && row.state !== 'frozen') {
         return { sample: null };
       }
-      const m = await executor.metrics(row.sandboxId);
+      const m = await executor.metrics(row.id);
       return { sample: { timestamp: new Date().toISOString(), ...m } };
     },
   );
@@ -371,7 +367,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
   // averages erase them. An unsampled window answers an empty array; the
   // native face never takes a live reading to fill silence (the E2B face
   // does, as compatibility politeness — the asymmetry is deliberate).
-  // History is keyed by sandboxId under the hood, so it survives rebuilds.
+  // History is keyed by the sandbox id under the hood, so it survives rebuilds.
   app.post(
     '/getSandboxMetricsHistory',
     {
@@ -381,13 +377,10 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { externalId, start, end } = request.body;
-      const row = findByExternalId(db, externalId);
+      const { name, start, end } = request.body;
+      const row = findByName(db, name);
       if (!row) {
-        throw httpError(
-          404,
-          `no sandbox for key "${externalId}" — acquire it first`,
-        );
+        throw httpError(404, `no sandbox named "${name}" — acquire it first`);
       }
       const { startIso, endIso, startMs, endMs } = resolveWindow(
         start,
@@ -395,7 +388,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         3600_000,
         new Date(),
       );
-      const rows = querySandboxSamples(db, row.sandboxId, startIso, endIso);
+      const rows = querySandboxSamples(db, row.id, startIso, endIso);
       const bucketSeconds = resolveBucketSeconds(rows.length, startMs, endMs);
       const sliced =
         bucketSeconds === null
@@ -432,10 +425,10 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       const samples = await Promise.all(
         rows.map(async (row) => {
           try {
-            const m = await executor.metrics(row.sandboxId);
+            const m = await executor.metrics(row.id);
             return {
-              externalId: row.externalId,
-              sandboxId: row.sandboxId,
+              sandboxName: row.name,
+              sandboxId: row.id,
               sample: { timestamp: new Date().toISOString(), ...m },
             };
           } catch {
@@ -473,15 +466,15 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
           let image: string | null = null;
           if (row.state !== 'archived' && row.state !== 'restoring') {
             try {
-              image = await executor.imageOf(row.sandboxId);
+              image = await executor.imageOf(row.id);
             } catch {
               // Reading failed mid-vanish: no shell to report, same as null.
               image = null;
             }
           }
           return {
-            externalId: row.externalId,
-            sandboxId: row.sandboxId,
+            sandboxName: row.name,
+            sandboxId: row.id,
             image,
             nextImage,
             // A row without a shell is not upgradable: its very next boot
@@ -504,7 +497,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { externalId, command, timeoutSeconds, cwd, env } = request.body;
+      const { name, command, timeoutSeconds, cwd, env } = request.body;
 
       // Only the wake takes the key's queue slot — seconds of executor
       // work, the same serialization story as acquire. The exec itself
@@ -513,15 +506,15 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       // whole duration. The heartbeat keeps the scanner away; a concurrent
       // destroy mid-exec removes the container and this exec fails with
       // the executor's honest error — accepted, not defended against.
-      const row = await locks.run(externalId, () => wakeForUse(externalId));
+      const row = await locks.run(name, () => wakeForUse(name));
 
       const stopHeartbeat = startExecHeartbeat(
         db,
-        row.sandboxId,
+        row.id,
         row.freezeAfterSeconds,
       );
       try {
-        return await executor.exec(row.sandboxId, {
+        return await executor.exec(row.id, {
           command,
           timeoutSeconds,
           cwd,
@@ -532,7 +525,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         try {
           // The command itself was the activity: the idle countdown starts
           // when it ends, not when it started.
-          touch(db, row.sandboxId);
+          touch(db, row.id);
         } catch {
           // Released mid-exec; the exec's own result or error tells the story.
         }
@@ -565,12 +558,12 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { externalId, files } = request.body;
-      return locks.run(externalId, async () => {
-        const row = await wakeForUse(externalId);
+      const { name, files } = request.body;
+      return locks.run(name, async () => {
+        const row = await wakeForUse(name);
         try {
           await executor.writeFiles(
-            row.sandboxId,
+            row.id,
             files.map((file) => ({
               path: file.path,
               content: Buffer.from(file.contentBase64, 'base64'),
@@ -579,7 +572,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         } catch (error) {
           throwFileHttpError(error);
         }
-        touch(db, row.sandboxId);
+        touch(db, row.id);
         return {
           files: files.map((file) => ({ path: resolveSandboxPath(file.path) })),
         };
@@ -600,17 +593,17 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { externalId, path, contentBase64 } = request.body;
-      return locks.run(externalId, async () => {
-        const row = await wakeForUse(externalId);
+      const { name, path, contentBase64 } = request.body;
+      return locks.run(name, async () => {
+        const row = await wakeForUse(name);
         try {
-          await executor.writeFiles(row.sandboxId, [
+          await executor.writeFiles(row.id, [
             { path, content: Buffer.from(contentBase64, 'base64') },
           ]);
         } catch (error) {
           throwFileHttpError(error);
         }
-        touch(db, row.sandboxId);
+        touch(db, row.id);
         return { path: resolveSandboxPath(path) };
       });
     },
@@ -625,16 +618,16 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { externalId, path } = request.body;
-      return locks.run(externalId, async () => {
-        const row = await wakeForUse(externalId);
+      const { name, path } = request.body;
+      return locks.run(name, async () => {
+        const row = await wakeForUse(name);
         let content: Buffer;
         try {
-          content = await executor.readFile(row.sandboxId, path);
+          content = await executor.readFile(row.id, path);
         } catch (error) {
           throwFileHttpError(error);
         }
-        touch(db, row.sandboxId);
+        touch(db, row.id);
         return {
           path: resolveSandboxPath(path),
           contentBase64: content.toString('base64'),
@@ -655,15 +648,15 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { externalId, paths } = request.body;
-      return locks.run(externalId, async () => {
-        const row = await wakeForUse(externalId);
+      const { name, paths } = request.body;
+      return locks.run(name, async () => {
+        const row = await wakeForUse(name);
         const files: { path: string; contentBase64: string }[] = [];
         let totalBytes = 0;
         for (const path of paths) {
           let content: Buffer;
           try {
-            content = await executor.readFile(row.sandboxId, path);
+            content = await executor.readFile(row.id, path);
           } catch (error) {
             throwFileHttpError(error);
           }
@@ -679,7 +672,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
             contentBase64: content.toString('base64'),
           });
         }
-        touch(db, row.sandboxId);
+        touch(db, row.id);
         return { files };
       });
     },
@@ -694,26 +687,23 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { externalId } = request.body;
+      const { name } = request.body;
       // The whole verb holds the key's slot, like the file verbs: seconds of
       // executor work at worst, and the slot keeps the scanner and a
       // concurrent destroy from moving the sandbox under our feet.
-      return locks.run(externalId, async () => {
-        const existing = findByExternalId(db, externalId);
+      return locks.run(name, async () => {
+        const existing = findByName(db, name);
         if (!existing) {
           // Not a creator and not a destroyer: an unknown key is a typo,
           // not a goal state — same manners as exec.
-          throw httpError(
-            404,
-            `no sandbox for key "${externalId}" — acquire it first`,
-          );
+          throw httpError(404, `no sandbox named "${name}" — acquire it first`);
         }
         if (existing.state === 'archived' || existing.state === 'restoring') {
           // An archived sandbox has no container to swap; it already meets
           // rebuild's promise (its next wake builds from the current image).
           throw httpError(
             409,
-            `sandbox for key "${externalId}" is ${existing.state} — it has no container to rebuild`,
+            `sandbox "${name}" is ${existing.state} — it has no container to rebuild`,
           );
         }
         const row = await rebuildSandbox(db, executor, existing);
@@ -734,19 +724,19 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request, reply) => {
-      const { externalId, policy: patch } = request.body;
+      const { name, policy: patch } = request.body;
       // Unlike acquire, the merge base is the STORED policy, so validation
       // must wait for the row — it runs inside the slot, which also keeps a
       // concurrent destroy from deleting the row between check and write.
       const outcome = await locks.run<{ error: string } | { row: SandboxRow }>(
-        externalId,
+        name,
         async () => {
-          const existing = findByExternalId(db, externalId);
+          const existing = findByName(db, name);
           if (!existing) {
             // Not a creator: an unknown key is a typo, same manners as rebuild.
             throw httpError(
               404,
-              `no sandbox for key "${externalId}" — acquire it first`,
+              `no sandbox named "${name}" — acquire it first`,
             );
           }
           // Legal in every state: policy is a ledger attribute, not a container
@@ -795,13 +785,13 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
             // The goal state already holds; a no-op writes no history.
             return { row: existing };
           }
-          const row = updatePolicy(db, existing.sandboxId, merged.data);
+          const row = updatePolicy(db, existing.id, merged.data);
           const fmt = (seconds: number | null) =>
             seconds === null ? 'never' : `${seconds}s`;
           recordActivity(db, {
             kind: 'policy-changed',
-            externalId,
-            sandboxId: row.sandboxId,
+            sandboxName: name,
+            sandboxId: row.id,
             detail: changed
               .map(
                 (knob) =>
@@ -828,28 +818,25 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { externalId, metadata } = request.body;
+      const { name, metadata } = request.body;
       const serialized = serializeMetadata(metadata);
       // Inside the slot for the same reason as updatePolicy: a concurrent
       // destroy must not delete the row between check and write.
-      const row = await locks.run(externalId, async () => {
-        const existing = findByExternalId(db, externalId);
+      const row = await locks.run(name, async () => {
+        const existing = findByName(db, name);
         if (!existing) {
           // Not a creator: an unknown key is a typo, same manners as rebuild.
-          throw httpError(
-            404,
-            `no sandbox for key "${externalId}" — acquire it first`,
-          );
+          throw httpError(404, `no sandbox named "${name}" — acquire it first`);
         }
         if ((existing.metadata ?? null) === serialized) {
           // The goal state already holds; a no-op writes no history.
           return existing;
         }
-        const updated = updateMetadata(db, existing.sandboxId, serialized);
+        const updated = updateMetadata(db, existing.id, serialized);
         recordActivity(db, {
           kind: 'metadata-changed',
-          externalId,
-          sandboxId: updated.sandboxId,
+          sandboxName: name,
+          sandboxId: updated.id,
           detail:
             Object.entries(metadata)
               .map(([key, value]) => `${key}=${value}`)
@@ -870,13 +857,13 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       },
     },
     async (request) => {
-      const { externalId } = request.body;
+      const { name } = request.body;
       // Same slot as acquire and the scanner: two parallel destroys of one
       // key queue up — the first destroys, the second re-checks and reports
       // the goal state honestly instead of tripping over a half-destroyed
       // sandbox.
-      return locks.run(externalId, async () => {
-        const existing = findByExternalId(db, externalId);
+      return locks.run(name, async () => {
+        const existing = findByName(db, name);
         if (!existing) {
           // Idempotent like acquire: the desired end state — no sandbox
           // under this key — already holds.
@@ -891,7 +878,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         await destroySandbox(
           db,
           executor,
-          existing.sandboxId,
+          existing.id,
           archiver?.store ?? null,
         );
         return { destroyed: true };
diff --git a/packages/server/src/routes/templates.ts b/packages/server/src/routes/templates.ts
index 0700e13..1cd335f 100644
--- a/packages/server/src/routes/templates.ts
+++ b/packages/server/src/routes/templates.ts
@@ -8,10 +8,10 @@ import {
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import type { Db } from '../db/db';
 import {
-  externalIdsUsingTemplate,
   listTemplates,
   registerTemplate,
   removeTemplate,
+  sandboxNamesUsingTemplate,
 } from '../db/templates';
 import { httpError } from '../http-error';
 
@@ -68,7 +68,7 @@ export const templateRoutes: FastifyPluginAsyncZod<
       // Refused while referenced: a sandbox row pointing at a removed
       // template would wake onto a dangling name. Named keys, so the
       // operator knows exactly what to destroy.
-      const users = externalIdsUsingTemplate(db, name);
+      const users = sandboxNamesUsingTemplate(db, name);
       if (users.length > 0) {
         throw httpError(
           409,
diff --git a/packages/server/src/sandbox-proxy.test.ts b/packages/server/src/sandbox-proxy.test.ts
index 166d26f..a00ae9b 100644
--- a/packages/server/src/sandbox-proxy.test.ts
+++ b/packages/server/src/sandbox-proxy.test.ts
@@ -5,7 +5,7 @@ import { afterEach, describe, expect, it } from 'vitest';
 import { buildApp } from './app';
 import { loadConfig } from './config';
 import { migrateDb, openDb } from './db/db';
-import { findBySandboxId } from './db/ledger';
+import { findById } from './db/ledger';
 import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
 import { parseSandboxHost } from './sandbox-proxy';
@@ -141,7 +141,7 @@ describe('sandbox port proxy', () => {
     const sandboxId = await createSandbox(t.port);
     // Freeze the real way — the idle scanner, told it is later — so the
     // ledger and reality move together, exactly the state traffic finds.
-    const row = findBySandboxId(t.db, sandboxId);
+    const row = findById(t.db, sandboxId);
     const later = new Date(
       Date.now() + ((row?.freezeAfterSeconds ?? 0) + 60) * 1000,
     );
diff --git a/packages/server/src/sandbox-proxy.ts b/packages/server/src/sandbox-proxy.ts
index 39d4404..7529379 100644
--- a/packages/server/src/sandbox-proxy.ts
+++ b/packages/server/src/sandbox-proxy.ts
@@ -4,7 +4,7 @@ import net from 'node:net';
 import type { Duplex } from 'node:stream';
 import type { Config } from './config';
 import type { Db } from './db/db';
-import { findBySandboxId, touch } from './db/ledger';
+import { findById, touch } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import { e2bView } from './e2b/view';
 import { startExecHeartbeat } from './exec-heartbeat';
@@ -73,7 +73,7 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
   const domain = config.DORMICE_SANDBOX_DOMAIN ?? '';
 
   function liveRow(sandboxId: string): SandboxRow {
-    const row = findBySandboxId(db, sandboxId);
+    const row = findById(db, sandboxId);
     if (!row || e2bView(row, new Date()) !== 'running') {
       throw new ProxyRefusal(
         !row || e2bView(row, new Date()) === 'dead'
@@ -97,12 +97,12 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
     const parsed = parseSandboxHost(req.headers.host, domain);
     if (!parsed) throw new ProxyRefusal('not sandbox traffic');
     const before = liveRow(parsed.sandboxId);
-    const row = await locks.run(before.externalId, async () => {
+    const row = await locks.run(before.name, async () => {
       const fresh = liveRow(parsed.sandboxId);
       const awake = await wakeSandbox(db, executor, fresh);
-      return touch(db, awake.sandboxId);
+      return touch(db, awake.id);
     });
-    const target = await executor.resolvePortTarget(row.sandboxId, parsed.port);
+    const target = await executor.resolvePortTarget(row.id, parsed.port);
     return { row, port: parsed.port, target };
   }
 
@@ -143,7 +143,7 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
         // as the connection, then the idle countdown restarts.
         const stopHeartbeat = startExecHeartbeat(
           db,
-          row.sandboxId,
+          row.id,
           row.freezeAfterSeconds,
         );
         let settled = false;
@@ -152,7 +152,7 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
           settled = true;
           stopHeartbeat();
           try {
-            touch(db, row.sandboxId);
+            touch(db, row.id);
           } catch {
             // Released mid-request; the connection's ending tells the story.
           }
@@ -173,10 +173,7 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
         });
         upstream.on('error', () => {
           settle();
-          refuse(
-            res,
-            `sandbox ${row.sandboxId} is not listening on port ${port}`,
-          );
+          refuse(res, `sandbox ${row.id} is not listening on port ${port}`);
         });
         res.on('close', () => {
           settle();
@@ -203,7 +200,7 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
         const { row, target } = resolved;
         const stopHeartbeat = startExecHeartbeat(
           db,
-          row.sandboxId,
+          row.id,
           row.freezeAfterSeconds,
         );
         let settled = false;
@@ -212,7 +209,7 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
           settled = true;
           stopHeartbeat();
           try {
-            touch(db, row.sandboxId);
+            touch(db, row.id);
           } catch {
             // Released mid-connection.
           }
diff --git a/packages/server/src/scanner.test.ts b/packages/server/src/scanner.test.ts
index 4f8abae..44107fc 100644
--- a/packages/server/src/scanner.test.ts
+++ b/packages/server/src/scanner.test.ts
@@ -12,12 +12,7 @@ import { Archiver } from './archive/archiver';
 import { MemStore } from './archive/mem-store';
 import { objectKey } from './archive/store';
 import { type Db, migrateDb, openDb } from './db/db';
-import {
-  createSandbox,
-  findByExternalId,
-  setDeadline,
-  touch,
-} from './db/ledger';
+import { createSandbox, findByName, setDeadline, touch } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
@@ -47,14 +42,14 @@ function setupWithArchiver() {
 async function seed(
   db: Db,
   executor: FakeExecutor,
-  externalId: string,
+  name: string,
   policy: LifecyclePolicy = DEFAULT_LIFECYCLE_POLICY,
 ): Promise<SandboxRow> {
-  const sandboxId = randomUUID();
-  await executor.create(sandboxId);
+  const id = randomUUID();
+  await executor.create(id);
   return createSandbox(db, {
-    sandboxId,
-    externalId,
+    id,
+    name,
     nodeId: 'node-test',
     policy,
   });
@@ -77,8 +72,8 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'alice')?.state).toBe('active');
-    expect(executor.stateOf(row.sandboxId)).toBe('running');
+    expect(findByName(db, 'alice')?.state).toBe('active');
+    expect(executor.stateOf(row.id)).toBe('running');
   });
 
   it('freezes a sandbox idle past freezeAfterSeconds', async () => {
@@ -97,8 +92,8 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'alice')?.state).toBe('frozen');
-    expect(executor.stateOf(row.sandboxId)).toBe('paused');
+    expect(findByName(db, 'alice')?.state).toBe('frozen');
+    expect(executor.stateOf(row.id)).toBe('paused');
   });
 
   it('stops a frozen sandbox idle past stopAfterSeconds', async () => {
@@ -118,8 +113,8 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
-    expect(executor.stateOf(row.sandboxId)).toBe('stopped');
+    expect(findByName(db, 'alice')?.state).toBe('stopped');
+    expect(executor.stateOf(row.id)).toBe('stopped');
   });
 
   it('moves one rung per sweep, even for a long-dead sandbox', async () => {
@@ -133,7 +128,7 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'alice')?.state).toBe('frozen');
+    expect(findByName(db, 'alice')?.state).toBe('frozen');
     expect(await scanOnce(db, executor, locks, yearLater)).toEqual({
       frozen: 0,
       stopped: 1,
@@ -141,7 +136,7 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
+    expect(findByName(db, 'alice')?.state).toBe('stopped');
   });
 
   it('applies each sandbox its own policy', async () => {
@@ -159,9 +154,9 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'quick')?.state).toBe('frozen');
-    expect(findByExternalId(db, 'slow')?.state).toBe('active');
-    expect(executor.stateOf(slow.sandboxId)).toBe('running');
+    expect(findByName(db, 'quick')?.state).toBe('frozen');
+    expect(findByName(db, 'slow')?.state).toBe('active');
+    expect(executor.stateOf(slow.id)).toBe('running');
   });
 
   it('never stops a frozen sandbox whose policy says stop: null', async () => {
@@ -173,7 +168,7 @@ describe('idle scanner', () => {
       archiveAfterSeconds: null,
     });
     await scanOnce(db, executor, locks, after(row, row.freezeAfterSeconds));
-    expect(findByExternalId(db, 'resident')?.state).toBe('frozen');
+    expect(findByName(db, 'resident')?.state).toBe('frozen');
 
     const yearLater = await scanOnce(
       db,
@@ -188,7 +183,7 @@ describe('idle scanner', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'resident')?.state).toBe('frozen');
+    expect(findByName(db, 'resident')?.state).toBe('frozen');
   });
 
   it('keeps sweeping past a sandbox whose container has vanished', async () => {
@@ -197,7 +192,7 @@ describe('idle scanner', () => {
     const alive = await seed(db, executor, 'alive');
     // Container and disk gone behind the ledger's back. The row still says
     // active; the freeze attempt fails honestly.
-    await executor.destroy(dead.sandboxId);
+    await executor.destroy(dead.id);
 
     const result = await scanOnce(
       db,
@@ -208,16 +203,16 @@ describe('idle scanner', () => {
     // The dead row is reported, the row behind it still cools down.
     expect(result.failures).toEqual([
       {
-        sandboxId: dead.sandboxId,
+        sandboxId: dead.id,
         message: expect.stringContaining('absent'),
       },
     ]);
     expect(result.frozen).toBe(1);
-    expect(findByExternalId(db, 'alive')?.state).toBe('frozen');
-    expect(executor.stateOf(alive.sandboxId)).toBe('paused');
+    expect(findByName(db, 'alive')?.state).toBe('frozen');
+    expect(executor.stateOf(alive.id)).toBe('paused');
     // The dead row was not written: reality never moved. Repairing it is
     // reconciliation's job, not the scanner's.
-    expect(findByExternalId(db, 'dead')?.state).toBe('active');
+    expect(findByName(db, 'dead')?.state).toBe('active');
   });
 });
 
@@ -251,7 +246,7 @@ describe('idle scanner vs the per-key queue', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'alice')?.state).toBe('active');
+    expect(findByName(db, 'alice')?.state).toBe('active');
 
     release();
     await holder;
@@ -296,7 +291,7 @@ describe('idle scanner vs the per-key queue', () => {
       after(first, first.freezeAfterSeconds),
     );
     const released = locks.run('doomed', () =>
-      destroySandbox(db, executor, doomed.sandboxId, null),
+      destroySandbox(db, executor, doomed.id, null),
     );
     const [result] = await Promise.all([sweep, released]);
 
@@ -307,7 +302,7 @@ describe('idle scanner vs the per-key queue', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'doomed')).toBeUndefined();
+    expect(findByName(db, 'doomed')).toBeUndefined();
   });
 });
 
@@ -327,13 +322,13 @@ describe('idle scanner: the archive rung', () => {
   ): Promise<void> {
     await scanOnce(db, executor, locks, after(row, 60));
     await scanOnce(db, executor, locks, after(row, 120));
-    expect(findByExternalId(db, row.externalId)?.state).toBe('stopped');
+    expect(findByName(db, row.name)?.state).toBe('stopped');
   }
 
   it('archives a stopped sandbox idle past archiveAfterSeconds', async () => {
     const { db, executor, locks, store, archiver } = setupWithArchiver();
     const row = await seed(db, executor, 'alice', ARCHIVING_POLICY);
-    await executor.writeFiles(row.sandboxId, [
+    await executor.writeFiles(row.id, [
       { path: 'kept.txt', content: Buffer.from('made it') },
     ]);
     await walkToStopped(db, executor, locks, row);
@@ -352,11 +347,11 @@ describe('idle scanner: the archive rung', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'alice')?.state).toBe('archived');
-    expect(store.has(objectKey(row.sandboxId))).toBe(true);
+    expect(findByName(db, 'alice')?.state).toBe('archived');
+    expect(store.has(objectKey(row.id))).toBe(true);
     // Local copy freed: container and disk both gone.
-    expect(executor.stateOf(row.sandboxId)).toBeUndefined();
-    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+    expect(executor.stateOf(row.id)).toBeUndefined();
+    expect(await executor.listDisks()).not.toContain(row.id);
   });
 
   it('never moves the archive rung without an archiver', async () => {
@@ -367,8 +362,8 @@ describe('idle scanner: the archive rung', () => {
     // No archiver passed: the row keeps its recorded intent, untouched.
     const result = await scanOnce(db, executor, locks, after(row, 9999));
     expect(result.archived).toBe(0);
-    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
-    expect(await executor.listDisks()).toContain(row.sandboxId);
+    expect(findByName(db, 'alice')?.state).toBe('stopped');
+    expect(await executor.listDisks()).toContain(row.id);
   });
 
   it('never archives a policy that says archive: null', async () => {
@@ -387,7 +382,7 @@ describe('idle scanner: the archive rung', () => {
       archiver,
     );
     expect(yearLater.archived).toBe(0);
-    expect(findByExternalId(db, 'alice')?.state).toBe('stopped');
+    expect(findByName(db, 'alice')?.state).toBe('stopped');
   });
 
   it('an archive failure lands in failures without blocking the sweep', async () => {
@@ -415,13 +410,13 @@ describe('idle scanner: the archive rung', () => {
     expect(result.archived).toBe(0);
     expect(result.failures).toEqual([
       {
-        sandboxId: doomed.sandboxId,
+        sandboxId: doomed.id,
         message: expect.stringContaining('the bucket said no'),
       },
     ]);
     // Retryable: still stopped, disk still local.
-    expect(findByExternalId(db, 'doomed')?.state).toBe('stopped');
-    expect(await executor.listDisks()).toContain(doomed.sandboxId);
+    expect(findByName(db, 'doomed')?.state).toBe('stopped');
+    expect(await executor.listDisks()).toContain(doomed.id);
   });
 
   it('kill-deadline on an archived row deletes the S3 object too', async () => {
@@ -429,8 +424,8 @@ describe('idle scanner: the archive rung', () => {
     const row = await seed(db, executor, 'alice', ARCHIVING_POLICY);
     await walkToStopped(db, executor, locks, row);
     await scanOnce(db, executor, locks, after(row, 180), archiver);
-    expect(store.has(objectKey(row.sandboxId))).toBe(true);
-    setDeadline(db, row.sandboxId, {
+    expect(store.has(objectKey(row.id))).toBe(true);
+    setDeadline(db, row.id, {
       deadlineAt: after(row, 200).toISOString(),
       onDeadline: 'kill',
     });
@@ -443,8 +438,8 @@ describe('idle scanner: the archive rung', () => {
       archiver,
     );
     expect(result.expiredKilled).toBe(1);
-    expect(findByExternalId(db, 'alice')).toBeUndefined();
-    expect(store.has(objectKey(row.sandboxId))).toBe(false);
+    expect(findByName(db, 'alice')).toBeUndefined();
+    expect(store.has(objectKey(row.id))).toBe(false);
   });
 
   it('kill-deadline on a restoring row is deferred one sweep', async () => {
@@ -463,11 +458,11 @@ describe('idle scanner: the archive rung', () => {
       await gate;
       return innerGet(key, dest, onProgress);
     };
-    const archived = findByExternalId(db, 'alice');
+    const archived = findByName(db, 'alice');
     if (!archived) throw new Error('row vanished');
     archiver.beginRestore(archived);
-    expect(findByExternalId(db, 'alice')?.state).toBe('restoring');
-    setDeadline(db, row.sandboxId, {
+    expect(findByName(db, 'alice')?.state).toBe('restoring');
+    setDeadline(db, row.id, {
       deadlineAt: after(row, 200).toISOString(),
       onDeadline: 'kill',
     });
@@ -481,11 +476,11 @@ describe('idle scanner: the archive rung', () => {
       archiver,
     );
     expect(during.expiredKilled).toBe(0);
-    expect(findByExternalId(db, 'alice')?.state).toBe('restoring');
+    expect(findByName(db, 'alice')?.state).toBe('restoring');
 
     releaseDownload();
-    await archiver.restoreJoin(row.sandboxId);
-    expect(findByExternalId(db, 'alice')?.state).toBe('active');
+    await archiver.restoreJoin(row.id);
+    expect(findByName(db, 'alice')?.state).toBe('active');
 
     // Next sweep, with the restore settled, the kill lands clean.
     const settled = await scanOnce(
@@ -496,7 +491,7 @@ describe('idle scanner: the archive rung', () => {
       archiver,
     );
     expect(settled.expiredKilled).toBe(1);
-    expect(findByExternalId(db, 'alice')).toBeUndefined();
+    expect(findByName(db, 'alice')).toBeUndefined();
   });
 });
 
@@ -504,13 +499,13 @@ describe('E2B deadline rule', () => {
   async function seedWithDeadline(
     db: Db,
     executor: FakeExecutor,
-    externalId: string,
+    name: string,
     row: SandboxRow | null,
     afterSeconds: number,
     onDeadline: 'kill' | 'pause',
   ): Promise<SandboxRow> {
-    const seeded = row ?? (await seed(db, executor, externalId));
-    setDeadline(db, seeded.sandboxId, {
+    const seeded = row ?? (await seed(db, executor, name));
+    setDeadline(db, seeded.id, {
       deadlineAt: after(seeded, afterSeconds).toISOString(),
       onDeadline,
     });
@@ -546,9 +541,9 @@ describe('E2B deadline rule', () => {
       expiredKilled: 1,
       failures: [],
     });
-    expect(findByExternalId(db, 'doomed')).toBeUndefined();
-    expect(executor.stateOf(row.sandboxId)).toBeUndefined();
-    expect(await executor.listDisks()).not.toContain(row.sandboxId);
+    expect(findByName(db, 'doomed')).toBeUndefined();
+    expect(executor.stateOf(row.id)).toBeUndefined();
+    expect(await executor.listDisks()).not.toContain(row.id);
   });
 
   it('the deadline outranks idle cooling: due for both means dead, not frozen', async () => {
@@ -568,7 +563,7 @@ describe('E2B deadline rule', () => {
       expiredKilled: 1,
       failures: [],
     });
-    expect(findByExternalId(db, 'both')).toBeUndefined();
+    expect(findByName(db, 'both')).toBeUndefined();
   });
 
   it('activity does not extend a deadline — it is an absolute clock', async () => {
@@ -576,10 +571,10 @@ describe('E2B deadline rule', () => {
     const row = await seedWithDeadline(db, executor, 'busy', null, 100, 'kill');
     // The sandbox stays busy right up to the deadline; E2B kills anyway —
     // only create/connect/setTimeout move a deadline, never activity.
-    touch(db, row.sandboxId, after(row, 99).toISOString());
+    touch(db, row.id, after(row, 99).toISOString());
     const result = await scanOnce(db, executor, locks, after(row, 101));
     expect(result.expiredKilled).toBe(1);
-    expect(findByExternalId(db, 'busy')).toBeUndefined();
+    expect(findByName(db, 'busy')).toBeUndefined();
   });
 
   it('parks an expired pause-deadline sandbox frozen, once, and keeps the row', async () => {
@@ -601,8 +596,8 @@ describe('E2B deadline rule', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'parked')?.state).toBe('frozen');
-    expect(executor.stateOf(row.sandboxId)).toBe('paused');
+    expect(findByName(db, 'parked')?.state).toBe('frozen');
+    expect(executor.stateOf(row.id)).toBe('paused');
 
     // A second sweep finds no physical work left: frozen already satisfies
     // the pause action, and the logical view reads the deadline directly.
@@ -614,6 +609,6 @@ describe('E2B deadline rule', () => {
       expiredKilled: 0,
       failures: [],
     });
-    expect(findByExternalId(db, 'parked')?.state).toBe('frozen');
+    expect(findByName(db, 'parked')?.state).toBe('frozen');
   });
 });
diff --git a/packages/server/src/scanner.ts b/packages/server/src/scanner.ts
index 0c5b7f4..afd4bb0 100644
--- a/packages/server/src/scanner.ts
+++ b/packages/server/src/scanner.ts
@@ -1,6 +1,6 @@
 import type { Archiver } from './archive/archiver';
 import type { Db } from './db/db';
-import { findBySandboxId, listSandboxes } from './db/ledger';
+import { findById, listSandboxes } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
@@ -128,8 +128,8 @@ export async function scanOnce(
       continue;
     }
     try {
-      await locks.tryRun(row.externalId, async () => {
-        const fresh = findBySandboxId(db, row.sandboxId);
+      await locks.tryRun(row.name, async () => {
+        const fresh = findById(db, row.id);
         if (!fresh) {
           return; // Released since the sweep's snapshot.
         }
@@ -140,7 +140,7 @@ export async function scanOnce(
           await destroySandbox(
             db,
             executor,
-            fresh.sandboxId,
+            fresh.id,
             archiver?.store ?? null,
             { kind: 'expired-killed', cause: 'E2B deadline (kill) reached' },
           );
@@ -151,7 +151,7 @@ export async function scanOnce(
           await freezeSandbox(
             db,
             executor,
-            fresh.sandboxId,
+            fresh.id,
             'E2B deadline reached (pause)',
           );
           result.frozen += 1;
@@ -162,7 +162,7 @@ export async function scanOnce(
           await freezeSandbox(
             db,
             executor,
-            fresh.sandboxId,
+            fresh.id,
             `idle ${fresh.freezeAfterSeconds}s reached — memory squeezed into swap (scanner)`,
           );
           result.frozen += 1;
@@ -170,7 +170,7 @@ export async function scanOnce(
           await stopSandbox(
             db,
             executor,
-            fresh.sandboxId,
+            fresh.id,
             `idle ${fresh.stopAfterSeconds}s reached — container torn down, disk kept (scanner)`,
           );
           result.stopped += 1;
@@ -178,7 +178,7 @@ export async function scanOnce(
       });
     } catch (error) {
       result.failures.push({
-        sandboxId: row.sandboxId,
+        sandboxId: row.id,
         message: error instanceof Error ? error.message : String(error),
       });
     }
@@ -187,8 +187,8 @@ export async function scanOnce(
   if (archiver === undefined) return result;
   for (const row of archiveDue) {
     try {
-      await locks.tryRun(row.externalId, async () => {
-        const fresh = findBySandboxId(db, row.sandboxId);
+      await locks.tryRun(row.name, async () => {
+        const fresh = findById(db, row.id);
         // Re-verified in the slot: phase one may have killed it by
         // deadline, an acquire may have woken it, a destroy removed it —
         // the snapshot's opinion is void either way.
@@ -204,7 +204,7 @@ export async function scanOnce(
       });
     } catch (error) {
       result.failures.push({
-        sandboxId: row.sandboxId,
+        sandboxId: row.id,
         message: error instanceof Error ? error.message : String(error),
       });
     }
diff --git a/packages/shared/src/acquire.ts b/packages/shared/src/acquire.ts
index efe65b0..74afbe0 100644
--- a/packages/shared/src/acquire.ts
+++ b/packages/shared/src/acquire.ts
@@ -1,21 +1,21 @@
 import { z } from 'zod';
 import { lifecyclePolicyOverrideSchema } from './policy';
 import {
-  externalIdSchema,
   sandboxMetadataSchema,
+  sandboxNameSchema,
   sandboxSchema,
 } from './sandbox';
 import { templateNameSchema } from './templates';
 
 /**
- * acquire(externalId) — the platform's single entry point. Idempotent:
+ * acquire(name) — the platform's single entry point. Idempotent:
  * no sandbox → create; frozen → wake; stopped → rebuild; archived → restore.
  */
 export const acquireRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
   /**
    * Lifecycle override applied when this acquire creates the sandbox;
-   * omitted fields fall back to the daemon's global defaults. When the key
+   * omitted fields fall back to the daemon's global defaults. When the name
    * already has a sandbox, the stored policy stays — acquire is not an
    * update verb — but an invalid override is still answered with a 400,
    * never silently ignored.
@@ -44,14 +44,23 @@ export type AcquireRequest = z.infer<typeof acquireRequestSchema>;
  * in seconds and returns `ready`; an archived sandbox returns `restoring`
  * with progress immediately, and the caller polls acquire() until it flips
  * to `ready`.
+ *
+ * `created` makes the idempotency observable per call: names collide by
+ * converging, never by erroring, so this flag is the only way a caller
+ * learns "I got an existing sandbox back" at the moment it happens (and
+ * that the policy/template/metadata in the request were therefore ignored).
  */
 export const acquireResponseSchema = z.discriminatedUnion('status', [
   z.object({
     status: z.literal('ready'),
+    /** True when this acquire created the sandbox; false when the name already had one. */
+    created: z.boolean(),
     sandbox: sandboxSchema,
   }),
   z.object({
     status: z.literal('restoring'),
+    /** Always false: only an already-archived sandbox restores. */
+    created: z.boolean(),
     sandbox: sandboxSchema,
     progress: z.object({
       /** downloading — pulling the archive from S3; extracting — decompressing onto local disk. */
diff --git a/packages/shared/src/activity.ts b/packages/shared/src/activity.ts
index ae04595..a298653 100644
--- a/packages/shared/src/activity.ts
+++ b/packages/shared/src/activity.ts
@@ -52,8 +52,12 @@ export const activityEventSchema = z.object({
   /** ISO 8601 UTC. */
   at: z.string(),
   kind: activityKindSchema,
-  /** Null for events with no owning sandbox (orphan sweeps, daemon start). */
-  externalId: z.string().nullable(),
+  /**
+   * Null for events with no owning sandbox (orphan sweeps, daemon start).
+   * Prefixed because they reference another entity: a bare `name` here
+   * would read as the event's own name (`id` above already is its own).
+   */
+  sandboxName: z.string().nullable(),
   sandboxId: z.string().nullable(),
   /** One short line of context: which actor, which threshold, what was repaired. */
   detail: z.string(),
diff --git a/packages/shared/src/destroy.ts b/packages/shared/src/destroy.ts
index b1ba8f2..68450d0 100644
--- a/packages/shared/src/destroy.ts
+++ b/packages/shared/src/destroy.ts
@@ -1,20 +1,20 @@
 import { z } from 'zod';
-import { externalIdSchema } from './sandbox';
+import { sandboxNameSchema } from './sandbox';
 
 /**
- * destroySandbox(externalId) — the end of a sandbox's life: container and disk
- * are destroyed for good. Idempotent like acquire, and on the same key: the
- * desired end state is "no sandbox under this key", so destroying a key that
- * has nothing is not an error.
+ * destroySandbox(name) — the end of a sandbox's life: container and disk
+ * are destroyed for good. Idempotent like acquire, and on the same name: the
+ * desired end state is "no sandbox under this name", so destroying a name
+ * that has nothing is not an error.
  */
 export const destroySandboxRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
 });
 
 export type DestroySandboxRequest = z.infer<typeof destroySandboxRequestSchema>;
 
 export const destroySandboxResponseSchema = z.object({
-  /** True when a sandbox existed and was destroyed; false when the key already had nothing. */
+  /** True when a sandbox existed and was destroyed; false when the name already had nothing. */
   destroyed: z.boolean(),
 });
 
diff --git a/packages/shared/src/exec.ts b/packages/shared/src/exec.ts
index bcab7b4..2e3b906 100644
--- a/packages/shared/src/exec.ts
+++ b/packages/shared/src/exec.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { externalIdSchema } from './sandbox';
+import { sandboxNameSchema } from './sandbox';
 
 /** In-container deadline applied when the caller does not set one. */
 export const DEFAULT_EXEC_TIMEOUT_SECONDS = 300;
@@ -16,13 +16,13 @@ export const MAX_EXEC_TIMEOUT_SECONDS = 86_400;
 export const EXEC_OUTPUT_LIMIT_BYTES = 1024 * 1024;
 
 /**
- * execCommand(externalId, command) — runs a shell command inside the sandbox
- * behind the key and waits for it to finish. A cold (frozen/stopped) sandbox
+ * execCommand(name, command) — runs a shell command inside the sandbox
+ * behind the name and waits for it to finish. A cold (frozen/stopped) sandbox
  * is woken first; a running command counts as activity, so the idle scanner
  * never freezes a sandbox mid-command.
  */
 export const execCommandRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
   /** A shell string, executed as `bash -c <command>` inside the sandbox. */
   command: z.string().min(1),
   /**
diff --git a/packages/shared/src/files.ts b/packages/shared/src/files.ts
index a21d3f2..720ef2f 100644
--- a/packages/shared/src/files.ts
+++ b/packages/shared/src/files.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { externalIdSchema } from './sandbox';
+import { sandboxNameSchema } from './sandbox';
 
 /**
  * Per-file size cap, write and read alike. Content crosses the wire as
@@ -75,14 +75,14 @@ const fileContentSchema = z
   });
 
 /**
- * writeFiles(externalId, files) — writes every file in the batch into the
- * sandbox behind the key, waking it first if it is cold. Parent directories
+ * writeFiles(name, files) — writes every file in the batch into the
+ * sandbox behind the name, waking it first if it is cold. Parent directories
  * are created as needed; an existing file is overwritten. Writes happen in
  * array order and fail fast: on error the earlier files are already written
  * — the batch is a round-trip saver, not a transaction.
  */
 export const writeFilesRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
   files: z
     .array(
       z.object({
@@ -104,13 +104,13 @@ export const writeFilesResponseSchema = z.object({
 export type WriteFilesResponse = z.infer<typeof writeFilesResponseSchema>;
 
 /**
- * writeFile(externalId, path, content) — the single-file form of writeFiles:
+ * writeFile(name, path, content) — the single-file form of writeFiles:
  * same rules (parents created, existing file overwritten, same size cap),
  * one file, no array to wrap and unwrap. Kept as its own verb so the wire,
  * the SDK and the docs stay one name per intent.
  */
 export const writeFileRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
   path: sandboxPathSchema,
   /** The file's bytes, base64. Text is just UTF-8 bytes — the SDK encodes strings transparently. */
   contentBase64: fileContentSchema,
@@ -126,14 +126,14 @@ export const writeFileResponseSchema = z.object({
 export type WriteFileResponse = z.infer<typeof writeFileResponseSchema>;
 
 /**
- * readFile(externalId, path) — returns one file's bytes. A file over the size
+ * readFile(name, path) — returns one file's bytes. A file over the size
  * limit is refused outright (413 naming the actual size), never truncated:
  * unlike exec output, where a capped log still informs, a truncated file is
  * simply a corrupt file — an honest error beats delivering damaged goods.
  * Missing file: 404. Directory or other non-regular file: 400.
  */
 export const readFileRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
   path: sandboxPathSchema,
 });
 
@@ -148,7 +148,7 @@ export const readFileResponseSchema = z.object({
 export type ReadFileResponse = z.infer<typeof readFileResponseSchema>;
 
 /**
- * readFiles(externalId, paths) — the batch form of readFile, all or nothing:
+ * readFiles(name, paths) — the batch form of readFile, all or nothing:
  * one missing path fails the whole call (404 naming it), same for a
  * non-regular file (400) or a per-file size overrun (413). A partial result
  * is not offered on purpose — a batch read that silently drops a file is a
@@ -157,7 +157,7 @@ export type ReadFileResponse = z.infer<typeof readFileResponseSchema>;
  * by READ_FILES_TOTAL_LIMIT_BYTES (413 when the haul exceeds it).
  */
 export const readFilesRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
   paths: z.array(sandboxPathSchema).min(1),
 });
 
diff --git a/packages/shared/src/images.ts b/packages/shared/src/images.ts
index 190c029..c861c6c 100644
--- a/packages/shared/src/images.ts
+++ b/packages/shared/src/images.ts
@@ -21,8 +21,10 @@ export type ListSandboxImagesRequest = z.infer<
 
 export const listSandboxImagesResponseSchema = z.object({
   images: z.array(
+    // Prefixed because these reference the sandbox from outside it — and a
+    // bare `name` in a row about images would read as an image name.
     z.object({
-      externalId: z.string(),
+      sandboxName: z.string(),
       sandboxId: z.string(),
       /**
        * The image the current shell was born from. Null when no shell
diff --git a/packages/shared/src/metrics.ts b/packages/shared/src/metrics.ts
index c1e3225..91d4fad 100644
--- a/packages/shared/src/metrics.ts
+++ b/packages/shared/src/metrics.ts
@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { externalIdSchema } from './sandbox';
+import { sandboxNameSchema } from './sandbox';
 
 /**
- * getSandboxMetrics(externalId) — one sandbox's point-in-time resource
+ * getSandboxMetrics(name) — one sandbox's point-in-time resource
  * reading: the per-sandbox sibling of getHostMetrics, and the native twin
  * of the E2B surface's metrics endpoint (same executor reading). For the
  * past instead of the present, getSandboxMetricsHistory below serves the
@@ -27,7 +27,7 @@ export const sandboxMetricsSampleSchema = z.object({
 export type SandboxMetricsSample = z.infer<typeof sandboxMetricsSampleSchema>;
 
 export const getSandboxMetricsRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
 });
 
 export type GetSandboxMetricsRequest = z.infer<
@@ -58,8 +58,10 @@ export type ListSandboxMetricsRequest = z.infer<
 
 export const listSandboxMetricsResponseSchema = z.object({
   samples: z.array(
+    // References from outside the sandbox object carry the entity's name:
+    // a bare `name`/`id` here would read as the row's own identity.
     z.object({
-      externalId: z.string(),
+      sandboxName: z.string(),
       sandboxId: z.string(),
       sample: sandboxMetricsSampleSchema,
     }),
@@ -71,7 +73,7 @@ export type ListSandboxMetricsResponse = z.infer<
 >;
 
 /**
- * getSandboxMetricsHistory(externalId, start?, end?) — the sampled past of
+ * getSandboxMetricsHistory(name, start?, end?) — the sampled past of
  * one sandbox. The daemon's background sampler persists a reading per
  * measurable sandbox every DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS; this
  * verb slices that history. History exists because it is a compatibility
@@ -101,7 +103,7 @@ const isoTimestampSchema = z
   });
 
 export const getSandboxMetricsHistoryRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
   /** ISO 8601; defaults to one hour before `end`. */
   start: isoTimestampSchema.optional(),
   /** ISO 8601; defaults to now. */
diff --git a/packages/shared/src/rebuild.ts b/packages/shared/src/rebuild.ts
index 0933af6..43bb734 100644
--- a/packages/shared/src/rebuild.ts
+++ b/packages/shared/src/rebuild.ts
@@ -1,18 +1,18 @@
 import { z } from 'zod';
-import { externalIdSchema, sandboxSchema } from './sandbox';
+import { sandboxNameSchema, sandboxSchema } from './sandbox';
 
 /**
- * rebuildSandbox(externalId) — swap the container, keep the disk. The disk is
+ * rebuildSandbox(name) — swap the container, keep the disk. The disk is
  * the sandbox's body; the container is a replaceable shell built from the
  * daemon's current base image. Removing the shell and letting the next wake
  * rebuild it is how an existing sandbox picks up a new base image without
  * losing a byte of /home/user.
  *
- * Not idempotent-forgiving like destroy: rebuilding a key that has no
+ * Not idempotent-forgiving like destroy: rebuilding a name that has no
  * sandbox is a caller's confusion (a typo, not a goal state) and answers 404.
  */
 export const rebuildSandboxRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
 });
 
 export type RebuildSandboxRequest = z.infer<typeof rebuildSandboxRequestSchema>;
diff --git a/packages/shared/src/sandbox.ts b/packages/shared/src/sandbox.ts
index 29688d9..0bb17cf 100644
--- a/packages/shared/src/sandbox.ts
+++ b/packages/shared/src/sandbox.ts
@@ -4,13 +4,17 @@ import { SANDBOX_STATES } from './states';
 import { templateNameSchema } from './templates';
 
 /**
- * The caller's identifier from their own system — a user id, a session id,
- * a CI job name — that acquire() is idempotent on: same external id, same
- * sandbox, whatever state it was in. sandboxId is the daemon's internal
- * identity; this is the external one, and it is the API's handle. Opaque to
- * the daemon; bounded so it can serve as an indexed column.
+ * The caller-chosen name of a sandbox — a user id, a session id, a CI job
+ * name — and the identifier every verb addresses sandboxes by. UNIQUE per
+ * daemon, but not the way most systems are: acquire(name) never rejects a
+ * duplicate — the same name always comes back to the same sandbox, whatever
+ * state it was in (get-or-create, like `docker --name` or a Kubernetes
+ * metadata.name). The name is the address across lifetimes: destroy a
+ * sandbox and acquire its name again, and a brand-new sandbox answers under
+ * the old address. Opaque to the daemon; bounded so it can serve as an
+ * indexed column.
  */
-export const externalIdSchema = z.string().min(1).max(128);
+export const sandboxNameSchema = z.string().min(1).max(128);
 
 /**
  * Caller-owned labels on a sandbox — a string→string map, opaque to the
@@ -26,11 +30,17 @@ export type SandboxMetadata = z.infer<typeof sandboxMetadataSchema>;
 /**
  * A sandbox as reported by the daemon — the wire shape shared by the HTTP
  * API, the SDK, and the web console.
+ *
+ * Two identities, two jobs: `name` is the caller's address (unique,
+ * acquire-idempotent, survives destroy-and-recreate as an address), `id` is
+ * the platform's identity for THIS incarnation — rebuild keeps it, destroy
+ * plus re-acquire mints a new one. Verbs take `name`; `id` appears only in
+ * answers and internal references, never as a request parameter.
  */
 export const sandboxSchema = z.object({
-  /** Generated by the daemon. UUID, never a DB autoincrement — ids must stay unique across machines. */
-  sandboxId: z.string(),
-  externalId: externalIdSchema,
+  /** Platform-assigned UUID, never a DB autoincrement — ids must stay unique across machines. */
+  id: z.string(),
+  name: sandboxNameSchema,
   state: z.enum(SANDBOX_STATES),
   /** Machine that owns this sandbox. Single-machine today; the field keeps the ledger shardable. */
   nodeId: z.string(),
diff --git a/packages/shared/src/update-metadata.ts b/packages/shared/src/update-metadata.ts
index 8dd0988..153d506 100644
--- a/packages/shared/src/update-metadata.ts
+++ b/packages/shared/src/update-metadata.ts
@@ -1,12 +1,12 @@
 import { z } from 'zod';
 import {
-  externalIdSchema,
   sandboxMetadataSchema,
+  sandboxNameSchema,
   sandboxSchema,
 } from './sandbox';
 
 /**
- * updateMetadata(externalId, metadata) — the update verb acquire deliberately
+ * updateMetadata(name, metadata) — the update verb acquire deliberately
  * is not. Without it, a sandbox could only ever be labeled at birth: the
  * fleet you already run would be un-groupable forever.
  *
@@ -19,7 +19,7 @@ import {
  * and the idle clock is NOT refreshed — relabeling is not sandbox activity.
  */
 export const updateMetadataRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
   metadata: sandboxMetadataSchema,
 });
 
diff --git a/packages/shared/src/update-policy.ts b/packages/shared/src/update-policy.ts
index e313c63..a3dac98 100644
--- a/packages/shared/src/update-policy.ts
+++ b/packages/shared/src/update-policy.ts
@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { lifecyclePolicyOverrideSchema } from './policy';
-import { externalIdSchema, sandboxSchema } from './sandbox';
+import { sandboxNameSchema, sandboxSchema } from './sandbox';
 
 /**
- * updatePolicy(externalId, policy) — the update verb acquire deliberately is not.
+ * updatePolicy(name, policy) — the update verb acquire deliberately is not.
  * Without it, changing a live sandbox's lifecycle (say, promoting it to a
  * never-stop resident agent) would require destroy + re-acquire, and destroy
  * removes the disk — the one thing this platform promises to keep.
@@ -18,7 +18,7 @@ import { externalIdSchema, sandboxSchema } from './sandbox';
  * thresholds apply to the idle time already accumulated.
  */
 export const updatePolicyRequestSchema = z.object({
-  externalId: externalIdSchema,
+  name: sandboxNameSchema,
   policy: lifecyclePolicyOverrideSchema,
 });
 
diff --git a/skills/dormice/SKILL.md b/skills/dormice/SKILL.md
index 97a82c4..2e62d70 100644
--- a/skills/dormice/SKILL.md
+++ b/skills/dormice/SKILL.md
@@ -10,11 +10,11 @@ sandboxes that are **permanent** — idle ones cool down
 (`active → frozen → stopped → archived`) instead of being destroyed, and any
 acquire brings them back. Two facts drive every workflow below:
 
-- **`acquireSandbox(externalId)` is the entire mental model.** Idempotent:
-  the same key always returns the same sandbox, whatever state it was in.
+- **`acquireSandbox(name)` is the entire mental model.** Idempotent — the name is a unique address that never errors as a duplicate:
+  the same name always returns the same sandbox, whatever state it was in.
   No sandbox → create; frozen → wake (~50 ms); stopped → start; archived →
   restore. Only `acquireSandbox` creates — other verbs answer 404 for an
-  unknown key.
+  unknown name.
 - **The disk, not the container, is the sandbox's body.** Files survive
   freezes, stops, daemon restarts, and host reboots. Only `destroySandbox`
   loses data.
@@ -70,7 +70,7 @@ sandbox.commands.run("echo hello")
 
 `Sandbox.create` makes a fresh sandbox each time (faithful E2B semantics).
 To get Dormice's idempotent acquire through the E2B surface, pass
-`metadata: { externalId: 'my-project' }` — the same key then always returns
+`metadata: { name: 'my-project' }` — the same name then always returns
 the same sandbox with its files intact. E2B `timeoutMs` deadlines are real:
 at the deadline the sandbox is killed, or parked with
 `lifecycle: { onTimeout: 'pause' }` and revived by `connect`.
@@ -107,7 +107,7 @@ The same loop in curl:
 curl -X POST http://127.0.0.1:3676/acquireSandbox \
   -H "Authorization: Bearer $DORMICE_API_TOKEN" \
   -H "content-type: application/json" \
-  -d '{"externalId": "my-agent"}'
+  -d '{"name": "my-agent"}'
 ```
 
 Verbs: `acquireSandbox` (optionally with `metadata` — string-to-string
@@ -126,7 +126,7 @@ runs an old template image), `listActivity` (recent daemon history),
 `getConfig` (effective config, secrets redacted), `getIngress` /
 `setIngress` (bind domains on the daemon's managed reverse proxy).
 `execCommand` takes
-`{ externalId, command, timeoutSeconds?, cwd?, env? }` and returns
+`{ name, command, timeoutSeconds?, cwd?, env? }` and returns
 `{ exitCode, stdout, stderr, ... }` — **a non-zero exit code is a result,
 not an HTTP error**. When a sandbox is coming back from S3, `acquireSandbox`
 returns `{ status: 'restoring', progress }` immediately; poll it until the
diff --git a/website/content/docs/cli.mdx b/website/content/docs/cli.mdx
index 3aed83c..6e3ceb8 100644
--- a/website/content/docs/cli.mdx
+++ b/website/content/docs/cli.mdx
@@ -30,24 +30,24 @@ terminal.)
 ## dor sandbox exec
 
 ```sh
-dor sandbox exec <externalId> '<command>' [-t <seconds>]
+dor sandbox exec <name> '<command>' [-t <seconds>]
 ```
 
-Runs a shell command in the sandbox behind the key, waking it first. The
+Runs a shell command in the named sandbox, waking it first. The
 command is one quoted argument, executed as `bash -c`. Its stdout and
 stderr pass through to yours, and **its exit code becomes `dor`'s exit
 code** — so `dor sandbox exec` in a script behaves like the command
 itself.
 
 `-t, --timeout <seconds>` kills the command after that long
-([enforced inside the container](/docs/commands)). An unknown key is a
+([enforced inside the container](/docs/commands)). An unknown name is a
 404, never a sandbox created by accident.
 
 ## dor sandbox push / pull
 
 ```sh
-dor sandbox push <externalId> <localPath> [remotePath]
-dor sandbox pull <externalId> <remotePath> [localPath]
+dor sandbox push <name> <localPath> [remotePath]
+dor sandbox pull <name> <remotePath> [localPath]
 ```
 
 One file in, one file out. Relative remote paths land under
@@ -58,7 +58,7 @@ wherever. Both obey the [16 MiB single-file limit](/docs/files).
 ## dor sandbox rebuild
 
 ```sh
-dor sandbox rebuild <externalId>
+dor sandbox rebuild <name>
 ```
 
 Swaps the container and keeps `/home/user` — the sandbox's next use
@@ -69,11 +69,11 @@ Details: [Rebuild a sandbox](/docs/persistence#rebuild-a-sandbox).
 ## dor sandbox destroy
 
 ```sh
-dor sandbox destroy <externalId>
+dor sandbox destroy <name>
 ```
 
 Destroys the sandbox — container, disk, and (if archived) the S3
-object. The only command that loses data. Idempotent: destroying a key
+object. The only command that loses data. Idempotent: destroying a name
 that has no sandbox reports so and exits 0.
 
 ## dor template
diff --git a/website/content/docs/commands.mdx b/website/content/docs/commands.mdx
index 51ee472..bf0d317 100644
--- a/website/content/docs/commands.mdx
+++ b/website/content/docs/commands.mdx
@@ -23,7 +23,7 @@ result.stdoutTruncated; // false — see "Output limits" below
 
 **A non-zero exit code is a result, not an error.** `execCommand`
 resolves with `exitCode: 1` — it does not throw. Errors are reserved for
-the protocol failing: 404 when no sandbox exists behind the key (one is
+the protocol failing: 404 when no sandbox exists behind the name (one is
 never silently created), 409 while a sandbox is mid-restore.
 
 ## Run a command from the CLI
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
index bfa2054..624cb13 100644
--- a/website/content/docs/console.mdx
+++ b/website/content/docs/console.mdx
@@ -43,7 +43,7 @@ at 90%; a host without swap gets an amber warning pointing at
 The live list — every sandbox with its state and live CPU, memory, and
 disk columns, refreshed every few seconds, with search, a state filter,
 sorting, and multi-select batch destroy. Creating a sandbox from here
-is exactly `acquireSandbox`: a key, the lifecycle knobs (including the
+is exactly `acquireSandbox`: a name, the lifecycle knobs (including the
 never-stop [resident-agent switch](/docs/resident-agents)), and a
 template dropdown when templates are registered. After a
 [template upgrade](/docs/templates#update-a-template), sandboxes still
diff --git a/website/content/docs/core-concepts.mdx b/website/content/docs/core-concepts.mdx
index 329ae6d..f3f4f87 100644
--- a/website/content/docs/core-concepts.mdx
+++ b/website/content/docs/core-concepts.mdx
@@ -58,6 +58,19 @@ or lost to a crash, and the sandbox's files survive every time. Only
 `destroySandbox` deletes the disk. [Sandbox
 persistence](/docs/persistence) is the full story.
 
+Every sandbox carries two identifiers, and they answer two different
+questions. The **name** is yours — a user id, a session id, a CI job
+name — and it is how every API call addresses the sandbox. Names are
+unique, but not the way most systems are: `acquireSandbox(name)` never
+rejects a duplicate — the same name always comes back to the same
+sandbox, waking or restoring it as needed (like `docker --name`, or a
+Kubernetes resource name). Destroy a sandbox and acquire its name again,
+and a brand-new sandbox answers under the old address; the response's
+`created` flag tells you which happened. The **id** is the platform's —
+a UUID minted at creation that identifies *this incarnation*: rebuilding
+keeps it, destroy-and-recreate mints a new one. You never pass `id` to
+an API call; it only appears in responses.
+
 ## The daemon
 
 A daemon is a program that runs in the background forever rather than
diff --git a/website/content/docs/e2b-differences.mdx b/website/content/docs/e2b-differences.mdx
index 8d3d745..194b4f3 100644
--- a/website/content/docs/e2b-differences.mdx
+++ b/website/content/docs/e2b-differences.mdx
@@ -42,7 +42,7 @@ daemon:
 - **Permanence stays the default.** Sandboxes created through the E2B
   surface get real deadlines, as E2B semantics demand; deadlines are
   never imposed on natively created sandboxes.
-- **`metadata.externalId`** turns `Sandbox.create` into Dormice's
+- **`metadata.name`** turns `Sandbox.create` into Dormice's
   idempotent acquire — see
   [Using the official E2B SDKs](/docs/e2b-sdks).
 - **One domain, not one subdomain per sandbox.** The SDK addresses
diff --git a/website/content/docs/e2b-sdks.mdx b/website/content/docs/e2b-sdks.mdx
index f188db5..700debf 100644
--- a/website/content/docs/e2b-sdks.mdx
+++ b/website/content/docs/e2b-sdks.mdx
@@ -61,14 +61,14 @@ construction, so the Python SDK's validation never bites.
 
 ## Reuse the same sandbox across creates
 
-A Dormice extension: pass `metadata: { externalId: '...' }` and
-`Sandbox.create` behaves like the native `acquireSandbox` — the same key
+A Dormice extension: pass `metadata: { name: '...' }` and
+`Sandbox.create` behaves like the native `acquireSandbox` — the same name
 always returns the same sandbox instead of a new one, whatever state it
 was in, files intact:
 
 ```ts
 const sbx = await Sandbox.create({
-  metadata: { externalId: 'my-project' },
+  metadata: { name: 'my-project' },
   // ...the two URLs and apiKey as above
 });
 ```
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
index 6332bc4..540d728 100644
--- a/website/content/docs/http-api.mdx
+++ b/website/content/docs/http-api.mdx
@@ -11,7 +11,7 @@ method name, so there is nothing the SDK can do that curl cannot:
 curl -X POST http://127.0.0.1:3676/acquireSandbox \
   -H "Authorization: Bearer $DORMICE_API_TOKEN" \
   -H "content-type: application/json" \
-  -d '{"externalId": "my-agent"}'
+  -d '{"name": "my-agent"}'
 ```
 
 Two rules cover the whole surface:
@@ -32,16 +32,16 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 
 | Route | Does | Errors worth knowing |
 | --- | --- | --- |
-| `POST /acquireSandbox` | create, wake, or restore — idempotent per key | 400 invalid policy/unknown template, 429 at the sandbox limit |
-| `POST /updatePolicy` | patch an existing sandbox's [lifecycle policy](/docs/lifecycle#change-the-policy-later) in place; never wakes, never resets the idle clock | 404 unknown key, 400 invalid merged policy |
-| `POST /updateMetadata` | replace an existing sandbox's label set wholesale (`{}` clears); never wakes, never resets the idle clock | 404 unknown key |
+| `POST /acquireSandbox` | create, wake, or restore — idempotent per name | 400 invalid policy/unknown template, 429 at the sandbox limit |
+| `POST /updatePolicy` | patch an existing sandbox's [lifecycle policy](/docs/lifecycle#change-the-policy-later) in place; never wakes, never resets the idle clock | 404 unknown name, 400 invalid merged policy |
+| `POST /updateMetadata` | replace an existing sandbox's label set wholesale (`{}` clears); never wakes, never resets the idle clock | 404 unknown name |
 | `POST /listSandboxes` | every sandbox and its state; never wakes anything | — |
-| `POST /execCommand` | run a command, buffered | 404 unknown key, 409 archived/restoring |
+| `POST /execCommand` | run a command, buffered | 404 unknown name, 409 archived/restoring |
 | `POST /writeFiles` | batch write, base64 in JSON | 404/409 as above; body over 48 MiB refused |
 | `POST /writeFile` | write one file — the single form of `writeFiles` | same as `writeFiles` |
 | `POST /readFile` | read one file, base64 out | 404 no such file, 400 not a file, 413 over 16 MiB (names the real size) |
 | `POST /readFiles` | batch read, all or nothing, request order | first bad path fails the whole batch; 413 over 48 MiB total |
-| `POST /rebuildSandbox` | swap container, keep `/home/user` | 404 unknown key, 409 archived/restoring |
+| `POST /rebuildSandbox` | swap container, keep `/home/user` | 404 unknown name, 409 archived/restoring |
 | `POST /destroySandbox` | destroy; idempotent | 409 mid-restore — retry when it finishes |
 | `POST /registerTemplate` | upsert name → image | 400 `'base'` is reserved |
 | `POST /listTemplates` | every registered template | — |
@@ -50,7 +50,7 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | `POST /listApiKeys` | every key ever minted, revoked ones included, newest first — no secrets | — |
 | `POST /revokeApiKey` | soft-revoke the active key under a name; idempotent (`revoked: false` when none was) | — |
 | `POST /getHostMetrics` | host snapshot; never wakes anything | — |
-| `POST /getSandboxMetrics` | one sandbox's live CPU/memory/disk sample; `sample` is `null` when nothing is running | 404 unknown key |
+| `POST /getSandboxMetrics` | one sandbox's live CPU/memory/disk sample; `sample` is `null` when nothing is running | 404 unknown name |
 | `POST /listSandboxMetrics` | every measurable sandbox's sample in one answer | — |
 | `POST /listSandboxImages` | each sandbox's born image vs its template's current one | — |
 | `POST /listActivity` | the daemon's recent history, newest first — a bounded ring, not an audit log | — |
@@ -59,8 +59,8 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | `POST /setIngress` | rewrite the managed proxy config to exactly this domain list (empty list unbinds all) | 400 when the daemon manages no proxy |
 
 **Only `acquireSandbox` creates.** The use verbs (`execCommand`, files,
-`rebuildSandbox`) answer 404 for an unknown key rather than creating a
-sandbox as a side effect — an unknown key is more likely a typo than an
+`rebuildSandbox`) answer 404 for an unknown name rather than creating a
+sandbox as a side effect — an unknown name is more likely a typo than an
 intent.
 
 ## The sandbox object
@@ -69,7 +69,7 @@ Everything that returns a sandbox returns this shape:
 
 ```json
 {
-  "sandboxId": "8b1e…-uuid", "externalId": "my-agent",
+  "id": "8b1e…-uuid", "name": "my-agent",
   "state": "active", "nodeId": "…", "endpoint": "http://127.0.0.1:3676",
   "policy": { "freezeAfterSeconds": 600, "stopAfterSeconds": 259200, "archiveAfterSeconds": null },
   "template": null, "metadata": { "app": "crawler", "env": "prod" },
@@ -77,8 +77,12 @@ Everything that returns a sandbox returns this shape:
 }
 ```
 
+`name` is yours and `id` is the platform's — [two identities with two
+jobs](/docs/core-concepts#sandboxes). Every verb addresses sandboxes by
+`name`; `id` only ever appears in responses.
+
 `metadata` is your own string-to-string labels — pass it to
-`acquireSandbox` at creation (`{"externalId": "…", "metadata": {"app": "crawler"}}`),
+`acquireSandbox` at creation (`{"name": "…", "metadata": {"app": "crawler"}}`),
 relabel later with `updateMetadata`, group and filter on it in the
 console or your own `listSandboxes` loop. The daemon never interprets
 it; a sandbox without labels reads `{}`, never `null`. Like `policy`
@@ -88,11 +92,14 @@ which is what `updateMetadata` is for.
 
 `state` is one of `active | frozen | stopped | archived | restoring`
 (the [lifecycle states](/docs/lifecycle)). `acquireSandbox` wraps it in
-a union: `{ "status": "ready", "sandbox": … }`, or — when the sandbox is
-coming back from S3 —
-`{ "status": "restoring", "sandbox": …, "progress": { "phase": "downloading" | "extracting", "percent": … } }`;
+a union: `{ "status": "ready", "created": true | false, "sandbox": … }`,
+or — when the sandbox is coming back from S3 —
+`{ "status": "restoring", "created": false, "sandbox": …, "progress": { "phase": "downloading" | "extracting", "percent": … } }`;
 poll acquire until it flips to `ready` (see
-[Archiving](/docs/archiving)).
+[Archiving](/docs/archiving)). `created` is how a caller sees which side
+of the idempotency it landed on: names converge on the existing sandbox
+instead of erroring as duplicates, so `created: false` is the only
+signal that the policy/template/metadata in the request were ignored.
 
 ## API keys
 
@@ -116,15 +123,15 @@ your rotation history.
 
 ## Commands and files on the wire
 
-`execCommand` takes `{ externalId, command, timeoutSeconds?, cwd?, env? }`
+`execCommand` takes `{ name, command, timeoutSeconds?, cwd?, env? }`
 and returns
 `{ exitCode, stdout, stderr, stdoutTruncated, stderrTruncated }` — a
 non-zero exit code is a result, not an HTTP error
 ([details](/docs/commands)).
 
 File content crosses the wire as base64 inside JSON: `writeFiles` takes
-`{ externalId, files: [{ path, contentBase64 }] }`; `readFile` takes
-`{ externalId, path }` and returns `{ path, contentBase64 }` with the
+`{ name, files: [{ path, contentBase64 }] }`; `readFile` takes
+`{ name, path }` and returns `{ path, contentBase64 }` with the
 path resolved absolute. Each has a twin for the other arity: `writeFile`
 writes one file without the array, `readFiles` reads a batch all or
 nothing. Limits and error semantics: [Moving files](/docs/files).
diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdx
index a371293..fd8671e 100644
--- a/website/content/docs/index.mdx
+++ b/website/content/docs/index.mdx
@@ -33,7 +33,7 @@ console.log(result.stdout); // Hello from Dormice!
 - **Sandboxes are permanent.** Cloud sandbox platforms charge for every
   second a sandbox exists, so their sandboxes are disposable. Dormice
   inverts that: `acquireSandbox('my-agent')` always returns the same
-  sandbox for the same key — today, tomorrow, next month — with all its
+  sandbox for the same name — today, tomorrow, next month — with all its
   files intact.
 - **Idle costs almost nothing.** Idle sandboxes cool down on their own
   (`active → frozen → stopped → archived` — the
diff --git a/website/content/docs/metrics.mdx b/website/content/docs/metrics.mdx
index d8b1286..3d26058 100644
--- a/website/content/docs/metrics.mdx
+++ b/website/content/docs/metrics.mdx
@@ -46,7 +46,7 @@ a dashboard over N sandboxes costs one call, not N:
 
 ```ts
 const samples = await client.listSandboxMetrics();
-// [{ externalId, sandboxId, sample }, …]
+// [{ sandboxName, sandboxId, sample }, …]
 ```
 
 Only sandboxes with a running or frozen container appear; colder
diff --git a/website/content/docs/persistence.mdx b/website/content/docs/persistence.mdx
index 00d50ff..d1fdd40 100644
--- a/website/content/docs/persistence.mdx
+++ b/website/content/docs/persistence.mdx
@@ -32,7 +32,7 @@ gVisor host:
 - **Out-of-memory** — a sandbox that hits its memory cap
   (`DORMICE_SANDBOX_MEMORY_GB`, default 2 GB) is killed with exit
   code 137, the Linux convention for "forcibly killed", and recorded as
-  stopped. The same key acquires it right back, files intact.
+  stopped. The same name acquires it right back, files intact.
 - **Archive → restore** — the disk round-trips through S3 and comes
   back byte-for-byte.
 
diff --git a/website/content/docs/quickstart.mdx b/website/content/docs/quickstart.mdx
index e11beed..48174d8 100644
--- a/website/content/docs/quickstart.mdx
+++ b/website/content/docs/quickstart.mdx
@@ -52,7 +52,7 @@ await client.writeFiles('my-agent', [
 await client.destroySandbox('my-agent'); // destroy — the only verb that loses data
 ```
 
-That's the whole loop: `acquireSandbox` is idempotent (the same key
+That's the whole loop: `acquireSandbox` is idempotent (the same name
 always returns the same sandbox, whatever state it was in), commands run
 inside the sandbox, files persist until you destroy it.
 
diff --git a/website/content/docs/resident-agents.mdx b/website/content/docs/resident-agents.mdx
index e1ebff1..1cf5220 100644
--- a/website/content/docs/resident-agents.mdx
+++ b/website/content/docs/resident-agents.mdx
@@ -20,7 +20,7 @@ const res = await client.acquireSandbox(`agent-${userId}`, {
 hardware, ~1 GiB of resident memory drops to ~5 MiB — and any touch
 wakes it in about 50 ms. It never decays to a seconds-long cold start.
 
-Every later `acquireSandbox` with the same key — tomorrow, next month —
+Every later `acquireSandbox` with the same name — tomorrow, next month —
 returns the same sandbox: same files, same installed packages, same
 processes. A runnable version of this pattern lives at
 [`examples/resident-agent.mjs`](https://github.com/BitMiracle-AI/Dormice/blob/main/examples/resident-agent.mjs).
diff --git a/website/content/docs/templates.mdx b/website/content/docs/templates.mdx
index 5eb1d84..cab154c 100644
--- a/website/content/docs/templates.mdx
+++ b/website/content/docs/templates.mdx
@@ -101,6 +101,6 @@ home directory, non-root user at uid 1000.
   with no template argument means the daemon's base image; the name
   `base` cannot be registered.
 - **Templates apply at creation only.** An acquire with a `template` on
-  a key that already has a sandbox keeps the sandbox it finds, template
+  a name that already has a sandbox keeps the sandbox it finds, template
   unchanged — but an unknown name is still refused, never silently
   ignored.
diff --git a/website/content/docs/upgrading.mdx b/website/content/docs/upgrading.mdx
index 7402516..7b130ac 100644
--- a/website/content/docs/upgrading.mdx
+++ b/website/content/docs/upgrading.mdx
@@ -57,7 +57,7 @@ whoever is using the sandbox and should happen on your schedule:
 docker build -t dormice-base:NEW -f images/Dockerfile images/
 # point DORMICE_BASE_IMAGE at the new tag in /etc/dormice/env, then:
 systemctl restart dormice
-dor sandbox rebuild <externalId>   # per sandbox, when it suits you
+dor sandbox rebuild <name>   # per sandbox, when it suits you
 ```
 
 [Rebuild](/docs/persistence#rebuild-a-sandbox) swaps the container and
diff --git a/website/src/components/sections/Features.tsx b/website/src/components/sections/Features.tsx
index a969e89..9616c06 100644
--- a/website/src/components/sections/Features.tsx
+++ b/website/src/components/sections/Features.tsx
@@ -11,9 +11,9 @@ const features: { title: string; body: ReactNode }[] = [
     title: 'Sandboxes are permanent',
     body: (
       <>
-        <code>acquireSandbox(externalId)</code> is the entire mental model — the
-        same key always comes back to the same sandbox: created, woken or
-        restarted as needed.
+        <code>acquireSandbox(name)</code> is the entire mental model — the same
+        key always comes back to the same sandbox: created, woken or restarted
+        as needed.
       </>
     ),
   },

From ba79eec76c0bf58e370de6a80740838faf898056 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 15:34:01 +0800
Subject: [PATCH 093/133] =?UTF-8?q?The=20rename=20survives=20its=20own=20r?=
 =?UTF-8?q?eview,=20three=20gaps=20closed:=20the=20created=20flag=20?=
 =?UTF-8?q?=E2=80=94=20the=20whole=20point=20of=20making=20convergence=20o?=
 =?UTF-8?q?bservable=20=E2=80=94=20had=20schema-presence=20but=20zero=20va?=
 =?UTF-8?q?lue=20assertions,=20so=20a=20flipped=20boolean=20would=20have?=
 =?UTF-8?q?=20sailed=20through=20every=20suite;=20now=20the=20idempotent?=
 =?UTF-8?q?=20pair=20asserts=20true-then-false,=20the=20frozen=20wake=20an?=
 =?UTF-8?q?d=20the=20pruned-container=20survival=20assert=20false=20(a=20c?=
 =?UTF-8?q?aller=20who=20trusts=20created=20would=20wrongly=20assume=20an?=
 =?UTF-8?q?=20empty=20/home/user),=20the=20truly-gone=20rebirth=20asserts?=
 =?UTF-8?q?=20true,=20and=20the=20restore=20poll=20loop=20asserts=20no=20a?=
 =?UTF-8?q?rm=20ever=20claims=20created.=20Seven=20comments=20and=20test?=
 =?UTF-8?q?=20titles=20still=20said=20"external=20id"=20in=20prose=20?=
 =?UTF-8?q?=E2=80=94=20the=20spaced=20spelling=20every=20externalId=20grep?=
 =?UTF-8?q?=20missed=20=E2=80=94=20and=20now=20speak=20name.=20And=20listA?=
 =?UTF-8?q?piKeys'=20newest-first=20promise=20was=20flaking=20on=20same-mi?=
 =?UTF-8?q?llisecond=20mints=20(createdAt=20ties,=20order=20random);=20row?=
 =?UTF-8?q?id=20breaks=20the=20tie=20by=20insertion=20order,=20trustworthy?=
 =?UTF-8?q?=20precisely=20because=20api=5Fkeys=20rows=20are=20never=20dele?=
 =?UTF-8?q?ted=20=E2=80=94=20revoke=20is=20soft=20=E2=80=94=20so=20rowids?=
 =?UTF-8?q?=20are=20never=20reused.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/src/native.test.ts                 |  2 +-
 packages/server/src/app.test.ts        | 22 ++++++++++++++++++----
 packages/server/src/db/api-keys.ts     | 16 +++++++++++++---
 packages/server/src/db/ledger.test.ts  |  4 ++--
 packages/server/src/keyed-queue.ts     |  2 +-
 packages/server/src/reconciler.test.ts |  4 ++--
 packages/server/src/reconciler.ts      |  2 +-
 7 files changed, 38 insertions(+), 14 deletions(-)

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index ce614cc..bbadad3 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -1,7 +1,7 @@
 import { DEFAULT_LIFECYCLE_POLICY, Dormice } from '@dormice/sdk';
 import { describe, expect, inject, it } from 'vitest';
 
-// One daemon serves the whole run, so every test uses its own external id to
+// One daemon serves the whole run, so every test uses its own sandbox name to
 // stay independent of the others.
 function client(token = inject('dormiceToken')) {
   return new Dormice({ endpoint: inject('dormiceEndpoint'), token });
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index bc5791f..620a7e7 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -107,14 +107,18 @@ describe('POST /acquireSandbox', () => {
     expect(executor.stateOf(body.sandbox.id)).toBe('running');
   });
 
-  it('is idempotent: same external id returns the same sandbox', async () => {
+  it('is idempotent: the same name returns the same sandbox', async () => {
     const { app } = testApp();
     const first = (await acquire(app, { name: 'alice' })).json();
     const second = (await acquire(app, { name: 'alice' })).json();
     expect(second.sandbox.id).toBe(first.sandbox.id);
+    // `created` is how a caller sees which of the two happened — the flag
+    // must not lie in either direction.
+    expect(first.created).toBe(true);
+    expect(second.created).toBe(false);
   });
 
-  it('gives different external ids different sandboxes', async () => {
+  it('gives different names different sandboxes', async () => {
     const { app } = testApp();
     const alice = (await acquire(app, { name: 'alice' })).json();
     const bob = (await acquire(app, { name: 'bob' })).json();
@@ -307,6 +311,8 @@ describe('acquire wakes cold sandboxes', () => {
     const woken = (await acquire(app, { name: 'alice' })).json();
     expect(woken.sandbox.id).toBe(id);
     expect(woken.sandbox.state).toBe('active');
+    // A wake is not a creation, however cold the start.
+    expect(woken.created).toBe(false);
     expect(executor.stateOf(id)).toBe('running');
   });
 
@@ -431,6 +437,8 @@ describe('acquire after reality moved behind the ledger', () => {
     const again = (await acquire(app, { name: 'alice' })).json();
     expect(again.status).toBe('ready');
     expect(again.sandbox.id).not.toBe(created.sandbox.id);
+    // The old incarnation's row is gone, so this acquire genuinely creates.
+    expect(again.created).toBe(true);
     // This time the sandbox is real.
     expect(executor.stateOf(again.sandbox.id)).toBe('running');
   });
@@ -439,8 +447,8 @@ describe('acquire after reality moved behind the ledger', () => {
     // A stopped sandbox is an exited container plus a disk, and a routine
     // `docker container prune` eats the container object. The disk — the
     // sandbox's actual data — survives, so the sandbox must survive too:
-    // same key, same sandboxId, rebuilt from the disk. Never a silent
-    // fresh empty box.
+    // same name, same id, rebuilt from the disk. Never a silent fresh
+    // empty box.
     const { app, db, executor, locks } = testApp();
     const created = (
       await acquire(app, {
@@ -459,6 +467,9 @@ describe('acquire after reality moved behind the ledger', () => {
     const again = (await acquire(app, { name: 'alice' })).json();
     expect(again.sandbox.id).toBe(id);
     expect(again.sandbox.state).toBe('active');
+    // The survival must not be misreported as a creation — a caller who
+    // trusts `created` would wrongly assume an empty /home/user.
+    expect(again.created).toBe(false);
     expect(executor.stateOf(id)).toBe('running');
   });
 });
@@ -1149,6 +1160,9 @@ describe('the archiver through the app', () => {
     const deadline = Date.now() + 5_000;
     while (true) {
       const body = (await acquire(app, { name })).json();
+      // Only an already-archived sandbox restores, and the ready it lands
+      // on is a wake — no arm of this poll loop may ever claim `created`.
+      expect(body.created).toBe(false);
       if (body.status === 'ready') return body;
       expect(body.status).toBe('restoring');
       expect(body.progress.phase).toMatch(/downloading|extracting/);
diff --git a/packages/server/src/db/api-keys.ts b/packages/server/src/db/api-keys.ts
index 01bacdd..ac781d4 100644
--- a/packages/server/src/db/api-keys.ts
+++ b/packages/server/src/db/api-keys.ts
@@ -1,5 +1,5 @@
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
-import { and, desc, eq, isNull, lt, or } from 'drizzle-orm';
+import { and, desc, eq, isNull, lt, or, sql } from 'drizzle-orm';
 import { recordActivity } from './activity';
 import type { Db } from './db';
 import { type ApiKeyRow, apiKeys } from './schema';
@@ -60,9 +60,19 @@ export function findActiveApiKeyByName(
     .get();
 }
 
-/** Every key ever minted, revoked ones included — the rotation history. */
+/**
+ * Every key ever minted, revoked ones included — the rotation history.
+ * createdAt has millisecond granularity, so two keys minted back-to-back
+ * can tie; rowid breaks the tie by insertion order, and it is trustworthy
+ * here because api_keys rows are never deleted (revoke is soft), so rowids
+ * are never reused.
+ */
 export function listApiKeys(db: Db): ApiKeyRow[] {
-  return db.select().from(apiKeys).orderBy(desc(apiKeys.createdAt)).all();
+  return db
+    .select()
+    .from(apiKeys)
+    .orderBy(desc(apiKeys.createdAt), desc(sql`rowid`))
+    .all();
 }
 
 /**
diff --git a/packages/server/src/db/ledger.test.ts b/packages/server/src/db/ledger.test.ts
index 5908036..ac0bf5a 100644
--- a/packages/server/src/db/ledger.test.ts
+++ b/packages/server/src/db/ledger.test.ts
@@ -23,7 +23,7 @@ function create(db: Db, name = 'user-1') {
 }
 
 describe('ledger', () => {
-  it('creates a sandbox in active state and finds it by external id', () => {
+  it('creates a sandbox in active state and finds it by name', () => {
     const db = testDb();
     const created = create(db);
     expect(created.state).toBe('active');
@@ -31,7 +31,7 @@ describe('ledger', () => {
     expect(findByName(db, 'someone-else')).toBeUndefined();
   });
 
-  it('enforces one sandbox per external id at the database level', () => {
+  it('enforces one sandbox per name at the database level', () => {
     const db = testDb();
     create(db);
     expect(() => create(db)).toThrow(/UNIQUE/);
diff --git a/packages/server/src/keyed-queue.ts b/packages/server/src/keyed-queue.ts
index ec234b0..1ca413a 100644
--- a/packages/server/src/keyed-queue.ts
+++ b/packages/server/src/keyed-queue.ts
@@ -4,7 +4,7 @@ export const SKIPPED: unique symbol = Symbol('skipped');
 /**
  * The single serialization point for everything that operates on one
  * sandbox: acquire, destroy, the idle scanner's cooling moves and the
- * reconciler's repairs all take the sandbox's external-id slot before they
+ * reconciler's repairs all take the sandbox's name slot before they
  * check-then-act. Each of those verbs has seconds of executor work between
  * its check and its act (create builds a disk, freeze can hold 45s in
  * memory.reclaim), and interleaving in that gap produced real corruption:
diff --git a/packages/server/src/reconciler.test.ts b/packages/server/src/reconciler.test.ts
index 741bce0..097c252 100644
--- a/packages/server/src/reconciler.test.ts
+++ b/packages/server/src/reconciler.test.ts
@@ -89,7 +89,7 @@ describe('startup reconcile', () => {
 
     const result = await reconcile(db, executor, locks);
     // Not a death: the sandbox is recorded as stopped, its row keeps the
-    // external id, and the next acquire rebuilds the container from the disk.
+    // name, and the next acquire rebuilds the container from the disk.
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
     expect(findByName(db, 'alice')?.state).toBe('stopped');
     expect(await executor.listDisks()).toContain(row.id);
@@ -111,7 +111,7 @@ describe('startup reconcile', () => {
   it('destroys a container no row points at', async () => {
     const { db, executor, locks } = setup();
     // Crash between executor.create() and createSandbox(): a container was
-    // born but never entered the ledger, so no external id can ever reach it.
+    // born but never entered the ledger, so no name can ever reach it.
     await executor.create('orphan');
 
     const result = await reconcile(db, executor, locks);
diff --git a/packages/server/src/reconciler.ts b/packages/server/src/reconciler.ts
index 5cdfe50..dfb21b5 100644
--- a/packages/server/src/reconciler.ts
+++ b/packages/server/src/reconciler.ts
@@ -61,7 +61,7 @@ const LEDGER_STATE: Record<ContainerState, SandboxState> = {
  *                                survivable instead of silent data loss.
  * - container and disk gone   -> the sandbox truly is gone (an interrupted
  *                                destroy, a wiped data dir): the row is
- *                                deleted and the external id is free again
+ *                                deleted and the name is free again
  * - container without a row   -> destroyed; without a row it has no user
  *                                key, so nothing could ever reach it
  * - disk owned by nothing     -> removed; leaked disks silently eat the host

From b43cb75e4107556386c251a9655ed3d169f244f6 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 15:35:34 +0800
Subject: [PATCH 094/133] =?UTF-8?q?The=20console's=20front=20door=20learns?=
 =?UTF-8?q?=20openasi's=20welcome:=20the=20login=20page=20becomes=20a=20sp?=
 =?UTF-8?q?lit=20card=20whose=20left=20half=20is=20a=20Grainient=20shader?=
 =?UTF-8?q?=20panel=20(react-bits=20registry=20via=20shadcn,=20vendored=20?=
 =?UTF-8?q?with=20three=20noUncheckedIndexedAccess=20fix-ups)=20carrying?=
 =?UTF-8?q?=20the=20wordmark=20and=20the=20SQLite-of-agent-sandboxes=20man?=
 =?UTF-8?q?ifesto,=20while=20the=20right=20half=20keeps=20the=20three=20fo?=
 =?UTF-8?q?rms=20=E2=80=94=20login,=20first-run=20initialization,=20token?=
 =?UTF-8?q?=20reset=20=E2=80=94=20logic=20untouched,=20their=20inputs=20an?=
 =?UTF-8?q?d=20submit=20buttons=20squared=20to=20h-8.5=20and=20the=20butto?=
 =?UTF-8?q?n=20given=20breathing=20room=20above.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 biome.json                                    |   1 +
 packages/console/components.json              |   8 +-
 packages/console/package.json                 |   1 +
 packages/console/src/components/Grainient.tsx | 324 ++++++++++++++++++
 .../src/features/auth/pages/LoginPage.tsx     | 118 +++++--
 pnpm-lock.yaml                                |   8 +
 6 files changed, 433 insertions(+), 27 deletions(-)
 create mode 100644 packages/console/src/components/Grainient.tsx

diff --git a/biome.json b/biome.json
index 96718dd..91f3ffa 100644
--- a/biome.json
+++ b/biome.json
@@ -5,6 +5,7 @@
       "**",
       "!packages/*/drizzle",
       "!packages/console/src/components/ui",
+      "!packages/console/src/components/Grainient.tsx",
       "!packages/console/src/hooks/use-mobile.ts",
       "!packages/console/src/lib/utils.ts",
       "!packages/console/src/shadcn.css",
diff --git a/packages/console/components.json b/packages/console/components.json
index f9d6812..2158c48 100644
--- a/packages/console/components.json
+++ b/packages/console/components.json
@@ -12,6 +12,8 @@
   },
   "iconLibrary": "hugeicons",
   "rtl": false,
+  "menuColor": "default-translucent",
+  "menuAccent": "subtle",
   "aliases": {
     "components": "@/components",
     "utils": "@/lib/utils",
@@ -19,7 +21,7 @@
     "lib": "@/lib",
     "hooks": "@/hooks"
   },
-  "menuColor": "default-translucent",
-  "menuAccent": "subtle",
-  "registries": {}
+  "registries": {
+    "@react-bits": "https://reactbits.dev/r/{name}.json"
+  }
 }
diff --git a/packages/console/package.json b/packages/console/package.json
index 7f3fd27..36ba05f 100644
--- a/packages/console/package.json
+++ b/packages/console/package.json
@@ -29,6 +29,7 @@
     "embla-carousel-react": "^8.6.0",
     "input-otp": "^1.4.2",
     "next-themes": "^0.4.6",
+    "ogl": "^1.0.11",
     "react": "^19.2.7",
     "react-day-picker": "^10.0.1",
     "react-dom": "^19.2.7",
diff --git a/packages/console/src/components/Grainient.tsx b/packages/console/src/components/Grainient.tsx
new file mode 100644
index 0000000..428e3de
--- /dev/null
+++ b/packages/console/src/components/Grainient.tsx
@@ -0,0 +1,324 @@
+import React, { useEffect, useRef } from 'react';
+import { Renderer, Program, Mesh, Triangle } from 'ogl';
+
+interface GrainientProps {
+  timeSpeed?: number;
+  colorBalance?: number;
+  warpStrength?: number;
+  warpFrequency?: number;
+  warpSpeed?: number;
+  warpAmplitude?: number;
+  blendAngle?: number;
+  blendSoftness?: number;
+  rotationAmount?: number;
+  noiseScale?: number;
+  grainAmount?: number;
+  grainScale?: number;
+  grainAnimated?: boolean;
+  contrast?: number;
+  gamma?: number;
+  saturation?: number;
+  centerX?: number;
+  centerY?: number;
+  zoom?: number;
+  color1?: string;
+  color2?: string;
+  color3?: string;
+  className?: string;
+}
+
+const hexToRgb = (hex: string): [number, number, number] => {
+  // Fix-up for this repo's noUncheckedIndexedAccess (registry code assumes
+  // plain indexing) — see RULES/前端.md shadcn known pits.
+  const [, r, g, b] = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex) ?? [];
+  if (!r || !g || !b) return [1, 1, 1];
+  return [parseInt(r, 16) / 255, parseInt(g, 16) / 255, parseInt(b, 16) / 255];
+};
+
+const vertex = `#version 300 es
+in vec2 position;
+void main() {
+  gl_Position = vec4(position, 0.0, 1.0);
+}
+`;
+
+const fragment = `#version 300 es
+precision highp float;
+uniform vec2 iResolution;
+uniform float iTime;
+uniform float uTimeSpeed;
+uniform float uColorBalance;
+uniform float uWarpStrength;
+uniform float uWarpFrequency;
+uniform float uWarpSpeed;
+uniform float uWarpAmplitude;
+uniform float uBlendAngle;
+uniform float uBlendSoftness;
+uniform float uRotationAmount;
+uniform float uNoiseScale;
+uniform float uGrainAmount;
+uniform float uGrainScale;
+uniform float uGrainAnimated;
+uniform float uContrast;
+uniform float uGamma;
+uniform float uSaturation;
+uniform vec2 uCenterOffset;
+uniform float uZoom;
+uniform vec3 uColor1;
+uniform vec3 uColor2;
+uniform vec3 uColor3;
+out vec4 fragColor;
+#define S(a,b,t) smoothstep(a,b,t)
+mat2 Rot(float a){float s=sin(a),c=cos(a);return mat2(c,-s,s,c);} 
+vec2 hash(vec2 p){p=vec2(dot(p,vec2(2127.1,81.17)),dot(p,vec2(1269.5,283.37)));return fract(sin(p)*43758.5453);} 
+float noise(vec2 p){vec2 i=floor(p),f=fract(p),u=f*f*(3.0-2.0*f);float n=mix(mix(dot(-1.0+2.0*hash(i+vec2(0.0,0.0)),f-vec2(0.0,0.0)),dot(-1.0+2.0*hash(i+vec2(1.0,0.0)),f-vec2(1.0,0.0)),u.x),mix(dot(-1.0+2.0*hash(i+vec2(0.0,1.0)),f-vec2(0.0,1.0)),dot(-1.0+2.0*hash(i+vec2(1.0,1.0)),f-vec2(1.0,1.0)),u.x),u.y);return 0.5+0.5*n;}
+void mainImage(out vec4 o, vec2 C){
+  float t=iTime*uTimeSpeed;
+  vec2 uv=C/iResolution.xy;
+  float ratio=iResolution.x/iResolution.y;
+  vec2 tuv=uv-0.5+uCenterOffset;
+  tuv/=max(uZoom,0.001);
+
+  float degree=noise(vec2(t*0.1,tuv.x*tuv.y)*uNoiseScale);
+  tuv.y*=1.0/ratio;
+  tuv*=Rot(radians((degree-0.5)*uRotationAmount+180.0));
+  tuv.y*=ratio;
+
+  float frequency=uWarpFrequency;
+  float ws=max(uWarpStrength,0.001);
+  float amplitude=uWarpAmplitude/ws;
+  float warpTime=t*uWarpSpeed;
+  tuv.x+=sin(tuv.y*frequency+warpTime)/amplitude;
+  tuv.y+=sin(tuv.x*(frequency*1.5)+warpTime)/(amplitude*0.5);
+
+  vec3 colLav=uColor1;
+  vec3 colOrg=uColor2;
+  vec3 colDark=uColor3;
+  float b=uColorBalance;
+  float s=max(uBlendSoftness,0.0);
+  mat2 blendRot=Rot(radians(uBlendAngle));
+  float blendX=(tuv*blendRot).x;
+  float edge0=-0.3-b-s;
+  float edge1=0.2-b+s;
+  float v0=0.5-b+s;
+  float v1=-0.3-b-s;
+  vec3 layer1=mix(colDark,colOrg,S(edge0,edge1,blendX));
+  vec3 layer2=mix(colOrg,colLav,S(edge0,edge1,blendX));
+  vec3 col=mix(layer1,layer2,S(v0,v1,tuv.y));
+
+  vec2 grainUv=uv*max(uGrainScale,0.001);
+  if(uGrainAnimated>0.5){grainUv+=vec2(iTime*0.05);} 
+  float grain=fract(sin(dot(grainUv,vec2(12.9898,78.233)))*43758.5453);
+  col+=(grain-0.5)*uGrainAmount;
+
+  col=(col-0.5)*uContrast+0.5;
+  float luma=dot(col,vec3(0.2126,0.7152,0.0722));
+  col=mix(vec3(luma),col,uSaturation);
+  col=pow(max(col,0.0),vec3(1.0/max(uGamma,0.001)));
+  col=clamp(col,0.0,1.0);
+
+  o=vec4(col,1.0);
+}
+void main(){
+  vec4 o=vec4(0.0);
+  mainImage(o,gl_FragCoord.xy);
+  fragColor=o;
+}
+`;
+
+
+// Keep renderer/program alive across re-renders so Effect 2 can update
+// uniforms without ever rebuilding the WebGL context.
+type GrainientCtx = {
+  renderer: InstanceType<typeof Renderer>;
+  program: InstanceType<typeof Program>;
+  mesh: InstanceType<typeof Mesh>;
+};
+const ctxMap = new WeakMap<HTMLDivElement, GrainientCtx>();
+
+const Grainient: React.FC<GrainientProps> = ({
+  timeSpeed = 0.25,
+  colorBalance = 0.0,
+  warpStrength = 1.0,
+  warpFrequency = 5.0,
+  warpSpeed = 2.0,
+  warpAmplitude = 50.0,
+  blendAngle = 0.0,
+  blendSoftness = 0.05,
+  rotationAmount = 500.0,
+  noiseScale = 2.0,
+  grainAmount = 0.1,
+  grainScale = 2.0,
+  grainAnimated = false,
+  contrast = 1.5,
+  gamma = 1.0,
+  saturation = 1.0,
+  centerX = 0.0,
+  centerY = 0.0,
+  zoom = 0.9,
+  color1 = '#FF9FFC',
+  color2 = '#5227FF',
+  color3 = '#B497CF',
+  className = ''
+}) => {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  // Effect 1: build WebGL context once, pause when offscreen / tab hidden
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const renderer = new Renderer({
+      webgl: 2,
+      alpha: true,
+      antialias: false,
+      dpr: Math.min(window.devicePixelRatio || 1, 2)
+    });
+
+    const gl = renderer.gl;
+    const canvas = gl.canvas as HTMLCanvasElement;
+    canvas.style.width = '100%';
+    canvas.style.height = '100%';
+    canvas.style.display = 'block';
+    container.appendChild(canvas);
+
+    const geometry = new Triangle(gl);
+    const program = new Program(gl, {
+      vertex,
+      fragment,
+      uniforms: {
+        iTime:           { value: 0 },
+        iResolution:     { value: new Float32Array([1, 1]) },
+        uTimeSpeed:      { value: 0.25 },
+        uColorBalance:   { value: 0.0 },
+        uWarpStrength:   { value: 1.0 },
+        uWarpFrequency:  { value: 5.0 },
+        uWarpSpeed:      { value: 2.0 },
+        uWarpAmplitude:  { value: 50.0 },
+        uBlendAngle:     { value: 0.0 },
+        uBlendSoftness:  { value: 0.05 },
+        uRotationAmount: { value: 500.0 },
+        uNoiseScale:     { value: 2.0 },
+        uGrainAmount:    { value: 0.1 },
+        uGrainScale:     { value: 2.0 },
+        uGrainAnimated:  { value: 0.0 },
+        uContrast:       { value: 1.5 },
+        uGamma:          { value: 1.0 },
+        uSaturation:     { value: 1.0 },
+        uCenterOffset:   { value: new Float32Array([0, 0]) },
+        uZoom:           { value: 0.9 },
+        uColor1:         { value: new Float32Array([1, 1, 1]) },
+        uColor2:         { value: new Float32Array([1, 1, 1]) },
+        uColor3:         { value: new Float32Array([1, 1, 1]) }
+      }
+    });
+
+    const mesh = new Mesh(gl, { geometry, program });
+    ctxMap.set(container, { renderer, program, mesh });
+
+    const setSize = () => {
+      const rect = container.getBoundingClientRect();
+      const w = Math.max(1, Math.floor(rect.width));
+      const h = Math.max(1, Math.floor(rect.height));
+      renderer.setSize(w, h);
+      const res = (program.uniforms.iResolution as { value: Float32Array }).value;
+      res[0] = gl.drawingBufferWidth;
+      res[1] = gl.drawingBufferHeight;
+      renderer.render({ scene: mesh });
+    };
+
+    const ro = new ResizeObserver(setSize);
+    ro.observe(container);
+    setSize();
+
+    let raf = 0;
+    let isVisible = true;
+    let isPageVisible = !document.hidden;
+    const t0 = performance.now();
+
+    const loop = (t: number) => {
+      (program.uniforms.iTime as { value: number }).value = (t - t0) * 0.001;
+      renderer.render({ scene: mesh });
+      raf = requestAnimationFrame(loop);
+    };
+
+    const tryStart = () => {
+      if (isVisible && isPageVisible && raf === 0) raf = requestAnimationFrame(loop);
+    };
+    const tryStop = () => {
+      if (raf !== 0) { cancelAnimationFrame(raf); raf = 0; }
+    };
+
+    const io = new IntersectionObserver(
+      ([entry]) => { isVisible = entry?.isIntersecting ?? false; isVisible ? tryStart() : tryStop(); },
+      { threshold: 0 }
+    );
+    io.observe(container);
+
+    const onVisibility = () => {
+      isPageVisible = !document.hidden;
+      isPageVisible ? tryStart() : tryStop();
+    };
+    document.addEventListener('visibilitychange', onVisibility);
+
+    tryStart();
+
+    return () => {
+      tryStop();
+      ro.disconnect();
+      io.disconnect();
+      document.removeEventListener('visibilitychange', onVisibility);
+      ctxMap.delete(container);
+      try { container.removeChild(canvas); } catch { /* ignore */ }
+    };
+  }, []); // renderer created once
+
+  // Effect 2: sync props to uniforms — zero GPU cost, no teardown
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const ctx = ctxMap.get(container);
+    if (!ctx) return;
+    const { program } = ctx;
+    // Literal-key cast instead of a string index, same noUncheckedIndexedAccess fix-up.
+    const u = program.uniforms as Record<
+      'uTimeSpeed' | 'uColorBalance' | 'uWarpStrength' | 'uWarpFrequency' | 'uWarpSpeed' |
+      'uWarpAmplitude' | 'uBlendAngle' | 'uBlendSoftness' | 'uRotationAmount' | 'uNoiseScale' |
+      'uGrainAmount' | 'uGrainScale' | 'uGrainAnimated' | 'uContrast' | 'uGamma' | 'uSaturation' |
+      'uCenterOffset' | 'uZoom' | 'uColor1' | 'uColor2' | 'uColor3',
+      { value: any }
+    >;
+
+    u.uTimeSpeed.value      = timeSpeed;
+    u.uColorBalance.value   = colorBalance;
+    u.uWarpStrength.value   = warpStrength;
+    u.uWarpFrequency.value  = warpFrequency;
+    u.uWarpSpeed.value      = warpSpeed;
+    u.uWarpAmplitude.value  = warpAmplitude;
+    u.uBlendAngle.value     = blendAngle;
+    u.uBlendSoftness.value  = blendSoftness;
+    u.uRotationAmount.value = rotationAmount;
+    u.uNoiseScale.value     = noiseScale;
+    u.uGrainAmount.value    = grainAmount;
+    u.uGrainScale.value     = grainScale;
+    u.uGrainAnimated.value  = grainAnimated ? 1.0 : 0.0;
+    u.uContrast.value       = contrast;
+    u.uGamma.value          = gamma;
+    u.uSaturation.value     = saturation;
+    u.uCenterOffset.value   = new Float32Array([centerX, centerY]);
+    u.uZoom.value           = zoom;
+    u.uColor1.value         = new Float32Array(hexToRgb(color1));
+    u.uColor2.value         = new Float32Array(hexToRgb(color2));
+    u.uColor3.value         = new Float32Array(hexToRgb(color3));
+  }, [
+    timeSpeed, colorBalance, warpStrength, warpFrequency, warpSpeed,
+    warpAmplitude, blendAngle, blendSoftness, rotationAmount, noiseScale,
+    grainAmount, grainScale, grainAnimated, contrast, gamma, saturation,
+    centerX, centerY, zoom, color1, color2, color3
+  ]);
+
+
+  return <div ref={containerRef} className={`relative h-full w-full overflow-hidden ${className}`.trim()} />;
+};
+
+export default Grainient;
diff --git a/packages/console/src/features/auth/pages/LoginPage.tsx b/packages/console/src/features/auth/pages/LoginPage.tsx
index 6c46514..bc149b8 100644
--- a/packages/console/src/features/auth/pages/LoginPage.tsx
+++ b/packages/console/src/features/auth/pages/LoginPage.tsx
@@ -1,6 +1,7 @@
 import { useMutation, useQuery } from '@tanstack/react-query';
 import { useSearch } from '@tanstack/react-router';
 import { useState } from 'react';
+import Grainient from '@/components/Grainient';
 import { Button } from '@/components/ui/button';
 import {
   Card,
@@ -25,6 +26,10 @@ import { setSessionMarker } from '@/lib/session';
  *
  * Success does a full-page jump (not a client-side navigate): the cookie is
  * brand new, and a reload guarantees every query starts from it.
+ *
+ * The shell is openasi's split card (2026-07-16, user's pick): brand panel
+ * with a shader gradient on the left, the forms on the right. The panel is
+ * md+ only — on a phone the form is the whole story.
  */
 export function LoginPage() {
   const { redirect } = useSearch({ from: '/login' });
@@ -39,24 +44,84 @@ export function LoginPage() {
   };
 
   return (
-    <main className="flex min-h-screen items-center justify-center p-4">
-      <Card className="w-full max-w-sm">
-        {status.isPending ? (
-          <CardContent className="flex justify-center py-10">
-            <Spinner />
-          </CardContent>
-        ) : status.isError ? (
-          <CardContent className="py-10 text-center text-sm text-muted-foreground">
-            无法连接 daemon：{status.error.message}
-          </CardContent>
-        ) : status.data.accountExists && !resetting ? (
-          <LoginForm onSuccess={enter} onForgot={() => setResetting(true)} />
-        ) : (
-          <SetupForm
-            onSuccess={enter}
-            onBack={resetting ? () => setResetting(false) : undefined}
-          />
-        )}
+    <main className="flex min-h-svh items-center justify-center p-6">
+      <Card className="w-full max-w-4xl overflow-hidden p-0">
+        {/* min-h keeps the login form roomy; the setup form is taller and
+            simply stretches the card — no fixed height, no inner scroll. */}
+        <div className="grid md:min-h-[32rem] md:grid-cols-2">
+          {/* 左侧品牌面板：着色器渐变，小屏隐藏。三色与主题主色同为蓝紫色族。 */}
+          <div className="relative hidden md:block">
+            <Grainient
+              color1="#FF9FFC"
+              color2="#5227FF"
+              color3="#B497CF"
+              timeSpeed={0.25}
+              colorBalance={0}
+              warpStrength={1}
+              warpFrequency={5}
+              warpSpeed={2}
+              warpAmplitude={50}
+              blendAngle={0}
+              blendSoftness={0.05}
+              rotationAmount={500}
+              noiseScale={2}
+              grainAmount={0.1}
+              grainScale={2}
+              grainAnimated={false}
+              contrast={1.5}
+              gamma={1}
+              saturation={1}
+              centerX={0}
+              centerY={0}
+              zoom={0.9}
+              className="absolute inset-0"
+            />
+            <div className="absolute inset-0 bg-gradient-to-b from-black/40 via-transparent to-black/65" />
+            {/* 顶部品牌标记：wordmark 在上，产品定位在下 */}
+            <div className="absolute inset-x-0 top-0 p-9">
+              <p className="text-xl font-semibold tracking-tight text-white [font-family:'Google_Sans',sans-serif]">
+                Dormice
+              </p>
+              <p className="mt-1.5 text-sm text-white/90">
+                自托管 Agent 沙箱平台
+              </p>
+            </div>
+            {/* 底部主张：大字主张 + 细横线 + 副文案 */}
+            <div className="absolute inset-x-0 bottom-0 p-9">
+              <h2 className="text-3xl leading-[1.2] font-semibold tracking-tight text-white [font-family:'Google_Sans',sans-serif]">
+                The SQLite of
+                <br />
+                agent sandboxes
+              </h2>
+              <div className="mt-6 h-px w-12 bg-white/40" />
+              <p className="mt-5 text-sm leading-relaxed text-white/75">
+                单机部署，沙箱永生，空闲即免费——一台机器，就是你的沙箱舰队。
+              </p>
+            </div>
+          </div>
+          {/* 右侧表单：读取/连不上/登录/初始化四态，逻辑与改版前一致 */}
+          <div className="flex flex-col justify-center gap-6 px-2 py-10">
+            {status.isPending ? (
+              <CardContent className="flex justify-center py-10">
+                <Spinner />
+              </CardContent>
+            ) : status.isError ? (
+              <CardContent className="py-10 text-center text-sm text-muted-foreground">
+                无法连接 daemon：{status.error.message}
+              </CardContent>
+            ) : status.data.accountExists && !resetting ? (
+              <LoginForm
+                onSuccess={enter}
+                onForgot={() => setResetting(true)}
+              />
+            ) : (
+              <SetupForm
+                onSuccess={enter}
+                onBack={resetting ? () => setResetting(false) : undefined}
+              />
+            )}
+          </div>
+        </div>
       </Card>
     </main>
   );
@@ -104,8 +169,8 @@ function LoginForm({
   return (
     <>
       <CardHeader>
-        <CardTitle className="text-2xl">Dormice</CardTitle>
-        <CardDescription>输入账号密码进入控制台。</CardDescription>
+        <CardTitle className="text-xl">欢迎回来</CardTitle>
+        <CardDescription>登录以管理你的沙箱。</CardDescription>
       </CardHeader>
       <CardContent>
         <form
@@ -119,6 +184,7 @@ function LoginForm({
             <FieldLabel htmlFor="username">用户名</FieldLabel>
             <Input
               id="username"
+              className="h-8.5"
               autoFocus
               autoComplete="username"
               value={username}
@@ -129,6 +195,7 @@ function LoginForm({
             <FieldLabel htmlFor="password">密码</FieldLabel>
             <Input
               id="password"
+              className="h-8.5"
               type="password"
               autoComplete="current-password"
               value={password}
@@ -148,7 +215,7 @@ function LoginForm({
               password.length === 0 ||
               mutation.isPending
             }
-            className="w-full"
+            className="mt-4 h-8.5 w-full"
           >
             {mutation.isPending && <Spinner />}
             登录
@@ -192,7 +259,7 @@ function SetupForm({
   return (
     <>
       <CardHeader>
-        <CardTitle className="text-2xl">
+        <CardTitle className="text-xl">
           {onBack ? '重置控制台账号' : '初始化 Dormice 控制台'}
         </CardTitle>
         <CardDescription>
@@ -218,7 +285,7 @@ function SetupForm({
               value={token}
               onChange={(event) => setToken(event.target.value)}
               placeholder="DORMICE_API_TOKEN"
-              className="font-mono"
+              className="h-8.5 font-mono"
               aria-invalid={mutation.isError || undefined}
             />
             {mutation.isError && (
@@ -231,6 +298,7 @@ function SetupForm({
             <FieldLabel htmlFor="new-username">用户名</FieldLabel>
             <Input
               id="new-username"
+              className="h-8.5"
               autoComplete="username"
               value={username}
               onChange={(event) => setUsername(event.target.value)}
@@ -240,6 +308,7 @@ function SetupForm({
             <FieldLabel htmlFor="new-password">密码</FieldLabel>
             <Input
               id="new-password"
+              className="h-8.5"
               type="password"
               autoComplete="new-password"
               value={password}
@@ -252,6 +321,7 @@ function SetupForm({
             <FieldLabel htmlFor="confirm-password">确认密码</FieldLabel>
             <Input
               id="confirm-password"
+              className="h-8.5"
               type="password"
               autoComplete="new-password"
               value={confirm}
@@ -263,7 +333,7 @@ function SetupForm({
           <Button
             type="submit"
             disabled={!ready || mutation.isPending}
-            className="w-full"
+            className="mt-4 h-8.5 w-full"
           >
             {mutation.isPending && <Spinner />}
             {onBack ? '重置并登录' : '初始化并登录'}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d704809..669bb48 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -115,6 +115,9 @@ importers:
       next-themes:
         specifier: ^0.4.6
         version: 0.4.6(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      ogl:
+        specifier: ^1.0.11
+        version: 1.0.11
       react:
         specifier: ^19.2.7
         version: 19.2.7
@@ -4317,6 +4320,9 @@ packages:
     resolution: {integrity: sha512-9miFgM2OFba7hB+pRgvtV84pYTBaoTHohvmIgiRt6dRIzbwEOIaNaP+dIlGs2fNFoB0SeISs0Jz5WFVRid6Xyg==}
     engines: {node: '>=12.20.0'}
 
+  ogl@1.0.11:
+    resolution: {integrity: sha512-kUpC154AFfxi16pmZUK4jk3J+8zxwTWGPo03EoYA8QPbzikHoaC82n6pNTbd+oEaJonaE8aPWBlX7ad9zrqLsA==}
+
   on-exit-leak-free@2.1.2:
     resolution: {integrity: sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA==}
     engines: {node: '>=14.0.0'}
@@ -9500,6 +9506,8 @@ snapshots:
 
   obug@2.1.3: {}
 
+  ogl@1.0.11: {}
+
   on-exit-leak-free@2.1.2: {}
 
   on-finished@2.4.1:

From d59d6365415aa7aef51f07c60a8d7a20e3ff5440 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 17:11:09 +0800
Subject: [PATCH 095/133] =?UTF-8?q?The=20console=20learns=20openasi's=20wh?=
 =?UTF-8?q?ole=20posture,=20not=20just=20its=20front=20door:=20the=20shell?=
 =?UTF-8?q?=20now=20locks=20to=20the=20viewport=20(sidebar=20slimmed=20to?=
 =?UTF-8?q?=2015rem,=20GitHub=20and=20docs=20links=20seated=20in=20its=20f?=
 =?UTF-8?q?ooter)=20and=20every=20page=20carries=20its=20own=20max-w-6xl?=
 =?UTF-8?q?=20container=20under=20a=20text-xl=20medium=20heading,=20so=20l?=
 =?UTF-8?q?ist=20pages=20can=20finally=20do=20the=20thing=20tables=20owe?=
 =?UTF-8?q?=20their=20readers=20=E2=80=94=20fill=20the=20remaining=20heigh?=
 =?UTF-8?q?t,=20scroll=20inside=20their=20card,=20and=20keep=20a=20paginat?=
 =?UTF-8?q?ion=20bar=20pinned=20to=20the=20bottom=20whether=20there=20are?=
 =?UTF-8?q?=20eight=20rows=20or=20eight=20hundred=20(DataTable=20grows=20a?=
 =?UTF-8?q?=20fill=20mode,=20TablePager=20and=20paginate()=20are=20the=20o?=
 =?UTF-8?q?ne=20shared=20answer).=20The=20dashboard's=20top=20row=20become?=
 =?UTF-8?q?s=20four=20stat=20cards=20by=20lifting=20sandbox=20disks=20out?=
 =?UTF-8?q?=20of=20the=20basement,=20settings=20and=20version=20part=20way?=
 =?UTF-8?q?s=20into=20two=20pages=20with=20the=20upgrade=20badge=20followi?=
 =?UTF-8?q?ng=20version,=20the=20whole=20app=20turns=20select-none=20excep?=
 =?UTF-8?q?t=20the=20surfaces=20born=20to=20be=20copied=20(code,=20inputs,?=
 =?UTF-8?q?=20the=20terminal),=20and=20the=20sandbox=20table=20is=20squeez?=
 =?UTF-8?q?ed=20to=20zero=20horizontal=20overflow=20=E2=80=94=20measured,?=
 =?UTF-8?q?=20not=20eyeballed=20=E2=80=94=20by=20shortening=20the=20policy?=
 =?UTF-8?q?=20header,=20wrapping=20policy=20lines=20only=20at=20their=20do?=
 =?UTF-8?q?t=20seams,=20truncating=20label=20chips=20from=20an=20inner=20s?=
 =?UTF-8?q?pan,=20and=20deliberately=20dropping=20the=20redundant=20create?=
 =?UTF-8?q?d-age=20column.=20Also=20caught=20in=20passing:=20seed.mjs=20st?=
 =?UTF-8?q?ill=20spoke=20externalId=20to=20a=20daemon=20that=20now=20only?=
 =?UTF-8?q?=20answers=20to=20name.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/console/scripts/seed.mjs             |  26 ++---
 packages/console/src/components/AppShell.tsx  |  17 ++-
 .../console/src/components/AppSidebar.tsx     |  37 +++++-
 packages/console/src/components/DataTable.tsx |  18 ++-
 .../console/src/components/TablePager.tsx     |  94 ++++++++++++++++
 .../features/activity/pages/ActivityPage.tsx  |  56 +++++----
 .../features/connect/pages/ConnectPage.tsx    |   4 +-
 .../src/features/doctor/pages/DoctorPage.tsx  |  20 ++--
 .../features/ingress/pages/DomainsPage.tsx    |  15 +--
 .../overview/components/FleetStatCards.tsx    |  18 +--
 .../overview/components/RangeSwitcher.tsx     |  12 +-
 .../overview/components/SandboxDisksCard.tsx  |   6 +-
 .../features/overview/pages/OverviewPage.tsx  |  29 ++---
 .../sandboxes/components/SandboxTerminal.tsx  |   3 +-
 .../sandboxes/pages/SandboxDetailPage.tsx     |  13 ++-
 .../sandboxes/pages/SandboxesPage.tsx         | 106 +++++++++++-------
 .../features/settings/pages/SettingsPage.tsx  |  51 ++++++---
 .../features/settings/pages/VersionPage.tsx   |  18 +++
 .../templates/pages/TemplatesPage.tsx         |  37 +++---
 packages/console/src/index.css                |  16 ++-
 packages/console/src/routeTree.gen.ts         |  21 ++++
 packages/console/src/routes/_app/version.tsx  |   6 +
 22 files changed, 443 insertions(+), 180 deletions(-)
 create mode 100644 packages/console/src/components/TablePager.tsx
 create mode 100644 packages/console/src/features/settings/pages/VersionPage.tsx
 create mode 100644 packages/console/src/routes/_app/version.tsx

diff --git a/packages/console/scripts/seed.mjs b/packages/console/scripts/seed.mjs
index b5af365..413d837 100644
--- a/packages/console/scripts/seed.mjs
+++ b/packages/console/scripts/seed.mjs
@@ -41,9 +41,9 @@ async function rpc(path, body = {}) {
   return res.json();
 }
 
-const write = (externalId, files) =>
+const write = (name, files) =>
   rpc('/writeFiles', {
-    externalId,
+    name,
     files: files.map(([path, text]) => ({
       path,
       contentBase64: Buffer.from(text, 'utf8').toString('base64'),
@@ -66,55 +66,55 @@ for (const [name, image] of templates) {
 // stopAfterSeconds: null 是常驻 agent 档,永远停在 frozen。
 const sandboxes = [
   {
-    externalId: 'demo-agent',
+    name: 'demo-agent',
     policy: { freezeAfterSeconds: 300, stopAfterSeconds: null },
     template: 'claude-code',
     metadata: { app: 'assistant', env: 'prod' },
   },
   {
-    externalId: 'web-scraper',
+    name: 'web-scraper',
     policy: { freezeAfterSeconds: 5 },
     template: 'python-ml',
     metadata: { app: 'crawler', env: 'prod' },
   },
   {
-    externalId: 'build-runner',
+    name: 'build-runner',
     policy: { freezeAfterSeconds: 3, stopAfterSeconds: 8 },
     metadata: { app: 'ci' },
   },
   {
-    externalId: 'docs-writer',
+    name: 'docs-writer',
     policy: { freezeAfterSeconds: 5 },
     template: 'node-agent',
     metadata: { app: 'assistant', env: 'staging' },
   },
   {
-    externalId: 'email-triage',
+    name: 'email-triage',
     policy: { freezeAfterSeconds: 600, stopAfterSeconds: null },
     metadata: { app: 'assistant', env: 'prod' },
   },
   {
-    externalId: 'ci-check',
+    name: 'ci-check',
     policy: { freezeAfterSeconds: 4, stopAfterSeconds: 10 },
     metadata: { app: 'ci' },
   },
   {
-    externalId: 'data-pipeline',
+    name: 'data-pipeline',
     policy: { freezeAfterSeconds: 900 },
     template: 'python-ml',
     metadata: { app: 'crawler', env: 'staging' },
   },
   // 刻意不带标签:列表的标签列该有留白的样子,筛选也筛得掉它。
-  { externalId: 'scratch' },
+  { name: 'scratch' },
 ];
-for (const { externalId, policy, template, metadata } of sandboxes) {
+for (const { name, policy, template, metadata } of sandboxes) {
   await rpc('/acquireSandbox', {
-    externalId,
+    name,
     ...(policy ? { policy } : {}),
     ...(template ? { template } : {}),
     ...(metadata ? { metadata } : {}),
   });
-  console.log(`沙箱  ${externalId}`);
+  console.log(`沙箱  ${name}`);
 }
 
 // ---- 文件(给文件浏览器一些可看的内容)---------------------------------
diff --git a/packages/console/src/components/AppShell.tsx b/packages/console/src/components/AppShell.tsx
index 1530262..055b01c 100644
--- a/packages/console/src/components/AppShell.tsx
+++ b/packages/console/src/components/AppShell.tsx
@@ -1,5 +1,5 @@
 import { Outlet, useRouterState } from '@tanstack/react-router';
-import { Fragment } from 'react';
+import { type CSSProperties, Fragment } from 'react';
 import { AppSidebar } from '@/components/AppSidebar';
 import { CommandMenu } from '@/components/CommandMenu';
 import {
@@ -21,9 +21,11 @@ const SEGMENT_LABELS: Record<string, string> = {
   sandboxes: '沙箱',
   templates: '模板',
   activity: '活动',
+  'api-keys': 'API 密钥',
   domains: '域名',
   doctor: '体检',
   settings: '设置',
+  version: '版本',
   connect: '连接',
 };
 
@@ -46,9 +48,15 @@ export function AppShell() {
   const crumbs = crumbsOf(pathname);
 
   return (
-    <SidebarProvider>
+    // 外壳锁定视口高度,滚动只发生在内容区(openasi 版式,2026-07-16):
+    // 表格页因此能"表格占满剩余高度框内滚、分页钉底"。侧栏 15rem
+    // (openasi 同宽;vendored sidebar.tsx 不动,用 CSS 变量覆写)。
+    <SidebarProvider
+      className="h-svh overflow-hidden"
+      style={{ '--sidebar-width': '15rem' } as CSSProperties}
+    >
       <AppSidebar />
-      <SidebarInset>
+      <SidebarInset className="min-h-0 overflow-hidden">
         <header className="flex h-14 shrink-0 items-center gap-2 border-b px-4">
           <SidebarTrigger className="-ml-1" />
           {/* 组件自带 data-vertical:self-stretch,限高后会钉在顶栏上沿 — 压回居中。 */}
@@ -79,7 +87,8 @@ export function AppShell() {
           </Breadcrumb>
           <CommandMenu />
         </header>
-        <div className="flex flex-1 flex-col gap-4 p-4 md:p-6">
+        {/* 页面自带容器(max-w/padding/gap 按页型),这里只给滚动口。 */}
+        <div className="min-h-0 flex-1 overflow-y-auto">
           <Outlet />
         </div>
       </SidebarInset>
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index bd27520..f41545d 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -1,6 +1,9 @@
 import {
   Activity01Icon,
+  Book02Icon,
   DashboardSquare01Icon,
+  GitCommitIcon,
+  GithubIcon,
   Globe02Icon,
   Key01Icon,
   Layers01Icon,
@@ -60,6 +63,7 @@ export const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
       { to: '/domains', label: '域名', icon: Globe02Icon },
       { to: '/doctor', label: '体检', icon: StethoscopeIcon, mock: true },
       { to: '/settings', label: '设置', icon: Settings01Icon },
+      { to: '/version', label: '版本', icon: GitCommitIcon },
     ],
   },
   {
@@ -129,7 +133,7 @@ export function AppSidebar() {
                         <span>{item.label}</span>
                       </SidebarMenuButton>
                       {item.mock && <SidebarMenuBadge>预览</SidebarMenuBadge>}
-                      {item.to === '/settings' && upgradable && (
+                      {item.to === '/version' && upgradable && (
                         <SidebarMenuBadge>
                           <span
                             className="size-2 rounded-full bg-amber-500"
@@ -148,6 +152,37 @@ export function AppSidebar() {
 
       <SidebarFooter>
         <SidebarMenu>
+          {/* 项目主页与文档站(2026-07-16 用户拍板):真外链,新标签页打开。 */}
+          <SidebarMenuItem>
+            <SidebarMenuButton
+              className={menuButtonClass}
+              render={
+                <a
+                  href="https://github.com/BitMiracle-AI/Dormice"
+                  target="_blank"
+                  rel="noreferrer"
+                />
+              }
+            >
+              <HugeiconsIcon icon={GithubIcon} strokeWidth={2} />
+              <span>GitHub</span>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+          <SidebarMenuItem>
+            <SidebarMenuButton
+              className={menuButtonClass}
+              render={
+                <a
+                  href="https://dormice.dev"
+                  target="_blank"
+                  rel="noreferrer"
+                />
+              }
+            >
+              <HugeiconsIcon icon={Book02Icon} strokeWidth={2} />
+              <span>文档</span>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
           <SidebarMenuItem>
             <SidebarMenuButton
               className={menuButtonClass}
diff --git a/packages/console/src/components/DataTable.tsx b/packages/console/src/components/DataTable.tsx
index dfa7f6d..81c3727 100644
--- a/packages/console/src/components/DataTable.tsx
+++ b/packages/console/src/components/DataTable.tsx
@@ -13,21 +13,33 @@ const TABLE_CHROME =
 /**
  * 数据表外壳:卡面(bg-card + 大圆角 + ring)包一层滚动容器,再套统一
  * 密度的 Table — 密度与边距只在这里定一次,全站表格共用,漂移无从发生。
- * 长表传 containerClassName="max-h-[70vh]" 限高框内滚,吸顶表头才有得贴。
  * vendored table.tsx 不动,覆写全在这一侧。
+ *
+ * 两种形态:
+ * - 默认:卡面随内容长高,长表可传 containerClassName="max-h-[70vh]"
+ *   限高框内滚(详情页 tab 内的面板用这种)。
+ * - fill(openasi 列表页版式,2026-07-16 用户拍板):卡面吃掉父级 flex
+ *   列的全部剩余高度,行多在框内滚、行少留白 — 无论数据多少,表格都
+ *   占满页面剩余空间,分页条得以钉在底部。要求父链有确定高度
+ *   (AppShell 已锁 h-svh,页面容器用 h-full flex-col)。
  */
 export function DataTable({
+  fill = false,
   containerClassName,
   className,
   ...props
-}: React.ComponentProps<typeof Table> & { containerClassName?: string }) {
+}: React.ComponentProps<typeof Table> & {
+  fill?: boolean;
+  containerClassName?: string;
+}) {
   return (
-    <Card className="p-0">
+    <Card className={cn('p-0', fill && 'min-h-0 flex-1 overflow-hidden')}>
       {/* vendored Table 自带 overflow-x-auto 内容器 — 把它放开,让这层
           成为唯一滚动口:竖向吸顶与横向滚动发生在同一个容器上。 */}
       <div
         className={cn(
           'overflow-auto [&_[data-slot=table-container]]:overflow-visible',
+          fill && 'min-h-0 flex-1',
           containerClassName,
         )}
       >
diff --git a/packages/console/src/components/TablePager.tsx b/packages/console/src/components/TablePager.tsx
new file mode 100644
index 0000000..c458471
--- /dev/null
+++ b/packages/console/src/components/TablePager.tsx
@@ -0,0 +1,94 @@
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from '@/components/ui/pagination';
+
+/** 分页窗口:最多 5 个页码,当前页居中,边界处贴边(openasi 同款)。 */
+function pageWindow(current: number, total: number): number[] {
+  const size = Math.min(5, total);
+  let start = Math.max(1, current - 2);
+  if (start + size - 1 > total) start = total - size + 1;
+  return Array.from({ length: size }, (_, i) => start + i);
+}
+
+/**
+ * 列表页底部的常驻分页条(openasi 版式,2026-07-16 用户拍板):左边
+ * 「共 N 条」,右边上一页/页码/下一页 — 数据只有一页时也在,底部有没
+ * 有这一条不该取决于数据多少。分页是纯前端的:列表本来就整份在手里
+ * (轮询/环形记录),切页不打请求。
+ */
+export function TablePager({
+  page,
+  pageCount,
+  total,
+  onPageChange,
+}: {
+  page: number;
+  pageCount: number;
+  total: number;
+  onPageChange: (page: number) => void;
+}) {
+  return (
+    <div className="flex shrink-0 flex-wrap items-center justify-between gap-3">
+      <p className="text-sm text-muted-foreground tabular-nums">
+        共 {total} 条,第 {page} / {pageCount} 页
+      </p>
+      <Pagination className="mx-0 w-auto justify-end">
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationPrevious
+              text="上一页"
+              aria-disabled={page <= 1}
+              className={
+                page <= 1 ? 'pointer-events-none opacity-50' : undefined
+              }
+              onClick={() => onPageChange(Math.max(1, page - 1))}
+            />
+          </PaginationItem>
+          {pageWindow(page, pageCount).map((p) => (
+            <PaginationItem key={p}>
+              <PaginationLink
+                isActive={p === page}
+                onClick={() => onPageChange(p)}
+              >
+                {p}
+              </PaginationLink>
+            </PaginationItem>
+          ))}
+          <PaginationItem>
+            <PaginationNext
+              text="下一页"
+              aria-disabled={page >= pageCount}
+              className={
+                page >= pageCount ? 'pointer-events-none opacity-50' : undefined
+              }
+              onClick={() => onPageChange(Math.min(pageCount, page + 1))}
+            />
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>
+    </div>
+  );
+}
+
+/**
+ * 客户端分页的公分母:page 夹回合法区间(过滤把列表缩短时不留空页),
+ * 返回当页切片。各列表页共用,别再各自发明。
+ */
+export function paginate<T>(
+  items: T[],
+  page: number,
+  pageSize: number,
+): { rows: T[]; safePage: number; pageCount: number } {
+  const pageCount = Math.max(1, Math.ceil(items.length / pageSize));
+  const safePage = Math.min(Math.max(1, page), pageCount);
+  return {
+    rows: items.slice((safePage - 1) * pageSize, safePage * pageSize),
+    safePage,
+    pageCount,
+  };
+}
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index 587bad5..3a050a4 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -5,6 +5,7 @@ import { Link } from '@tanstack/react-router';
 import { useMemo, useState } from 'react';
 import { DataTable } from '@/components/DataTable';
 import { FilterMenu } from '@/components/FilterMenu';
+import { paginate, TablePager } from '@/components/TablePager';
 import { Badge } from '@/components/ui/badge';
 import {
   Empty,
@@ -30,6 +31,8 @@ import { cn } from '@/lib/utils';
 import { useActivity } from '../hooks/useActivity';
 import { ACTIVITY_KIND_LABELS, ACTIVITY_KIND_STYLES } from '../kinds';
 
+const PAGE_SIZE = 50;
+
 /**
  * 「我不在的时候发生了什么」:daemon 每一次生命周期动作(创建、降温、
  * 唤醒、销毁)和对账修复的有界环形记录 — 事件写在动作发生处,这里只读。
@@ -40,6 +43,7 @@ export function ActivityPage() {
   const { data, isPending, isError, error } = useActivity();
   const [search, setSearch] = useState('');
   const [kindFilter, setKindFilter] = useState<'all' | ActivityKind>('all');
+  const [page, setPage] = useState(1);
 
   const events = data?.events ?? [];
   const filtered = useMemo(
@@ -54,18 +58,17 @@ export function ActivityPage() {
       ),
     [events, kindFilter, search],
   );
+  const { rows, safePage, pageCount } = paginate(filtered, page, PAGE_SIZE);
 
   return (
-    <>
-      <div>
-        <h1 className="text-2xl font-semibold">活动</h1>
-        <p className="text-sm text-muted-foreground">
-          账本的历史:谁被创建、冻结、停止、销毁,对账修了什么。保留最近 1000
-          条,更老的自然滚出。
-        </p>
-      </div>
+    // openasi 列表页版式(2026-07-16 用户拍板):限宽居中、表格吃掉剩余
+    // 高度框内滚、分页条钉底。
+    <div className="mx-auto flex h-full w-full max-w-6xl flex-col gap-5 p-4 md:p-6">
+      <header className="shrink-0">
+        <h1 className="text-xl font-medium">活动</h1>
+      </header>
 
-      <div className="flex flex-wrap items-center gap-2">
+      <div className="flex shrink-0 flex-wrap items-center gap-2">
         <InputGroup className="w-64">
           <InputGroupAddon>
             <HugeiconsIcon
@@ -75,7 +78,10 @@ export function ActivityPage() {
           </InputGroupAddon>
           <InputGroupInput
             value={search}
-            onChange={(event) => setSearch(event.target.value)}
+            onChange={(event) => {
+              setSearch(event.target.value);
+              setPage(1);
+            }}
             placeholder="按名称搜索"
           />
         </InputGroup>
@@ -87,9 +93,10 @@ export function ActivityPage() {
               [ActivityKind, string]
             >
           ).map(([kind, label]) => ({ value: kind, label }))}
-          onChange={(value) =>
-            setKindFilter(value === '' ? 'all' : (value as ActivityKind))
-          }
+          onChange={(value) => {
+            setKindFilter(value === '' ? 'all' : (value as ActivityKind));
+            setPage(1);
+          }}
         />
         <span className="text-sm text-muted-foreground">
           {filtered.length} / {events.length} 条
@@ -101,14 +108,14 @@ export function ActivityPage() {
           <Spinner /> 读取活动
         </div>
       ) : isError ? (
-        <Empty className="border border-dashed">
+        <Empty className="flex-1 border border-dashed">
           <EmptyHeader>
             <EmptyTitle>读取失败</EmptyTitle>
             <EmptyDescription>{error.message}</EmptyDescription>
           </EmptyHeader>
         </Empty>
       ) : events.length === 0 ? (
-        <Empty className="border border-dashed">
+        <Empty className="flex-1 border border-dashed">
           <EmptyHeader>
             <EmptyTitle>还没有活动</EmptyTitle>
             <EmptyDescription>
@@ -117,15 +124,15 @@ export function ActivityPage() {
           </EmptyHeader>
         </Empty>
       ) : filtered.length === 0 ? (
-        <Empty className="border border-dashed">
+        <Empty className="flex-1 border border-dashed">
           <EmptyHeader>
             <EmptyTitle>没有匹配的事件</EmptyTitle>
             <EmptyDescription>换个关键词或事件类型试试。</EmptyDescription>
           </EmptyHeader>
         </Empty>
       ) : (
-        // 环形记录上限 1000 条,是全站最长的表 — 限高框内滚,表头吸顶。
-        <DataTable containerClassName="max-h-[70vh]">
+        // 环形记录上限 1000 条,是全站最长的表 — fill 框内滚,表头吸顶。
+        <DataTable fill>
           <TableHeader>
             <TableRow>
               <TableHead className="w-28">时间</TableHead>
@@ -135,7 +142,7 @@ export function ActivityPage() {
             </TableRow>
           </TableHeader>
           <TableBody>
-            {filtered.map((event) => (
+            {rows.map((event) => (
               <TableRow key={event.id}>
                 <TableCell
                   className="tabular-nums text-muted-foreground"
@@ -177,6 +184,15 @@ export function ActivityPage() {
           </TableBody>
         </DataTable>
       )}
-    </>
+
+      {!isPending && !isError && filtered.length > 0 && (
+        <TablePager
+          page={safePage}
+          pageCount={pageCount}
+          total={filtered.length}
+          onPageChange={setPage}
+        />
+      )}
+    </div>
   );
 }
diff --git a/packages/console/src/features/connect/pages/ConnectPage.tsx b/packages/console/src/features/connect/pages/ConnectPage.tsx
index 739f340..2c672fb 100644
--- a/packages/console/src/features/connect/pages/ConnectPage.tsx
+++ b/packages/console/src/features/connect/pages/ConnectPage.tsx
@@ -19,9 +19,9 @@ export function ConnectPage() {
   const origin = window.location.origin;
 
   return (
-    <div className="mx-auto w-full max-w-3xl">
+    <div className="mx-auto w-full max-w-3xl p-4 md:p-6">
       <div className="mb-1">
-        <h1 className="text-2xl font-semibold">连接</h1>
+        <h1 className="text-xl font-medium">连接</h1>
       </div>
       <p className="mb-6 text-sm text-muted-foreground">
         这个 daemon 的地址是 <code className="font-mono">{origin}</code> —
diff --git a/packages/console/src/features/doctor/pages/DoctorPage.tsx b/packages/console/src/features/doctor/pages/DoctorPage.tsx
index 5904c3a..5a43a10 100644
--- a/packages/console/src/features/doctor/pages/DoctorPage.tsx
+++ b/packages/console/src/features/doctor/pages/DoctorPage.tsx
@@ -85,17 +85,11 @@ export function DoctorPage() {
   );
 
   return (
-    <>
-      <div className="flex flex-wrap items-center justify-between gap-3">
-        <div>
-          <h1 className="flex items-center gap-2 text-2xl font-semibold">
-            体检 <SampleDataBadge />
-          </h1>
-          <p className="text-sm text-muted-foreground">
-            与 <code className="font-mono">dor doctor</code> 同一套只读检查:
-            这台机器能不能跑 daemon。只查不修,修是 install.sh 的活。
-          </p>
-        </div>
+    <div className="mx-auto flex w-full max-w-6xl flex-col gap-5 p-4 md:p-6">
+      <header className="flex flex-wrap items-center justify-between gap-3">
+        <h1 className="flex items-center gap-2 text-xl font-medium">
+          体检 <SampleDataBadge />
+        </h1>
         <Tooltip>
           <TooltipTrigger
             render={
@@ -108,7 +102,7 @@ export function DoctorPage() {
           />
           <TooltipContent>接入 runDoctor 端点后可用</TooltipContent>
         </Tooltip>
-      </div>
+      </header>
 
       <div className="flex flex-wrap items-center gap-2 text-sm">
         <Badge
@@ -176,6 +170,6 @@ export function DoctorPage() {
           </ul>
         </CardContent>
       </Card>
-    </>
+    </div>
   );
 }
diff --git a/packages/console/src/features/ingress/pages/DomainsPage.tsx b/packages/console/src/features/ingress/pages/DomainsPage.tsx
index d46e119..727bb7c 100644
--- a/packages/console/src/features/ingress/pages/DomainsPage.tsx
+++ b/packages/console/src/features/ingress/pages/DomainsPage.tsx
@@ -247,19 +247,14 @@ export function DomainsPage() {
   };
 
   return (
-    // 内容是竖排的域名条目与指引,同设置页限宽居中。
-    <div className="mx-auto flex w-full max-w-4xl flex-col gap-4">
-      <div className="flex flex-wrap items-center justify-between gap-3">
-        <div>
-          <h1 className="text-2xl font-semibold">域名</h1>
-          <p className="text-sm text-muted-foreground">
-            给控制台(和 API)绑定域名,可以绑多个;HTTPS 证书自动申请与续期。
-          </p>
-        </div>
+    // 内容是竖排的域名条目与指引 — 不是表格页,限宽 4xl 读起来舒服。
+    <div className="mx-auto flex w-full max-w-4xl flex-col gap-5 p-4 md:p-6">
+      <header className="flex flex-wrap items-center justify-between gap-3">
+        <h1 className="text-xl font-medium">域名</h1>
         {data?.managed && statuses.length > 0 && (
           <BindDomainDialog bound={bound} publicIp={publicIp} />
         )}
-      </div>
+      </header>
 
       {isPending ? (
         <div className="flex items-center gap-2 text-sm text-muted-foreground">
diff --git a/packages/console/src/features/overview/components/FleetStatCards.tsx b/packages/console/src/features/overview/components/FleetStatCards.tsx
index 2342abe..aed593c 100644
--- a/packages/console/src/features/overview/components/FleetStatCards.tsx
+++ b/packages/console/src/features/overview/components/FleetStatCards.tsx
@@ -8,12 +8,14 @@ import {
 } from '../hooks/useFleetTimeline';
 import { useHostMetrics } from '../hooks/useHostMetrics';
 import { Meter } from './Meter';
+import { SandboxDisksCard } from './SandboxDisksCard';
 import { Sparkline } from './Sparkline';
 import { StatCard, StatCardSkeleton } from './StatCard';
 
 /**
- * 舰队三卡:当前活跃(5 秒一刷的快照 + 窗口内活跃数 sparkline)、窗口
- * 峰值、总数/容量。当前值来自 /getHostMetrics;峰值与 sparkline 来自
+ * 舰队四卡(openasi 顶排版式,2026-07-16 沙箱磁盘上顶):当前活跃
+ * (5 秒一刷的快照 + 窗口内活跃数 sparkline)、窗口峰值、总数/容量、
+ * 沙箱磁盘账单。当前值来自 /getHostMetrics;峰值与 sparkline 来自
  * /getFleetTimeline — daemon 采样器 30 秒落一行,峰值由原始行现算,
  * 分桶抹不掉它。档位由页头的全局切换器驱动。
  */
@@ -36,8 +38,8 @@ export function FleetStatCards({ range }: { range: TimelineRangeKey }) {
 
   if (!host.data || !timeline.data) {
     return (
-      <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
-        {['active', 'peak', 'total'].map((slot) => (
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
+        {['active', 'peak', 'total', 'disks'].map((slot) => (
           <StatCardSkeleton key={slot} />
         ))}
       </div>
@@ -52,12 +54,13 @@ export function FleetStatCards({ range }: { range: TimelineRangeKey }) {
   );
 
   return (
-    <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
+    <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
       <StatCard
         label="当前活跃"
+        // 四列布局下 footer 左栏只有 8 个汉字宽,文案按这个上限写。
         value={String(sandboxes.byState.active)}
-        hint="此刻正在运行的沙箱"
-        sub="其余状态都不占 CPU"
+        hint="正在运行的沙箱"
+        sub="其余状态不占 CPU"
         corner={
           <Sparkline
             data={activeSeries}
@@ -87,6 +90,7 @@ export function FleetStatCards({ range }: { range: TimelineRangeKey }) {
         }
         to="/sandboxes"
       />
+      <SandboxDisksCard />
     </div>
   );
 }
diff --git a/packages/console/src/features/overview/components/RangeSwitcher.tsx b/packages/console/src/features/overview/components/RangeSwitcher.tsx
index 73df6b7..8996eb9 100644
--- a/packages/console/src/features/overview/components/RangeSwitcher.tsx
+++ b/packages/console/src/features/overview/components/RangeSwitcher.tsx
@@ -39,11 +39,17 @@ export function RangeSwitcher({
           if (typeof next === 'string') onChange(next as TimelineRangeKey);
         }}
         variant="outline"
-        size="sm"
-        className="hidden sm:flex"
+        spacing={0}
+        // openasi 同款分段控件(2026-07-16):无缝拼接、加宽点按面,
+        // 切档不闪过渡动画。
+        className="hidden *:data-[slot=toggle-group-item]:px-3.5 sm:flex"
       >
         {TIMELINE_RANGES.map((r) => (
-          <ToggleGroupItem key={r.key} value={r.key}>
+          <ToggleGroupItem
+            key={r.key}
+            value={r.key}
+            className="transition-none"
+          >
             {r.label}
           </ToggleGroupItem>
         ))}
diff --git a/packages/console/src/features/overview/components/SandboxDisksCard.tsx b/packages/console/src/features/overview/components/SandboxDisksCard.tsx
index 883f8a8..1df7ec1 100644
--- a/packages/console/src/features/overview/components/SandboxDisksCard.tsx
+++ b/packages/console/src/features/overview/components/SandboxDisksCard.tsx
@@ -30,9 +30,11 @@ export function SandboxDisksCard() {
   return (
     <StatCard
       label="沙箱磁盘"
+      // 稀疏镜像只为真实内容付费:大数字是实占,hint 是许诺 — 差值即超卖。
+      // 四列布局下 footer 左栏只有 8 个汉字宽,文案按这个上限写。
       value={formatBytes(sandboxDisks.actualBytes)}
-      hint={`${sandboxDisks.count} 块盘共许诺 ${formatBytes(sandboxDisks.nominalBytes)}`}
-      sub={`实占 ${usedPct}% — 稀疏镜像只为真实内容付费`}
+      hint={`共许诺 ${formatBytes(sandboxDisks.nominalBytes)}`}
+      sub={`${sandboxDisks.count} 块盘 · 实占 ${usedPct}%`}
       corner={
         <div className="w-20 shrink-0 pb-1.5 @[250px]/card:w-24">
           <Meter pct={usedPct} />
diff --git a/packages/console/src/features/overview/pages/OverviewPage.tsx b/packages/console/src/features/overview/pages/OverviewPage.tsx
index 61a48b1..2849d3e 100644
--- a/packages/console/src/features/overview/pages/OverviewPage.tsx
+++ b/packages/console/src/features/overview/pages/OverviewPage.tsx
@@ -4,39 +4,30 @@ import { FleetStatCards } from '../components/FleetStatCards';
 import { HostHealthCard } from '../components/HostHealthCard';
 import { QuickConnectCard } from '../components/QuickConnectCard';
 import { RangeSwitcher } from '../components/RangeSwitcher';
-import { SandboxDisksCard } from '../components/SandboxDisksCard';
 import type { TimelineRangeKey } from '../hooks/useFleetTimeline';
 
 /**
  * 回答三个问题:沙箱群现在多忙、一段时间以来多忙(daemon 采样器落库
- * 的舰队时间线,含窗口峰值)、这台机器还好吗。版式参考 openasi 仪表盘:
- * 页头右侧的全局档位切换统一驱动统计卡与主图,主图区 3:1(走势图配
- * 宿主健康竖卡),底部一行沙箱磁盘账单 + 快速接入(「换两个 URL 直连」
- * 放上第一屏)。
+ * 的舰队时间线,含窗口峰值)、这台机器还好吗。版式仿 openasi 仪表盘
+ * (2026-07-16 用户拍板对齐页头与容器):max-w-6xl 限宽居中,页头一行
+ * 标题 + 全局档位,顶排四张统计卡(沙箱磁盘也在其中),主图区 3:1
+ * (走势图配宿主健康竖卡),底部快速接入(「换两个 URL 直连」放上第一屏)。
  */
 export function OverviewPage() {
   const [range, setRange] = useState<TimelineRangeKey>('24h');
 
   return (
-    <>
-      <div className="flex flex-wrap items-center justify-between gap-3">
-        <div>
-          <h1 className="text-2xl font-semibold">仪表盘</h1>
-          <p className="text-sm text-muted-foreground">
-            沙箱群的并发走势,与这台机器的健康状况。
-          </p>
-        </div>
+    <div className="mx-auto w-full max-w-6xl space-y-6 p-4 md:p-6">
+      <header className="flex flex-wrap items-center justify-between gap-3">
+        <h1 className="text-xl font-medium">仪表盘</h1>
         <RangeSwitcher range={range} onChange={setRange} />
-      </div>
+      </header>
       <FleetStatCards range={range} />
       <div className="grid grid-cols-1 gap-4 lg:grid-cols-4">
         <FleetChart range={range} className="min-h-[420px] lg:col-span-3" />
         <HostHealthCard className="min-h-[420px] lg:col-span-1" />
       </div>
-      <div className="grid gap-4 md:grid-cols-2">
-        <SandboxDisksCard />
-        <QuickConnectCard />
-      </div>
-    </>
+      <QuickConnectCard />
+    </div>
   );
 }
diff --git a/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx b/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
index 2f32ca6..e44a372 100644
--- a/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
+++ b/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
@@ -80,7 +80,8 @@ function LiveTerminal({ sandboxId }: { sandboxId: string }) {
     <div className="flex flex-col gap-2">
       <div
         ref={containerRef}
-        className="h-80 w-full overflow-hidden rounded-md bg-black p-2"
+        // select-text:全局 select-none 下终端输出必须仍可选中复制。
+        className="h-80 w-full select-text overflow-hidden rounded-md bg-black p-2"
       />
       {closedReason && (
         <div className="flex items-center justify-between rounded-md border px-3 py-2 text-sm text-muted-foreground">
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index 18bdbeb..cb0751d 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -66,7 +66,7 @@ export function SandboxDetailPage() {
 
   if (!sandbox) {
     return isSuccess ? (
-      <Empty className="border border-dashed">
+      <Empty className="m-4 border border-dashed md:m-6">
         <EmptyHeader>
           <EmptyTitle>没有叫「{name}」的沙箱</EmptyTitle>
           <EmptyDescription>
@@ -89,10 +89,11 @@ export function SandboxDetailPage() {
   }
 
   return (
-    <>
-      <div className="flex flex-wrap items-center justify-between gap-3">
+    // 工作区页:与列表页同宽限 6xl,页头随 openasi 版式(text-xl medium)。
+    <div className="mx-auto flex w-full max-w-6xl flex-col gap-4 p-4 md:p-6">
+      <header className="flex flex-wrap items-center justify-between gap-3">
         <div className="flex items-center gap-3">
-          <h1 className="font-mono text-2xl font-semibold">{sandbox.name}</h1>
+          <h1 className="font-mono text-xl font-medium">{sandbox.name}</h1>
           <SandboxStateBadge state={sandbox.state} />
           <LifecycleCountdown sandbox={sandbox} />
         </div>
@@ -104,7 +105,7 @@ export function SandboxDetailPage() {
             onDestroyed={() => navigate({ to: '/sandboxes' })}
           />
         </div>
-      </div>
+      </header>
 
       {(sandbox.state === 'archived' || sandbox.state === 'restoring') && (
         <RestoreCard sandbox={sandbox} />
@@ -209,6 +210,6 @@ export function SandboxDetailPage() {
           <HistoryPanel name={sandbox.name} />
         </TabsContent>
       </Tabs>
-    </>
+    </div>
   );
 }
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index cbc503b..30e4848 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -14,6 +14,7 @@ import { useMemo, useState } from 'react';
 import { toast } from 'sonner';
 import { DataTable } from '@/components/DataTable';
 import { FilterMenu } from '@/components/FilterMenu';
+import { paginate, TablePager } from '@/components/TablePager';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import {
   AlertDialog,
@@ -78,8 +79,10 @@ const STATE_FILTERS: Array<SandboxState> = [
   'restoring',
 ];
 
+const PAGE_SIZE = 50;
+
 /** 可排序的列:字符串比较对 name 和 ISO 时间戳同样成立。 */
-type SortKey = 'name' | 'lastActiveAt' | 'createdAt';
+type SortKey = 'name' | 'lastActiveAt';
 type Sort = { key: SortKey; dir: 1 | -1 };
 
 /** 一个沙箱的标签摊平成 "key=value" 串 — 筛选项与展示共用同一拼法。 */
@@ -94,15 +97,18 @@ function MetadataChips({ sandbox }: { sandbox: Sandbox }) {
   const pairs = labelPairs(sandbox);
   if (pairs.length === 0) return null;
   return (
-    <span className="inline-flex max-w-[16rem] flex-wrap gap-1">
+    // 上限收着点:列要在 max-w-6xl 里一屏放下,肥列多一寸,「操作」列
+    // 就被挤出视野一寸(2026-07-16 实测过溢出)。truncate 放内层 span:
+    // Badge 是 flex 容器,直接截自己会从两侧裁字、省略号不出现。
+    <span className="inline-flex max-w-[13rem] flex-wrap gap-1">
       {pairs.map((pair) => (
         <Badge
           key={pair}
           variant="outline"
-          className="max-w-[10rem] truncate font-mono text-xs font-normal text-muted-foreground"
+          className="max-w-[6.5rem] font-mono text-xs font-normal text-muted-foreground"
           title={pair}
         >
-          {pair}
+          <span className="truncate">{pair}</span>
         </Badge>
       ))}
     </span>
@@ -314,6 +320,9 @@ export function SandboxesPage() {
   const [metadataFilter, setMetadataFilter] = useState('');
   const [selected, setSelected] = useState<Set<string>>(new Set());
   const [sort, setSort] = useState<Sort | null>(null);
+  // 分页是纯前端的(列表整份在手里);筛选变化回第一页,排序不回 —
+  // 排序改的是全序不是集合。
+  const [page, setPage] = useState(1);
 
   const metadataOptions = useMemo(() => {
     const pairs = new Set(sandboxes.flatMap(labelPairs));
@@ -342,6 +351,8 @@ export function SandboxesPage() {
     );
   }, [sandboxes, stateFilter, metadataFilter, search, sort]);
 
+  const { rows, safePage, pageCount } = paginate(filtered, page, PAGE_SIZE);
+
   // 选中集随现实收敛:被别处销毁的沙箱不该留在选中里撑数字。
   const selectedVisible = filtered.filter((s) => selected.has(s.name));
   const allVisibleSelected =
@@ -362,18 +373,15 @@ export function SandboxesPage() {
   };
 
   return (
-    <>
-      <div className="flex flex-wrap items-center justify-between gap-3">
-        <div>
-          <h1 className="text-2xl font-semibold">沙箱</h1>
-          <p className="text-sm text-muted-foreground">
-            账本里的全部沙箱,每 2 秒刷新 — 看着不会吵醒任何一个。
-          </p>
-        </div>
+    // openasi 列表页版式(2026-07-16 用户拍板):限宽居中、页头一行、
+    // 表格吃掉剩余高度框内滚、分页条钉底。h-full 接住外壳锁定的视口高。
+    <div className="mx-auto flex h-full w-full max-w-6xl flex-col gap-5 p-4 md:p-6">
+      <header className="flex shrink-0 flex-wrap items-center justify-between gap-3">
+        <h1 className="text-xl font-medium">沙箱</h1>
         <CreateSandboxDialog />
-      </div>
+      </header>
 
-      <div className="flex flex-wrap items-center gap-2">
+      <div className="flex shrink-0 flex-wrap items-center gap-2">
         <InputGroup className="w-64">
           <InputGroupAddon>
             <HugeiconsIcon
@@ -383,7 +391,10 @@ export function SandboxesPage() {
           </InputGroupAddon>
           <InputGroupInput
             value={search}
-            onChange={(event) => setSearch(event.target.value)}
+            onChange={(event) => {
+              setSearch(event.target.value);
+              setPage(1);
+            }}
             placeholder="按 name 搜索"
           />
         </InputGroup>
@@ -394,16 +405,20 @@ export function SandboxesPage() {
             value: state,
             label: STATE_LABELS[state],
           }))}
-          onChange={(value) =>
-            setStateFilter(value === '' ? 'all' : (value as SandboxState))
-          }
+          onChange={(value) => {
+            setStateFilter(value === '' ? 'all' : (value as SandboxState));
+            setPage(1);
+          }}
         />
         {metadataOptions.length > 0 && (
           <FilterMenu
             label="标签"
             value={metadataFilter}
             options={metadataOptions}
-            onChange={setMetadataFilter}
+            onChange={(value) => {
+              setMetadataFilter(value);
+              setPage(1);
+            }}
           />
         )}
         <span className="text-sm text-muted-foreground">
@@ -426,7 +441,7 @@ export function SandboxesPage() {
       )}
 
       {query.isSuccess && sandboxes.length === 0 && (
-        <Empty className="border border-dashed">
+        <Empty className="flex-1 border border-dashed">
           <EmptyHeader>
             <EmptyMedia variant="icon">
               <HugeiconsIcon icon={PackageIcon} />
@@ -440,7 +455,7 @@ export function SandboxesPage() {
       )}
 
       {query.isSuccess && sandboxes.length > 0 && filtered.length === 0 && (
-        <Empty className="border border-dashed">
+        <Empty className="flex-1 border border-dashed">
           <EmptyHeader>
             <EmptyTitle>没有匹配的沙箱</EmptyTitle>
             <EmptyDescription>换个关键词或状态试试。</EmptyDescription>
@@ -449,8 +464,8 @@ export function SandboxesPage() {
       )}
 
       {filtered.length > 0 && (
-        // 限高让长列表在框内滚,表头吸顶 — 列名滚不丢。
-        <DataTable containerClassName="max-h-[70vh]">
+        // fill:表格占满剩余高度框内滚,表头吸顶 — 列名滚不丢。
+        <DataTable fill>
           <TableHeader>
             <TableRow>
               <TableHead className="w-0">
@@ -483,20 +498,13 @@ export function SandboxesPage() {
                   onSort={toggleSort}
                 />
               </TableHead>
-              <TableHead>生命周期策略</TableHead>
-              <TableHead>
-                <SortableHead
-                  label="存活"
-                  sortKey="createdAt"
-                  sort={sort}
-                  onSort={toggleSort}
-                />
-              </TableHead>
+              {/* 短表头:6 个字的表头会把列最小宽钉死,行内容才是主角。 */}
+              <TableHead title="生命周期策略">策略</TableHead>
               <TableHead className="text-right">操作</TableHead>
             </TableRow>
           </TableHeader>
           <TableBody>
-            {filtered.map((sandbox: Sandbox) => (
+            {rows.map((sandbox: Sandbox) => (
               <TableRow
                 key={sandbox.id}
                 data-state={selected.has(sandbox.name) ? 'selected' : undefined}
@@ -567,14 +575,19 @@ export function SandboxesPage() {
                 >
                   {since(sandbox.lastActiveAt)}
                 </TableCell>
-                <TableCell className="text-xs text-muted-foreground">
-                  {policyLine(sandbox.policy)}
-                </TableCell>
-                <TableCell
-                  className="tabular-nums text-muted-foreground"
-                  title={`创建于:${new Date(sandbox.createdAt).toLocaleString()}`}
-                >
-                  {since(sandbox.createdAt)}
+                {/* 限宽 + 放开 nowrap(vendored TableCell 默认不换行)让长
+                    策略折行,且只在「·」分隔处断 — CJK 默认哪里都能断,
+                    会把「停止」劈成两半。「存活」列刻意不设(2026-07-16
+                    版式取舍):创建时长与空闲高度重复,详情页有它的家。 */}
+                <TableCell className="max-w-[10rem] whitespace-normal text-xs text-muted-foreground">
+                  {policyLine(sandbox.policy)
+                    .split(' · ')
+                    .map((segment, index) => (
+                      <span key={segment}>
+                        {index > 0 && ' · '}
+                        <span className="whitespace-nowrap">{segment}</span>
+                      </span>
+                    ))}
                 </TableCell>
                 <TableCell className="text-right">
                   <SandboxRowMenu name={sandbox.name} />
@@ -584,6 +597,15 @@ export function SandboxesPage() {
           </TableBody>
         </DataTable>
       )}
-    </>
+
+      {filtered.length > 0 && (
+        <TablePager
+          page={safePage}
+          pageCount={pageCount}
+          total={filtered.length}
+          onPageChange={setPage}
+        />
+      )}
+    </div>
   );
 }
diff --git a/packages/console/src/features/settings/pages/SettingsPage.tsx b/packages/console/src/features/settings/pages/SettingsPage.tsx
index 2a047bb..d30c14e 100644
--- a/packages/console/src/features/settings/pages/SettingsPage.tsx
+++ b/packages/console/src/features/settings/pages/SettingsPage.tsx
@@ -1,5 +1,7 @@
 import type { ConfigEntry } from '@dormice/shared';
+import { useState } from 'react';
 import { DataTable } from '@/components/DataTable';
+import { paginate, TablePager } from '@/components/TablePager';
 import { Badge } from '@/components/ui/badge';
 import {
   Empty,
@@ -16,7 +18,6 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { formatDuration } from '@/features/sandboxes/format';
-import { VersionCard } from '../components/VersionCard';
 import { useConfig } from '../hooks/useConfig';
 
 /**
@@ -68,6 +69,8 @@ function ValueCell({ entry }: { entry: ConfigEntry }) {
   return <>{entry.value}</>;
 }
 
+const PAGE_SIZE = 50;
+
 /**
  * daemon 生效配置的只读观察窗:回答"这台 daemon 开了哪些旋钮"。刻意
  * 只读 — 配置的真身在 /etc/dormice/env,改完重启 daemon 生效;网页里
@@ -75,31 +78,38 @@ function ValueCell({ entry }: { entry: ConfigEntry }) {
  */
 export function SettingsPage() {
   const { data, isPending, isError, error } = useConfig();
+  const [page, setPage] = useState(1);
 
   if (isPending) {
     return (
-      <div className="flex items-center gap-2 text-sm text-muted-foreground">
+      <div className="flex items-center gap-2 p-4 text-sm text-muted-foreground md:p-6">
         <Spinner /> 读取生效配置
       </div>
     );
   }
   if (isError) {
     return (
-      <Empty className="border border-dashed">
-        <EmptyHeader>
-          <EmptyTitle>读取失败</EmptyTitle>
-          <EmptyDescription>{error.message}</EmptyDescription>
-        </EmptyHeader>
-      </Empty>
+      <div className="mx-auto flex h-full w-full max-w-6xl flex-col p-4 md:p-6">
+        <Empty className="flex-1 border border-dashed">
+          <EmptyHeader>
+            <EmptyTitle>读取失败</EmptyTitle>
+            <EmptyDescription>{error.message}</EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      </div>
     );
   }
 
+  const { rows, safePage, pageCount } = paginate(data.entries, page, PAGE_SIZE);
+
   return (
-    // 四列窄表,铺满宽屏一行字拉太长 — 限宽居中,读起来是一页文档。
-    <div className="mx-auto flex w-full max-w-4xl flex-col gap-4">
-      <div>
-        <h1 className="text-2xl font-semibold">设置</h1>
-        <p className="text-sm text-muted-foreground">
+    // openasi 列表页版式(2026-07-16 用户拍板);版本卡已拆去独立的
+    // /version 页 — 设置是设置,版本是版本。
+    <div className="mx-auto flex h-full w-full max-w-6xl flex-col gap-5 p-4 md:p-6">
+      <header className="shrink-0">
+        <h1 className="text-xl font-medium">设置</h1>
+        {/* 这行不是装饰:配置的真身与改法只在这里说 — 页面本体是只读的。 */}
+        <p className="mt-1 text-sm text-muted-foreground">
           daemon 的生效配置,只读。改配置在主机的{' '}
           <code className="font-mono">/etc/dormice/env</code>,改完{' '}
           <code className="font-mono">systemctl restart dormice</code>。归档:
@@ -108,11 +118,9 @@ export function SettingsPage() {
             : '未启用 — 配齐 DORMICE_S3_* 四件套后可用'}
           。
         </p>
-      </div>
-
-      <VersionCard />
+      </header>
 
-      <DataTable>
+      <DataTable fill>
         <TableHeader>
           <TableRow>
             <TableHead>旋钮</TableHead>
@@ -122,7 +130,7 @@ export function SettingsPage() {
           </TableRow>
         </TableHeader>
         <TableBody>
-          {data.entries.map((entry) => (
+          {rows.map((entry) => (
             <TableRow key={entry.key}>
               <TableCell className="font-mono text-xs font-medium">
                 {entry.key}
@@ -144,6 +152,13 @@ export function SettingsPage() {
           ))}
         </TableBody>
       </DataTable>
+
+      <TablePager
+        page={safePage}
+        pageCount={pageCount}
+        total={data.entries.length}
+        onPageChange={setPage}
+      />
     </div>
   );
 }
diff --git a/packages/console/src/features/settings/pages/VersionPage.tsx b/packages/console/src/features/settings/pages/VersionPage.tsx
new file mode 100644
index 0000000..0942449
--- /dev/null
+++ b/packages/console/src/features/settings/pages/VersionPage.tsx
@@ -0,0 +1,18 @@
+import { VersionCard } from '../components/VersionCard';
+
+/**
+ * daemon 的版本与升级,从设置页拆出的独立页(2026-07-16 用户拍板:
+ * 版本是版本,设置是设置)。逻辑全在 VersionCard — 检测更新、一键升级
+ * 弹窗、真进度;侧栏的可升级角标也挂在这一项上。窄内容页限宽 4xl,
+ * 一张卡不摊大饼。
+ */
+export function VersionPage() {
+  return (
+    <div className="mx-auto flex w-full max-w-4xl flex-col gap-5 p-4 md:p-6">
+      <header>
+        <h1 className="text-xl font-medium">版本</h1>
+      </header>
+      <VersionCard />
+    </div>
+  );
+}
diff --git a/packages/console/src/features/templates/pages/TemplatesPage.tsx b/packages/console/src/features/templates/pages/TemplatesPage.tsx
index 555139b..96df212 100644
--- a/packages/console/src/features/templates/pages/TemplatesPage.tsx
+++ b/packages/console/src/features/templates/pages/TemplatesPage.tsx
@@ -11,6 +11,7 @@ import { Link } from '@tanstack/react-router';
 import { useState } from 'react';
 import { toast } from 'sonner';
 import { DataTable } from '@/components/DataTable';
+import { paginate, TablePager } from '@/components/TablePager';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import {
   AlertDialog,
@@ -273,6 +274,8 @@ function TemplateRowMenu({ template }: { template: Template }) {
   );
 }
 
+const PAGE_SIZE = 50;
+
 /**
  * 模板注册表:名字 → 镜像的账本行。宿主机的 Docker daemon 就是镜像库,
  * 这一页管的只是指向;引用数从 2 秒轮询的沙箱列表现算,不发明新端点。
@@ -281,21 +284,18 @@ export function TemplatesPage() {
   const templates = useTemplates();
   const sandboxes = useSandboxes().data?.sandboxes ?? [];
   const list = templates.data?.templates ?? [];
+  const [page, setPage] = useState(1);
+  const { rows, safePage, pageCount } = paginate(list, page, PAGE_SIZE);
 
   const referenceCount = (name: string) =>
     sandboxes.filter((sandbox) => sandbox.template === name).length;
 
   return (
-    // 六列窄表,同设置页限宽居中 — 宽屏上不摊大饼。
-    <div className="mx-auto flex w-full max-w-4xl flex-col gap-4">
-      <div className="flex flex-wrap items-center justify-between gap-3">
-        <div>
-          <h1 className="text-2xl font-semibold">模板</h1>
-          <p className="text-sm text-muted-foreground">
-            模板 = 命名的 Docker 镜像。名字即 E2B 的 templateID,重新注册
-            即升级。
-          </p>
-        </div>
+    // openasi 列表页版式(2026-07-16 用户拍板):限宽居中、表格吃掉剩余
+    // 高度框内滚、分页条钉底。
+    <div className="mx-auto flex h-full w-full max-w-6xl flex-col gap-5 p-4 md:p-6">
+      <header className="flex shrink-0 flex-wrap items-center justify-between gap-3">
+        <h1 className="text-xl font-medium">模板</h1>
         <RegisterTemplateDialog
           trigger={
             <Button size="sm">
@@ -304,7 +304,7 @@ export function TemplatesPage() {
             </Button>
           }
         />
-      </div>
+      </header>
 
       {templates.isError && (
         <Alert variant="destructive">
@@ -313,7 +313,7 @@ export function TemplatesPage() {
       )}
 
       {templates.isSuccess && list.length === 0 && (
-        <Empty className="border border-dashed">
+        <Empty className="flex-1 border border-dashed">
           <EmptyHeader>
             <EmptyMedia variant="icon">
               <HugeiconsIcon icon={Layers01Icon} />
@@ -328,7 +328,7 @@ export function TemplatesPage() {
       )}
 
       {list.length > 0 && (
-        <DataTable>
+        <DataTable fill>
           <TableHeader>
             <TableRow>
               <TableHead>名字</TableHead>
@@ -340,7 +340,7 @@ export function TemplatesPage() {
             </TableRow>
           </TableHeader>
           <TableBody>
-            {list.map((template) => {
+            {rows.map((template) => {
               const references = referenceCount(template.name);
               return (
                 <TableRow key={template.name}>
@@ -384,6 +384,15 @@ export function TemplatesPage() {
           </TableBody>
         </DataTable>
       )}
+
+      {list.length > 0 && (
+        <TablePager
+          page={safePage}
+          pageCount={pageCount}
+          total={list.length}
+          onPageChange={setPage}
+        />
+      )}
     </div>
   );
 }
diff --git a/packages/console/src/index.css b/packages/console/src/index.css
index 61ca628..58e76f3 100644
--- a/packages/console/src/index.css
+++ b/packages/console/src/index.css
@@ -10,7 +10,19 @@
 @layer base {
   body {
     /* macOS 浏览器默认亚像素渲染把字形描粗,medium/semibold 都显臃肿;
-       灰度平滑(antialiased)才是 Inter 设计稿上的粗细。 */
-    @apply antialiased;
+       灰度平滑(antialiased)才是 Inter 设计稿上的粗细。
+       select-none:全站默认禁选(2026-07-16 用户拍板,对齐 openasi 的
+       桌面应用感);生来要被复制的表面在下面整类放开。 */
+    @apply antialiased select-none;
+  }
+
+  /* 代码与输入区是"读了就要拿走"的内容,禁选对它们是残疾不是质感。 */
+  code,
+  pre,
+  kbd,
+  samp,
+  input,
+  textarea {
+    @apply select-text;
   }
 }
diff --git a/packages/console/src/routeTree.gen.ts b/packages/console/src/routeTree.gen.ts
index 74fb4ab..e309840 100644
--- a/packages/console/src/routeTree.gen.ts
+++ b/packages/console/src/routeTree.gen.ts
@@ -12,6 +12,7 @@ import { Route as rootRouteImport } from './routes/__root'
 import { Route as LoginRouteImport } from './routes/login'
 import { Route as AppRouteImport } from './routes/_app'
 import { Route as AppIndexRouteImport } from './routes/_app/index'
+import { Route as AppVersionRouteImport } from './routes/_app/version'
 import { Route as AppTemplatesRouteImport } from './routes/_app/templates'
 import { Route as AppSettingsRouteImport } from './routes/_app/settings'
 import { Route as AppDomainsRouteImport } from './routes/_app/domains'
@@ -36,6 +37,11 @@ const AppIndexRoute = AppIndexRouteImport.update({
   path: '/',
   getParentRoute: () => AppRoute,
 } as any)
+const AppVersionRoute = AppVersionRouteImport.update({
+  id: '/version',
+  path: '/version',
+  getParentRoute: () => AppRoute,
+} as any)
 const AppTemplatesRoute = AppTemplatesRouteImport.update({
   id: '/templates',
   path: '/templates',
@@ -92,6 +98,7 @@ export interface FileRoutesByFullPath {
   '/domains': typeof AppDomainsRoute
   '/settings': typeof AppSettingsRoute
   '/templates': typeof AppTemplatesRoute
+  '/version': typeof AppVersionRoute
   '/sandboxes/$name': typeof AppSandboxesNameRoute
   '/sandboxes/': typeof AppSandboxesIndexRoute
 }
@@ -104,6 +111,7 @@ export interface FileRoutesByTo {
   '/domains': typeof AppDomainsRoute
   '/settings': typeof AppSettingsRoute
   '/templates': typeof AppTemplatesRoute
+  '/version': typeof AppVersionRoute
   '/': typeof AppIndexRoute
   '/sandboxes/$name': typeof AppSandboxesNameRoute
   '/sandboxes': typeof AppSandboxesIndexRoute
@@ -119,6 +127,7 @@ export interface FileRoutesById {
   '/_app/domains': typeof AppDomainsRoute
   '/_app/settings': typeof AppSettingsRoute
   '/_app/templates': typeof AppTemplatesRoute
+  '/_app/version': typeof AppVersionRoute
   '/_app/': typeof AppIndexRoute
   '/_app/sandboxes/$name': typeof AppSandboxesNameRoute
   '/_app/sandboxes/': typeof AppSandboxesIndexRoute
@@ -135,6 +144,7 @@ export interface FileRouteTypes {
     | '/domains'
     | '/settings'
     | '/templates'
+    | '/version'
     | '/sandboxes/$name'
     | '/sandboxes/'
   fileRoutesByTo: FileRoutesByTo
@@ -147,6 +157,7 @@ export interface FileRouteTypes {
     | '/domains'
     | '/settings'
     | '/templates'
+    | '/version'
     | '/'
     | '/sandboxes/$name'
     | '/sandboxes'
@@ -161,6 +172,7 @@ export interface FileRouteTypes {
     | '/_app/domains'
     | '/_app/settings'
     | '/_app/templates'
+    | '/_app/version'
     | '/_app/'
     | '/_app/sandboxes/$name'
     | '/_app/sandboxes/'
@@ -194,6 +206,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AppIndexRouteImport
       parentRoute: typeof AppRoute
     }
+    '/_app/version': {
+      id: '/_app/version'
+      path: '/version'
+      fullPath: '/version'
+      preLoaderRoute: typeof AppVersionRouteImport
+      parentRoute: typeof AppRoute
+    }
     '/_app/templates': {
       id: '/_app/templates'
       path: '/templates'
@@ -268,6 +287,7 @@ interface AppRouteChildren {
   AppDomainsRoute: typeof AppDomainsRoute
   AppSettingsRoute: typeof AppSettingsRoute
   AppTemplatesRoute: typeof AppTemplatesRoute
+  AppVersionRoute: typeof AppVersionRoute
   AppIndexRoute: typeof AppIndexRoute
   AppSandboxesNameRoute: typeof AppSandboxesNameRoute
   AppSandboxesIndexRoute: typeof AppSandboxesIndexRoute
@@ -281,6 +301,7 @@ const AppRouteChildren: AppRouteChildren = {
   AppDomainsRoute: AppDomainsRoute,
   AppSettingsRoute: AppSettingsRoute,
   AppTemplatesRoute: AppTemplatesRoute,
+  AppVersionRoute: AppVersionRoute,
   AppIndexRoute: AppIndexRoute,
   AppSandboxesNameRoute: AppSandboxesNameRoute,
   AppSandboxesIndexRoute: AppSandboxesIndexRoute,
diff --git a/packages/console/src/routes/_app/version.tsx b/packages/console/src/routes/_app/version.tsx
new file mode 100644
index 0000000..9f80625
--- /dev/null
+++ b/packages/console/src/routes/_app/version.tsx
@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router';
+import { VersionPage } from '@/features/settings/pages/VersionPage';
+
+export const Route = createFileRoute('/_app/version')({
+  component: VersionPage,
+});

From fc1efffa37399f0c139a5943952bbe74a53a04a0 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 17:14:20 +0800
Subject: [PATCH 096/133] =?UTF-8?q?API=20keys=20grow=20a=20full=20lifecycl?=
 =?UTF-8?q?e=20and=20lose=20the=20power=20to=20govern=20themselves:=20the?=
 =?UTF-8?q?=20four=20management=20verbs=20(create/list/update/revoke)=20no?=
 =?UTF-8?q?w=20sit=20behind=20an=20admin-only=20gate=20that=20accepts=20th?=
 =?UTF-8?q?e=20env=20token=20or=20a=20console=20session=20and=20answers=20?=
 =?UTF-8?q?a=20live=20ledger=20key=20with=20an=20honest=20403=20=E2=80=94?=
 =?UTF-8?q?=20key-manages-key=20was=20a=20self-replication=20ladder=20wher?=
 =?UTF-8?q?e=20one=20leaked=20credential=20mints=20itself=20an=20unrevoked?=
 =?UTF-8?q?=20successor,=20and=20the=20refusal's=20ledger=20lookup=20is=20?=
 =?UTF-8?q?a=20pure=20read=20so=20a=20rejected=20request=20leaves=20no=20l?=
 =?UTF-8?q?astUsedAt=20fingerprint=20(a=20disabled=20or=20expired=20key=20?=
 =?UTF-8?q?falls=20through=20to=20the=20same=20401=20as=20garbage,=20becau?=
 =?UTF-8?q?se=20a=20403=20for=20it=20would=20leak=20that=20the=20row=20exi?=
 =?UTF-8?q?sts).=20Between=20minting=20and=20revoking=20there=20are=20now?=
 =?UTF-8?q?=20two=20gentler=20states:=20disabledAt=20parks=20a=20key=20rev?=
 =?UTF-8?q?ersibly=20and=20expiresAt=20lets=20it=20lapse=20on=20schedule?=
 =?UTF-8?q?=20(normalized=20to=20exact=20toISOString=20on=20every=20write?=
 =?UTF-8?q?=20=E2=80=94=20wire=20ISO=20precision=20varies,=20and=20an=20un?=
 =?UTF-8?q?-normalized=20string=20compare=20would=20call=20an=20earlier=20?=
 =?UTF-8?q?instant=20later),=20with=20one=20liveness=20WHERE=20adjudicatin?=
 =?UTF-8?q?g=20all=20three=20exits=20for=20both=20credential=20faces.=20Th?=
 =?UTF-8?q?e=20new=20updateApiKey=20renames,=20re-expires=20and=20parks=20?=
 =?UTF-8?q?in=20patch=20semantics,=20which=20makes=20the=20name=20mutable?=
 =?UTF-8?q?=20and=20therefore=20no=20longer=20an=20address:=20revoke=20and?=
 =?UTF-8?q?=20update=20speak=20id=20on=20the=20wire=20(the=20sandbox=20nam?=
 =?UTF-8?q?e/id=20doctrine=20applied=20to=20keys),=20while=20the=20CLI=20k?=
 =?UTF-8?q?eeps=20talking=20names=20and=20resolves=20them=20against=20the?=
 =?UTF-8?q?=20non-revoked=20row=20=E2=80=94=20disabled=20keys=20still=20ho?=
 =?UTF-8?q?ld=20their=20name=20because=20they=20must=20remain=20reachable?=
 =?UTF-8?q?=20to=20re-enable.=20The=20console=20page=20grows=20the=20opena?=
 =?UTF-8?q?si=20apparatus=20the=20threat=20model=20permits=20=E2=80=94=20e?=
 =?UTF-8?q?nable/disable=20switch,=20expiry=20picker=20to=20end-of-local-d?=
 =?UTF-8?q?ay,=20edit=20dialog,=20bulk=20revoke,=20a=20copy-connection-con?=
 =?UTF-8?q?fig=20second=20act,=20masked=20prefixes,=20and=20a=20pinned=20v?=
 =?UTF-8?q?irtual=20row=20making=20DORMICE=5FAPI=5FTOKEN=20visible=20as=20?=
 =?UTF-8?q?the=20undeletable=20default=20=E2=80=94=20and=20deliberately=20?=
 =?UTF-8?q?not=20the=20part=20it=20forbids:=20keys=20stay=20hashed,=20neve?=
 =?UTF-8?q?r=20re-shown,=20because=20a=20Dormice=20key=20is=20full=20sandb?=
 =?UTF-8?q?ox=20power=20and=20a=20ledger=20file=20in=20a=20backup=20must?=
 =?UTF-8?q?=20not=20be=20a=20credential=20dump=20('forgot=20to=20save=20it?=
 =?UTF-8?q?'=20is=20answered=20by=20cheap=20rotation,=20not=20plaintext).?=
 =?UTF-8?q?=20dor=20apikey=20gains=20disable/enable=20and=20create=20--exp?=
 =?UTF-8?q?ires=20YYYY-MM-DD;=20migration=200012=20adds=20the=20two=20colu?=
 =?UTF-8?q?mns;=20three=20activity=20kinds=20(updated/disabled/enabled)=20?=
 =?UTF-8?q?make=20the=20security=20events=20separately=20filterable;=20and?=
 =?UTF-8?q?=20the=20e2e=20rotation=20story=20caught=20the=20exact=20bug=20?=
 =?UTF-8?q?the=20honest-false=20doctrine=20warns=20about=20=E2=80=94=20a?=
 =?UTF-8?q?=20leftover=20name-addressed=20revoke=20silently=20answering=20?=
 =?UTF-8?q?revoked:false=20while=20the=20key=20lived=20on.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 e2e/src/cli.test.ts                           |  23 +
 e2e/src/e2b.test.ts                           |   4 +-
 e2e/src/native.test.ts                        |  23 +-
 packages/cli/src/commands.test.ts             |  61 +-
 packages/cli/src/commands.ts                  | 110 ++-
 packages/cli/src/main.ts                      |  28 +-
 .../console/src/features/activity/kinds.ts    |   9 +
 .../src/features/api-keys/hooks/useApiKeys.ts |  31 +-
 .../features/api-keys/pages/ApiKeysPage.tsx   | 683 +++++++++++++++---
 .../console/src/features/sandboxes/format.ts  |   5 +
 packages/console/src/lib/api.ts               |  22 +-
 packages/sdk/src/client.test.ts               |  48 +-
 packages/sdk/src/client.ts                    |  47 +-
 .../drizzle/0012_apikey-expiry-disable.sql    |   2 +
 .../server/drizzle/meta/0012_snapshot.json    | 552 ++++++++++++++
 packages/server/drizzle/meta/_journal.json    |   7 +
 packages/server/src/app.test.ts               | 273 +++++--
 packages/server/src/app.ts                    |  23 +-
 packages/server/src/auth.ts                   |  83 ++-
 packages/server/src/db/api-keys.ts            | 167 ++++-
 packages/server/src/db/schema.ts              |  12 +
 packages/server/src/e2b/compat.test.ts        |  49 +-
 packages/server/src/routes/api-keys.ts        |  60 +-
 packages/shared/src/activity.ts               |   6 +
 packages/shared/src/api-keys.ts               | 100 ++-
 skills/dormice/SKILL.md                       |  10 +-
 website/content/docs/cli.mdx                  |  19 +-
 website/content/docs/console.mdx              |  22 +-
 website/content/docs/e2b-sdks.mdx             |   4 +-
 website/content/docs/http-api.mdx             |  37 +-
 30 files changed, 2224 insertions(+), 296 deletions(-)
 create mode 100644 packages/server/drizzle/0012_apikey-expiry-disable.sql
 create mode 100644 packages/server/drizzle/meta/0012_snapshot.json

diff --git a/e2e/src/cli.test.ts b/e2e/src/cli.test.ts
index 8f5db5c..ccd781b 100644
--- a/e2e/src/cli.test.ts
+++ b/e2e/src/cli.test.ts
@@ -167,6 +167,29 @@ describe('dor CLI against a real daemon', () => {
     expect(listed.stdout).toMatch(/NAME\s{2,}PREFIX\s{2,}CREATED/);
     expect(listed.stdout).toMatch(/cli-key\s{2,}[0-9a-f]{8}.*active/);
 
+    // Disable parks the credential (next request dies), enable revives it.
+    const disabled = await cli('apikey', 'disable', 'cli-key');
+    expect(disabled.stdout).toContain('Disabled API key "cli-key"');
+    await expect(
+      run('node', [CLI, 'sandbox', 'ls'], {
+        env: {
+          ...process.env,
+          DORMICE_ENDPOINT: inject('dormiceEndpoint'),
+          DORMICE_API_TOKEN: token,
+        },
+      }),
+    ).rejects.toMatchObject({ code: 1 });
+    const enabled = await cli('apikey', 'enable', 'cli-key');
+    expect(enabled.stdout).toContain('Enabled API key "cli-key"');
+    const revived = await run('node', [CLI, 'sandbox', 'ls'], {
+      env: {
+        ...process.env,
+        DORMICE_ENDPOINT: inject('dormiceEndpoint'),
+        DORMICE_API_TOKEN: token,
+      },
+    });
+    expect(revived.stdout).toBeDefined();
+
     const revoked = await cli('apikey', 'revoke', 'cli-key');
     expect(revoked.stdout).toContain('Revoked API key "cli-key"');
     await expect(
diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 6c3d0b4..366af7b 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -80,7 +80,7 @@ describe('official e2b SDK against the daemon', () => {
       endpoint: inject('dormiceEndpoint'),
       token: inject('dormiceToken'),
     });
-    const { token } = await dormice.createApiKey('e2b-face');
+    const { apiKey, token } = await dormice.createApiKey('e2b-face');
     try {
       const sbx = await Sandbox.create({
         ...connection(),
@@ -93,7 +93,7 @@ describe('official e2b SDK against the daemon', () => {
         await sbx.kill();
       }
     } finally {
-      await dormice.revokeApiKey('e2b-face');
+      await dormice.revokeApiKey(apiKey.id);
     }
     // Revoked: the same key is refused at the control-plane door.
     await expect(
diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index bbadad3..8684b2d 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -417,7 +417,7 @@ describe('native API over a real daemon', () => {
     });
   });
 
-  it('API keys: the rolling-rotation story — mint, work, revoke, the env token survives', async () => {
+  it('API keys: the rolling-rotation story — mint, work, park, revoke, the env token survives', async () => {
     const { apiKey, token } = await client().createApiKey('rotation');
     expect(token).toMatch(/^[0-9a-f]{64}$/);
     expect(apiKey.prefix).toBe(token.slice(0, 8));
@@ -433,14 +433,31 @@ describe('native API over a real daemon', () => {
     const mine = listed.find((k) => k.name === 'rotation');
     expect(mine?.lastUsedAt).not.toBeNull();
 
-    expect(await client().revokeApiKey('rotation')).toEqual({ revoked: true });
+    // Key-manages-key is refused with the honest 403 — a leaked key must
+    // not be able to mint itself an unrevoked successor.
+    await expect(keyed.listApiKeys()).rejects.toMatchObject({
+      name: 'DormiceApiError',
+      status: 403,
+      message: expect.stringMatching(/cannot manage API keys/),
+    });
+    await expect(keyed.createApiKey('backdoor')).rejects.toMatchObject({
+      status: 403,
+    });
+
+    // Disable is the reversible hold: 401 while parked, alive again after.
+    await client().updateApiKey(apiKey.id, { disabled: true });
+    await expect(keyed.listSandboxes()).rejects.toMatchObject({ status: 401 });
+    await client().updateApiKey(apiKey.id, { disabled: false });
+    expect(await keyed.listSandboxes()).toBeDefined();
+
+    expect(await client().revokeApiKey(apiKey.id)).toEqual({ revoked: true });
     await expect(keyed.listSandboxes()).rejects.toMatchObject({
       name: 'DormiceApiError',
       status: 401,
     });
     // The env token is the bootstrap credential: revocation never touches it.
     expect(await client().listSandboxes()).toBeDefined();
-    expect(await client().revokeApiKey('rotation')).toEqual({
+    expect(await client().revokeApiKey(apiKey.id)).toEqual({
       revoked: false,
     });
   });
diff --git a/packages/cli/src/commands.test.ts b/packages/cli/src/commands.test.ts
index 6281b92..d9fd9b7 100644
--- a/packages/cli/src/commands.test.ts
+++ b/packages/cli/src/commands.test.ts
@@ -11,6 +11,8 @@ import {
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import {
   apikeyCreate,
+  apikeyDisable,
+  apikeyEnable,
   apikeyLs,
   apikeyRevoke,
   clientFromEnv,
@@ -37,6 +39,7 @@ const MIGRATIONS = fileURLToPath(
 
 let app: ReturnType<typeof buildApp>;
 let client: Dormice;
+let endpoint: string;
 
 beforeAll(async () => {
   const db = openDb(':memory:');
@@ -62,10 +65,8 @@ beforeAll(async () => {
   if (typeof address !== 'object' || address === null) {
     throw new Error('expected a TCP address');
   }
-  client = new Dormice({
-    endpoint: `http://127.0.0.1:${address.port}`,
-    token: TOKEN,
-  });
+  endpoint = `http://127.0.0.1:${address.port}`;
+  client = new Dormice({ endpoint, token: TOKEN });
 });
 
 afterAll(async () => {
@@ -235,9 +236,9 @@ describe('apikey commands over real HTTP', () => {
 
     const output = await apikeyLs(client);
     expect(output.split('\n')[0]).toMatch(
-      /^NAME\s{2,}PREFIX\s{2,}CREATED\s{2,}LAST USED\s{2,}STATUS$/,
+      /^NAME\s{2,}PREFIX\s{2,}CREATED\s{2,}LAST USED\s{2,}EXPIRES\s{2,}STATUS$/,
     );
-    expect(output).toMatch(/ci\s{2,}[0-9a-f]{8}.*never\s{2,}active/);
+    expect(output).toMatch(/ci\s{2,}[0-9a-f]{8}.*never\s{2,}never\s{2,}active/);
 
     expect(await apikeyRevoke(client, 'ci')).toBe(
       'Revoked API key "ci" — it stops working immediately.',
@@ -247,6 +248,54 @@ describe('apikey commands over real HTTP', () => {
     );
     expect(await apikeyLs(client)).toMatch(/ci\s{2,}.*revoked/);
   });
+
+  it('disable parks a key by name; enable resumes it; a disabled key still revokes by name', async () => {
+    await apikeyCreate(client, 'park-me');
+
+    expect(await apikeyDisable(client, 'park-me')).toBe(
+      'Disabled API key "park-me" — it stops working until re-enabled.',
+    );
+    expect(await apikeyLs(client)).toMatch(/park-me\s{2,}.*disabled/);
+
+    expect(await apikeyEnable(client, 'park-me')).toBe(
+      'Enabled API key "park-me".',
+    );
+    expect(await apikeyLs(client)).toMatch(/park-me\s{2,}.*active/);
+
+    // Disabled keys keep their name — revoke must still reach them by it.
+    await apikeyDisable(client, 'park-me');
+    expect(await apikeyRevoke(client, 'park-me')).toBe(
+      'Revoked API key "park-me" — it stops working immediately.',
+    );
+    await expect(apikeyDisable(client, 'park-me')).rejects.toThrow(
+      /no API key named "park-me"/,
+    );
+  });
+
+  it('--expires mints a TTL key through end-of-day and refuses garbage dates', async () => {
+    const created = await apikeyCreate(client, 'ttl', '2030-06-15');
+    expect(created.split('\n')[0]).toMatch(
+      /^Created API key "ttl" \(prefix [0-9a-f]{8}, expires 2030-06-1[56]T.*\)\.$/,
+    );
+    expect(await apikeyLs(client)).toMatch(/ttl\s{2,}.*active/);
+
+    await expect(apikeyCreate(client, 'bad', 'next tuesday')).rejects.toThrow(
+      /--expires must be a date like 2026-12-31/,
+    );
+    await expect(apikeyCreate(client, 'bad', '2030-02-31')).rejects.toThrow(
+      /--expires/,
+    );
+  });
+
+  it("a minted key is refused on the management verbs with the server's honest 403", async () => {
+    const created = await apikeyCreate(client, 'not-admin');
+    const token = created.split('\n')[1] ?? '';
+    expect(token).toMatch(/^[0-9a-f]{64}$/);
+    const keyed = new Dormice({ endpoint, token });
+    await expect(apikeyLs(keyed)).rejects.toThrow(
+      /cannot manage API keys — use DORMICE_API_TOKEN or the console/,
+    );
+  });
 });
 
 describe('template commands over real HTTP', () => {
diff --git a/packages/cli/src/commands.ts b/packages/cli/src/commands.ts
index c264fdd..beeda56 100644
--- a/packages/cli/src/commands.ts
+++ b/packages/cli/src/commands.ts
@@ -1,5 +1,6 @@
 import {
   type ApiKey,
+  apiKeyStatus,
   Dormice,
   type ReadFileResult,
   type Sandbox,
@@ -270,17 +271,74 @@ export async function templateRm(
 }
 
 /**
- * `dor apikey create <name>`: mint an API key. The token line is the one
- * and only time the key material exists outside the daemon's hash — the
- * warning is part of the output, not decoration.
+ * The CLI speaks names; the wire speaks ids (names are renameable, so the
+ * id is the stable address). One resolver, used by every verb that edits a
+ * key. "Not revoked" is the filter, deliberately wider than "live":
+ * disabled and expired keys still hold their name, and the operator must
+ * be able to enable or revoke them by it.
+ */
+async function resolveApiKeyId(
+  client: Dormice,
+  name: string,
+): Promise<string | null> {
+  const keys = await client.listApiKeys();
+  return keys.find((k) => k.name === name && k.revokedAt === null)?.id ?? null;
+}
+
+/**
+ * Strictly YYYY-MM-DD, expiring at the END of that local day — "expires
+ * 2026-08-01" naturally reads as "works through August 1st", and the
+ * console's date picker uses the same semantics.
+ */
+function parseExpiresDate(value: string): string {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) {
+    throw new Error(
+      `--expires must be a date like 2026-12-31 (got "${printable(value)}")`,
+    );
+  }
+  const [, year, month, day] = match;
+  const endOfDay = new Date(
+    Number(year),
+    Number(month) - 1,
+    Number(day),
+    23,
+    59,
+    59,
+    999,
+  );
+  // The Date constructor rolls impossible dates over (Feb 31 -> Mar 3)
+  // instead of failing; a round-trip check keeps the refusal honest.
+  if (
+    endOfDay.getFullYear() !== Number(year) ||
+    endOfDay.getMonth() !== Number(month) - 1 ||
+    endOfDay.getDate() !== Number(day)
+  ) {
+    throw new Error(`--expires: "${printable(value)}" is not a real date`);
+  }
+  return endOfDay.toISOString();
+}
+
+/**
+ * `dor apikey create <name> [--expires YYYY-MM-DD]`: mint an API key. The
+ * token line is the one and only time the key material exists outside the
+ * daemon's hash — the warning is part of the output, not decoration.
  */
 export async function apikeyCreate(
   client: Dormice,
   name: string,
+  expires?: string,
 ): Promise<string> {
-  const { apiKey, token } = await client.createApiKey(name);
+  const expiresAt =
+    expires === undefined ? undefined : parseExpiresDate(expires);
+  const { apiKey, token } = await client.createApiKey(
+    name,
+    expiresAt ? { expiresAt } : undefined,
+  );
   return (
-    `Created API key "${printable(apiKey.name)}" (prefix ${apiKey.prefix}).\n` +
+    `Created API key "${printable(apiKey.name)}" (prefix ${apiKey.prefix}` +
+    (apiKey.expiresAt ? `, expires ${apiKey.expiresAt}` : '') +
+    ').\n' +
     `${token}\n` +
     'Store it now — it will never be shown again.'
   );
@@ -292,12 +350,14 @@ export async function apikeyLs(client: Dormice): Promise<string> {
   if (keys.length === 0) {
     return 'No API keys.';
   }
+  const now = Date.now();
   const columns: { header: string; value: (k: ApiKey) => string }[] = [
     { header: 'NAME', value: (k) => k.name },
     { header: 'PREFIX', value: (k) => k.prefix },
     { header: 'CREATED', value: (k) => k.createdAt },
     { header: 'LAST USED', value: (k) => k.lastUsedAt ?? 'never' },
-    { header: 'STATUS', value: (k) => (k.revokedAt ? 'revoked' : 'active') },
+    { header: 'EXPIRES', value: (k) => k.expiresAt ?? 'never' },
+    { header: 'STATUS', value: (k) => apiKeyStatus(k, now) },
   ];
   return renderTable(
     columns.map((column) => column.header),
@@ -306,16 +366,46 @@ export async function apikeyLs(client: Dormice): Promise<string> {
 }
 
 /**
- * `dor apikey revoke <name>`: kill the active key under a name. The false
- * branch is said out loud — a silent miss here would leave a leaked key
- * alive behind a typo.
+ * `dor apikey revoke <name>`: kill the non-revoked key under a name. The
+ * false branch is said out loud — a silent miss here would leave a leaked
+ * key alive behind a typo.
  */
 export async function apikeyRevoke(
   client: Dormice,
   name: string,
 ): Promise<string> {
-  const { revoked } = await client.revokeApiKey(name);
+  const id = await resolveApiKeyId(client, name);
+  const revoked = id === null ? false : (await client.revokeApiKey(id)).revoked;
   return revoked
     ? `Revoked API key "${printable(name)}" — it stops working immediately.`
     : `No active API key named "${printable(name)}" — nothing to revoke.`;
 }
+
+/**
+ * `dor apikey disable <name>`: park a key reversibly — it stops working on
+ * the next request but keeps its name and history, unlike revoke.
+ */
+export async function apikeyDisable(
+  client: Dormice,
+  name: string,
+): Promise<string> {
+  const id = await resolveApiKeyId(client, name);
+  if (id === null) {
+    throw new Error(`no API key named "${printable(name)}"`);
+  }
+  await client.updateApiKey(id, { disabled: true });
+  return `Disabled API key "${printable(name)}" — it stops working until re-enabled.`;
+}
+
+/** `dor apikey enable <name>`: resume a parked key. */
+export async function apikeyEnable(
+  client: Dormice,
+  name: string,
+): Promise<string> {
+  const id = await resolveApiKeyId(client, name);
+  if (id === null) {
+    throw new Error(`no API key named "${printable(name)}"`);
+  }
+  await client.updateApiKey(id, { disabled: false });
+  return `Enabled API key "${printable(name)}".`;
+}
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index 712077a..e4898ce 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -8,6 +8,8 @@ import path from 'node:path';
 import { Command } from 'commander';
 import {
   apikeyCreate,
+  apikeyDisable,
+  apikeyEnable,
   apikeyLs,
   apikeyRevoke,
   clientFromEnv,
@@ -208,8 +210,14 @@ apikey
   .command('create')
   .description('Mint an API key; the token is printed once and never again')
   .argument('<name>', 'a human handle for the key, e.g. ci or laptop')
-  .action(async (name: string) => {
-    console.log(await apikeyCreate(clientFromEnv(process.env), name));
+  .option(
+    '--expires <date>',
+    'expiry date (YYYY-MM-DD, works through that day); omit for never',
+  )
+  .action(async (name: string, options: { expires?: string }) => {
+    console.log(
+      await apikeyCreate(clientFromEnv(process.env), name, options.expires),
+    );
   });
 
 apikey
@@ -219,6 +227,22 @@ apikey
     console.log(await apikeyLs(clientFromEnv(process.env)));
   });
 
+apikey
+  .command('disable')
+  .description('Park an API key reversibly — it stops working until re-enabled')
+  .argument('<name>', 'name of the key to disable')
+  .action(async (name: string) => {
+    console.log(await apikeyDisable(clientFromEnv(process.env), name));
+  });
+
+apikey
+  .command('enable')
+  .description('Resume a parked API key')
+  .argument('<name>', 'name of the key to enable')
+  .action(async (name: string) => {
+    console.log(await apikeyEnable(clientFromEnv(process.env), name));
+  });
+
 apikey
   .command('revoke')
   .description(
diff --git a/packages/console/src/features/activity/kinds.ts b/packages/console/src/features/activity/kinds.ts
index be72eaa..041af9b 100644
--- a/packages/console/src/features/activity/kinds.ts
+++ b/packages/console/src/features/activity/kinds.ts
@@ -22,6 +22,9 @@ export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
   'daemon-started': 'daemon 启动',
   'ingress-updated': '域名配置',
   'apikey-created': '密钥创建',
+  'apikey-updated': '密钥调整',
+  'apikey-disabled': '密钥停用',
+  'apikey-enabled': '密钥启用',
   'apikey-revoked': '密钥吊销',
   'upgrade-started': '发起升级',
 };
@@ -59,6 +62,12 @@ export const ACTIVITY_KIND_STYLES: Record<ActivityKind, string> = {
     'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
   'apikey-created':
     'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  'apikey-updated':
+    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  'apikey-disabled':
+    'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
+  'apikey-enabled':
+    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
   'apikey-revoked':
     'border-red-500/40 bg-red-500/10 text-red-600 dark:text-red-400',
   'upgrade-started':
diff --git a/packages/console/src/features/api-keys/hooks/useApiKeys.ts b/packages/console/src/features/api-keys/hooks/useApiKeys.ts
index da9b056..7c77edf 100644
--- a/packages/console/src/features/api-keys/hooks/useApiKeys.ts
+++ b/packages/console/src/features/api-keys/hooks/useApiKeys.ts
@@ -1,5 +1,10 @@
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { createApiKey, listApiKeys, revokeApiKey } from '@/lib/api';
+import {
+  createApiKey,
+  listApiKeys,
+  revokeApiKey,
+  updateApiKey,
+} from '@/lib/api';
 
 /**
  * API 密钥实体的数据层,一个文件聚合。密钥变化在操作员速度(铸造/吊销
@@ -17,16 +22,34 @@ export function useApiKeys() {
 export function useCreateApiKey() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: (name: string) => createApiKey(name),
+    mutationFn: ({ name, expiresAt }: { name: string; expiresAt?: string }) =>
+      createApiKey(name, expiresAt),
     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['apiKeys'] }),
   });
 }
 
-/** 软吊销:行留作轮换历史,凭证下一个请求就失效。 */
+/** 就地编辑:改名/改过期/启停都是这一个动词,缺省字段不动。 */
+export function useUpdateApiKey() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({
+      id,
+      ...patch
+    }: {
+      id: string;
+      name?: string;
+      expiresAt?: string | null;
+      disabled?: boolean;
+    }) => updateApiKey(id, patch),
+    onSettled: () => queryClient.invalidateQueries({ queryKey: ['apiKeys'] }),
+  });
+}
+
+/** 软吊销:行留作轮换历史,凭证下一个请求就失效。按 id 寻址。 */
 export function useRevokeApiKey() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: (name: string) => revokeApiKey(name),
+    mutationFn: (id: string) => revokeApiKey(id),
     onSettled: () => queryClient.invalidateQueries({ queryKey: ['apiKeys'] }),
   });
 }
diff --git a/packages/console/src/features/api-keys/pages/ApiKeysPage.tsx b/packages/console/src/features/api-keys/pages/ApiKeysPage.tsx
index c7ee05b..f022d58 100644
--- a/packages/console/src/features/api-keys/pages/ApiKeysPage.tsx
+++ b/packages/console/src/features/api-keys/pages/ApiKeysPage.tsx
@@ -1,15 +1,17 @@
-import type { ApiKey } from '@dormice/shared';
+import { type ApiKey, apiKeyStatus } from '@dormice/shared';
 import {
   Add01Icon,
+  Calendar03Icon,
   Copy01Icon,
   Delete02Icon,
-  Key01Icon,
+  Edit02Icon,
   MoreVerticalIcon,
 } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
 import { useState } from 'react';
 import { toast } from 'sonner';
 import { DataTable } from '@/components/DataTable';
+import { paginate, TablePager } from '@/components/TablePager';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import {
   AlertDialog,
@@ -23,6 +25,8 @@ import {
 } from '@/components/ui/alert-dialog';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
+import { Calendar } from '@/components/ui/calendar';
+import { Checkbox } from '@/components/ui/checkbox';
 import {
   Dialog,
   DialogContent,
@@ -38,13 +42,6 @@ import {
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from '@/components/ui/dropdown-menu';
-import {
-  Empty,
-  EmptyDescription,
-  EmptyHeader,
-  EmptyMedia,
-  EmptyTitle,
-} from '@/components/ui/empty';
 import {
   Field,
   FieldDescription,
@@ -53,7 +50,13 @@ import {
   FieldLabel,
 } from '@/components/ui/field';
 import { Input } from '@/components/ui/input';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/ui/popover';
 import { Spinner } from '@/components/ui/spinner';
+import { Switch } from '@/components/ui/switch';
 import {
   TableBody,
   TableCell,
@@ -61,22 +64,94 @@ import {
   TableHeader,
   TableRow,
 } from '@/components/ui/table';
-import { since } from '@/features/sandboxes/format';
+import { since, until } from '@/features/sandboxes/format';
 import { copyText } from '@/lib/copy';
 import {
   useApiKeys,
   useCreateApiKey,
   useRevokeApiKey,
+  useUpdateApiKey,
 } from '../hooks/useApiKeys';
 
+/** 选中的日期 → 当地时区当日 23:59:59.999 的 ISO:"到 8 月 1 日"自然读作"8 月 1 日当天还能用"。 */
+function endOfDayIso(date: Date): string {
+  return new Date(
+    date.getFullYear(),
+    date.getMonth(),
+    date.getDate(),
+    23,
+    59,
+    59,
+    999,
+  ).toISOString();
+}
+
+/**
+ * 过期日期选择:Popover + Calendar,不选 = 永不过期,选了可一键清除。
+ * 只到日粒度 — 密钥过期是"这周/这季度"级别的决定,时分秒是伪精度。
+ */
+function ExpiryPicker({
+  value,
+  onChange,
+  id,
+}: {
+  value: Date | undefined;
+  onChange: (next: Date | undefined) => void;
+  id: string;
+}) {
+  const [open, setOpen] = useState(false);
+  return (
+    <div className="flex items-center gap-2">
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger
+          render={
+            <Button
+              id={id}
+              type="button"
+              variant="outline"
+              className="justify-start font-normal"
+            >
+              <HugeiconsIcon icon={Calendar03Icon} />
+              {value ? value.toLocaleDateString() : '永不过期'}
+            </Button>
+          }
+        />
+        <PopoverContent className="w-auto p-0" align="start">
+          <Calendar
+            mode="single"
+            selected={value}
+            onSelect={(next) => {
+              onChange(next ?? undefined);
+              setOpen(false);
+            }}
+            disabled={{ before: new Date() }}
+          />
+        </PopoverContent>
+      </Popover>
+      {value && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          onClick={() => onChange(undefined)}
+        >
+          清除
+        </Button>
+      )}
+    </div>
+  );
+}
+
 /**
- * 铸造对话框演两幕:表单幕收名字,成功幕展示 token — daemon 只存哈希,
- * 这是 token 在世上唯一一次露面,所以成功后不自动关窗,复制按钮和
- * 「只显示这一次」的警告都长在这一幕里。关窗即翻篇,token 随之消失。
+ * 铸造对话框演两幕:表单幕收名字和可选过期日,成功幕展示 token — daemon
+ * 只存哈希,这是 token 在世上唯一一次露面,所以成功后不自动关窗,复制
+ * 按钮、「复制接入配置」和「只显示这一次」的警告都长在这一幕里。关窗即
+ * 翻篇,token 随之消失。
  */
 function CreateApiKeyDialog() {
   const [open, setOpen] = useState(false);
   const [name, setName] = useState('');
+  const [expiry, setExpiry] = useState<Date | undefined>(undefined);
   const [minted, setMinted] = useState<{ name: string; token: string } | null>(
     null,
   );
@@ -86,11 +161,17 @@ function CreateApiKeyDialog() {
     setOpen(next);
     if (next) {
       setName('');
+      setExpiry(undefined);
       setMinted(null);
       mutation.reset();
     }
   };
 
+  // 接入配置 = 端点 + 凭证,一次粘进 CI secrets 或 shell 配置。端点用
+  // 当前页面的 origin:操作员就是从这个地址够到 daemon 的。
+  const connectSnippet = (token: string) =>
+    `DORMICE_ENDPOINT=${window.location.origin}\nDORMICE_API_TOKEN=${token}`;
+
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogTrigger
@@ -108,16 +189,22 @@ function CreateApiKeyDialog() {
               <DialogTitle>创建 API 密钥</DialogTitle>
               <DialogDescription>
                 密钥与 DORMICE_API_TOKEN 等效通行(SDK、CLI、E2B 包都认),
-                区别是可以在这里随时吊销,不用改服务器配置、不用重启。
+                区别是可以在这里随时停用或吊销,不用改服务器配置、不用重启。
               </DialogDescription>
             </DialogHeader>
             <form
               onSubmit={(event) => {
                 event.preventDefault();
-                mutation.mutate(name, {
-                  onSuccess: ({ apiKey, token }) =>
-                    setMinted({ name: apiKey.name, token }),
-                });
+                mutation.mutate(
+                  {
+                    name,
+                    ...(expiry ? { expiresAt: endOfDayIso(expiry) } : {}),
+                  },
+                  {
+                    onSuccess: ({ apiKey, token }) =>
+                      setMinted({ name: apiKey.name, token }),
+                  },
+                );
               }}
             >
               <FieldGroup>
@@ -132,7 +219,18 @@ function CreateApiKeyDialog() {
                   />
                   <FieldDescription>
                     给人看的把手,比如 ci、laptop。
-                    同名同时只能有一把活跃密钥,吊销后名字可以再用。
+                    同名同时只能有一把未吊销的密钥,吊销后名字可以再用。
+                  </FieldDescription>
+                </Field>
+                <Field>
+                  <FieldLabel htmlFor="apikey-expiry">过期日期</FieldLabel>
+                  <ExpiryPicker
+                    id="apikey-expiry"
+                    value={expiry}
+                    onChange={setExpiry}
+                  />
+                  <FieldDescription>
+                    到期当天过完即失效;之后可以在编辑里延期或清除。
                   </FieldDescription>
                 </Field>
                 {mutation.isError && (
@@ -177,7 +275,18 @@ function CreateApiKeyDialog() {
                 <HugeiconsIcon icon={Copy01Icon} />
               </Button>
             </div>
-            <DialogFooter>
+            <DialogFooter className="flex-col gap-2 sm:flex-row sm:justify-between">
+              <Button
+                variant="outline"
+                onClick={() =>
+                  copyText(connectSnippet(minted.token)).then(
+                    () => toast.success('接入配置已复制 — 端点与凭证两行'),
+                    () => toast.error('复制失败 — 请手动选中复制'),
+                  )
+                }
+              >
+                复制接入配置
+              </Button>
               <Button onClick={() => onOpenChange(false)}>我已存好</Button>
             </DialogFooter>
           </>
@@ -187,24 +296,130 @@ function CreateApiKeyDialog() {
   );
 }
 
+/**
+ * 编辑弹窗:改名 + 改过期,只提交真正变化的字段(updateApiKey 的 patch
+ * 语义)。过期字段带 touched 标记 — 服务端存的 ISO 精确到毫秒,不碰它
+ * 就不该上 wire,否则会把别处设的精确时刻悄悄挪到当日末。
+ */
+function EditApiKeyDialog({
+  apiKey,
+  open,
+  onOpenChange,
+}: {
+  apiKey: ApiKey;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const [name, setName] = useState(apiKey.name);
+  const [expiry, setExpiry] = useState<Date | undefined>(
+    apiKey.expiresAt ? new Date(apiKey.expiresAt) : undefined,
+  );
+  const [expiryTouched, setExpiryTouched] = useState(false);
+  const mutation = useUpdateApiKey();
+
+  const reset = (next: boolean) => {
+    if (next) {
+      setName(apiKey.name);
+      setExpiry(apiKey.expiresAt ? new Date(apiKey.expiresAt) : undefined);
+      setExpiryTouched(false);
+      mutation.reset();
+    }
+    onOpenChange(next);
+  };
+
+  const submit = () => {
+    const patch: { name?: string; expiresAt?: string | null } = {};
+    if (name.trim() !== apiKey.name) patch.name = name.trim();
+    if (expiryTouched) patch.expiresAt = expiry ? endOfDayIso(expiry) : null;
+    if (Object.keys(patch).length === 0) {
+      onOpenChange(false);
+      return;
+    }
+    mutation.mutate(
+      { id: apiKey.id, ...patch },
+      {
+        onSuccess: () => {
+          toast.success(`已更新「${patch.name ?? apiKey.name}」`);
+          onOpenChange(false);
+        },
+        onError: (error) => toast.error(error.message),
+      },
+    );
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={reset}>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>编辑「{apiKey.name}」</DialogTitle>
+          <DialogDescription>
+            改名或调整过期日期。密钥本体不可见也不可换 — 要换材质就吊销重铸。
+          </DialogDescription>
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            submit();
+          }}
+        >
+          <FieldGroup>
+            <Field>
+              <FieldLabel htmlFor="apikey-edit-name">名字</FieldLabel>
+              <Input
+                id="apikey-edit-name"
+                value={name}
+                onChange={(event) => setName(event.target.value)}
+                className="font-mono"
+              />
+            </Field>
+            <Field>
+              <FieldLabel htmlFor="apikey-edit-expiry">过期日期</FieldLabel>
+              <ExpiryPicker
+                id="apikey-edit-expiry"
+                value={expiry}
+                onChange={(next) => {
+                  setExpiry(next);
+                  setExpiryTouched(true);
+                }}
+              />
+            </Field>
+            {mutation.isError && (
+              <FieldError>{mutation.error.message}</FieldError>
+            )}
+          </FieldGroup>
+          <DialogFooter className="mt-6">
+            <Button
+              type="submit"
+              disabled={name.trim() === '' || mutation.isPending}
+            >
+              {mutation.isPending && <Spinner />}
+              保存
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
 function RevokeApiKeyDialog({
-  name,
+  apiKey,
   open,
   onOpenChange,
 }: {
-  name: string;
+  apiKey: ApiKey;
   open: boolean;
   onOpenChange: (open: boolean) => void;
 }) {
   const mutation = useRevokeApiKey();
 
   const revoke = () =>
-    mutation.mutate(name, {
+    mutation.mutate(apiKey.id, {
       // false 要说响亮:漏杀一把泄露的密钥比报错更糟。
       onSuccess: ({ revoked }) =>
         revoked
-          ? toast.success(`已吊销「${name}」— 下一个请求就失效`)
-          : toast.error(`「${name}」名下没有活跃密钥 — 没有吊销任何东西`),
+          ? toast.success(`已吊销「${apiKey.name}」— 下一个请求就失效`)
+          : toast.error(`「${apiKey.name}」已不在 — 没有吊销任何东西`),
       onError: (error) => toast.error(error.message),
     });
 
@@ -212,10 +427,11 @@ function RevokeApiKeyDialog({
     <AlertDialog open={open} onOpenChange={onOpenChange}>
       <AlertDialogContent>
         <AlertDialogHeader>
-          <AlertDialogTitle>吊销密钥「{name}」?</AlertDialogTitle>
+          <AlertDialogTitle>吊销密钥「{apiKey.name}」?</AlertDialogTitle>
           <AlertDialogDescription>
             立即生效,不可恢复 — 还在用它的客户端下一个请求就会 401。
-            记录会留在列表里作轮换历史,名字可以再用。
+            只是暂时不用的话,停用开关是可逆的。记录会留在列表里作
+            轮换历史,名字可以再用。
           </AlertDialogDescription>
         </AlertDialogHeader>
         <AlertDialogFooter>
@@ -229,8 +445,9 @@ function RevokeApiKeyDialog({
   );
 }
 
-/** 行操作收进「⋯」菜单;吊销弹窗挂菜单外 — 菜单关闭即卸载,放里面会跟着消失。 */
+/** 行操作收进「⋯」菜单;弹窗挂菜单外 — 菜单关闭即卸载,放里面会跟着消失。 */
 function ApiKeyRowMenu({ apiKey }: { apiKey: ApiKey }) {
+  const [editOpen, setEditOpen] = useState(false);
   const [revokeOpen, setRevokeOpen] = useState(false);
 
   return (
@@ -248,6 +465,10 @@ function ApiKeyRowMenu({ apiKey }: { apiKey: ApiKey }) {
           }
         />
         <DropdownMenuContent align="end">
+          <DropdownMenuItem onClick={() => setEditOpen(true)}>
+            <HugeiconsIcon icon={Edit02Icon} />
+            编辑
+          </DropdownMenuItem>
           <DropdownMenuItem
             variant="destructive"
             onClick={() => setRevokeOpen(true)}
@@ -257,8 +478,13 @@ function ApiKeyRowMenu({ apiKey }: { apiKey: ApiKey }) {
           </DropdownMenuItem>
         </DropdownMenuContent>
       </DropdownMenu>
+      <EditApiKeyDialog
+        apiKey={apiKey}
+        open={editOpen}
+        onOpenChange={setEditOpen}
+      />
       <RevokeApiKeyDialog
-        name={apiKey.name}
+        apiKey={apiKey}
         open={revokeOpen}
         onOpenChange={setRevokeOpen}
       />
@@ -266,28 +492,168 @@ function ApiKeyRowMenu({ apiKey }: { apiKey: ApiKey }) {
   );
 }
 
+/** 批量吊销:逐个顺序执行,失败点名,成功一句汇总(BulkDestroyButton 同款)。 */
+function BulkRevokeButton({
+  keys,
+  onDone,
+}: {
+  keys: ApiKey[];
+  onDone: () => void;
+}) {
+  const [confirmOpen, setConfirmOpen] = useState(false);
+  const mutation = useRevokeApiKey();
+  const [running, setRunning] = useState(false);
+
+  const revokeAll = async () => {
+    setRunning(true);
+    const failures: string[] = [];
+    for (const key of keys) {
+      try {
+        await mutation.mutateAsync(key.id);
+      } catch {
+        failures.push(key.name);
+      }
+    }
+    setRunning(false);
+    setConfirmOpen(false);
+    onDone();
+    if (failures.length > 0) {
+      toast.error(`吊销失败:${failures.join('、')}`);
+    } else {
+      toast.success(`已吊销 ${keys.length} 把密钥`);
+    }
+  };
+
+  return (
+    <>
+      <Button
+        variant="destructive"
+        size="sm"
+        onClick={() => setConfirmOpen(true)}
+      >
+        <HugeiconsIcon icon={Delete02Icon} />
+        吊销所选({keys.length})
+      </Button>
+      <AlertDialog open={confirmOpen} onOpenChange={setConfirmOpen}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>
+              吊销选中的 {keys.length} 把密钥?
+            </AlertDialogTitle>
+            <AlertDialogDescription>
+              {keys.map((k) => k.name).join('、')}—
+              立即生效,不可恢复,还在用它们的客户端下一个请求就会 401。
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={running}>先留着</AlertDialogCancel>
+            <AlertDialogAction
+              variant="destructive"
+              disabled={running}
+              onClick={(event) => {
+                // 手动跑完再关窗:批量是多个请求,关窗即失控。
+                event.preventDefault();
+                void revokeAll();
+              }}
+            >
+              {running && <Spinner />}
+              吊销全部
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  );
+}
+
+const PAGE_SIZE = 50;
+const SOON_MS = 7 * 24 * 3600_000;
+
+const STATUS_BADGE: Record<
+  ReturnType<typeof apiKeyStatus>,
+  { label: string; className?: string; variant: 'outline' | 'secondary' }
+> = {
+  active: { label: '活跃', variant: 'outline' },
+  disabled: {
+    label: '已停用',
+    variant: 'outline',
+    className:
+      'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
+  },
+  expired: {
+    label: '已过期',
+    variant: 'outline',
+    className:
+      'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
+  },
+  revoked: { label: '已吊销', variant: 'secondary' },
+};
+
 /**
- * API 密钥账本:铸造、吊销、看谁还活着。密钥本体永不再现(daemon 只存
- * 哈希),所以表格只有前缀可看;已吊销的行留着 — 那是轮换历史,不是垃圾。
- * DORMICE_API_TOKEN 不在这张表里:它是引导/恢复凭证,吊销它 = 改服务器
- * 配置文件。
+ * API 密钥账本:铸造、编辑、启停、吊销,批量与分页齐备。密钥本体永不
+ * 再现(daemon 只存哈希),所以表格只有前缀可看;已吊销的行留着 — 那是
+ * 轮换历史,不是垃圾。DORMICE_API_TOKEN 以置顶虚拟行的身份出现:它不在
+ * 账本里,轮换它 = 改服务器配置并重启,这里只让它可见,不让它可操作 —
+ * 管理动词(含本页全部按钮)也只认它或 console 登录态,密钥管不了密钥。
  */
 export function ApiKeysPage() {
   const query = useApiKeys();
   const keys = query.data?.apiKeys ?? [];
+  const [page, setPage] = useState(1);
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+  const update = useUpdateApiKey();
+  const { rows, safePage, pageCount } = paginate(keys, page, PAGE_SIZE);
+  const now = Date.now();
+
+  // 选择向现实收敛:被别处吊销的行自动掉出选择集;可选 = 当前页未吊销行。
+  const selectable = rows.filter((k) => k.revokedAt === null);
+  const selectedLive = keys.filter(
+    (k) => selected.has(k.id) && k.revokedAt === null,
+  );
+  const allSelected =
+    selectable.length > 0 && selectable.every((k) => selected.has(k.id));
+
+  const toggleAll = () =>
+    setSelected((prev) => {
+      const next = new Set(prev);
+      for (const k of selectable) {
+        if (allSelected) next.delete(k.id);
+        else next.add(k.id);
+      }
+      return next;
+    });
+
+  const toggleOne = (id: string) =>
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
 
   return (
-    // 六列窄表,同模板页限宽居中 — 宽屏上不摊大饼。
-    <div className="mx-auto flex w-full max-w-4xl flex-col gap-4">
-      <div className="flex flex-wrap items-center justify-between gap-3">
-        <div>
-          <h1 className="text-2xl font-semibold">API 密钥</h1>
-          <p className="text-sm text-muted-foreground">
-            与 DORMICE_API_TOKEN 等效的可吊销凭证 — 轮换不停机,泄露即止损。
-          </p>
+    // openasi 列表页版式(2026-07-16 用户拍板):限宽居中、表格吃掉剩余
+    // 高度框内滚、分页条钉底。
+    <div className="mx-auto flex h-full w-full max-w-6xl flex-col gap-5 p-4 md:p-6">
+      <header className="flex shrink-0 flex-wrap items-center justify-between gap-3">
+        <div className="flex items-center gap-3">
+          <h1 className="text-xl font-medium">API 密钥</h1>
+          {selectedLive.length > 0 && (
+            <span className="text-sm text-muted-foreground">
+              已选 {selectedLive.length} 把
+            </span>
+          )}
         </div>
-        <CreateApiKeyDialog />
-      </div>
+        <div className="flex items-center gap-2">
+          {selectedLive.length > 0 && (
+            <BulkRevokeButton
+              keys={selectedLive}
+              onDone={() => setSelected(new Set())}
+            />
+          )}
+          <CreateApiKeyDialog />
+        </div>
+      </header>
 
       {query.isError && (
         <Alert variant="destructive">
@@ -295,81 +661,170 @@ export function ApiKeysPage() {
         </Alert>
       )}
 
-      {query.isSuccess && keys.length === 0 && (
-        <Empty className="border border-dashed">
-          <EmptyHeader>
-            <EmptyMedia variant="icon">
-              <HugeiconsIcon icon={Key01Icon} />
-            </EmptyMedia>
-            <EmptyTitle>还没有 API 密钥</EmptyTitle>
-            <EmptyDescription>
-              现在全靠 DORMICE_API_TOKEN 一枚凭证。创建一把密钥给每个
-              客户端,泄露时吊销那一把就够,不用全局换钥匙。
-            </EmptyDescription>
-          </EmptyHeader>
-        </Empty>
-      )}
+      <DataTable fill>
+        <TableHeader>
+          <TableRow>
+            <TableHead className="w-0">
+              <Checkbox
+                checked={allSelected}
+                onCheckedChange={toggleAll}
+                disabled={selectable.length === 0}
+                aria-label="全选本页"
+              />
+            </TableHead>
+            <TableHead>名字</TableHead>
+            <TableHead>前缀</TableHead>
+            <TableHead>创建</TableHead>
+            <TableHead>最后使用</TableHead>
+            <TableHead>过期</TableHead>
+            <TableHead>启用</TableHead>
+            <TableHead>状态</TableHead>
+            <TableHead className="text-right">操作</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {/* 引导凭证的虚拟行:不在账本、不进分页与选择集,只为让
+              「全部凭证」在一张表里可见。 */}
+          <TableRow className="bg-muted/30">
+            <TableCell />
+            <TableCell
+              className="font-mono font-medium"
+              title="引导/恢复凭证,来自服务器环境变量 — 轮换它 = 改服务器配置并重启 daemon,console 无法吊销"
+            >
+              <span className="flex items-center gap-2">
+                DORMICE_API_TOKEN
+                <Badge variant="secondary">默认</Badge>
+              </span>
+            </TableCell>
+            <TableCell className="text-muted-foreground">环境变量</TableCell>
+            <TableCell className="text-muted-foreground">—</TableCell>
+            <TableCell className="text-muted-foreground">—</TableCell>
+            <TableCell className="text-muted-foreground">永不过期</TableCell>
+            <TableCell />
+            <TableCell>
+              <Badge variant="outline">常驻</Badge>
+            </TableCell>
+            <TableCell />
+          </TableRow>
 
-      {keys.length > 0 && (
-        <DataTable>
-          <TableHeader>
+          {query.isSuccess && keys.length === 0 && (
             <TableRow>
-              <TableHead>名字</TableHead>
-              <TableHead>前缀</TableHead>
-              <TableHead>创建</TableHead>
-              <TableHead>最后使用</TableHead>
-              <TableHead>状态</TableHead>
-              <TableHead className="text-right">操作</TableHead>
+              <TableCell
+                colSpan={9}
+                className="py-8 text-center text-sm text-muted-foreground"
+              >
+                还没有账本密钥 — 现在全靠上面那一枚环境变量凭证。
+                给每个客户端创建一把密钥,泄露时吊销那一把就够,不用全局换钥匙。
+              </TableCell>
             </TableRow>
-          </TableHeader>
-          <TableBody>
-            {keys.map((apiKey) => {
-              const revoked = apiKey.revokedAt !== null;
-              return (
-                <TableRow
-                  key={apiKey.id}
-                  className={revoked ? 'text-muted-foreground' : undefined}
+          )}
+
+          {rows.map((apiKey) => {
+            const status = apiKeyStatus(apiKey, now);
+            const revoked = status === 'revoked';
+            const badge = STATUS_BADGE[status];
+            const expiresSoon =
+              apiKey.expiresAt !== null &&
+              status === 'active' &&
+              Date.parse(apiKey.expiresAt) - now < SOON_MS;
+            return (
+              <TableRow
+                key={apiKey.id}
+                data-state={selected.has(apiKey.id) ? 'selected' : undefined}
+                className={revoked ? 'text-muted-foreground' : undefined}
+              >
+                <TableCell>
+                  <Checkbox
+                    checked={selected.has(apiKey.id)}
+                    onCheckedChange={() => toggleOne(apiKey.id)}
+                    disabled={revoked}
+                    aria-label={`选择 ${apiKey.name}`}
+                  />
+                </TableCell>
+                <TableCell className="font-mono font-medium">
+                  {apiKey.name}
+                </TableCell>
+                <TableCell className="font-mono text-muted-foreground">
+                  {apiKey.prefix}
+                  ••••
+                </TableCell>
+                <TableCell
+                  className="tabular-nums text-muted-foreground"
+                  title={new Date(apiKey.createdAt).toLocaleString()}
                 >
-                  <TableCell className="font-mono font-medium">
-                    {apiKey.name}
-                  </TableCell>
-                  <TableCell className="font-mono text-muted-foreground">
-                    {apiKey.prefix}…
-                  </TableCell>
-                  <TableCell
-                    className="tabular-nums text-muted-foreground"
-                    title={new Date(apiKey.createdAt).toLocaleString()}
-                  >
-                    {since(apiKey.createdAt)}前
-                  </TableCell>
-                  <TableCell
-                    className="tabular-nums text-muted-foreground"
-                    title={
-                      apiKey.lastUsedAt
-                        ? new Date(apiKey.lastUsedAt).toLocaleString()
-                        : undefined
-                    }
-                  >
-                    {apiKey.lastUsedAt
-                      ? `${since(apiKey.lastUsedAt)}前`
-                      : '从未'}
-                  </TableCell>
-                  <TableCell>
-                    {revoked ? (
-                      <Badge variant="secondary">已吊销</Badge>
-                    ) : (
-                      <Badge variant="outline">活跃</Badge>
-                    )}
-                  </TableCell>
-                  <TableCell className="text-right">
-                    {!revoked && <ApiKeyRowMenu apiKey={apiKey} />}
-                  </TableCell>
-                </TableRow>
-              );
-            })}
-          </TableBody>
-        </DataTable>
-      )}
+                  {since(apiKey.createdAt)}前
+                </TableCell>
+                <TableCell
+                  className="tabular-nums text-muted-foreground"
+                  title={
+                    apiKey.lastUsedAt
+                      ? new Date(apiKey.lastUsedAt).toLocaleString()
+                      : undefined
+                  }
+                >
+                  {apiKey.lastUsedAt ? `${since(apiKey.lastUsedAt)}前` : '从未'}
+                </TableCell>
+                <TableCell
+                  className={`tabular-nums ${
+                    expiresSoon
+                      ? 'text-amber-600 dark:text-amber-400'
+                      : 'text-muted-foreground'
+                  }`}
+                  title={
+                    apiKey.expiresAt
+                      ? new Date(apiKey.expiresAt).toLocaleString()
+                      : undefined
+                  }
+                >
+                  {apiKey.expiresAt === null
+                    ? '永不过期'
+                    : status === 'expired' || status === 'revoked'
+                      ? new Date(apiKey.expiresAt).toLocaleDateString()
+                      : `${until(apiKey.expiresAt)}后`}
+                </TableCell>
+                <TableCell>
+                  {!revoked && (
+                    <Switch
+                      checked={apiKey.disabledAt === null}
+                      disabled={update.isPending}
+                      aria-label={`${apiKey.name} 启用开关`}
+                      onCheckedChange={(enabled) =>
+                        update.mutate(
+                          { id: apiKey.id, disabled: !enabled },
+                          {
+                            onSuccess: () =>
+                              toast.success(
+                                enabled
+                                  ? `已启用「${apiKey.name}」`
+                                  : `已停用「${apiKey.name}」— 可随时重新启用`,
+                              ),
+                            onError: (error) => toast.error(error.message),
+                          },
+                        )
+                      }
+                    />
+                  )}
+                </TableCell>
+                <TableCell>
+                  <Badge variant={badge.variant} className={badge.className}>
+                    {badge.label}
+                  </Badge>
+                </TableCell>
+                <TableCell className="text-right">
+                  {!revoked && <ApiKeyRowMenu apiKey={apiKey} />}
+                </TableCell>
+              </TableRow>
+            );
+          })}
+        </TableBody>
+      </DataTable>
+
+      <TablePager
+        page={safePage}
+        pageCount={pageCount}
+        total={keys.length}
+        onPageChange={setPage}
+      />
     </div>
   );
 }
diff --git a/packages/console/src/features/sandboxes/format.ts b/packages/console/src/features/sandboxes/format.ts
index 0776666..2c137b5 100644
--- a/packages/console/src/features/sandboxes/format.ts
+++ b/packages/console/src/features/sandboxes/format.ts
@@ -78,6 +78,11 @@ export function since(iso: string): string {
   return formatDuration((Date.now() - Date.parse(iso)) / 1000);
 }
 
+/** 距离某时刻还有多久:"6天3小时"(调用方自己加"后");已过去则为"0秒"。 */
+export function until(iso: string): string {
+  return formatDuration((Date.parse(iso) - Date.now()) / 1000);
+}
+
 /**
  * 沙箱的下一步降温:与 daemon 扫描器同一套语义 — 空闲时长从
  * lastActiveAt 起算,按当前状态取对应旋钮,一次只降一档。旋钮为 null
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 1b1f6d4..9ae554f 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -202,13 +202,25 @@ export const listApiKeys = () => rpc<{ apiKeys: ApiKey[] }>('/listApiKeys');
 
 // The response's `token` is the key material's ONE appearance — the daemon
 // stores only its hash. Show it, offer copy, never ask for it back.
-export const createApiKey = (name: string) =>
-  rpc<CreateApiKeyResponse>('/createApiKey', { name });
+// expiresAt omitted = never expires.
+export const createApiKey = (name: string, expiresAt?: string) =>
+  rpc<CreateApiKeyResponse>('/createApiKey', {
+    name,
+    ...(expiresAt !== undefined ? { expiresAt } : {}),
+  });
+
+// Patch semantics: an absent field is untouched, expiresAt null clears to
+// never, disabled parks/resumes reversibly. Addressed by id — names are
+// renameable, the id is the stable handle.
+export const updateApiKey = (
+  id: string,
+  patch: { name?: string; expiresAt?: string | null; disabled?: boolean },
+) => rpc<{ apiKey: ApiKey }>('/updateApiKey', { id, ...patch });
 
 // Soft revoke: the row stays listed as rotation history; the credential
-// stops working on its next request. False = no active key had that name.
-export const revokeApiKey = (name: string) =>
-  rpc<{ revoked: boolean }>('/revokeApiKey', { name });
+// stops working on its next request. False = no non-revoked key had that id.
+export const revokeApiKey = (id: string) =>
+  rpc<{ revoked: boolean }>('/revokeApiKey', { id });
 
 // An upsert: re-registering a name points it at a new image — that IS the
 // template upgrade front door (then rebuild the sandboxes that should move).
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 8aeebd1..36e4d16 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -373,22 +373,62 @@ describe('API keys over real HTTP', () => {
     const mine = listed.find((k) => k.name === 'sdk-rotation');
     expect(mine?.lastUsedAt).not.toBeNull();
 
-    expect(await client.revokeApiKey('sdk-rotation')).toEqual({
+    expect(await client.revokeApiKey(apiKey.id)).toEqual({
       revoked: true,
     });
     await expect(keyed.listSandboxes()).rejects.toMatchObject({ status: 401 });
-    expect(await client.revokeApiKey('sdk-rotation')).toEqual({
+    expect(await client.revokeApiKey(apiKey.id)).toEqual({
       revoked: false,
     });
   });
 
   it("surfaces the server's 409 for a duplicate active name", async () => {
-    await client.createApiKey('sdk-dup');
+    const { apiKey } = await client.createApiKey('sdk-dup');
     await expect(client.createApiKey('sdk-dup')).rejects.toMatchObject({
       status: 409,
       message: expect.stringMatching(/sdk-dup/),
     });
-    await client.revokeApiKey('sdk-dup');
+    await client.revokeApiKey(apiKey.id);
+  });
+
+  it('updateApiKey renames, parks and expires a key in place', async () => {
+    const future = new Date(Date.now() + 3600_000).toISOString();
+    const { apiKey, token } = await client.createApiKey('sdk-edit', {
+      expiresAt: future,
+    });
+    expect(apiKey.expiresAt).toBe(future);
+
+    const keyed = new Dormice({ endpoint, token });
+    await keyed.listSandboxes();
+
+    // Park it: the credential dies on the next request, reversibly.
+    const parked = await client.updateApiKey(apiKey.id, { disabled: true });
+    expect(parked.apiKey.disabledAt).not.toBeNull();
+    await expect(keyed.listSandboxes()).rejects.toMatchObject({ status: 401 });
+
+    const resumed = await client.updateApiKey(apiKey.id, {
+      disabled: false,
+      name: 'sdk-edit-2',
+      expiresAt: null,
+    });
+    expect(resumed.apiKey).toMatchObject({
+      name: 'sdk-edit-2',
+      disabledAt: null,
+      expiresAt: null,
+    });
+    await keyed.listSandboxes();
+
+    await client.revokeApiKey(apiKey.id);
+  });
+
+  it('a ledger key gets the honest 403 on the management verbs', async () => {
+    const { apiKey, token } = await client.createApiKey('sdk-not-admin');
+    const keyed = new Dormice({ endpoint, token });
+    await expect(keyed.listApiKeys()).rejects.toMatchObject({
+      status: 403,
+      message: expect.stringMatching(/cannot manage API keys/),
+    });
+    await client.revokeApiKey(apiKey.id);
   });
 });
 
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index e90a133..be3b9e9 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -52,8 +52,10 @@ import {
   type SetIngressResponse,
   setIngressResponseSchema,
   type Template,
+  type UpdateApiKeyResponse,
   type UpdateMetadataResponse,
   type UpdatePolicyResponse,
+  updateApiKeyResponseSchema,
   updateMetadataResponseSchema,
   updatePolicyResponseSchema,
   type WriteFileResponse,
@@ -438,10 +440,23 @@ export class Dormice {
    * be revoked without touching the server. The returned `token` (64 hex
    * chars) is shown here EXACTLY ONCE: the daemon stores only its hash, so
    * no later call can retrieve it. Refused with a 409 while an active key
-   * already answers to this name.
+   * already answers to this name. Optional `expiresAt` (ISO) mints a TTL
+   * key; omitted means never expires.
+   *
+   * The apiKey management verbs are admin-only: this client must be
+   * authenticated with DORMICE_API_TOKEN itself — a ledger key gets an
+   * honest 403 (keys cannot manage keys).
    */
-  async createApiKey(name: string): Promise<CreateApiKeyResponse> {
-    const data = await this.rpc('createApiKey', { name });
+  async createApiKey(
+    name: string,
+    options?: { expiresAt?: string },
+  ): Promise<CreateApiKeyResponse> {
+    const data = await this.rpc('createApiKey', {
+      name,
+      ...(options?.expiresAt !== undefined
+        ? { expiresAt: options.expiresAt }
+        : {}),
+    });
     return createApiKeyResponseSchema.parse(data);
   }
 
@@ -452,12 +467,28 @@ export class Dormice {
   }
 
   /**
-   * Revokes the active key under a name — the credential stops working on
-   * the very next request; the row stays listed as rotation history.
-   * Idempotent: an unknown or already-revoked name answers `revoked: false`.
+   * Edits a live key in place, addressed by id (names are renameable — the
+   * id is the stable handle). An absent field is untouched; `expiresAt:
+   * null` clears to never-expires; `disabled` parks or resumes the key
+   * reversibly (unlike revoke). 404 on an unknown id, 409 on a revoked row
+   * or a name collision with a live key.
+   */
+  async updateApiKey(
+    id: string,
+    patch: { name?: string; expiresAt?: string | null; disabled?: boolean },
+  ): Promise<UpdateApiKeyResponse> {
+    const data = await this.rpc('updateApiKey', { id, ...patch });
+    return updateApiKeyResponseSchema.parse(data);
+  }
+
+  /**
+   * Revokes the key with this id — the credential stops working on the
+   * very next request; the row stays listed as rotation history and the
+   * name is freed. Idempotent: an unknown or already-revoked id answers
+   * `revoked: false`.
    */
-  async revokeApiKey(name: string): Promise<RevokeApiKeyResponse> {
-    const data = await this.rpc('revokeApiKey', { name });
+  async revokeApiKey(id: string): Promise<RevokeApiKeyResponse> {
+    const data = await this.rpc('revokeApiKey', { id });
     return revokeApiKeyResponseSchema.parse(data);
   }
 
diff --git a/packages/server/drizzle/0012_apikey-expiry-disable.sql b/packages/server/drizzle/0012_apikey-expiry-disable.sql
new file mode 100644
index 0000000..23fcd12
--- /dev/null
+++ b/packages/server/drizzle/0012_apikey-expiry-disable.sql
@@ -0,0 +1,2 @@
+ALTER TABLE `api_keys` ADD `expires_at` text;--> statement-breakpoint
+ALTER TABLE `api_keys` ADD `disabled_at` text;
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/0012_snapshot.json b/packages/server/drizzle/meta/0012_snapshot.json
new file mode 100644
index 0000000..c73e8ba
--- /dev/null
+++ b/packages/server/drizzle/meta/0012_snapshot.json
@@ -0,0 +1,552 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "aa76853b-453d-43c0-945f-8afd07a827a4",
+  "prevId": "3de8f547-6677-4f7b-a4fb-03d8e45c2c88",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_name": {
+          "name": "sandbox_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "api_keys": {
+      "name": "api_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "prefix": {
+          "name": "prefix",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "disabled_at": {
+          "name": "disabled_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "api_keys_key_hash_unique": {
+          "name": "api_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        },
+        "api_keys_active_name_idx": {
+          "name": "api_keys_active_name_idx",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true,
+          "where": "\"api_keys\".\"revoked_at\" IS NULL"
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "daemon_secrets": {
+      "name": "daemon_secrets",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "envd_signing_secret": {
+          "name": "envd_signing_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "fleet_snapshots": {
+      "name": "fleet_snapshots",
+      "columns": {
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active": {
+          "name": "active",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "frozen": {
+          "name": "frozen",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stopped": {
+          "name": "stopped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archived": {
+          "name": "archived",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "restoring": {
+          "name": "restoring",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "total": {
+          "name": "total",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandbox_metrics_samples": {
+      "name": "sandbox_metrics_samples",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_count": {
+          "name": "cpu_count",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_used_pct": {
+          "name": "cpu_used_pct",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_used_bytes": {
+          "name": "mem_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_total_bytes": {
+          "name": "mem_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_cache_bytes": {
+          "name": "mem_cache_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_used_bytes": {
+          "name": "disk_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_total_bytes": {
+          "name": "disk_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "sandbox_metrics_samples_sandbox_at_idx": {
+          "name": "sandbox_metrics_samples_sandbox_at_idx",
+          "columns": [
+            "sandbox_id",
+            "at"
+          ],
+          "isUnique": false
+        },
+        "sandbox_metrics_samples_at_idx": {
+          "name": "sandbox_metrics_samples_at_idx",
+          "columns": [
+            "at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_name_unique": {
+          "name": "sandboxes_name_unique",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index af19379..c576e8d 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -85,6 +85,13 @@
       "when": 1784149139146,
       "tag": "0011_sandbox-name-id",
       "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "6",
+      "when": 1784190171073,
+      "tag": "0012_apikey-expiry-disable",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index 620a7e7..9b12c8e 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -12,6 +12,7 @@ import { buildApp } from './app';
 import { Archiver } from './archive/archiver';
 import { MemStore } from './archive/mem-store';
 import { objectKey } from './archive/store';
+import { CONSOLE_HEADER, SESSION_COOKIE } from './auth';
 import { loadConfig } from './config';
 import { migrateDb, openDb } from './db/db';
 import { transition } from './db/ledger';
@@ -1562,6 +1563,37 @@ describe('POST /getHostMetrics', () => {
 });
 
 describe('API keys', () => {
+  /** Mint through the wire and hand back everything a test needs. */
+  async function mint(
+    app: ReturnType<typeof testApp>['app'],
+    name: string,
+    expiresAt?: string,
+  ) {
+    const res = await rpc(app, '/createApiKey', {
+      name,
+      ...(expiresAt ? { expiresAt } : {}),
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    return {
+      id: body.apiKey.id as string,
+      token: body.token as string,
+      apiKey: body.apiKey,
+    };
+  }
+
+  const useKey = (
+    app: ReturnType<typeof testApp>['app'],
+    token: string,
+    url = '/listSandboxes',
+  ) =>
+    app.inject({
+      method: 'POST',
+      url,
+      headers: { authorization: `Bearer ${token}` },
+      payload: {},
+    });
+
   it('mints a 64-hex token, shown once and never stored in the view', async () => {
     const { app } = testApp();
     const res = await rpc(app, '/createApiKey', { name: 'ci' });
@@ -1572,6 +1604,8 @@ describe('API keys', () => {
       name: 'ci',
       prefix: body.token.slice(0, 8),
       lastUsedAt: null,
+      expiresAt: null,
+      disabledAt: null,
       revokedAt: null,
     });
     // The view carries no secret — not the token, not its hash.
@@ -1581,27 +1615,14 @@ describe('API keys', () => {
 
   it('a minted key opens the Bearer door; revoking closes it on the next request', async () => {
     const { app } = testApp();
-    const { token } = (await rpc(app, '/createApiKey', { name: 'ci' })).json();
-    const asKey = { authorization: `Bearer ${token}` };
+    const { id, token } = await mint(app, 'ci');
 
-    const before = await app.inject({
-      method: 'POST',
-      url: '/listSandboxes',
-      headers: asKey,
-      payload: {},
-    });
-    expect(before.statusCode).toBe(200);
+    expect((await useKey(app, token)).statusCode).toBe(200);
 
-    expect((await rpc(app, '/revokeApiKey', { name: 'ci' })).json()).toEqual({
+    expect((await rpc(app, '/revokeApiKey', { id })).json()).toEqual({
       revoked: true,
     });
-    const afterRevoke = await app.inject({
-      method: 'POST',
-      url: '/listSandboxes',
-      headers: asKey,
-      payload: {},
-    });
-    expect(afterRevoke.statusCode).toBe(401);
+    expect((await useKey(app, token)).statusCode).toBe(401);
 
     // The env token is the bootstrap credential: revocation never touches it.
     expect((await rpc(app, '/listSandboxes')).statusCode).toBe(200);
@@ -1609,34 +1630,34 @@ describe('API keys', () => {
 
   it('refuses a second active key under the same name with a 409, and frees the name after revoke', async () => {
     const { app } = testApp();
-    await rpc(app, '/createApiKey', { name: 'ci' });
+    const { id } = await mint(app, 'ci');
     const dup = await rpc(app, '/createApiKey', { name: 'ci' });
     expect(dup.statusCode).toBe(409);
     expect(dup.json().message).toMatch(/'ci' already exists/);
 
-    await rpc(app, '/revokeApiKey', { name: 'ci' });
+    await rpc(app, '/revokeApiKey', { id });
     expect((await rpc(app, '/createApiKey', { name: 'ci' })).statusCode).toBe(
       200,
     );
   });
 
-  it('revoke is idempotent: an unknown or already-revoked name answers { revoked: false }', async () => {
+  it('revoke is idempotent: an unknown or already-revoked id answers { revoked: false }', async () => {
     const { app } = testApp();
-    expect((await rpc(app, '/revokeApiKey', { name: 'ghost' })).json()).toEqual(
-      { revoked: false },
-    );
-    await rpc(app, '/createApiKey', { name: 'ci' });
-    await rpc(app, '/revokeApiKey', { name: 'ci' });
-    expect((await rpc(app, '/revokeApiKey', { name: 'ci' })).json()).toEqual({
+    expect((await rpc(app, '/revokeApiKey', { id: 'ghost' })).json()).toEqual({
+      revoked: false,
+    });
+    const { id } = await mint(app, 'ci');
+    await rpc(app, '/revokeApiKey', { id });
+    expect((await rpc(app, '/revokeApiKey', { id })).json()).toEqual({
       revoked: false,
     });
   });
 
   it('lists every key ever minted, revoked rows included, newest first', async () => {
     const { app } = testApp();
-    await rpc(app, '/createApiKey', { name: 'old' });
-    await rpc(app, '/revokeApiKey', { name: 'old' });
-    await rpc(app, '/createApiKey', { name: 'new' });
+    const { id } = await mint(app, 'old');
+    await rpc(app, '/revokeApiKey', { id });
+    await mint(app, 'new');
 
     const keys = (await rpc(app, '/listApiKeys')).json().apiKeys;
     expect(keys).toHaveLength(2);
@@ -1648,30 +1669,22 @@ describe('API keys', () => {
 
   it('stamps lastUsedAt on first use and throttles the write to 60s granularity', async () => {
     const { app } = testApp();
-    const { token } = (await rpc(app, '/createApiKey', { name: 'ci' })).json();
-    const asKey = { authorization: `Bearer ${token}` };
-    const use = () =>
-      app.inject({
-        method: 'POST',
-        url: '/listSandboxes',
-        headers: asKey,
-        payload: {},
-      });
+    const { token } = await mint(app, 'ci');
 
-    await use();
+    await useKey(app, token);
     const first = (await rpc(app, '/listApiKeys')).json().apiKeys[0];
     expect(first.lastUsedAt).not.toBeNull();
 
     // A second use inside the 60s window must not move the stamp.
-    await use();
+    await useKey(app, token);
     const second = (await rpc(app, '/listApiKeys')).json().apiKeys[0];
     expect(second.lastUsedAt).toBe(first.lastUsedAt);
   });
 
   it('records mint and revoke in the activity ring, token nowhere in sight', async () => {
     const { app } = testApp();
-    const { token } = (await rpc(app, '/createApiKey', { name: 'ci' })).json();
-    await rpc(app, '/revokeApiKey', { name: 'ci' });
+    const { id, token } = await mint(app, 'ci');
+    await rpc(app, '/revokeApiKey', { id });
 
     const events = (await rpc(app, '/listActivity')).json().events;
     const kinds = events.map((e: { kind: string }) => e.kind);
@@ -1679,4 +1692,180 @@ describe('API keys', () => {
     expect(kinds).toContain('apikey-revoked');
     expect(JSON.stringify(events)).not.toContain(token);
   });
+
+  it('disable parks the key reversibly: 401 while disabled, 200 again after enable', async () => {
+    const { app } = testApp();
+    const { id, token } = await mint(app, 'ci');
+    expect((await useKey(app, token)).statusCode).toBe(200);
+
+    const disabled = (
+      await rpc(app, '/updateApiKey', { id, disabled: true })
+    ).json().apiKey;
+    expect(disabled.disabledAt).not.toBeNull();
+    expect((await useKey(app, token)).statusCode).toBe(401);
+
+    // Disabling twice is idempotent: the original stamp stays, no new event.
+    const again = (
+      await rpc(app, '/updateApiKey', { id, disabled: true })
+    ).json().apiKey;
+    expect(again.disabledAt).toBe(disabled.disabledAt);
+
+    const enabled = (
+      await rpc(app, '/updateApiKey', { id, disabled: false })
+    ).json().apiKey;
+    expect(enabled.disabledAt).toBeNull();
+    expect((await useKey(app, token)).statusCode).toBe(200);
+
+    const kinds = (await rpc(app, '/listActivity'))
+      .json()
+      .events.map((e: { kind: string }) => e.kind);
+    expect(kinds.filter((k: string) => k === 'apikey-disabled')).toHaveLength(
+      1,
+    );
+    expect(kinds.filter((k: string) => k === 'apikey-enabled')).toHaveLength(1);
+  });
+
+  it('expiry closes the door: a past expiresAt is 401, clearing it reopens', async () => {
+    const { app } = testApp();
+    const past = new Date(Date.now() - 1000).toISOString();
+    const { id, token } = await mint(app, 'ttl', past);
+    expect((await useKey(app, token)).statusCode).toBe(401);
+
+    const cleared = (
+      await rpc(app, '/updateApiKey', { id, expiresAt: null })
+    ).json().apiKey;
+    expect(cleared.expiresAt).toBeNull();
+    expect((await useKey(app, token)).statusCode).toBe(200);
+
+    const future = new Date(Date.now() + 3600_000).toISOString();
+    await rpc(app, '/updateApiKey', { id, expiresAt: future });
+    expect((await useKey(app, token)).statusCode).toBe(200);
+  });
+
+  it('normalizes expiresAt on write: wire precision variants land as toISOString()', async () => {
+    const { app } = testApp();
+    // No-millis wire form would sort AFTER a with-millis "now" while being
+    // chronologically earlier — the ledger must store the canonical shape.
+    const { apiKey } = await mint(app, 'ttl', '2030-01-01T00:00:00Z');
+    expect(apiKey.expiresAt).toBe('2030-01-01T00:00:00.000Z');
+  });
+
+  it('updateApiKey renames, refuses collisions honestly, and leaves history alone', async () => {
+    const { app } = testApp();
+    const { id } = await mint(app, 'ci');
+    const other = await mint(app, 'laptop');
+
+    const renamed = (
+      await rpc(app, '/updateApiKey', { id, name: 'ci-2026' })
+    ).json().apiKey;
+    expect(renamed.name).toBe('ci-2026');
+
+    // Onto a live name: refused like create.
+    const clash = await rpc(app, '/updateApiKey', { id, name: 'laptop' });
+    expect(clash.statusCode).toBe(409);
+
+    // Onto a revoked name: revoke freed it.
+    await rpc(app, '/revokeApiKey', { id: other.id });
+    expect(
+      (await rpc(app, '/updateApiKey', { id, name: 'laptop' })).statusCode,
+    ).toBe(200);
+
+    // Unknown id is a 404; a revoked row is history, not editable.
+    expect(
+      (await rpc(app, '/updateApiKey', { id: 'ghost', name: 'x' })).statusCode,
+    ).toBe(404);
+    const edited = await rpc(app, '/updateApiKey', {
+      id: other.id,
+      name: 'zombie',
+    });
+    expect(edited.statusCode).toBe(409);
+    expect(edited.json().message).toMatch(/rotation history/);
+  });
+
+  it('a no-op patch changes nothing and records nothing', async () => {
+    const { app } = testApp();
+    const { id } = await mint(app, 'ci');
+    const before = (await rpc(app, '/listActivity')).json().events.length;
+
+    const res = await rpc(app, '/updateApiKey', {
+      id,
+      name: 'ci',
+      disabled: false,
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().apiKey.name).toBe('ci');
+
+    const after = (await rpc(app, '/listActivity')).json().events.length;
+    expect(after).toBe(before);
+  });
+
+  it('carries expiresAt from mint into the list', async () => {
+    const { app } = testApp();
+    const future = new Date(Date.now() + 86_400_000).toISOString();
+    await mint(app, 'ttl', future);
+    const keys = (await rpc(app, '/listApiKeys')).json().apiKeys;
+    expect(keys[0].expiresAt).toBe(future);
+  });
+
+  it('admin-only: a live key gets an honest 403 on every management verb, without a lastUsedAt fingerprint', async () => {
+    const { app } = testApp();
+    const { id, token } = await mint(app, 'ci');
+    const asKey = { authorization: `Bearer ${token}` };
+
+    const attempts = [
+      ['/createApiKey', { name: 'evil' }],
+      ['/listApiKeys', {}],
+      ['/updateApiKey', { id, disabled: true }],
+      ['/revokeApiKey', { id }],
+    ] as const;
+    for (const [url, payload] of attempts) {
+      const res = await app.inject({
+        method: 'POST',
+        url,
+        headers: asKey,
+        payload,
+      });
+      expect(res.statusCode).toBe(403);
+      expect(res.json().message).toMatch(/cannot manage API keys/);
+    }
+
+    // The refusals honored nothing: no lastUsedAt fingerprint, key untouched.
+    const row = (await rpc(app, '/listApiKeys')).json().apiKeys[0];
+    expect(row.lastUsedAt).toBeNull();
+    expect(row.disabledAt).toBeNull();
+    expect(row.revokedAt).toBeNull();
+
+    // Garbage stays garbage: 401, not 403.
+    expect(
+      (
+        await app.inject({
+          method: 'POST',
+          url: '/createApiKey',
+          headers: { authorization: 'Bearer not-a-key' },
+          payload: { name: 'x' },
+        })
+      ).statusCode,
+    ).toBe(401);
+  });
+
+  it('admin-only: a console session opens the management verbs', async () => {
+    const { app } = testApp();
+    const setup = await app.inject({
+      method: 'POST',
+      url: '/console/auth/setup',
+      payload: { token: TOKEN, username: 'operator', password: 'horse pass' },
+    });
+    expect(setup.statusCode).toBe(200);
+    const cookie = setup.cookies.find((c) => c.name === SESSION_COOKIE);
+    expect(cookie).toBeDefined();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/createApiKey',
+      headers: { [CONSOLE_HEADER]: '1' },
+      cookies: { [SESSION_COOKIE]: (cookie as { value: string }).value },
+      payload: { name: 'from-console' },
+    });
+    expect(res.statusCode).toBe(200);
+  });
 });
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index f552c06..20164fe 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -10,10 +10,10 @@ import {
 import { type Logger, pino } from 'pino';
 import { z } from 'zod';
 import type { Archiver } from './archive/archiver';
-import { requireApiAuth, tokensEqual } from './auth';
+import { requireAdminAuth, requireApiAuth, tokensEqual } from './auth';
 import { type Config, type ConfigSources, configSources } from './config';
 import { getConsoleAccount } from './db/account';
-import { verifyApiKeyToken } from './db/api-keys';
+import { isLiveApiKey, verifyApiKeyToken } from './db/api-keys';
 import type { Db } from './db/db';
 import { getOrCreateSigningSecret } from './db/secrets';
 import { registerE2bCompat } from './e2b';
@@ -205,6 +205,16 @@ export function buildApp({
     () => getConsoleAccount(db)?.sessionSecret ?? null,
   );
 
+  // The apiKey verbs are admin-only: a credential must not be able to
+  // manage the credential ledger it lives in (key-manages-key is a
+  // self-replication ladder for a leaked key). Env token or console
+  // session only; a live ledger key gets an honest 403, not a silent 401.
+  const adminAuth = requireAdminAuth(
+    (bare) => tokensEqual(bare, config.DORMICE_API_TOKEN),
+    (bare) => isLiveApiKey(db, bare),
+    () => getConsoleAccount(db)?.sessionSecret ?? null,
+  );
+
   // The envd/signed-URL derivation base. Captured once — unlike the session
   // secret there is no verb that rotates it (see db/secrets.ts) — and NOT
   // the API token: the two credentials must rotate independently.
@@ -221,7 +231,6 @@ export function buildApp({
       archiveDefaultSeconds,
     });
     await api.register(templateRoutes, { db });
-    await api.register(apiKeyRoutes, { db });
     await api.register(hostRoutes, { config, db, executor });
     await api.register(activityRoutes, { db });
     await api.register(ingressRoutes, { db, ingress });
@@ -233,6 +242,14 @@ export function buildApp({
     await api.register(upgradeRoutes, { updater, db });
   });
 
+  // The apiKey management verbs sit behind the stricter admin gate — their
+  // own scope, because a Fastify hook guards a whole scope and these four
+  // verbs are the only ones with a different answer to "who may call".
+  app.register(async (admin) => {
+    admin.addHook('onRequest', adminAuth);
+    await admin.register(apiKeyRoutes, { db });
+  });
+
   // The web console: account + session endpoints (open — setup and login
   // carry the credentials themselves) and the static SPA. Its API calls go
   // through the routes above.
diff --git a/packages/server/src/auth.ts b/packages/server/src/auth.ts
index fc625b6..ac24355 100644
--- a/packages/server/src/auth.ts
+++ b/packages/server/src/auth.ts
@@ -6,7 +6,7 @@ import {
   scrypt,
   timingSafeEqual,
 } from 'node:crypto';
-import type { onRequestAsyncHookHandler } from 'fastify';
+import type { FastifyRequest, onRequestAsyncHookHandler } from 'fastify';
 
 // Hand-rolled instead of util.promisify: promisify picks the overload
 // without the options argument, and the cost parameters live there.
@@ -133,10 +133,33 @@ export function verifySession(
   return tokensEqual(value.slice(dot + 1), sessionHmac(secret, expiresAt));
 }
 
+/**
+ * The console-session leg shared verbatim by both auth hooks: cookie
+ * present, an account exists (secret non-null), the CSRF header rode along
+ * (see CONSOLE_HEADER), and the HMAC verifies. The session secret is
+ * fetched per request, not captured at startup: setup can replace the
+ * account (and its secret) while the daemon runs, and the arbiter must
+ * judge against the current one. Null means no account exists yet — no
+ * cookie can be valid.
+ */
+function sessionCookieValid(
+  request: FastifyRequest,
+  getSessionSecret: () => string | null,
+): boolean {
+  const cookie = request.cookies?.[SESSION_COOKIE];
+  const secret = getSessionSecret();
+  return Boolean(
+    cookie &&
+      secret !== null &&
+      request.headers[CONSOLE_HEADER] !== undefined &&
+      verifySession(secret, cookie),
+  );
+}
+
 /**
  * The single arbiter of who may call the API (/healthz stays open —
  * liveness probes have no secrets). Two credentials open the same door:
- * a Bearer credential (SDK, CLI, curl — the env token or any active API
+ * a Bearer credential (SDK, CLI, curl — the env token or any live API
  * key, adjudicated by verifyCredential) and the web console's session
  * cookie (which additionally requires the console header, see above). A
  * second route surface with its own auth would be a second truth.
@@ -146,11 +169,6 @@ export function verifySession(
  * closure, one truth, two dialects. The 'Bearer ' prefix is public
  * framing, not a secret, so stripping it needs no constant time; the
  * secret comparisons live inside verifyCredential.
- *
- * The session secret is fetched per request, not captured at startup: setup
- * can replace the account (and its secret) while the daemon runs, and the
- * arbiter must judge against the current one. Null means no account exists
- * yet — no cookie can be valid.
  */
 export function requireApiAuth(
   verifyCredential: (bareToken: string) => boolean,
@@ -162,14 +180,49 @@ export function requireApiAuth(
     if (bare !== null && verifyCredential(bare)) {
       return;
     }
-    const cookie = request.cookies?.[SESSION_COOKIE];
-    const secret = getSessionSecret();
-    if (
-      cookie &&
-      secret !== null &&
-      request.headers[CONSOLE_HEADER] !== undefined &&
-      verifySession(secret, cookie)
-    ) {
+    if (sessionCookieValid(request, getSessionSecret)) {
+      return;
+    }
+    await reply.code(401).send({ message: 'missing or invalid API token' });
+  };
+}
+
+/**
+ * The admin gate for the apiKey management verbs: only the env token
+ * (Bearer) or a console session may pass. A key that is otherwise valid
+ * gets an honest 403 instead of a silent 401 — key-manages-key would let
+ * one leaked credential mint itself an unrevoked successor and revoke
+ * every legitimate peer, so the refusal names the rule. The console-setup
+ * door (routes/console.ts) rests on the same doctrine: a machine
+ * credential must not escalate into managing credentials.
+ *
+ * Leg order matters twice. The isLiveApiKey lookup runs only after both
+ * accepting legs failed, so a console session with a stray key header
+ * still passes, and the ledger is consulted only for requests already
+ * being refused. And isLiveApiKey must be a pure read that never stamps
+ * lastUsedAt — the request is being refused, not honored. A disabled or
+ * expired key is no longer a valid credential and falls through to the
+ * same 401 as garbage: a 403 for it would leak that the row exists.
+ */
+export function requireAdminAuth(
+  isEnvToken: (bareToken: string) => boolean,
+  isLiveApiKey: (bareToken: string) => boolean,
+  getSessionSecret: () => string | null,
+): onRequestAsyncHookHandler {
+  return async (request, reply) => {
+    const header = request.headers.authorization;
+    const bare = header?.startsWith('Bearer ') ? header.slice(7) : null;
+    if (bare !== null && isEnvToken(bare)) {
+      return;
+    }
+    if (sessionCookieValid(request, getSessionSecret)) {
+      return;
+    }
+    if (bare !== null && isLiveApiKey(bare)) {
+      await reply.code(403).send({
+        message:
+          'API keys cannot manage API keys — use DORMICE_API_TOKEN or the console',
+      });
       return;
     }
     await reply.code(401).send({ message: 'missing or invalid API token' });
diff --git a/packages/server/src/db/api-keys.ts b/packages/server/src/db/api-keys.ts
index ac781d4..6c514b0 100644
--- a/packages/server/src/db/api-keys.ts
+++ b/packages/server/src/db/api-keys.ts
@@ -1,5 +1,5 @@
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
-import { and, desc, eq, isNull, lt, or, sql } from 'drizzle-orm';
+import { and, desc, eq, gt, isNull, lt, or, sql } from 'drizzle-orm';
 import { recordActivity } from './activity';
 import type { Db } from './db';
 import { type ApiKeyRow, apiKeys } from './schema';
@@ -17,6 +17,18 @@ export function hashApiKeyToken(token: string): string {
   return createHash('sha256').update(token).digest('hex');
 }
 
+/**
+ * The one write-side shape for timestamps that later feed string
+ * comparisons. Wire ISO input has variable precision ("…00Z" sorts after
+ * "…00.500Z" while being chronologically earlier), so every expiresAt is
+ * normalized to exact toISOString() output before it touches the ledger —
+ * after that, plain string compare is chronologically sound (the same
+ * argument the lastUsedAt throttle rests on).
+ */
+function normalizeIso(value: string): string {
+  return new Date(value).toISOString();
+}
+
 /**
  * Mints a key and returns the material exactly once — the row keeps only
  * the hash, so this return value is the caller's single chance to see it.
@@ -30,6 +42,7 @@ export function hashApiKeyToken(token: string): string {
 export function createApiKey(
   db: Db,
   name: string,
+  expiresAt?: string,
 ): { row: ApiKeyRow; token: string } {
   const token = randomBytes(32).toString('hex');
   const row: ApiKeyRow = {
@@ -39,12 +52,16 @@ export function createApiKey(
     prefix: token.slice(0, 8),
     createdAt: new Date().toISOString(),
     lastUsedAt: null,
+    expiresAt: expiresAt ? normalizeIso(expiresAt) : null,
+    disabledAt: null,
     revokedAt: null,
   };
   db.insert(apiKeys).values(row).run();
   recordActivity(db, {
     kind: 'apikey-created',
-    detail: `API key "${name}" (prefix ${row.prefix}) minted`,
+    detail:
+      `API key "${name}" (prefix ${row.prefix}) minted` +
+      (row.expiresAt ? `, expires ${row.expiresAt}` : ''),
   });
   return { row, token };
 }
@@ -60,6 +77,10 @@ export function findActiveApiKeyByName(
     .get();
 }
 
+export function findApiKeyById(db: Db, id: string): ApiKeyRow | undefined {
+  return db.select().from(apiKeys).where(eq(apiKeys.id, id)).get();
+}
+
 /**
  * Every key ever minted, revoked ones included — the rotation history.
  * createdAt has millisecond granularity, so two keys minted back-to-back
@@ -76,44 +97,138 @@ export function listApiKeys(db: Db): ApiKeyRow[] {
 }
 
 /**
- * Soft-revokes the active key under this name. Returns false when none was
- * active — the desired end state was already true. The row survives as
- * history; the name is immediately free for a new key.
+ * Soft-revokes the key with this id. Returns false when it does not exist
+ * or is already revoked — the desired end state was already true. The row
+ * survives as history; the name is immediately free for a new key.
  */
-export function revokeApiKey(db: Db, name: string): boolean {
-  const result = db
-    .update(apiKeys)
+export function revokeApiKey(db: Db, id: string): boolean {
+  const row = findApiKeyById(db, id);
+  if (!row || row.revokedAt !== null) {
+    return false;
+  }
+  db.update(apiKeys)
     .set({ revokedAt: new Date().toISOString() })
-    .where(and(eq(apiKeys.name, name), isNull(apiKeys.revokedAt)))
+    .where(eq(apiKeys.id, id))
     .run();
-  const revoked = result.changes > 0;
-  if (revoked) {
-    recordActivity(db, {
-      kind: 'apikey-revoked',
-      detail: `API key "${name}" revoked`,
+  recordActivity(db, {
+    kind: 'apikey-revoked',
+    detail: `API key "${row.name}" revoked`,
+  });
+  return true;
+}
+
+/**
+ * Edits a non-revoked key in place. The route has already adjudicated the
+ * 404 (unknown id), the 409s (revoked row, name collision) — this function
+ * only computes the changed-field set against the row it was handed and
+ * writes once. A field equal to its current value is not a change (the
+ * updatePolicy idiom: a no-op patch is the goal state, not an error), so
+ * disabling an already-disabled key keeps its original disabledAt and
+ * records nothing. One request can still yield two activity events — a
+ * disable that also renames is two facts, each separately filterable.
+ */
+export function updateApiKey(
+  db: Db,
+  row: ApiKeyRow,
+  patch: { name?: string; expiresAt?: string | null; disabled?: boolean },
+): ApiKeyRow {
+  const changes: Partial<ApiKeyRow> = {};
+  const facts: {
+    kind: 'apikey-updated' | 'apikey-disabled' | 'apikey-enabled';
+    detail: string;
+  }[] = [];
+  const updated: string[] = [];
+
+  if (patch.name !== undefined && patch.name !== row.name) {
+    changes.name = patch.name;
+    updated.push(`renamed to "${patch.name}"`);
+  }
+  if (patch.expiresAt !== undefined) {
+    const next =
+      patch.expiresAt === null ? null : normalizeIso(patch.expiresAt);
+    if (next !== row.expiresAt) {
+      changes.expiresAt = next;
+      updated.push(`expires ${row.expiresAt ?? 'never'} -> ${next ?? 'never'}`);
+    }
+  }
+  if (updated.length > 0) {
+    facts.push({
+      kind: 'apikey-updated',
+      detail: `API key "${row.name}" ${updated.join(', ')}`,
     });
   }
-  return revoked;
+  if (patch.disabled === true && row.disabledAt === null) {
+    changes.disabledAt = new Date().toISOString();
+    facts.push({
+      kind: 'apikey-disabled',
+      detail: `API key "${row.name}" disabled`,
+    });
+  } else if (patch.disabled === false && row.disabledAt !== null) {
+    changes.disabledAt = null;
+    facts.push({
+      kind: 'apikey-enabled',
+      detail: `API key "${row.name}" enabled`,
+    });
+  }
+
+  if (Object.keys(changes).length === 0) {
+    return row;
+  }
+  db.update(apiKeys).set(changes).where(eq(apiKeys.id, row.id)).run();
+  for (const fact of facts) {
+    recordActivity(db, fact);
+  }
+  return { ...row, ...changes };
+}
+
+/**
+ * The single liveness adjudication: revoked, disabled and expired all close
+ * the door, in one WHERE. Pure read — it never stamps lastUsedAt — so the
+ * admin gate can consult it for its honest 403 without a refused request
+ * leaving "recently used" fingerprints. The expiry compare is a plain
+ * string > against toISOString(now), sound because expiresAt is normalized
+ * on write (see normalizeIso).
+ */
+export function findLiveApiKeyByHash(
+  db: Db,
+  hash: string,
+): { id: string; lastUsedAt: string | null } | undefined {
+  return db
+    .select({ id: apiKeys.id, lastUsedAt: apiKeys.lastUsedAt })
+    .from(apiKeys)
+    .where(
+      and(
+        eq(apiKeys.keyHash, hash),
+        isNull(apiKeys.revokedAt),
+        isNull(apiKeys.disabledAt),
+        or(
+          isNull(apiKeys.expiresAt),
+          gt(apiKeys.expiresAt, new Date().toISOString()),
+        ),
+      ),
+    )
+    .get();
+}
+
+/** findLiveApiKeyByHash for callers holding the bare token — hashing stays in this module. */
+export function isLiveApiKey(db: Db, bareToken: string): boolean {
+  return findLiveApiKeyByHash(db, hashApiKeyToken(bareToken)) !== undefined;
 }
 
 /**
- * The ledger leg of credential verification: does this bare token match an
- * active key? An indexed exact-match lookup on sha256(token) — not a
+ * The ledger leg of credential verification: does this bare token match a
+ * live key? An indexed exact-match lookup on sha256(token) — not a
  * timing-safe scan, deliberately: the comparison can at worst leak bytes of
  * sha256(key), which preimage resistance makes worthless to an attacker
  * (the argument GitHub token storage rests on).
  *
- * A hit also stamps lastUsedAt, throttled to LAST_USED_GRANULARITY_MS so a
- * polling client does not write the ledger per request. ISO strings compare
- * lexicographically as timestamps, so the cutoff is a plain string <.
+ * A hit also stamps lastUsedAt — only a hit: verification is the one moment
+ * a credential was actually honored. Throttled to LAST_USED_GRANULARITY_MS
+ * so a polling client does not write the ledger per request. ISO strings
+ * compare lexicographically as timestamps, so the cutoff is a plain string <.
  */
 export function verifyApiKeyToken(db: Db, bareToken: string): boolean {
-  const hash = hashApiKeyToken(bareToken);
-  const row = db
-    .select({ id: apiKeys.id, lastUsedAt: apiKeys.lastUsedAt })
-    .from(apiKeys)
-    .where(and(eq(apiKeys.keyHash, hash), isNull(apiKeys.revokedAt)))
-    .get();
+  const row = findLiveApiKeyByHash(db, hashApiKeyToken(bareToken));
   if (!row) {
     return false;
   }
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index ed5eb7e..c7367e7 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -247,6 +247,18 @@ export const apiKeys = sqliteTable(
     createdAt: text('created_at').notNull(),
     /** Null = never used. Written with 60s granularity, not per request. */
     lastUsedAt: text('last_used_at'),
+    /**
+     * Null = never expires. Always written through normalizeIso (exact
+     * toISOString shape) so the liveness filter's string comparison against
+     * "now" is chronologically sound — wire input has variable precision.
+     */
+    expiresAt: text('expires_at'),
+    /**
+     * Null = enabled. The reversible half of revocation: set/cleared by
+     * updateApiKey, and the name stays held while disabled — only revoke
+     * frees a name.
+     */
+    disabledAt: text('disabled_at'),
     /** Null = active. Set once by revokeApiKey; never cleared. */
     revokedAt: text('revoked_at'),
   },
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index f089376..a275d11 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -220,7 +220,7 @@ describe('E2B control plane', () => {
       headers: { authorization: `Bearer ${TOKEN}` },
       payload: { name: 'e2b-client' },
     });
-    const { token } = minted.json();
+    const { token, apiKey } = minted.json();
 
     const prefixed = await t.app.inject({
       method: 'POST',
@@ -234,7 +234,7 @@ describe('E2B control plane', () => {
       method: 'POST',
       url: '/revokeApiKey',
       headers: { authorization: `Bearer ${TOKEN}` },
-      payload: { name: 'e2b-client' },
+      payload: { id: apiKey.id },
     });
     const revoked = await t.app.inject({
       method: 'POST',
@@ -246,6 +246,51 @@ describe('E2B control plane', () => {
     expect(revoked.json()).toEqual({ code: 401, message: 'invalid API key' });
   });
 
+  it('disabled and expired ledger keys are rejected on the X-API-KEY face too', async () => {
+    const t = testApp();
+    const native = { authorization: `Bearer ${TOKEN}` };
+    const useE2b = (token: string) =>
+      t.app.inject({
+        method: 'POST',
+        url: '/e2b/api/sandboxes',
+        headers: { 'x-api-key': `e2b_${token}` },
+        payload: {},
+      });
+
+    const parked = (
+      await t.app.inject({
+        method: 'POST',
+        url: '/createApiKey',
+        headers: native,
+        payload: { name: 'parked' },
+      })
+    ).json();
+    await t.app.inject({
+      method: 'POST',
+      url: '/updateApiKey',
+      headers: native,
+      payload: { id: parked.apiKey.id, disabled: true },
+    });
+    const disabled = await useE2b(parked.token);
+    expect(disabled.statusCode).toBe(401);
+    expect(disabled.json()).toEqual({ code: 401, message: 'invalid API key' });
+
+    const stale = (
+      await t.app.inject({
+        method: 'POST',
+        url: '/createApiKey',
+        headers: native,
+        payload: {
+          name: 'stale',
+          expiresAt: new Date(Date.now() - 1000).toISOString(),
+        },
+      })
+    ).json();
+    const expired = await useE2b(stale.token);
+    expect(expired.statusCode).toBe(401);
+    expect(expired.json()).toEqual({ code: 401, message: 'invalid API key' });
+  });
+
   it('creates a fresh sandbox per call — E2B semantics, no key given', async () => {
     const t = testApp();
     const first = await createSandbox(t);
diff --git a/packages/server/src/routes/api-keys.ts b/packages/server/src/routes/api-keys.ts
index 3ecf9db..f1b7ba3 100644
--- a/packages/server/src/routes/api-keys.ts
+++ b/packages/server/src/routes/api-keys.ts
@@ -5,13 +5,17 @@ import {
   listApiKeysResponseSchema,
   revokeApiKeyRequestSchema,
   revokeApiKeyResponseSchema,
+  updateApiKeyRequestSchema,
+  updateApiKeyResponseSchema,
 } from '@dormice/shared';
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import {
   createApiKey,
   findActiveApiKeyByName,
+  findApiKeyById,
   listApiKeys,
   revokeApiKey,
+  updateApiKey,
 } from '../db/api-keys';
 import type { Db } from '../db/db';
 import type { ApiKeyRow } from '../db/schema';
@@ -29,16 +33,19 @@ function view(row: ApiKeyRow): ApiKey {
     prefix: row.prefix,
     createdAt: row.createdAt,
     lastUsedAt: row.lastUsedAt,
+    expiresAt: row.expiresAt,
+    disabledAt: row.disabledAt,
     revokedAt: row.revokedAt,
   };
 }
 
 /**
- * API key management: mint, list, revoke. Pure ledger verbs — no executor,
- * no locks — sitting behind the same auth they extend: the first key is
- * minted with the env token (or a console session), later ones with any
- * live key. Verification itself lives in db/api-keys.ts and is consulted
- * by buildApp's verifyCredential closure, not here.
+ * API key management: mint, list, edit, revoke. Pure ledger verbs — no
+ * executor, no locks. Admin-only: buildApp registers this plugin behind
+ * requireAdminAuth (env token or console session; a live key gets an
+ * honest 403), because a credential must not manage the credential ledger
+ * it lives in. Verification itself lives in db/api-keys.ts and is
+ * consulted by buildApp's verifyCredential closure, not here.
  */
 export const apiKeyRoutes: FastifyPluginAsyncZod<ApiKeyRoutesOptions> = async (
   app,
@@ -53,7 +60,7 @@ export const apiKeyRoutes: FastifyPluginAsyncZod<ApiKeyRoutesOptions> = async (
       },
     },
     async (request) => {
-      const { name } = request.body;
+      const { name, expiresAt } = request.body;
       // Two live credentials answering to one name is a rotation mistake,
       // not a goal — refused by name, like removeTemplate's 409. The
       // partial unique index backstops this check as a schema fact; no
@@ -64,7 +71,7 @@ export const apiKeyRoutes: FastifyPluginAsyncZod<ApiKeyRoutesOptions> = async (
           `an active API key named '${name}' already exists — revoke it first or pick another name`,
         );
       }
-      const { row, token } = createApiKey(db, name);
+      const { row, token } = createApiKey(db, name, expiresAt);
       return { apiKey: view(row), token };
     },
   );
@@ -79,6 +86,43 @@ export const apiKeyRoutes: FastifyPluginAsyncZod<ApiKeyRoutesOptions> = async (
     async () => ({ apiKeys: listApiKeys(db).map(view) }),
   );
 
+  app.post(
+    '/updateApiKey',
+    {
+      schema: {
+        body: updateApiKeyRequestSchema,
+        response: { 200: updateApiKeyResponseSchema },
+      },
+    },
+    async (request) => {
+      const { id, ...patch } = request.body;
+      // Adjudication happens here, in order, with no await between the
+      // checks and the write (better-sqlite3 is sync — they cannot race).
+      const row = findApiKeyById(db, id);
+      if (!row) {
+        throw httpError(404, `no API key with id '${id}'`);
+      }
+      if (row.revokedAt !== null) {
+        throw httpError(
+          409,
+          `API key "${row.name}" is revoked — revoked rows are rotation history and cannot be changed`,
+        );
+      }
+      if (patch.name !== undefined && patch.name !== row.name) {
+        // Same courtesy as create: the name must not collide with any
+        // non-revoked key. findActiveApiKeyByName cannot return this row
+        // itself — the names differ.
+        if (findActiveApiKeyByName(db, patch.name)) {
+          throw httpError(
+            409,
+            `an active API key named '${patch.name}' already exists — revoke it first or pick another name`,
+          );
+        }
+      }
+      return { apiKey: view(updateApiKey(db, row, patch)) };
+    },
+  );
+
   app.post(
     '/revokeApiKey',
     {
@@ -87,6 +131,6 @@ export const apiKeyRoutes: FastifyPluginAsyncZod<ApiKeyRoutesOptions> = async (
         response: { 200: revokeApiKeyResponseSchema },
       },
     },
-    async (request) => ({ revoked: revokeApiKey(db, request.body.name) }),
+    async (request) => ({ revoked: revokeApiKey(db, request.body.id) }),
   );
 };
diff --git a/packages/shared/src/activity.ts b/packages/shared/src/activity.ts
index a298653..21d6ea7 100644
--- a/packages/shared/src/activity.ts
+++ b/packages/shared/src/activity.ts
@@ -33,6 +33,12 @@ export const ACTIVITY_KINDS = [
   'ingress-updated',
   /** An operator minted an API key (createApiKey). The token itself is never logged. */
   'apikey-created',
+  /** updateApiKey changed a key's name or expiry; the detail names what moved. */
+  'apikey-updated',
+  /** An operator parked an API key (updateApiKey disabled) — reversible, unlike revoke. */
+  'apikey-disabled',
+  /** An operator resumed a parked API key — the credential opens doors again. */
+  'apikey-enabled',
   /** An operator revoked an API key (revokeApiKey) — the credential died here. */
   'apikey-revoked',
   /**
diff --git a/packages/shared/src/api-keys.ts b/packages/shared/src/api-keys.ts
index f7a268d..171f294 100644
--- a/packages/shared/src/api-keys.ts
+++ b/packages/shared/src/api-keys.ts
@@ -9,8 +9,14 @@ import { z } from 'zod';
  * bootstrap/recovery credential (and the console-setup root of trust — a
  * key can NOT reset the console password).
  *
- * Every key is full-power. There is no per-key authorization scoping —
- * that would be a multi-tenant model, and Dormice is single-operator.
+ * Every key is full-power over sandboxes, with exactly one carve-out: the
+ * apiKey management verbs themselves (create/list/update/revoke) accept
+ * only the env token or a console session. A key that could manage keys is
+ * a self-replication ladder — one leaked credential minting itself an
+ * unrevoked successor and revoking every legitimate peer. Rotating
+ * credentials is an administrator's act, so it takes an administrator's
+ * credential. There is no other per-key authorization scoping — that would
+ * be a multi-tenant model, and Dormice is single-operator.
  *
  * The key material is 64 hex chars, no brand prefix: the official Python
  * E2B SDK validates `e2b_[0-9a-f]+` client-side, so anything non-hex could
@@ -19,7 +25,11 @@ import { z } from 'zod';
 export const apiKeyNameSchema = z.string().trim().min(1).max(64);
 
 export const apiKeySchema = z.object({
-  /** Row identity (UUID). The name is the human handle; this never changes. */
+  /**
+   * Row identity (UUID) and the wire address for update/revoke — the name
+   * became renameable, so the id is the stable handle (the sandbox
+   * name/id doctrine, applied to keys).
+   */
   id: z.string(),
   name: apiKeyNameSchema,
   /**
@@ -30,6 +40,19 @@ export const apiKeySchema = z.object({
   createdAt: z.iso.datetime(),
   /** Null = never used. Written with 60s granularity, not per request. */
   lastUsedAt: z.iso.datetime().nullable(),
+  /**
+   * Null = never expires. Always daemon-normalized toISOString() shape, so
+   * the daemon's string comparison against "now" is chronologically sound.
+   * An expired key stops verifying but keeps its name — extend it through
+   * updateApiKey or revoke it; only revoke frees the name.
+   */
+  expiresAt: z.iso.datetime().nullable(),
+  /**
+   * Null = enabled. Disabling is the reversible half of revoking: the key
+   * stops verifying on the next request but keeps its name and can be
+   * re-enabled — a hold, where revoke is an amputation.
+   */
+  disabledAt: z.iso.datetime().nullable(),
   /** Null = active. Revoked rows stay listed — they are the rotation history. */
   revokedAt: z.iso.datetime().nullable(),
 });
@@ -37,13 +60,38 @@ export const apiKeySchema = z.object({
 export type ApiKey = z.infer<typeof apiKeySchema>;
 
 /**
- * createApiKey(name) — mints a key and returns the token exactly once. The
- * ledger stores only its sha256, so no later call can ever reveal it again.
- * A second active key under the same name is refused with a 409: two live
- * credentials answering to one name is a rotation mistake, not a goal.
+ * The one display translation of a row into a lifecycle word, shared by the
+ * CLI table and the console badge so the two never drift. Precedence:
+ * revoked is terminal history, disabled is a deliberate operator act, and
+ * expired merely happened — so each earlier state wins over the later ones.
+ * The daemon's SQL liveness filter is the authentication arbiter; this is
+ * the presentation arbiter. One of each.
+ */
+export type ApiKeyStatus = 'active' | 'disabled' | 'expired' | 'revoked';
+
+export function apiKeyStatus(
+  key: Pick<ApiKey, 'revokedAt' | 'disabledAt' | 'expiresAt'>,
+  nowMs: number,
+): ApiKeyStatus {
+  if (key.revokedAt !== null) return 'revoked';
+  if (key.disabledAt !== null) return 'disabled';
+  if (key.expiresAt !== null && Date.parse(key.expiresAt) <= nowMs) {
+    return 'expired';
+  }
+  return 'active';
+}
+
+/**
+ * createApiKey(name, expiresAt?) — mints a key and returns the token
+ * exactly once. The ledger stores only its sha256, so no later call can
+ * ever reveal it again. A second active key under the same name is refused
+ * with a 409: two live credentials answering to one name is a rotation
+ * mistake, not a goal.
  */
 export const createApiKeyRequestSchema = z.object({
   name: apiKeyNameSchema,
+  /** Omitted = never expires. */
+  expiresAt: z.iso.datetime().optional(),
 });
 
 export type CreateApiKeyRequest = z.infer<typeof createApiKeyRequestSchema>;
@@ -64,21 +112,45 @@ export const listApiKeysResponseSchema = z.object({
 export type ListApiKeysResponse = z.infer<typeof listApiKeysResponseSchema>;
 
 /**
- * revokeApiKey(name) — soft-revokes the active key under this name: the row
- * stays as history, the credential stops opening doors on the next request.
- * Idempotent like destroySandbox: "no active key under this name" is the
- * desired end state, so an unknown or already-revoked name answers
+ * updateApiKey(id, patch) — edits a live key in place. An absent field is
+ * untouched (the updatePolicy patch idiom); expiresAt: null clears to
+ * never-expires; disabled: true/false parks or resumes the key (true on an
+ * already-disabled key is idempotent and keeps the original disabledAt).
+ * An unknown id is a 404; a revoked row is a 409 — revoked rows are
+ * rotation history, not editable credentials; renaming onto a name held by
+ * a live key is a 409 (create's courtesy).
+ */
+export const updateApiKeyRequestSchema = z.object({
+  id: z.string(),
+  name: apiKeyNameSchema.optional(),
+  expiresAt: z.iso.datetime().nullable().optional(),
+  disabled: z.boolean().optional(),
+});
+
+export type UpdateApiKeyRequest = z.infer<typeof updateApiKeyRequestSchema>;
+
+export const updateApiKeyResponseSchema = z.object({
+  apiKey: apiKeySchema,
+});
+
+export type UpdateApiKeyResponse = z.infer<typeof updateApiKeyResponseSchema>;
+
+/**
+ * revokeApiKey(id) — soft-revokes the key: the row stays as history, the
+ * credential stops opening doors on the next request, the name is freed
+ * for reuse. Idempotent like destroySandbox: "this key is not live" is the
+ * desired end state, so an unknown or already-revoked id answers
  * { revoked: false } rather than an error. Callers should say that false
- * out loud — a typo here would leave a leaked key alive.
+ * out loud — a miss here would leave a leaked key alive.
  */
 export const revokeApiKeyRequestSchema = z.object({
-  name: apiKeyNameSchema,
+  id: z.string(),
 });
 
 export type RevokeApiKeyRequest = z.infer<typeof revokeApiKeyRequestSchema>;
 
 export const revokeApiKeyResponseSchema = z.object({
-  /** True when an active key existed and was revoked; false when none did. */
+  /** True when a live-or-disabled key existed and was revoked; false when none did. */
   revoked: z.boolean(),
 });
 
diff --git a/skills/dormice/SKILL.md b/skills/dormice/SKILL.md
index 2e62d70..c3fe1e1 100644
--- a/skills/dormice/SKILL.md
+++ b/skills/dormice/SKILL.md
@@ -29,7 +29,9 @@ or a reverse-proxy domain (then use `https://their-domain`). Auth is one
 API token (created by the installer, hex): ask the user for the endpoint
 and token, conventionally held in `DORMICE_ENDPOINT` / `DORMICE_API_TOKEN`.
 API keys minted in the console (or with `dor apikey create <name>`) work
-everywhere the token does — same variables, revocable per client.
+everywhere the token does — same variables, revocable per client — except
+the apiKey management verbs themselves, which require the env token
+(keys cannot manage keys).
 
 ## Pick an entry path
 
@@ -118,8 +120,10 @@ an existing sandbox's lifecycle policy in place — no wake, no destroy),
 `execCommand`, `writeFiles` / `writeFile`, `readFile` / `readFiles`,
 `rebuildSandbox` (fresh container, `/home/user` kept), `destroySandbox`,
 `registerTemplate` / `listTemplates` / `removeTemplate`,
-`createApiKey` / `listApiKeys` / `revokeApiKey` (revocable peers of the
-API token; the create response shows the key once, never again),
+`createApiKey` / `listApiKeys` / `updateApiKey` / `revokeApiKey`
+(revocable peers of the API token with optional expiry and a reversible
+disable switch; the create response shows the key once, never again;
+these four verbs accept only the env token),
 `getHostMetrics`, `getSandboxMetrics` / `listSandboxMetrics` (live
 resource samples; never wake anything), `listSandboxImages` (who still
 runs an old template image), `listActivity` (recent daemon history),
diff --git a/website/content/docs/cli.mdx b/website/content/docs/cli.mdx
index 6e3ceb8..298f4bb 100644
--- a/website/content/docs/cli.mdx
+++ b/website/content/docs/cli.mdx
@@ -93,18 +93,25 @@ removes the image itself.
 ## dor apikey
 
 ```sh
-dor apikey create <name>   # prints the key once — store it immediately
-dor apikey ls
-dor apikey revoke <name>
+dor apikey create <name>                      # prints the key once — store it immediately
+dor apikey create <name> --expires 2026-12-31 # a TTL key, valid through that day
+dor apikey ls                                 # incl. EXPIRES and STATUS columns
+dor apikey disable <name>                     # reversible hold
+dor apikey enable <name>
+dor apikey revoke <name>                      # final; frees the name
 ```
 
 API keys are revocable peers of `DORMICE_API_TOKEN` — same power, but
 killable without touching the server ([details](/docs/http-api#api-keys)).
 `create` prints the 64-hex token exactly once; the daemon keeps only its
 hash. The minted key goes wherever the token goes, including this CLI's
-own `DORMICE_API_TOKEN` variable. `revoke` takes effect on the key's
-next request; revoking a name that has no active key says so honestly —
-check the spelling before assuming the leak is plugged.
+own `DORMICE_API_TOKEN` variable — with one exception: the `apikey`
+commands themselves require the env token (keys cannot manage keys; a
+key gets the daemon's honest 403). `disable` is the reversible half of
+`revoke`: the key stops working until re-enabled but keeps its name and
+history. `revoke` takes effect on the key's next request; revoking a
+name that has no active key says so honestly — check the spelling before
+assuming the leak is plugged.
 
 ## dor doctor
 
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
index 624cb13..3d43e4f 100644
--- a/website/content/docs/console.mdx
+++ b/website/content/docs/console.mdx
@@ -83,13 +83,21 @@ with the daemon's own message naming the sandboxes.
 ## API keys
 
 Mint revocable credentials without leaving the browser
-([what they are](/docs/http-api#api-keys)). The create dialog shows the
-key **exactly once** — the daemon stores only a hash — with a copy
-button and no second chance. The table keeps every key ever minted,
-revoked ones included, as your rotation history: name, prefix, creation
-time, last use, status. Revoking takes effect on the key's next request.
-`DORMICE_API_TOKEN` itself never appears here — it is the bootstrap
-credential, and retiring it means editing `/etc/dormice/env`.
+([what they are](/docs/http-api#api-keys)). The create dialog takes a
+name and an optional expiry date, then shows the key **exactly once** —
+the daemon stores only a hash — with a copy button, a "copy connection
+config" button (endpoint + credential, ready for CI secrets), and no
+second chance. The table keeps every key ever minted, revoked ones
+included, as your rotation history: name, masked prefix, creation time,
+last use, expiry, an enable/disable switch (the reversible half of
+revoking), and status. Rows can be edited in place (rename, change or
+clear the expiry), selected in bulk for revocation, and revoking takes
+effect on the key's next request. `DORMICE_API_TOKEN` itself appears as
+a pinned, read-only "default" row so all credentials are visible in one
+table — but it lives in the server's environment, so retiring it means
+editing `/etc/dormice/env`, and it (or a console session) is also the
+only credential the key-management actions themselves accept: keys
+cannot manage keys.
 
 ## Activity, domains, and settings
 
diff --git a/website/content/docs/e2b-sdks.mdx b/website/content/docs/e2b-sdks.mdx
index 700debf..2fa2d0c 100644
--- a/website/content/docs/e2b-sdks.mdx
+++ b/website/content/docs/e2b-sdks.mdx
@@ -57,7 +57,9 @@ wire.
 
 [API keys](/docs/http-api#api-keys) minted through the daemon work here
 too — `e2b_<key>` anywhere the token goes, and they are pure hex by
-construction, so the Python SDK's validation never bites.
+construction, so the Python SDK's validation never bites. A disabled,
+expired or revoked key is rejected on this surface the same instant it
+is on the native one — one credential truth, two dialects.
 
 ## Reuse the same sandbox across creates
 
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
index 540d728..d5cff4a 100644
--- a/website/content/docs/http-api.mdx
+++ b/website/content/docs/http-api.mdx
@@ -46,9 +46,10 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | `POST /registerTemplate` | upsert name → image | 400 `'base'` is reserved |
 | `POST /listTemplates` | every registered template | — |
 | `POST /removeTemplate` | unregister; idempotent | 409 while sandboxes still use it (names them) |
-| `POST /createApiKey` | mint an [API key](#api-keys); the token appears in this response once, never again | 409 while an active key already has this name |
+| `POST /createApiKey` | mint an [API key](#api-keys), optionally with an `expiresAt`; the token appears in this response once, never again | 409 while a non-revoked key already has this name |
 | `POST /listApiKeys` | every key ever minted, revoked ones included, newest first — no secrets | — |
-| `POST /revokeApiKey` | soft-revoke the active key under a name; idempotent (`revoked: false` when none was) | — |
+| `POST /updateApiKey` | edit a key by `id`: rename, change/clear `expiresAt`, park/resume via `disabled` — absent fields untouched | 404 unknown id; 409 revoked row or name collision |
+| `POST /revokeApiKey` | soft-revoke a key by `id`; idempotent (`revoked: false` when none was) | — |
 | `POST /getHostMetrics` | host snapshot; never wakes anything | — |
 | `POST /getSandboxMetrics` | one sandbox's live CPU/memory/disk sample; `sample` is `null` when nothing is running | 404 unknown name |
 | `POST /listSandboxMetrics` | every measurable sandbox's sample in one answer | — |
@@ -106,20 +107,34 @@ signal that the policy/template/metadata in the request were ignored.
 `DORMICE_API_TOKEN` works forever, but rotating it means editing
 `/etc/dormice/env` and restarting the daemon. API keys are its
 full-power, revocable peers: mint one per client with
-`POST /createApiKey {"name": "ci"}`, hand out the returned 64-hex
-`token`, and when a key leaks, `POST /revokeApiKey {"name": "ci"}` kills
-exactly that credential on its next request — no config edit, no
-restart, no other client disturbed.
+`POST /createApiKey {"name": "ci"}` (optionally with
+`"expiresAt": "<ISO>"` for a TTL key), hand out the returned 64-hex
+`token`, and when a key leaks, revoke it — the credential dies on its
+next request, no config edit, no restart, no other client disturbed.
 
 The token appears in the create response **once**. The daemon stores
 only its hash, so nothing can ever show it again — copy it then. Keys
 open every door the env token does, the
 [E2B surface](/docs/e2b-sdks) included (`e2b_<key>` works as an E2B API
-key); the one exception is console account setup/reset, which accepts
-only the env token — a leaked machine credential must not be able to
-take over the human account. Each key row carries `lastUsedAt` (written
-with 60-second granularity), and revoked rows stay in `listApiKeys` as
-your rotation history.
+key), with exactly two exceptions:
+
+- **Console account setup/reset** accepts only the env token — a leaked
+  machine credential must not be able to take over the human account.
+- **The four apiKey verbs themselves** (`createApiKey`, `listApiKeys`,
+  `updateApiKey`, `revokeApiKey`) accept only the env token or a console
+  session. A key that could manage keys is a self-replication ladder —
+  one leaked credential minting itself an unrevoked successor — so a
+  valid key gets an honest 403 on these routes.
+
+Each key has two handles: `name`, the human label (renameable through
+`updateApiKey`), and `id`, the stable address `updateApiKey` and
+`revokeApiKey` take. Three ways a key stops working, with different
+semantics: **disabling** (`updateApiKey {"disabled": true}`) is a
+reversible hold; **expiry** (`expiresAt`, extendable or clearable with
+`"expiresAt": null`) happens on its own; **revoking** is final, keeps
+the row as rotation history, and is the only one that frees the name
+for reuse. Each key row carries `lastUsedAt` (written with 60-second
+granularity), and revoked rows stay in `listApiKeys` forever.
 
 ## Commands and files on the wire
 

From 5d3847a83192fc89bf08708027134095f2393281 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 21:21:30 +0800
Subject: [PATCH 097/133] =?UTF-8?q?The=20console=20sheds=20its=20top=20bar?=
 =?UTF-8?q?:=20the=20breadcrumb=20was=20a=20second=20copy=20of=20every=20p?=
 =?UTF-8?q?age's=20own=20header=20(the=20user=20reads=20=E6=B2=99=E7=AE=B1?=
 =?UTF-8?q?=20twice,=20one=20line=20apart),=20so=20the=20whole=20strip=20g?=
 =?UTF-8?q?oes=20=E2=80=94=20on=20every=20page.=20The=20=E2=8C=98K=20comma?=
 =?UTF-8?q?nd=20palette=20keeps=20its=20visible=20doorway=20by=20moving=20?=
 =?UTF-8?q?into=20the=20sidebar=20header=20as=20a=20menu=20item=20under=20?=
 =?UTF-8?q?the=20wordmark=20(the=20keyboard=20shortcut=20alone=20would=20m?=
 =?UTF-8?q?ake=20search=20a=20secret),=20and=20sidebar=20collapse=20falls?=
 =?UTF-8?q?=20back=20to=20the=20vendored=20=E2=8C=98B=20binding=20now=20th?=
 =?UTF-8?q?at=20SidebarTrigger=20has=20no=20home.=20Moving=20the=20palette?=
 =?UTF-8?q?=20into=20the=20sidebar=20would=20have=20made=20AppSidebar=20an?=
 =?UTF-8?q?d=20CommandMenu=20import=20each=20other,=20so=20the=20nav=20man?=
 =?UTF-8?q?ifest=20(NAV=5FGROUPS)=20and=20the=20shared=20pill-button=20cla?=
 =?UTF-8?q?ss=20move=20out=20to=20components/nav.ts=20=E2=80=94=20still=20?=
 =?UTF-8?q?one=20list,=20now=20with=20no=20cycle.=20AppShell=20is=20left?=
 =?UTF-8?q?=20doing=20exactly=20its=20remaining=20job:=20lock=20the=20view?=
 =?UTF-8?q?port,=20host=20the=20sidebar,=20give=20pages=20a=20scroll=20por?=
 =?UTF-8?q?t.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/console/src/components/AppShell.tsx  | 80 ++-----------------
 .../console/src/components/AppSidebar.tsx     | 59 ++------------
 .../console/src/components/CommandMenu.tsx    | 27 ++++---
 packages/console/src/components/nav.ts        | 55 +++++++++++++
 4 files changed, 82 insertions(+), 139 deletions(-)
 create mode 100644 packages/console/src/components/nav.ts

diff --git a/packages/console/src/components/AppShell.tsx b/packages/console/src/components/AppShell.tsx
index 055b01c..e4b96c9 100644
--- a/packages/console/src/components/AppShell.tsx
+++ b/packages/console/src/components/AppShell.tsx
@@ -1,52 +1,14 @@
-import { Outlet, useRouterState } from '@tanstack/react-router';
-import { type CSSProperties, Fragment } from 'react';
+import { Outlet } from '@tanstack/react-router';
+import type { CSSProperties } from 'react';
 import { AppSidebar } from '@/components/AppSidebar';
-import { CommandMenu } from '@/components/CommandMenu';
-import {
-  Breadcrumb,
-  BreadcrumbItem,
-  BreadcrumbList,
-  BreadcrumbPage,
-  BreadcrumbSeparator,
-} from '@/components/ui/breadcrumb';
-import { Separator } from '@/components/ui/separator';
-import {
-  SidebarInset,
-  SidebarProvider,
-  SidebarTrigger,
-} from '@/components/ui/sidebar';
-
-// 路径段 → 中文名。没在表里的段(比如 name)原样展示 — 它就是名字本身。
-const SEGMENT_LABELS: Record<string, string> = {
-  sandboxes: '沙箱',
-  templates: '模板',
-  activity: '活动',
-  'api-keys': 'API 密钥',
-  domains: '域名',
-  doctor: '体检',
-  settings: '设置',
-  version: '版本',
-  connect: '连接',
-};
-
-function crumbsOf(pathname: string): string[] {
-  const segments = pathname.split('/').filter(Boolean);
-  if (segments.length === 0) return ['仪表盘'];
-  return segments.map(
-    (segment) => SEGMENT_LABELS[segment] ?? decodeURIComponent(segment),
-  );
-}
+import { SidebarInset, SidebarProvider } from '@/components/ui/sidebar';
 
 /**
- * 登录后的应用外壳:侧边栏 + 顶栏(开关 + 面包屑)+ 页面内容。页面自己
- * 不再各画返回箭头和站名 — 导航是外壳的职责,页面只管自己的内容区。
+ * 登录后的应用外壳:侧边栏 + 页面内容。顶栏 2026-07-16 用户拍板删除:
+ * 面包屑只是页面自带页头的第二份真相,⌘K 搜索入口随之移进侧栏
+ * (CommandMenu),侧栏开关保留键盘位(⌘B,vendored sidebar 自带)。
  */
 export function AppShell() {
-  const pathname = useRouterState({
-    select: (state) => state.location.pathname,
-  });
-  const crumbs = crumbsOf(pathname);
-
   return (
     // 外壳锁定视口高度,滚动只发生在内容区(openasi 版式,2026-07-16):
     // 表格页因此能"表格占满剩余高度框内滚、分页钉底"。侧栏 15rem
@@ -57,36 +19,6 @@ export function AppShell() {
     >
       <AppSidebar />
       <SidebarInset className="min-h-0 overflow-hidden">
-        <header className="flex h-14 shrink-0 items-center gap-2 border-b px-4">
-          <SidebarTrigger className="-ml-1" />
-          {/* 组件自带 data-vertical:self-stretch,限高后会钉在顶栏上沿 — 压回居中。 */}
-          <Separator
-            orientation="vertical"
-            className="mr-2 !h-4 !self-center"
-          />
-          <Breadcrumb>
-            <BreadcrumbList>
-              {crumbs.map((crumb, index) => (
-                // biome-ignore lint/suspicious/noArrayIndexKey: 面包屑是纯位置序列,段文本可重复
-                <Fragment key={index}>
-                  {index > 0 && <BreadcrumbSeparator />}
-                  <BreadcrumbItem>
-                    <BreadcrumbPage
-                      className={
-                        index < crumbs.length - 1
-                          ? 'font-normal text-muted-foreground'
-                          : undefined
-                      }
-                    >
-                      {crumb}
-                    </BreadcrumbPage>
-                  </BreadcrumbItem>
-                </Fragment>
-              ))}
-            </BreadcrumbList>
-          </Breadcrumb>
-          <CommandMenu />
-        </header>
         {/* 页面自带容器(max-w/padding/gap 按页型),这里只给滚动口。 */}
         <div className="min-h-0 flex-1 overflow-y-auto">
           <Outlet />
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index f41545d..ad6042f 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -1,23 +1,15 @@
 import {
-  Activity01Icon,
   Book02Icon,
-  DashboardSquare01Icon,
-  GitCommitIcon,
   GithubIcon,
-  Globe02Icon,
-  Key01Icon,
-  Layers01Icon,
   Logout01Icon,
   Moon02Icon,
-  PackageIcon,
-  PlugSocketIcon,
-  Settings01Icon,
-  StethoscopeIcon,
   Sun02Icon,
 } from '@hugeicons/core-free-icons';
-import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
+import { HugeiconsIcon } from '@hugeicons/react';
 import { Link, useRouterState } from '@tanstack/react-router';
 import { useTheme } from 'next-themes';
+import { CommandMenu } from '@/components/CommandMenu';
+import { menuButtonClass, NAV_GROUPS } from '@/components/nav';
 import {
   Sidebar,
   SidebarContent,
@@ -36,42 +28,6 @@ import { logout } from '@/lib/api';
 import { MOCK_PAGES_ENABLED } from '@/lib/mock';
 import { clearSessionMarker } from '@/lib/session';
 
-interface NavItem {
-  to: string;
-  label: string;
-  icon: NonNullable<HugeiconsProps['icon']>;
-  /** 服务端还没有的页面:dev 里带"预览"角标,生产构建整个隐藏。 */
-  mock?: boolean;
-}
-
-// 平台 = 管的对象(沙箱/模板),运维 = 管这台机器;连接页是给要接 SDK 的人。
-// 导出给命令面板(⌘K)复用 — 页面清单只有这一份,两处永远一致。
-export const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
-  {
-    label: '平台',
-    items: [
-      { to: '/', label: '仪表盘', icon: DashboardSquare01Icon },
-      { to: '/sandboxes', label: '沙箱', icon: PackageIcon },
-      { to: '/templates', label: '模板', icon: Layers01Icon },
-    ],
-  },
-  {
-    label: '运维',
-    items: [
-      { to: '/activity', label: '活动', icon: Activity01Icon },
-      { to: '/api-keys', label: 'API 密钥', icon: Key01Icon },
-      { to: '/domains', label: '域名', icon: Globe02Icon },
-      { to: '/doctor', label: '体检', icon: StethoscopeIcon, mock: true },
-      { to: '/settings', label: '设置', icon: Settings01Icon },
-      { to: '/version', label: '版本', icon: GitCommitIcon },
-    ],
-  },
-  {
-    label: '接入',
-    items: [{ to: '/connect', label: '连接', icon: PlugSocketIcon }],
-  },
-];
-
 async function signOut() {
   // 尽力而为:cookie 可能已经死了,无所谓 — 清掉标记回登录页才是正事。
   await logout().catch(() => undefined);
@@ -79,11 +35,6 @@ async function signOut() {
   window.location.href = '/console/login';
 }
 
-// 侧栏按钮统一药丸形 + medium 字重(风格参考 openasi 侧栏,2026-07-12)。
-// cursor-default 抹平 Link(手型)与 button(箭头)的光标分裂 — 侧栏是
-// 应用 chrome,不是网页链接。
-const menuButtonClass = 'rounded-full font-medium cursor-default';
-
 function isActivePath(pathname: string, to: string): boolean {
   if (to === '/') return pathname === '/';
   return pathname === to || pathname.startsWith(`${to}/`);
@@ -109,6 +60,10 @@ export function AppSidebar() {
             Dormice
           </span>
         </Link>
+        {/* ⌘K 搜索入口:顶栏删掉后(2026-07-16)它是全站搜索唯一的可见入口。 */}
+        <SidebarMenu>
+          <CommandMenu />
+        </SidebarMenu>
       </SidebarHeader>
 
       <SidebarContent>
diff --git a/packages/console/src/components/CommandMenu.tsx b/packages/console/src/components/CommandMenu.tsx
index c7717bb..5deea3b 100644
--- a/packages/console/src/components/CommandMenu.tsx
+++ b/packages/console/src/components/CommandMenu.tsx
@@ -6,8 +6,7 @@ import {
 import { HugeiconsIcon } from '@hugeicons/react';
 import { useNavigate } from '@tanstack/react-router';
 import { useEffect, useState } from 'react';
-import { NAV_GROUPS } from '@/components/AppSidebar';
-import { Button } from '@/components/ui/button';
+import { menuButtonClass, NAV_GROUPS } from '@/components/nav';
 import {
   CommandDialog,
   CommandEmpty,
@@ -17,6 +16,7 @@ import {
   CommandList,
 } from '@/components/ui/command';
 import { Kbd } from '@/components/ui/kbd';
+import { SidebarMenuButton, SidebarMenuItem } from '@/components/ui/sidebar';
 import { STATE_LABELS } from '@/features/sandboxes/format';
 import { useSandboxes } from '@/features/sandboxes/hooks/useSandboxes';
 import { MOCK_PAGES_ENABLED } from '@/lib/mock';
@@ -50,7 +50,8 @@ function SandboxItems({ onGo }: { onGo: (name: string) => void }) {
 }
 
 /**
- * ⌘K / Ctrl+K 命令面板:跳页面、按 name 跳沙箱。挂在 AppShell 上,
+ * ⌘K / Ctrl+K 命令面板:跳页面、按 name 跳沙箱。入口是侧栏顶部的
+ * 菜单项(顶栏 2026-07-16 删除:面包屑与页面自带页头是第二份真相),
  * 登录后全站可用;它只做导航 — 动作(销毁/重建)留在各自页面的确认
  * 流程里,快捷键不该绕过"删了就没有了"的那道闸。
  */
@@ -84,16 +85,16 @@ export function CommandMenu() {
 
   return (
     <>
-      <Button
-        variant="ghost"
-        size="sm"
-        className="ml-auto text-muted-foreground"
-        onClick={() => setOpen(true)}
-      >
-        <HugeiconsIcon icon={Search01Icon} className="size-4" />
-        搜索
-        <Kbd>⌘K</Kbd>
-      </Button>
+      <SidebarMenuItem>
+        <SidebarMenuButton
+          className={menuButtonClass}
+          onClick={() => setOpen(true)}
+        >
+          <HugeiconsIcon icon={Search01Icon} strokeWidth={2} />
+          <span>搜索</span>
+          <Kbd className="ml-auto">⌘K</Kbd>
+        </SidebarMenuButton>
+      </SidebarMenuItem>
       <CommandDialog
         open={open}
         onOpenChange={setOpen}
diff --git a/packages/console/src/components/nav.ts b/packages/console/src/components/nav.ts
new file mode 100644
index 0000000..c7300a3
--- /dev/null
+++ b/packages/console/src/components/nav.ts
@@ -0,0 +1,55 @@
+import {
+  Activity01Icon,
+  DashboardSquare01Icon,
+  GitCommitIcon,
+  Globe02Icon,
+  Key01Icon,
+  Layers01Icon,
+  PackageIcon,
+  PlugSocketIcon,
+  Settings01Icon,
+  StethoscopeIcon,
+} from '@hugeicons/core-free-icons';
+import type { HugeiconsProps } from '@hugeicons/react';
+
+export interface NavItem {
+  to: string;
+  label: string;
+  icon: NonNullable<HugeiconsProps['icon']>;
+  /** 服务端还没有的页面:dev 里带"预览"角标,生产构建整个隐藏。 */
+  mock?: boolean;
+}
+
+// 平台 = 管的对象(沙箱/模板),运维 = 管这台机器;连接页是给要接 SDK 的人。
+// 独立成文件:侧栏与命令面板(⌘K)都要这份清单,而搜索入口住在侧栏里,
+// 留在任何一边都会让两个组件互相 import。页面清单只有这一份,两处永远一致。
+export const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
+  {
+    label: '平台',
+    items: [
+      { to: '/', label: '仪表盘', icon: DashboardSquare01Icon },
+      { to: '/sandboxes', label: '沙箱', icon: PackageIcon },
+      { to: '/templates', label: '模板', icon: Layers01Icon },
+    ],
+  },
+  {
+    label: '运维',
+    items: [
+      { to: '/activity', label: '活动', icon: Activity01Icon },
+      { to: '/api-keys', label: 'API 密钥', icon: Key01Icon },
+      { to: '/domains', label: '域名', icon: Globe02Icon },
+      { to: '/doctor', label: '体检', icon: StethoscopeIcon, mock: true },
+      { to: '/settings', label: '设置', icon: Settings01Icon },
+      { to: '/version', label: '版本', icon: GitCommitIcon },
+    ],
+  },
+  {
+    label: '接入',
+    items: [{ to: '/connect', label: '连接', icon: PlugSocketIcon }],
+  },
+];
+
+// 侧栏按钮统一药丸形 + medium 字重(风格参考 openasi 侧栏,2026-07-12)。
+// cursor-default 抹平 Link(手型)与 button(箭头)的光标分裂 — 侧栏是
+// 应用 chrome,不是网页链接。搜索入口(CommandMenu)也穿这一件。
+export const menuButtonClass = 'rounded-full font-medium cursor-default';

From 82790d2635e3fbe4d89cf2dbfd978bd59268e2e1 Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Thu, 16 Jul 2026 22:51:07 -0700
Subject: [PATCH 098/133] install.sh: fix the gVisor 404 and survive hosts with
 their own Node or pnpm
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three failures from one end-to-end run on a Debian 12 host, each fatal:

- The gVisor download 404ed everywhere: GVISOR_RELEASE is the git tag
  (release-20260622.0), but the storage bucket keys releases by date
  alone (releases/release/20260622/x86_64). A fresh host could never
  get past the gVisor step. GVISOR_DATE now carries the path component;
  the pinned checksums were already right — verified against the
  binaries at the date-keyed path. Fixes #1

- A host whose own Node satisfied the >= 22 check got a crash-looping
  daemon: the skip branch never created /usr/local/bin/node, and
  dormice.service execs exactly that path (203/EXEC, restart counter
  climbing forever). Whatever node passed the check is now linked
  there. Fixes #2

- A host whose pnpm is a corepack shim died in the build step: npm
  refuses to overwrite a binary it does not own (EEXIST on
  /usr/bin/pnpm). When the pnpm on PATH resolves into corepack, the
  pinned version is now pinned through corepack — the shim's owner —
  instead of fought over with npm. CONTRIBUTING.md itself recommends
  corepack enable, so this collision was one dev host away. Fixes #3

With all three in place the same host installs end to end and
dor doctor reports 20 passed, 0 failed, 0 warnings, 3 skipped.
---
 deploy/install.sh | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/deploy/install.sh b/deploy/install.sh
index 04ac240..52401e6 100644
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -35,7 +35,11 @@ NODE_SHA256=55aa7153f9d88f28d765fcdad5ae6945b5c0f98a36881703817e4c450fa76742
 # gVisor is pinned to the release proven on real hardware, with checksums of
 # the binaries themselves — the .sha512 files published next to the binaries
 # only guard transit, not a poisoned origin.
+# The git release tag is release-YYYYMMDD.N, but the storage bucket keys the
+# binaries by date alone (…/releases/release/YYYYMMDD/x86_64) — GVISOR_DATE is
+# that path component; keep it in sync with GVISOR_RELEASE.
 GVISOR_RELEASE=release-20260622.0
+GVISOR_DATE=20260622
 RUNSC_SHA512=6df95d09363dbd9ee5d5c889c1549b457e1783b039ff60a8f9f16f8c94c774a2ca2eef5b1c370e36b863f6b0407b53ba3c69051c6ef051253843dabf89a6de4e
 SHIM_SHA512=87c63197836574b7a2c057d2c0647d2badb679187f0b9175ecf78ac52207cdaa3f101629d3e5d165c95930ca35fe81bc26bb90fcf08e09b99c2ee047b6235ce2
 
@@ -172,6 +176,14 @@ else
   done
   note "installed $(node --version) to /opt, linked into /usr/local/bin"
 fi
+# The systemd unit execs /usr/local/bin/node unconditionally, but a host whose
+# own Node satisfied the version check keeps it elsewhere (e.g. /usr/bin/node)
+# — link whatever node passed the check so the unit can always start.
+if [ ! -x /usr/local/bin/node ]; then
+  node_path=$(command -v node)
+  ln -sf "$node_path" /usr/local/bin/node
+  note "linked $node_path -> /usr/local/bin/node (the path dormice.service execs)"
+fi
 
 # ---- Docker ----------------------------------------------------------------
 log 'Docker'
@@ -228,7 +240,7 @@ if docker info --format '{{json .Runtimes}}' | grep -q '"runsc"'; then
   note "[skip] runsc is a registered Docker runtime ($(runsc --version | head -1))"
 else
   if [ ! -x /usr/local/bin/runsc ]; then
-    gvisor_url="https://storage.googleapis.com/gvisor/releases/release/$GVISOR_RELEASE/x86_64"
+    gvisor_url="https://storage.googleapis.com/gvisor/releases/release/$GVISOR_DATE/x86_64"
     for bin in runsc containerd-shim-runsc-v1; do
       curl -fsSL -o "/tmp/$bin" "$gvisor_url/$bin" || die "cannot download $bin from $gvisor_url —
     if this host cannot reach storage.googleapis.com, download runsc and
@@ -341,7 +353,16 @@ status_write running
 log 'build'
 pnpm_version=$(node -p "require('$INSTALL_DIR/package.json').packageManager.split('@')[1]")
 if ! command -v pnpm >/dev/null || [ "$(pnpm --version)" != "$pnpm_version" ]; then
-  if [ "$MIRROR" = cn ]; then
+  pnpm_path=$(command -v pnpm || true)
+  if [ -n "$pnpm_path" ] && readlink -f "$pnpm_path" 2>/dev/null | grep -q corepack; then
+    # The host's pnpm is a corepack shim (Node >= 16.9 ships corepack, and
+    # `corepack enable` shims pnpm next to node). npm install -g refuses to
+    # overwrite a binary it does not own and dies with EEXIST — so pin the
+    # version through corepack, the shim's actual owner, instead.
+    [ "$MIRROR" = cn ] && export COREPACK_NPM_REGISTRY=https://registry.npmmirror.com
+    corepack prepare "pnpm@$pnpm_version" --activate
+    note "pinned pnpm@$pnpm_version via corepack (the host's pnpm is a corepack shim)"
+  elif [ "$MIRROR" = cn ]; then
     npm install -g "pnpm@$pnpm_version" --registry=https://registry.npmmirror.com >/dev/null
   else
     npm install -g "pnpm@$pnpm_version" >/dev/null

From 38aaaa6ea3f8f054cf72cc0dc18b357e4c9532f7 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 21:57:00 +0800
Subject: [PATCH 099/133] =?UTF-8?q?The=20console=20grows=20a=20permanent?=
 =?UTF-8?q?=20rack=20for=20throwaway=20design=20lineups:=20one=20splat=20r?=
 =?UTF-8?q?oute=20(/temp/<date>/<topic>/<variant>,=20written=20flat=20as?=
 =?UTF-8?q?=20temp.$.tsx=20because=20a=20directory=20literally=20named=20t?=
 =?UTF-8?q?emp/=20would=20be=20swallowed=20by=20the=20gitignore=20rule=20t?=
 =?UTF-8?q?hat=20keeps=20scratch=20code=20out=20of=20an=20append-only=20pu?=
 =?UTF-8?q?blic=20history)=20plus=20a=20TempGallery=20loader=20that=20impo?=
 =?UTF-8?q?rt.meta.glob-collects=20whatever=20gallery=20topics=20exist=20o?=
 =?UTF-8?q?n=20this=20machine=20under=20features/temp/.=20The=20galleries?=
 =?UTF-8?q?=20themselves=20never=20enter=20git=20=E2=80=94=20in=20CI=20and?=
 =?UTF-8?q?=20production=20the=20glob=20is=20an=20empty=20table,=20routeTr?=
 =?UTF-8?q?ee.gen.ts=20stays=20stable=20no=20matter=20how=20galleries=20co?=
 =?UTF-8?q?me=20and=20go,=20and=20a=20beforeLoad=20guard=20bounces=20non-d?=
 =?UTF-8?q?ev=20visitors=20back=20home.=20First=20cargo=20(local-only,=20d?=
 =?UTF-8?q?eliberately=20untracked):=20four=20mock=20dashboard=20variants?=
 =?UTF-8?q?=20=E2=80=94=20chart-hero,=20bento,=20cockpit,=20editorial=20?=
 =?UTF-8?q?=E2=80=94=20sharing=20one=20seeded-random=20fleet=20timeline=20?=
 =?UTF-8?q?so=20switching=20variants=20compares=20layout,=20never=20data.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../console/src/components/TempGallery.tsx    | 76 +++++++++++++++++++
 packages/console/src/routeTree.gen.ts         | 21 +++++
 packages/console/src/routes/_app/temp.$.tsx   | 16 ++++
 3 files changed, 113 insertions(+)
 create mode 100644 packages/console/src/components/TempGallery.tsx
 create mode 100644 packages/console/src/routes/_app/temp.$.tsx

diff --git a/packages/console/src/components/TempGallery.tsx b/packages/console/src/components/TempGallery.tsx
new file mode 100644
index 0000000..11f1068
--- /dev/null
+++ b/packages/console/src/components/TempGallery.tsx
@@ -0,0 +1,76 @@
+import { useParams } from '@tanstack/react-router';
+import { type ComponentType, useEffect, useState } from 'react';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import { Spinner } from '@/components/ui/spinner';
+
+/**
+ * 临时陈列页的装载器(RULES/前端.md「方案先行」)。陈列内容不入库
+ * (.gitignore 的 temp/ 规则:公开仓历史 append-only,临时代码一次误
+ * 提交就永久留在历史里),所以不能走文件路由 — routeTree.gen.ts 是
+ * 入库文件,引用被忽略的路由文件会在 CI 上断链。这里用 import.meta.glob
+ * 在构建期收集本机存在的陈列主题:CI 与生产构建里 temp/ 为空,glob
+ * 自然是空表,挂架无害地长驻。
+ *
+ * 约定:features/temp/<日期>/<主题>/index.tsx 导出
+ * `TEMP_PAGES: Record<方案键, 组件>`,URL 即 /temp/<日期>/<主题>/<方案键>。
+ */
+const TOPICS = import.meta.glob('/src/features/temp/*/*/index.tsx');
+
+type TempPages = Record<string, ComponentType>;
+
+export function TempGallery() {
+  const { _splat } = useParams({ from: '/_app/temp/$' });
+  const [date, topic, page] = (_splat ?? '').split('/');
+  const loader = TOPICS[`/src/features/temp/${date}/${topic}/index.tsx`];
+
+  const [pages, setPages] = useState<TempPages | null>(null);
+  const [missing, setMissing] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    setPages(null);
+    setMissing(false);
+    if (!loader) {
+      setMissing(true);
+      return;
+    }
+    void loader().then((mod) => {
+      if (cancelled) return;
+      const exported = (mod as { TEMP_PAGES?: TempPages }).TEMP_PAGES;
+      if (exported) setPages(exported);
+      else setMissing(true);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [loader]);
+
+  const Page = pages?.[page ?? ''];
+
+  if (missing || (pages && !Page)) {
+    return (
+      <Empty className="m-6 border border-dashed">
+        <EmptyHeader>
+          <EmptyTitle>没有这个陈列页</EmptyTitle>
+          <EmptyDescription>
+            陈列页住在 features/temp/&lt;日期&gt;/&lt;主题&gt;/,不入库也不进
+            生产 — 它可能已经拍板删除了。
+          </EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    );
+  }
+  if (!Page) {
+    return (
+      <div className="flex justify-center p-10">
+        <Spinner />
+      </div>
+    );
+  }
+  return <Page />;
+}
diff --git a/packages/console/src/routeTree.gen.ts b/packages/console/src/routeTree.gen.ts
index e309840..74f2730 100644
--- a/packages/console/src/routeTree.gen.ts
+++ b/packages/console/src/routeTree.gen.ts
@@ -21,6 +21,7 @@ import { Route as AppConnectRouteImport } from './routes/_app/connect'
 import { Route as AppApiKeysRouteImport } from './routes/_app/api-keys'
 import { Route as AppActivityRouteImport } from './routes/_app/activity'
 import { Route as AppSandboxesIndexRouteImport } from './routes/_app/sandboxes/index'
+import { Route as AppTempSplatRouteImport } from './routes/_app/temp.$'
 import { Route as AppSandboxesNameRouteImport } from './routes/_app/sandboxes/$name'
 
 const LoginRoute = LoginRouteImport.update({
@@ -82,6 +83,11 @@ const AppSandboxesIndexRoute = AppSandboxesIndexRouteImport.update({
   path: '/sandboxes/',
   getParentRoute: () => AppRoute,
 } as any)
+const AppTempSplatRoute = AppTempSplatRouteImport.update({
+  id: '/temp/$',
+  path: '/temp/$',
+  getParentRoute: () => AppRoute,
+} as any)
 const AppSandboxesNameRoute = AppSandboxesNameRouteImport.update({
   id: '/sandboxes/$name',
   path: '/sandboxes/$name',
@@ -100,6 +106,7 @@ export interface FileRoutesByFullPath {
   '/templates': typeof AppTemplatesRoute
   '/version': typeof AppVersionRoute
   '/sandboxes/$name': typeof AppSandboxesNameRoute
+  '/temp/$': typeof AppTempSplatRoute
   '/sandboxes/': typeof AppSandboxesIndexRoute
 }
 export interface FileRoutesByTo {
@@ -114,6 +121,7 @@ export interface FileRoutesByTo {
   '/version': typeof AppVersionRoute
   '/': typeof AppIndexRoute
   '/sandboxes/$name': typeof AppSandboxesNameRoute
+  '/temp/$': typeof AppTempSplatRoute
   '/sandboxes': typeof AppSandboxesIndexRoute
 }
 export interface FileRoutesById {
@@ -130,6 +138,7 @@ export interface FileRoutesById {
   '/_app/version': typeof AppVersionRoute
   '/_app/': typeof AppIndexRoute
   '/_app/sandboxes/$name': typeof AppSandboxesNameRoute
+  '/_app/temp/$': typeof AppTempSplatRoute
   '/_app/sandboxes/': typeof AppSandboxesIndexRoute
 }
 export interface FileRouteTypes {
@@ -146,6 +155,7 @@ export interface FileRouteTypes {
     | '/templates'
     | '/version'
     | '/sandboxes/$name'
+    | '/temp/$'
     | '/sandboxes/'
   fileRoutesByTo: FileRoutesByTo
   to:
@@ -160,6 +170,7 @@ export interface FileRouteTypes {
     | '/version'
     | '/'
     | '/sandboxes/$name'
+    | '/temp/$'
     | '/sandboxes'
   id:
     | '__root__'
@@ -175,6 +186,7 @@ export interface FileRouteTypes {
     | '/_app/version'
     | '/_app/'
     | '/_app/sandboxes/$name'
+    | '/_app/temp/$'
     | '/_app/sandboxes/'
   fileRoutesById: FileRoutesById
 }
@@ -269,6 +281,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof AppSandboxesIndexRouteImport
       parentRoute: typeof AppRoute
     }
+    '/_app/temp/$': {
+      id: '/_app/temp/$'
+      path: '/temp/$'
+      fullPath: '/temp/$'
+      preLoaderRoute: typeof AppTempSplatRouteImport
+      parentRoute: typeof AppRoute
+    }
     '/_app/sandboxes/$name': {
       id: '/_app/sandboxes/$name'
       path: '/sandboxes/$name'
@@ -290,6 +309,7 @@ interface AppRouteChildren {
   AppVersionRoute: typeof AppVersionRoute
   AppIndexRoute: typeof AppIndexRoute
   AppSandboxesNameRoute: typeof AppSandboxesNameRoute
+  AppTempSplatRoute: typeof AppTempSplatRoute
   AppSandboxesIndexRoute: typeof AppSandboxesIndexRoute
 }
 
@@ -304,6 +324,7 @@ const AppRouteChildren: AppRouteChildren = {
   AppVersionRoute: AppVersionRoute,
   AppIndexRoute: AppIndexRoute,
   AppSandboxesNameRoute: AppSandboxesNameRoute,
+  AppTempSplatRoute: AppTempSplatRoute,
   AppSandboxesIndexRoute: AppSandboxesIndexRoute,
 }
 
diff --git a/packages/console/src/routes/_app/temp.$.tsx b/packages/console/src/routes/_app/temp.$.tsx
new file mode 100644
index 0000000..deca349
--- /dev/null
+++ b/packages/console/src/routes/_app/temp.$.tsx
@@ -0,0 +1,16 @@
+import { createFileRoute, redirect } from '@tanstack/react-router';
+import { TempGallery } from '@/components/TempGallery';
+
+/**
+ * 临时陈列页的挂架(RULES/前端.md「方案先行」):/temp/<日期>/<主题>/<方案>
+ * 一条 splat 路由接住全部陈列页。陈列内容住在 gitignore 的
+ * features/temp/ 里(公开仓历史 append-only,临时代码绝不入库),这里
+ * 只有挂架入库 — routeTree.gen.ts 因此永远稳定,陈列页来去不碰它。
+ */
+export const Route = createFileRoute('/_app/temp/$')({
+  beforeLoad: () => {
+    // 陈列页是 dev 专属:生产构建里这条路由直接弹回首页。
+    if (!import.meta.env.DEV) throw redirect({ to: '/' });
+  },
+  component: TempGallery,
+});

From 9b1e61ec3214fed657eee92ea6ce91fb3cb2f17a Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Thu, 16 Jul 2026 22:07:29 +0800
Subject: [PATCH 100/133] =?UTF-8?q?The=20sidebar=20sheds=20its=20last=20tw?=
 =?UTF-8?q?o=20utility=20buttons=20and=20gains=20honest=20edges:=20the=20s?=
 =?UTF-8?q?earch=20entry=20is=20gone=20(=E2=8C=98K=20becomes=20a=20keyboar?=
 =?UTF-8?q?d-only=20door=20=E2=80=94=20CommandMenu=20now=20renders=20nothi?=
 =?UTF-8?q?ng=20visible,=20just=20the=20shortcut=20and=20the=20dialog),=20?=
 =?UTF-8?q?GitHub=20and=20docs=20links=20wear=20a=20top-right=20arrow=20th?=
 =?UTF-8?q?at=20promises=20"this=20jumps=20out=20to=20a=20new=20tab",=20th?=
 =?UTF-8?q?e=20light/dark=20toggle=20is=20deleted=20because=20the=20consol?=
 =?UTF-8?q?e=20is=20now=20permanently=20dark=20(forcedTheme=20keeps=20ever?=
 =?UTF-8?q?y=20useTheme=20consumer=20answering=20dark,=20and=20the=20class?=
 =?UTF-8?q?=20is=20baked=20into=20index.html=20so=20the=20first=20pre-hydr?=
 =?UTF-8?q?ation=20frame=20doesn't=20flash=20white),=20and=20logout=20gets?=
 =?UTF-8?q?=20a=20confirmation=20dialog=20=E2=80=94=20not=20because=20it's?=
 =?UTF-8?q?=20destructive,=20but=20because=20a=20slipped=20click=20costs?=
 =?UTF-8?q?=20a=20password=20re-entry.=20Stale=20comments=20in=20nav.ts=20?=
 =?UTF-8?q?and=20AppShell=20that=20still=20claimed=20the=20search=20entry?=
 =?UTF-8?q?=20lived=20in=20the=20sidebar=20are=20corrected=20in=20the=20sa?=
 =?UTF-8?q?me=20pass.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/console/index.html                   |  3 +-
 packages/console/src/components/AppShell.tsx  |  2 +-
 .../console/src/components/AppSidebar.tsx     | 63 ++++++++-----
 .../console/src/components/CommandMenu.tsx    | 90 ++++++++-----------
 packages/console/src/components/nav.ts        |  6 +-
 packages/console/src/main.tsx                 |  4 +-
 6 files changed, 88 insertions(+), 80 deletions(-)

diff --git a/packages/console/index.html b/packages/console/index.html
index 199ebb8..035f606 100644
--- a/packages/console/index.html
+++ b/packages/console/index.html
@@ -1,5 +1,6 @@
 <!doctype html>
-<html lang="zh-CN">
+<!-- 恒定暗色:class 直接烙在 html 上,JS 挂载前的首帧就不闪白。 -->
+<html lang="zh-CN" class="dark">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
diff --git a/packages/console/src/components/AppShell.tsx b/packages/console/src/components/AppShell.tsx
index e4b96c9..5c66b90 100644
--- a/packages/console/src/components/AppShell.tsx
+++ b/packages/console/src/components/AppShell.tsx
@@ -5,7 +5,7 @@ import { SidebarInset, SidebarProvider } from '@/components/ui/sidebar';
 
 /**
  * 登录后的应用外壳:侧边栏 + 页面内容。顶栏 2026-07-16 用户拍板删除:
- * 面包屑只是页面自带页头的第二份真相,⌘K 搜索入口随之移进侧栏
+ * 面包屑只是页面自带页头的第二份真相,⌘K 命令面板成为纯键盘入口
  * (CommandMenu),侧栏开关保留键盘位(⌘B,vendored sidebar 自带)。
  */
 export function AppShell() {
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index ad6042f..e67fbbf 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -1,15 +1,24 @@
 import {
+  ArrowUpRight01Icon,
   Book02Icon,
   GithubIcon,
   Logout01Icon,
-  Moon02Icon,
-  Sun02Icon,
 } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
 import { Link, useRouterState } from '@tanstack/react-router';
-import { useTheme } from 'next-themes';
+import { useState } from 'react';
 import { CommandMenu } from '@/components/CommandMenu';
 import { menuButtonClass, NAV_GROUPS } from '@/components/nav';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@/components/ui/alert-dialog';
 import {
   Sidebar,
   SidebarContent,
@@ -44,9 +53,9 @@ export function AppSidebar() {
   const pathname = useRouterState({
     select: (state) => state.location.pathname,
   });
-  const { resolvedTheme, setTheme } = useTheme();
   // 只读缓存:设置页查过且有新版本才亮,角标自己绝不发请求。
   const upgradable = useCachedUpgradable();
+  const [logoutConfirmOpen, setLogoutConfirmOpen] = useState(false);
 
   return (
     <Sidebar variant="inset" className="px-1">
@@ -60,10 +69,8 @@ export function AppSidebar() {
             Dormice
           </span>
         </Link>
-        {/* ⌘K 搜索入口:顶栏删掉后(2026-07-16)它是全站搜索唯一的可见入口。 */}
-        <SidebarMenu>
-          <CommandMenu />
-        </SidebarMenu>
+        {/* ⌘K 命令面板:纯键盘入口,组件只挂快捷键和弹窗,不渲染可见节点。 */}
+        <CommandMenu />
       </SidebarHeader>
 
       <SidebarContent>
@@ -121,6 +128,12 @@ export function AppSidebar() {
             >
               <HugeiconsIcon icon={GithubIcon} strokeWidth={2} />
               <span>GitHub</span>
+              {/* 右上角箭头 = 外链,新标签页打开的视觉承诺。 */}
+              <HugeiconsIcon
+                icon={ArrowUpRight01Icon}
+                strokeWidth={2}
+                className="ml-auto size-3.5 text-muted-foreground"
+              />
             </SidebarMenuButton>
           </SidebarMenuItem>
           <SidebarMenuItem>
@@ -136,30 +149,40 @@ export function AppSidebar() {
             >
               <HugeiconsIcon icon={Book02Icon} strokeWidth={2} />
               <span>文档</span>
-            </SidebarMenuButton>
-          </SidebarMenuItem>
-          <SidebarMenuItem>
-            <SidebarMenuButton
-              className={menuButtonClass}
-              onClick={() =>
-                setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')
-              }
-            >
               <HugeiconsIcon
-                icon={resolvedTheme === 'dark' ? Sun02Icon : Moon02Icon}
+                icon={ArrowUpRight01Icon}
                 strokeWidth={2}
+                className="ml-auto size-3.5 text-muted-foreground"
               />
-              <span>{resolvedTheme === 'dark' ? '浅色模式' : '深色模式'}</span>
             </SidebarMenuButton>
           </SidebarMenuItem>
           <SidebarMenuItem>
-            <SidebarMenuButton className={menuButtonClass} onClick={signOut}>
+            <SidebarMenuButton
+              className={menuButtonClass}
+              onClick={() => setLogoutConfirmOpen(true)}
+            >
               <HugeiconsIcon icon={Logout01Icon} strokeWidth={2} />
               <span>退出登录</span>
             </SidebarMenuButton>
           </SidebarMenuItem>
         </SidebarMenu>
       </SidebarFooter>
+
+      {/* 退出确认:不是不可逆操作,但会话没了要重输密码,值得拦一下手滑。 */}
+      <AlertDialog open={logoutConfirmOpen} onOpenChange={setLogoutConfirmOpen}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>退出登录?</AlertDialogTitle>
+            <AlertDialogDescription>
+              退出后需要重新输入密码才能进入控制台。
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>再待会儿</AlertDialogCancel>
+            <AlertDialogAction onClick={signOut}>退出</AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
     </Sidebar>
   );
 }
diff --git a/packages/console/src/components/CommandMenu.tsx b/packages/console/src/components/CommandMenu.tsx
index 5deea3b..32f5cd4 100644
--- a/packages/console/src/components/CommandMenu.tsx
+++ b/packages/console/src/components/CommandMenu.tsx
@@ -1,12 +1,8 @@
-import {
-  ArrowRight01Icon,
-  PackageIcon,
-  Search01Icon,
-} from '@hugeicons/core-free-icons';
+import { ArrowRight01Icon, PackageIcon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
 import { useNavigate } from '@tanstack/react-router';
 import { useEffect, useState } from 'react';
-import { menuButtonClass, NAV_GROUPS } from '@/components/nav';
+import { NAV_GROUPS } from '@/components/nav';
 import {
   CommandDialog,
   CommandEmpty,
@@ -15,8 +11,6 @@ import {
   CommandItem,
   CommandList,
 } from '@/components/ui/command';
-import { Kbd } from '@/components/ui/kbd';
-import { SidebarMenuButton, SidebarMenuItem } from '@/components/ui/sidebar';
 import { STATE_LABELS } from '@/features/sandboxes/format';
 import { useSandboxes } from '@/features/sandboxes/hooks/useSandboxes';
 import { MOCK_PAGES_ENABLED } from '@/lib/mock';
@@ -50,10 +44,10 @@ function SandboxItems({ onGo }: { onGo: (name: string) => void }) {
 }
 
 /**
- * ⌘K / Ctrl+K 命令面板:跳页面、按 name 跳沙箱。入口是侧栏顶部的
- * 菜单项(顶栏 2026-07-16 删除:面包屑与页面自带页头是第二份真相),
- * 登录后全站可用;它只做导航 — 动作(销毁/重建)留在各自页面的确认
- * 流程里,快捷键不该绕过"删了就没有了"的那道闸。
+ * ⌘K / Ctrl+K 命令面板:跳页面、按 name 跳沙箱。纯键盘入口(2026-07-16
+ * 用户拍板去掉侧栏搜索按钮,快捷键是唯一门),组件不渲染可见节点、只挂
+ * 快捷键和弹窗,登录后全站可用;它只做导航 — 动作(销毁/重建)留在各自
+ * 页面的确认流程里,快捷键不该绕过"删了就没有了"的那道闸。
  */
 export function CommandMenu() {
   const [open, setOpen] = useState(false);
@@ -84,47 +78,35 @@ export function CommandMenu() {
   };
 
   return (
-    <>
-      <SidebarMenuItem>
-        <SidebarMenuButton
-          className={menuButtonClass}
-          onClick={() => setOpen(true)}
-        >
-          <HugeiconsIcon icon={Search01Icon} strokeWidth={2} />
-          <span>搜索</span>
-          <Kbd className="ml-auto">⌘K</Kbd>
-        </SidebarMenuButton>
-      </SidebarMenuItem>
-      <CommandDialog
-        open={open}
-        onOpenChange={setOpen}
-        title="命令面板"
-        description="跳转到页面或沙箱"
-      >
-        <CommandInput placeholder="搜页面、沙箱" />
-        <CommandList>
-          <CommandEmpty>没有匹配的结果。</CommandEmpty>
-          <CommandGroup heading="页面">
-            {NAV_GROUPS.flatMap((group) => group.items)
-              .filter((item) => !item.mock || MOCK_PAGES_ENABLED)
-              .map((item) => (
-                <CommandItem
-                  key={item.to}
-                  value={`page ${item.label}`}
-                  onSelect={() => goPage(item.to)}
-                >
-                  <HugeiconsIcon icon={item.icon} strokeWidth={1.8} />
-                  {item.label}
-                  <HugeiconsIcon
-                    icon={ArrowRight01Icon}
-                    className="ml-auto size-3.5 text-muted-foreground"
-                  />
-                </CommandItem>
-              ))}
-          </CommandGroup>
-          {open && <SandboxItems onGo={goSandbox} />}
-        </CommandList>
-      </CommandDialog>
-    </>
+    <CommandDialog
+      open={open}
+      onOpenChange={setOpen}
+      title="命令面板"
+      description="跳转到页面或沙箱"
+    >
+      <CommandInput placeholder="搜页面、沙箱" />
+      <CommandList>
+        <CommandEmpty>没有匹配的结果。</CommandEmpty>
+        <CommandGroup heading="页面">
+          {NAV_GROUPS.flatMap((group) => group.items)
+            .filter((item) => !item.mock || MOCK_PAGES_ENABLED)
+            .map((item) => (
+              <CommandItem
+                key={item.to}
+                value={`page ${item.label}`}
+                onSelect={() => goPage(item.to)}
+              >
+                <HugeiconsIcon icon={item.icon} strokeWidth={1.8} />
+                {item.label}
+                <HugeiconsIcon
+                  icon={ArrowRight01Icon}
+                  className="ml-auto size-3.5 text-muted-foreground"
+                />
+              </CommandItem>
+            ))}
+        </CommandGroup>
+        {open && <SandboxItems onGo={goSandbox} />}
+      </CommandList>
+    </CommandDialog>
   );
 }
diff --git a/packages/console/src/components/nav.ts b/packages/console/src/components/nav.ts
index c7300a3..934dfd1 100644
--- a/packages/console/src/components/nav.ts
+++ b/packages/console/src/components/nav.ts
@@ -21,8 +21,8 @@ export interface NavItem {
 }
 
 // 平台 = 管的对象(沙箱/模板),运维 = 管这台机器;连接页是给要接 SDK 的人。
-// 独立成文件:侧栏与命令面板(⌘K)都要这份清单,而搜索入口住在侧栏里,
-// 留在任何一边都会让两个组件互相 import。页面清单只有这一份,两处永远一致。
+// 独立成文件:侧栏与命令面板(⌘K)都要这份清单,留在任何一边都会让
+// 两个组件互相 import。页面清单只有这一份,两处永远一致。
 export const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
   {
     label: '平台',
@@ -51,5 +51,5 @@ export const NAV_GROUPS: Array<{ label: string; items: NavItem[] }> = [
 
 // 侧栏按钮统一药丸形 + medium 字重(风格参考 openasi 侧栏,2026-07-12)。
 // cursor-default 抹平 Link(手型)与 button(箭头)的光标分裂 — 侧栏是
-// 应用 chrome,不是网页链接。搜索入口(CommandMenu)也穿这一件。
+// 应用 chrome,不是网页链接。
 export const menuButtonClass = 'rounded-full font-medium cursor-default';
diff --git a/packages/console/src/main.tsx b/packages/console/src/main.tsx
index e90dde0..c710d20 100644
--- a/packages/console/src/main.tsx
+++ b/packages/console/src/main.tsx
@@ -20,7 +20,9 @@ declare module '@tanstack/react-router' {
 // biome-ignore lint/style/noNonNullAssertion: index.html always has #root
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
-    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+    {/* 控制台恒定暗色(2026-07-16 用户拍板),forcedTheme 让 sonner 等
+        useTheme 消费者拿到一致答案,不给亮色留后门。 */}
+    <ThemeProvider attribute="class" defaultTheme="dark" forcedTheme="dark">
       <QueryClientProvider client={queryClient}>
         <RouterProvider router={router} />
       </QueryClientProvider>

From 8f8fd27e12083957d96121f6989b185bd243f9eb Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Fri, 17 Jul 2026 23:41:28 +0800
Subject: [PATCH 101/133] =?UTF-8?q?The=20activity=20ring=20learns=20who:?=
 =?UTF-8?q?=20every=20event=20now=20carries=20an=20actor=20=E2=80=94=20'en?=
 =?UTF-8?q?v-token',=20'console',=20or=20'apikey:<id>'=20(by=20id,=20becau?=
 =?UTF-8?q?se=20names=20became=20renameable=20this=20same=20week=20and=20r?=
 =?UTF-8?q?evoked=20rows=20are=20never=20deleted,=20so=20the=20id=20always?=
 =?UTF-8?q?=20translates=20back=20to=20a=20display=20name),=20with=20null?=
 =?UTF-8?q?=20reserved=20for=20moves=20no=20credential=20asked=20for:=20th?=
 =?UTF-8?q?e=20idle=20scanner,=20the=20reconciler,=20the=20archiver,=20and?=
 =?UTF-8?q?=20data-plane=20wakes=20that=20carry=20no=20ledger=20credential?=
 =?UTF-8?q?.=20Identity=20is=20captured=20where=20it=20was=20already=20bei?=
 =?UTF-8?q?ng=20adjudicated=20and=20then=20thrown=20away=20=E2=80=94=20ver?=
 =?UTF-8?q?ifyCredential=20grows=20into=20identifyCredential,=20admission?=
 =?UTF-8?q?=20and=20attribution=20being=20the=20same=20act=20=E2=80=94=20a?=
 =?UTF-8?q?nd=20both=20auth=20faces=20ride=20the=20answer=20on=20request.a?=
 =?UTF-8?q?ctor,=20so=20no=20route=20re-derives=20who=20is=20calling;=20th?=
 =?UTF-8?q?e=20lifecycle=20verbs=20take=20an=20actor=20beside=20their=20ex?=
 =?UTF-8?q?isting=20cause,=20and=20the=20daemon's=20own=20callers=20pass?=
 =?UTF-8?q?=20nothing=20and=20stay=20honestly=20null.=20This=20turns=20dis?=
 =?UTF-8?q?able/expiry=20into=20a=20complete=20incident-response=20story:?=
 =?UTF-8?q?=20suspect=20a=20leak,=20disable=20to=20stop=20the=20bleeding,?=
 =?UTF-8?q?=20filter=20the=20ring=20by=20that=20key=20to=20read=20its=20bl?=
 =?UTF-8?q?ast=20radius,=20revoke=20and=20rotate=20=E2=80=94=20the=20conso?=
 =?UTF-8?q?le's=20activity=20page=20and=20the=20sandbox=20history=20tab=20?=
 =?UTF-8?q?grow=20an=20operator=20column=20and=20an=20actor=20filter=20for?=
 =?UTF-8?q?=20exactly=20that=20read,=20resolving=20apikey:<id>=20through?=
 =?UTF-8?q?=20the=20keys=20list=20the=20two=20pages=20already=20share.=20T?=
 =?UTF-8?q?he=20attribution=20is=20bounded=20the=20way=20the=20ring=20itse?=
 =?UTF-8?q?lf=20is:=20lifecycle=20verbs=20only,=20never=20exec=20or=20file?=
 =?UTF-8?q?=20traffic=20(which=20would=20flush=20the=201000-entry=20window?=
 =?UTF-8?q?=20in=20minutes)=20=E2=80=94=20a=20real=20audit=20log=20remains?=
 =?UTF-8?q?=20deliberately=20not=20this.=20Migration=200013=20is=20the=20o?=
 =?UTF-8?q?ne=20nullable=20column;=20pre-attribution=20rows=20read=20null?=
 =?UTF-8?q?=20and=20prune=20away=20within=20days.=20The=20'per-request=20a?=
 =?UTF-8?q?ttribution=20deliberately=20not=20done'=20doctrine=20is=20rewri?=
 =?UTF-8?q?tten=20rather=20than=20quietly=20contradicted:=20its=20cost=20a?=
 =?UTF-8?q?rgument=20was=20overtaken=20when=20the=20admin-gate=20refactor?=
 =?UTF-8?q?=20put=20the=20key=20row=20in=20the=20verifier's=20hand,=20leav?=
 =?UTF-8?q?ing=20attribution=20to=20cost=20one=20field,=20not=20a=20re-arc?=
 =?UTF-8?q?hitecture.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 e2e/src/native.test.ts                        |  16 +
 .../console/src/features/activity/actors.ts   |  29 +
 .../features/activity/pages/ActivityPage.tsx  |  45 +-
 .../sandboxes/components/HistoryPanel.tsx     |  12 +-
 .../server/drizzle/0013_activity-actor.sql    |   1 +
 .../server/drizzle/meta/0013_snapshot.json    | 559 ++++++++++++++++++
 packages/server/drizzle/meta/_journal.json    |   7 +
 packages/server/src/app.test.ts               |  90 +++
 packages/server/src/app.ts                    |  33 +-
 packages/server/src/auth.ts                   |  41 +-
 packages/server/src/db/activity.ts            |   8 +
 packages/server/src/db/api-keys.ts            |  32 +-
 packages/server/src/db/ledger.ts              |   6 +
 packages/server/src/db/schema.ts              |   7 +
 packages/server/src/e2b/compat.test.ts        |  34 ++
 packages/server/src/e2b/control.ts            |  23 +-
 packages/server/src/e2b/deps.ts               |   7 +-
 packages/server/src/e2b/protocol.ts           |  15 +-
 packages/server/src/lifecycle.ts              |  31 +-
 packages/server/src/routes/api-keys.ts        |  10 +-
 packages/server/src/routes/ingress.ts         |   1 +
 packages/server/src/routes/sandboxes.ts       |  31 +-
 packages/server/src/routes/upgrade.ts         |   3 +-
 packages/shared/src/activity.ts               |  43 +-
 website/content/docs/console.mdx              |   7 +-
 website/content/docs/http-api.mdx             |  18 +-
 26 files changed, 1040 insertions(+), 69 deletions(-)
 create mode 100644 packages/console/src/features/activity/actors.ts
 create mode 100644 packages/server/drizzle/0013_activity-actor.sql
 create mode 100644 packages/server/drizzle/meta/0013_snapshot.json

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index 8684b2d..3951ddf 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -433,6 +433,20 @@ describe('native API over a real daemon', () => {
     const mine = listed.find((k) => k.name === 'rotation');
     expect(mine?.lastUsedAt).not.toBeNull();
 
+    // Attribution answers the blast-radius question: the key's work carries
+    // its id, and the mint (done above on the env token) says who minted.
+    const story = await client().listActivity({ limit: 500 });
+    const keyWork = story.filter((e) => e.sandboxName === 'rotation-key');
+    expect(keyWork.map((e) => e.actor)).toEqual([
+      `apikey:${apiKey.id}`,
+      `apikey:${apiKey.id}`,
+    ]);
+    expect(
+      story.find(
+        (e) => e.kind === 'apikey-created' && e.detail.includes('"rotation"'),
+      )?.actor,
+    ).toBe('env-token');
+
     // Key-manages-key is refused with the honest 403 — a leaked key must
     // not be able to mint itself an unrevoked successor.
     await expect(keyed.listApiKeys()).rejects.toMatchObject({
@@ -630,6 +644,8 @@ describe('the observability verbs over a real daemon', () => {
     const mine = events.filter((e) => e.sandboxName === 'obs-story-key');
     expect(mine.map((e) => e.kind)).toEqual(['destroyed', 'created']);
     expect(mine[1]?.detail).toContain('acquireSandbox');
+    // Attribution: this suite runs on the env token, and the events say so.
+    expect(mine.map((e) => e.actor)).toEqual(['env-token', 'env-token']);
   });
 
   it('getSandboxMetricsHistory fills up as the sampler ticks, and 404s after destroy', async () => {
diff --git a/packages/console/src/features/activity/actors.ts b/packages/console/src/features/activity/actors.ts
new file mode 100644
index 0000000..139c510
--- /dev/null
+++ b/packages/console/src/features/activity/actors.ts
@@ -0,0 +1,29 @@
+import {
+  type ApiKey,
+  apiKeyActorId,
+  CONSOLE_ACTOR,
+  ENV_TOKEN_ACTOR,
+} from '@dormice/shared';
+
+/**
+ * 操作者的中文翻译 — kinds.ts 是 kind 的唯一翻译点,这里是 actor 的。
+ * 词表在 shared/activity.ts:'env-token' / 'console' / 'apikey:<id>' /
+ * null(=daemon 自动作业:闲置扫描、对账、归档,或不带账本凭证的数据面
+ * 唤醒)。key 按 id 归因(名字可改、id 才稳定),显示时经密钥列表翻译回
+ * 当前名 — 吊销是软删除、行永不消失,所以 id 永远翻得回来;密钥列表还
+ * 没到手时退回截断 id,不装懂。词表之外的字符串原样示人,不翻译也不吞。
+ */
+export function actorLabel(
+  actor: string | null,
+  apiKeys: Pick<ApiKey, 'id' | 'name'>[] | undefined,
+): string {
+  if (actor === null) return '系统';
+  if (actor === ENV_TOKEN_ACTOR) return '引导凭证';
+  if (actor === CONSOLE_ACTOR) return '控制台';
+  const keyId = apiKeyActorId(actor);
+  if (keyId !== null) {
+    const key = apiKeys?.find((k) => k.id === keyId);
+    return `密钥 ${key ? key.name : keyId.slice(0, 8)}`;
+  }
+  return actor;
+}
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index 3a050a4..73f71af 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -26,23 +26,35 @@ import {
   TableHeader,
   TableRow,
 } from '@/components/ui/table';
+import { useApiKeys } from '@/features/api-keys/hooks/useApiKeys';
 import { since } from '@/features/sandboxes/format';
 import { cn } from '@/lib/utils';
+import { actorLabel } from '../actors';
 import { useActivity } from '../hooks/useActivity';
 import { ACTIVITY_KIND_LABELS, ACTIVITY_KIND_STYLES } from '../kinds';
 
 const PAGE_SIZE = 50;
 
+/**
+ * 筛选器里 actor=null(系统)的哨兵值。词表是封闭的('env-token' /
+ * 'console' / 'apikey:<id>'),裸串 'system' 永不与真实 actor 相撞。
+ */
+const SYSTEM_ACTOR_FILTER = 'system';
+
 /**
  * 「我不在的时候发生了什么」:daemon 每一次生命周期动作(创建、降温、
  * 唤醒、销毁)和对账修复的有界环形记录 — 事件写在动作发生处,这里只读。
  * 筛选是纯前端的:环一共就 1000 条,全在手里,没必要为过滤发明服务端
- * 参数。
+ * 参数。操作者列回答事故响应的第一问(「这把 key 干了什么」):按 kind
+ * 之外再按 actor 筛,就是那把 key 的爆炸半径。
  */
 export function ActivityPage() {
   const { data, isPending, isError, error } = useActivity();
+  // 只为把 apikey:<id> 翻译回名字;密钥页共用一份缓存。
+  const apiKeys = useApiKeys().data?.apiKeys;
   const [search, setSearch] = useState('');
   const [kindFilter, setKindFilter] = useState<'all' | ActivityKind>('all');
+  const [actorFilter, setActorFilter] = useState('');
   const [page, setPage] = useState(1);
 
   const events = data?.events ?? [];
@@ -51,13 +63,25 @@ export function ActivityPage() {
       events.filter(
         (event) =>
           (kindFilter === 'all' || event.kind === kindFilter) &&
+          (actorFilter === '' ||
+            (actorFilter === SYSTEM_ACTOR_FILTER
+              ? event.actor === null
+              : event.actor === actorFilter)) &&
           (search === '' ||
             (event.sandboxName ?? '')
               .toLowerCase()
               .includes(search.toLowerCase())),
       ),
-    [events, kindFilter, search],
+    [events, kindFilter, actorFilter, search],
   );
+  // 选项来自数据里实际出现过的操作者 — 不虚构没干过活的候选。
+  const actorOptions = useMemo(() => {
+    const seen = new Set(events.map((event) => event.actor));
+    return [...seen].map((actor) => ({
+      value: actor ?? SYSTEM_ACTOR_FILTER,
+      label: actorLabel(actor, apiKeys),
+    }));
+  }, [events, apiKeys]);
   const { rows, safePage, pageCount } = paginate(filtered, page, PAGE_SIZE);
 
   return (
@@ -98,6 +122,15 @@ export function ActivityPage() {
             setPage(1);
           }}
         />
+        <FilterMenu
+          label="操作者"
+          value={actorFilter}
+          options={actorOptions}
+          onChange={(value) => {
+            setActorFilter(value);
+            setPage(1);
+          }}
+        />
         <span className="text-sm text-muted-foreground">
           {filtered.length} / {events.length} 条
         </span>
@@ -138,6 +171,7 @@ export function ActivityPage() {
               <TableHead className="w-28">时间</TableHead>
               <TableHead className="w-28">事件</TableHead>
               <TableHead className="w-40">名称</TableHead>
+              <TableHead className="w-32">操作者</TableHead>
               <TableHead>详情</TableHead>
             </TableRow>
           </TableHeader>
@@ -176,6 +210,13 @@ export function ActivityPage() {
                     <span className="text-muted-foreground">—</span>
                   )}
                 </TableCell>
+                <TableCell
+                  className={cn(
+                    event.actor === null && 'text-muted-foreground',
+                  )}
+                >
+                  {actorLabel(event.actor, apiKeys)}
+                </TableCell>
                 <TableCell className="text-muted-foreground">
                   {event.detail}
                 </TableCell>
diff --git a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
index a07602f..e01b34d 100644
--- a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
@@ -17,21 +17,25 @@ import {
   TableHeader,
   TableRow,
 } from '@/components/ui/table';
+import { actorLabel } from '@/features/activity/actors';
 import { useActivity } from '@/features/activity/hooks/useActivity';
 import {
   ACTIVITY_KIND_LABELS,
   ACTIVITY_KIND_STYLES,
 } from '@/features/activity/kinds';
+import { useApiKeys } from '@/features/api-keys/hooks/useApiKeys';
 import { cn } from '@/lib/utils';
 import { since } from '../format';
 
 /**
  * 「我的沙箱昨晚为什么停了」— 活动环里只属于这个沙箱的那几行。纯前端
  * 过滤:活动事件本来就带 name,不发明新端点;按环形表上限(1000)
- * 拉取,把这个沙箱的事件尽量捞全,再老的已经滚出环了。
+ * 拉取,把这个沙箱的事件尽量捞全,再老的已经滚出环了。操作者列在这里
+ * 尤其要紧:同一个沙箱被谁唤醒、被谁销毁,就是这一列的答案。
  */
 export function HistoryPanel({ name }: { name: string }) {
   const { data, isPending, isError, error } = useActivity(1000);
+  const apiKeys = useApiKeys().data?.apiKeys;
   const events = (data?.events ?? []).filter(
     (event) => event.sandboxName === name,
   );
@@ -76,6 +80,7 @@ export function HistoryPanel({ name }: { name: string }) {
           <TableRow>
             <TableHead className="w-28">时间</TableHead>
             <TableHead className="w-28">事件</TableHead>
+            <TableHead className="w-32">操作者</TableHead>
             <TableHead>详情</TableHead>
           </TableRow>
         </TableHeader>
@@ -99,6 +104,11 @@ export function HistoryPanel({ name }: { name: string }) {
                   {ACTIVITY_KIND_LABELS[event.kind]}
                 </Badge>
               </TableCell>
+              <TableCell
+                className={cn(event.actor === null && 'text-muted-foreground')}
+              >
+                {actorLabel(event.actor, apiKeys)}
+              </TableCell>
               <TableCell className="text-muted-foreground">
                 {event.detail}
               </TableCell>
diff --git a/packages/server/drizzle/0013_activity-actor.sql b/packages/server/drizzle/0013_activity-actor.sql
new file mode 100644
index 0000000..7eb7a76
--- /dev/null
+++ b/packages/server/drizzle/0013_activity-actor.sql
@@ -0,0 +1 @@
+ALTER TABLE `activity` ADD `actor` text;
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/0013_snapshot.json b/packages/server/drizzle/meta/0013_snapshot.json
new file mode 100644
index 0000000..f9c9799
--- /dev/null
+++ b/packages/server/drizzle/meta/0013_snapshot.json
@@ -0,0 +1,559 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "da4ece11-991e-4828-a929-998a3b71244b",
+  "prevId": "aa76853b-453d-43c0-945f-8afd07a827a4",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_name": {
+          "name": "sandbox_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "actor": {
+          "name": "actor",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "api_keys": {
+      "name": "api_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "prefix": {
+          "name": "prefix",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "disabled_at": {
+          "name": "disabled_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "api_keys_key_hash_unique": {
+          "name": "api_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        },
+        "api_keys_active_name_idx": {
+          "name": "api_keys_active_name_idx",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true,
+          "where": "\"api_keys\".\"revoked_at\" IS NULL"
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "daemon_secrets": {
+      "name": "daemon_secrets",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "envd_signing_secret": {
+          "name": "envd_signing_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "fleet_snapshots": {
+      "name": "fleet_snapshots",
+      "columns": {
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active": {
+          "name": "active",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "frozen": {
+          "name": "frozen",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stopped": {
+          "name": "stopped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archived": {
+          "name": "archived",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "restoring": {
+          "name": "restoring",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "total": {
+          "name": "total",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandbox_metrics_samples": {
+      "name": "sandbox_metrics_samples",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_count": {
+          "name": "cpu_count",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_used_pct": {
+          "name": "cpu_used_pct",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_used_bytes": {
+          "name": "mem_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_total_bytes": {
+          "name": "mem_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_cache_bytes": {
+          "name": "mem_cache_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_used_bytes": {
+          "name": "disk_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_total_bytes": {
+          "name": "disk_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "sandbox_metrics_samples_sandbox_at_idx": {
+          "name": "sandbox_metrics_samples_sandbox_at_idx",
+          "columns": [
+            "sandbox_id",
+            "at"
+          ],
+          "isUnique": false
+        },
+        "sandbox_metrics_samples_at_idx": {
+          "name": "sandbox_metrics_samples_at_idx",
+          "columns": [
+            "at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_name_unique": {
+          "name": "sandboxes_name_unique",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index c576e8d..cb770d0 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -92,6 +92,13 @@
       "when": 1784190171073,
       "tag": "0012_apikey-expiry-disable",
       "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "6",
+      "when": 1784208918062,
+      "tag": "0013_activity-actor",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index 9b12c8e..e5daa7b 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -1869,3 +1869,93 @@ describe('API keys', () => {
     expect(res.statusCode).toBe(200);
   });
 });
+
+describe('activity attribution', () => {
+  /**
+   * The newest event of this kind (listActivity is newest-first),
+   * optionally narrowed to one sandbox. Actor strings are asserted as
+   * literals on purpose: they are wire vocabulary, and a drifted constant
+   * must fail here, not ride through.
+   */
+  const eventOf = async (
+    app: ReturnType<typeof testApp>['app'],
+    kind: string,
+    sandboxName?: string,
+  ) => {
+    const events = (await rpc(app, '/listActivity')).json().events as Array<{
+      kind: string;
+      sandboxName: string | null;
+      actor: string | null;
+    }>;
+    return events.find(
+      (e) =>
+        e.kind === kind &&
+        (sandboxName === undefined || e.sandboxName === sandboxName),
+    );
+  };
+
+  it('lifecycle verbs name their credential: env token and API key are distinct actors', async () => {
+    const { app } = testApp();
+    const minted = (await rpc(app, '/createApiKey', { name: 'agent' })).json();
+    const asKey = { authorization: `Bearer ${minted.token}` };
+
+    await acquire(app, { name: 'mine' });
+    await acquire(app, { name: 'theirs' }, asKey);
+    expect((await eventOf(app, 'created', 'mine'))?.actor).toBe('env-token');
+    expect((await eventOf(app, 'created', 'theirs'))?.actor).toBe(
+      `apikey:${minted.apiKey.id}`,
+    );
+
+    // The blast-radius question a leak raises: which key destroyed this?
+    await app.inject({
+      method: 'POST',
+      url: '/destroySandbox',
+      headers: asKey,
+      payload: { name: 'mine' },
+    });
+    expect((await eventOf(app, 'destroyed', 'mine'))?.actor).toBe(
+      `apikey:${minted.apiKey.id}`,
+    );
+  });
+
+  it('daemon moves stay null; the wake that follows names its caller', async () => {
+    const { app, db, executor, locks } = testApp();
+    const created = (await acquire(app, { name: 'alice' })).json();
+
+    await scanOnce(
+      db,
+      executor,
+      locks,
+      after(
+        created.sandbox.lastActiveAt,
+        DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
+      ),
+    );
+    // The idle scanner froze it: no credential asked, so no actor.
+    expect((await eventOf(app, 'frozen', 'alice'))?.actor).toBeNull();
+
+    await acquire(app, { name: 'alice' });
+    expect((await eventOf(app, 'woken', 'alice'))?.actor).toBe('env-token');
+  });
+
+  it('apikey management events name the administrator: env token or console, never a key', async () => {
+    const { app } = testApp();
+    await rpc(app, '/createApiKey', { name: 'by-env' });
+    expect((await eventOf(app, 'apikey-created'))?.actor).toBe('env-token');
+
+    const setup = await app.inject({
+      method: 'POST',
+      url: '/console/auth/setup',
+      payload: { token: TOKEN, username: 'operator', password: 'horse pass' },
+    });
+    const cookie = setup.cookies.find((c) => c.name === SESSION_COOKIE);
+    await app.inject({
+      method: 'POST',
+      url: '/createApiKey',
+      headers: { [CONSOLE_HEADER]: '1' },
+      cookies: { [SESSION_COOKIE]: (cookie as { value: string }).value },
+      payload: { name: 'by-console' },
+    });
+    expect((await eventOf(app, 'apikey-created'))?.actor).toBe('console');
+  });
+});
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 20164fe..a118d7c 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -1,5 +1,6 @@
 import http from 'node:http';
 import nodePath from 'node:path';
+import { apiKeyActor, ENV_TOKEN_ACTOR } from '@dormice/shared';
 import fastifyCookie from '@fastify/cookie';
 import fastify, { type FastifyError, type FastifyServerFactory } from 'fastify';
 import {
@@ -187,21 +188,33 @@ export function buildApp({
   // cookie on the native routes, the /console surface mints and clears it.
   app.register(fastifyCookie);
 
-  // The one adjudication of "does this bare credential open the door":
-  // the env token (constant-time compare — the bootstrap credential, always
-  // valid) or any active ledger API key (sha256 indexed lookup, judged per
-  // request so a mint or revoke takes effect on the very next call). Both
-  // faces — the native Bearer header and the E2B X-API-KEY hook — feed this
-  // same closure: one truth, two dialects.
-  const verifyCredential = (bare: string): boolean =>
-    tokensEqual(bare, config.DORMICE_API_TOKEN) || verifyApiKeyToken(db, bare);
+  // Attribution rides the request from the auth hook that admitted it into
+  // every recordActivity the handler reaches. Declared once so the property
+  // shape is stable; null is what unauthenticated surfaces keep.
+  app.decorateRequest('actor', null);
+
+  // The one adjudication of "does this bare credential open the door" —
+  // and of who it is (the two are the same act, so identity is captured
+  // here, not re-derived later): the env token (constant-time compare —
+  // the bootstrap credential, always valid) or any active ledger API key
+  // (sha256 indexed lookup, judged per request so a mint or revoke takes
+  // effect on the very next call). Both faces — the native Bearer header
+  // and the E2B X-API-KEY hook — feed this same closure: one truth, two
+  // dialects.
+  const identifyCredential = (bare: string): string | null => {
+    if (tokensEqual(bare, config.DORMICE_API_TOKEN)) {
+      return ENV_TOKEN_ACTOR;
+    }
+    const keyId = verifyApiKeyToken(db, bare);
+    return keyId === null ? null : apiKeyActor(keyId);
+  };
 
   // Built once, used by every guarded surface. The secret getter reads the
   // ledger per request because setup can replace the account (and void its
   // sessions) while the daemon runs — a captured value would keep dead
   // sessions alive until restart.
   const apiAuth = requireApiAuth(
-    verifyCredential,
+    identifyCredential,
     () => getConsoleAccount(db)?.sessionSecret ?? null,
   );
 
@@ -280,7 +293,7 @@ export function buildApp({
       archiver,
       archiveDefaultSeconds,
       envdSigningSecret,
-      verifyCredential,
+      identifyCredential,
     });
   });
 
diff --git a/packages/server/src/auth.ts b/packages/server/src/auth.ts
index ac24355..a445d2a 100644
--- a/packages/server/src/auth.ts
+++ b/packages/server/src/auth.ts
@@ -6,8 +6,23 @@ import {
   scrypt,
   timingSafeEqual,
 } from 'node:crypto';
+import { CONSOLE_ACTOR, ENV_TOKEN_ACTOR } from '@dormice/shared';
 import type { FastifyRequest, onRequestAsyncHookHandler } from 'fastify';
 
+declare module 'fastify' {
+  interface FastifyRequest {
+    /**
+     * Attribution: who this request is, in the shared actor vocabulary
+     * ('env-token' | 'console' | 'apikey:<id>'). Set by whichever auth hook
+     * admitted the request — authentication is the one moment identity is
+     * adjudicated, so it is captured there and threaded into recordActivity,
+     * never re-derived. Null only on unauthenticated surfaces (/healthz,
+     * console setup/login), which record no activity.
+     */
+    actor: string | null;
+  }
+}
+
 // Hand-rolled instead of util.promisify: promisify picks the overload
 // without the options argument, and the cost parameters live there.
 function scryptAsync(
@@ -160,27 +175,35 @@ function sessionCookieValid(
  * The single arbiter of who may call the API (/healthz stays open —
  * liveness probes have no secrets). Two credentials open the same door:
  * a Bearer credential (SDK, CLI, curl — the env token or any live API
- * key, adjudicated by verifyCredential) and the web console's session
+ * key, adjudicated by identifyCredential) and the web console's session
  * cookie (which additionally requires the console header, see above). A
  * second route surface with its own auth would be a second truth.
  *
- * verifyCredential judges bare tokens, so both faces (this Bearer header
- * and the E2B X-API-KEY hook) feed it the same canonical form — one
- * closure, one truth, two dialects. The 'Bearer ' prefix is public
+ * identifyCredential judges bare tokens and answers who they are (the
+ * shared actor vocabulary; null = not a credential), so both faces (this
+ * Bearer header and the E2B X-API-KEY hook) feed it the same canonical
+ * form — one closure, one truth, two dialects. Admission and attribution
+ * are the same adjudication: the actor rides the request from here into
+ * every recordActivity the handler reaches. The 'Bearer ' prefix is public
  * framing, not a secret, so stripping it needs no constant time; the
- * secret comparisons live inside verifyCredential.
+ * secret comparisons live inside identifyCredential.
  */
 export function requireApiAuth(
-  verifyCredential: (bareToken: string) => boolean,
+  identifyCredential: (bareToken: string) => string | null,
   getSessionSecret: () => string | null,
 ): onRequestAsyncHookHandler {
   return async (request, reply) => {
     const header = request.headers.authorization;
     const bare = header?.startsWith('Bearer ') ? header.slice(7) : null;
-    if (bare !== null && verifyCredential(bare)) {
-      return;
+    if (bare !== null) {
+      const actor = identifyCredential(bare);
+      if (actor !== null) {
+        request.actor = actor;
+        return;
+      }
     }
     if (sessionCookieValid(request, getSessionSecret)) {
+      request.actor = CONSOLE_ACTOR;
       return;
     }
     await reply.code(401).send({ message: 'missing or invalid API token' });
@@ -213,9 +236,11 @@ export function requireAdminAuth(
     const header = request.headers.authorization;
     const bare = header?.startsWith('Bearer ') ? header.slice(7) : null;
     if (bare !== null && isEnvToken(bare)) {
+      request.actor = ENV_TOKEN_ACTOR;
       return;
     }
     if (sessionCookieValid(request, getSessionSecret)) {
+      request.actor = CONSOLE_ACTOR;
       return;
     }
     if (bare !== null && isLiveApiKey(bare)) {
diff --git a/packages/server/src/db/activity.ts b/packages/server/src/db/activity.ts
index a1cd317..3f3845b 100644
--- a/packages/server/src/db/activity.ts
+++ b/packages/server/src/db/activity.ts
@@ -16,6 +16,13 @@ export interface ActivityInput {
   /** The owning sandbox's name/id — prefixed: they reference another entity. */
   sandboxName?: string | null;
   sandboxId?: string | null;
+  /**
+   * Which credential asked (shared/activity.ts vocabulary), threaded from
+   * request.actor by the route that took the request. Absent = null = the
+   * daemon's own doing — the honest default for the scanner, reconciler
+   * and archiver, which pass nothing.
+   */
+  actor?: string | null;
   detail: string;
 }
 
@@ -33,6 +40,7 @@ export function recordActivity(db: Db, input: ActivityInput): void {
       kind: input.kind,
       sandboxName: input.sandboxName ?? null,
       sandboxId: input.sandboxId ?? null,
+      actor: input.actor ?? null,
       detail: input.detail,
     })
     .run();
diff --git a/packages/server/src/db/api-keys.ts b/packages/server/src/db/api-keys.ts
index 6c514b0..546bc08 100644
--- a/packages/server/src/db/api-keys.ts
+++ b/packages/server/src/db/api-keys.ts
@@ -42,7 +42,8 @@ function normalizeIso(value: string): string {
 export function createApiKey(
   db: Db,
   name: string,
-  expiresAt?: string,
+  expiresAt: string | undefined,
+  actor: string | null,
 ): { row: ApiKeyRow; token: string } {
   const token = randomBytes(32).toString('hex');
   const row: ApiKeyRow = {
@@ -59,6 +60,9 @@ export function createApiKey(
   db.insert(apiKeys).values(row).run();
   recordActivity(db, {
     kind: 'apikey-created',
+    // The admin gate means this actor can only be env-token or console —
+    // a key can never appear as the minter of another key.
+    actor,
     detail:
       `API key "${name}" (prefix ${row.prefix}) minted` +
       (row.expiresAt ? `, expires ${row.expiresAt}` : ''),
@@ -101,7 +105,11 @@ export function listApiKeys(db: Db): ApiKeyRow[] {
  * or is already revoked — the desired end state was already true. The row
  * survives as history; the name is immediately free for a new key.
  */
-export function revokeApiKey(db: Db, id: string): boolean {
+export function revokeApiKey(
+  db: Db,
+  id: string,
+  actor: string | null,
+): boolean {
   const row = findApiKeyById(db, id);
   if (!row || row.revokedAt !== null) {
     return false;
@@ -112,6 +120,7 @@ export function revokeApiKey(db: Db, id: string): boolean {
     .run();
   recordActivity(db, {
     kind: 'apikey-revoked',
+    actor,
     detail: `API key "${row.name}" revoked`,
   });
   return true;
@@ -131,6 +140,7 @@ export function updateApiKey(
   db: Db,
   row: ApiKeyRow,
   patch: { name?: string; expiresAt?: string | null; disabled?: boolean },
+  actor: string | null,
 ): ApiKeyRow {
   const changes: Partial<ApiKeyRow> = {};
   const facts: {
@@ -176,7 +186,7 @@ export function updateApiKey(
   }
   db.update(apiKeys).set(changes).where(eq(apiKeys.id, row.id)).run();
   for (const fact of facts) {
-    recordActivity(db, fact);
+    recordActivity(db, { ...fact, actor });
   }
   return { ...row, ...changes };
 }
@@ -222,15 +232,17 @@ export function isLiveApiKey(db: Db, bareToken: string): boolean {
  * sha256(key), which preimage resistance makes worthless to an attacker
  * (the argument GitHub token storage rests on).
  *
- * A hit also stamps lastUsedAt — only a hit: verification is the one moment
- * a credential was actually honored. Throttled to LAST_USED_GRANULARITY_MS
- * so a polling client does not write the ledger per request. ISO strings
- * compare lexicographically as timestamps, so the cutoff is a plain string <.
+ * A hit answers the key's id (attribution's raw material — the auth hook
+ * dresses it as an actor and rides it on the request) and stamps lastUsedAt
+ * — only a hit: verification is the one moment a credential was actually
+ * honored. Throttled to LAST_USED_GRANULARITY_MS so a polling client does
+ * not write the ledger per request. ISO strings compare lexicographically
+ * as timestamps, so the cutoff is a plain string <.
  */
-export function verifyApiKeyToken(db: Db, bareToken: string): boolean {
+export function verifyApiKeyToken(db: Db, bareToken: string): string | null {
   const row = findLiveApiKeyByHash(db, hashApiKeyToken(bareToken));
   if (!row) {
-    return false;
+    return null;
   }
   const now = Date.now();
   const cutoff = new Date(now - LAST_USED_GRANULARITY_MS).toISOString();
@@ -243,5 +255,5 @@ export function verifyApiKeyToken(db: Db, bareToken: string): boolean {
       ),
     )
     .run();
-  return true;
+  return row.id;
 }
diff --git a/packages/server/src/db/ledger.ts b/packages/server/src/db/ledger.ts
index 4977a1e..b1b6318 100644
--- a/packages/server/src/db/ledger.ts
+++ b/packages/server/src/db/ledger.ts
@@ -53,6 +53,11 @@ export interface CreateSandboxInput {
     deadlineAt: string;
     onDeadline: 'kill' | 'pause';
   };
+  /**
+   * Who asked (request.actor) — every creation is request-caused, so both
+   * faces pass this; absent only in tests that fabricate rows directly.
+   */
+  actor?: string | null;
 }
 
 /** Inserts a new sandbox row in `active` state. Throws if the name is taken. */
@@ -81,6 +86,7 @@ export function createSandbox(db: Db, input: CreateSandboxInput): SandboxRow {
     kind: 'created',
     sandboxName: row.name,
     sandboxId: row.id,
+    actor: input.actor,
     detail: `${input.e2b ? 'via E2B create' : 'via acquireSandbox'}${
       input.template ? `, template ${input.template}` : ''
     }`,
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index c7367e7..6b16cb1 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -98,6 +98,13 @@ export const activity = sqliteTable('activity', {
   /** Null for events with no owning sandbox (orphan sweeps, daemon start). */
   sandboxName: text('sandbox_name'),
   sandboxId: text('sandbox_id'),
+  /**
+   * Which credential asked — the closed vocabulary in shared/activity.ts
+   * ('env-token' | 'console' | 'apikey:<id>'). Null = no credential did:
+   * the daemon's own actors, plus rows from before attribution existed
+   * (the ring prunes those away within days).
+   */
+  actor: text('actor'),
   detail: text('detail').notNull(),
 });
 
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index a275d11..851cddb 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -291,6 +291,40 @@ describe('E2B control plane', () => {
     expect(expired.json()).toEqual({ code: 401, message: 'invalid API key' });
   });
 
+  it('E2B-created sandboxes attribute to the key that asked', async () => {
+    const t = testApp();
+    const minted = (
+      await t.app.inject({
+        method: 'POST',
+        url: '/createApiKey',
+        headers: { authorization: `Bearer ${TOKEN}` },
+        payload: { name: 'e2b-agent' },
+      })
+    ).json();
+
+    const created = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/api/sandboxes',
+      headers: { 'x-api-key': `e2b_${minted.token}` },
+      payload: {},
+    });
+    expect(created.statusCode).toBe(201);
+
+    // Both faces feed the same identity closure, so the created event names
+    // the key — the same attribution the native Bearer face gets.
+    const events = (
+      await t.app.inject({
+        method: 'POST',
+        url: '/listActivity',
+        headers: { authorization: `Bearer ${TOKEN}` },
+        payload: {},
+      })
+    ).json().events as Array<{ kind: string; actor: string | null }>;
+    expect(events.find((e) => e.kind === 'created')?.actor).toBe(
+      `apikey:${minted.apiKey.id}`,
+    );
+  });
+
   it('creates a fresh sandbox per call — E2B semantics, no key given', async () => {
     const t = testApp();
     const first = await createSandbox(t);
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index 6b9f6f0..36541a5 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -32,8 +32,8 @@ import {
   apiError,
   E2bError,
   ENVD_VERSION,
+  identifyApiKey,
   mintEnvdToken,
-  verifyApiKey,
 } from './protocol';
 import { e2bView } from './view';
 
@@ -100,7 +100,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     archiver,
     archiveDefaultSeconds,
     envdSigningSecret,
-    verifyCredential,
+    identifyCredential,
   },
 ) => {
   /**
@@ -132,9 +132,12 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
   app.addHook('onRequest', async (request, reply) => {
     const presented = request.headers['x-api-key'];
     const key = Array.isArray(presented) ? presented[0] : presented;
-    if (!verifyApiKey(verifyCredential, key)) {
+    const actor = identifyApiKey(identifyCredential, key);
+    if (actor === null) {
       await reply.code(401).send({ code: 401, message: 'invalid API key' });
+      return;
     }
+    request.actor = actor;
   });
 
   // The E2B error dialect: every non-2xx body is { code, message } — the
@@ -300,7 +303,12 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
           // E2B clothes. Stored metadata/envs stay (same principle as the
           // native policy's "override applies at creation only"); the
           // deadline is extended like a connect.
-          const awake = await wakeSandbox(db, executor, existing);
+          const awake = await wakeSandbox(
+            db,
+            executor,
+            existing,
+            request.actor,
+          );
           extendDeadline(awake, timeoutSeconds);
           return touch(db, awake.id);
         }
@@ -315,6 +323,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
             {
               kind: 'destroyed',
               cause: 'protocol-dead row reaped by E2B create',
+              actor: request.actor,
             },
           );
         }
@@ -335,6 +344,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
           nodeId: config.DORMICE_NODE_ID,
           policy: resolvePolicy(undefined, archiveDefaultSeconds),
           template,
+          actor: request.actor,
           metadata:
             body.metadata && Object.keys(body.metadata).length > 0
               ? JSON.stringify(body.metadata)
@@ -372,7 +382,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         if (!fresh || e2bView(fresh, new Date()) === 'dead') {
           throw notFound(id);
         }
-        const awake = await wakeSandbox(db, executor, fresh);
+        const awake = await wakeSandbox(db, executor, fresh, request.actor);
         extendDeadline(awake, request.body.timeout ?? DEFAULT_TIMEOUT_SECONDS);
         return touch(db, awake.id);
       });
@@ -510,6 +520,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       await destroySandbox(db, executor, fresh.id, archiver?.store ?? null, {
         kind: 'destroyed',
         cause: 'via E2B kill',
+        actor: request.actor,
       });
     });
     return reply.code(204).send();
@@ -555,6 +566,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
             executor,
             current.id,
             'paused via E2B',
+            request.actor,
           );
         }
         // keepMemory:false maps to stopped: filesystem only, cold boot on
@@ -565,6 +577,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
             executor,
             current.id,
             'paused via E2B (memory discarded)',
+            request.actor,
           );
         }
         setPausedByUser(db, fresh.id, true);
diff --git a/packages/server/src/e2b/deps.ts b/packages/server/src/e2b/deps.ts
index 473f6a4..d0c6337 100644
--- a/packages/server/src/e2b/deps.ts
+++ b/packages/server/src/e2b/deps.ts
@@ -33,8 +33,9 @@ export interface E2bDeps {
   envdSigningSecret: string;
   /**
    * buildApp's one adjudication of "does this bare credential open the
-   * door" (env token or any active ledger API key) — the same closure the
-   * native Bearer face uses, consulted here by the X-API-KEY hook.
+   * door" and who it is (the shared actor vocabulary; null = not a
+   * credential) — the same closure the native Bearer face uses, consulted
+   * here by the X-API-KEY hook, which rides the answer on request.actor.
    */
-  verifyCredential: (bareToken: string) => boolean;
+  identifyCredential: (bareToken: string) => string | null;
 }
diff --git a/packages/server/src/e2b/protocol.ts b/packages/server/src/e2b/protocol.ts
index e8b1f26..33ce28c 100644
--- a/packages/server/src/e2b/protocol.ts
+++ b/packages/server/src/e2b/protocol.ts
@@ -86,16 +86,17 @@ export function verifyEnvdToken(
  * X-API-KEY check. The official SDK formats keys as `e2b_<hex>` and our
  * hex credentials are compliant as `e2b_<token>`; the bare token is
  * accepted too — the prefix is the SDK's convention, not a secret. What
- * opens the door is adjudicated by verifyCredential (buildApp's closure:
- * env token or any active ledger API key), the same truth the native
- * Bearer face consults.
+ * opens the door — and who it is — is adjudicated by identifyCredential
+ * (buildApp's closure: env token or any active ledger API key), the same
+ * truth the native Bearer face consults; the answer is the actor (null =
+ * refused).
  */
-export function verifyApiKey(
-  verifyCredential: (bareToken: string) => boolean,
+export function identifyApiKey(
+  identifyCredential: (bareToken: string) => string | null,
   presented: string | undefined,
-): boolean {
+): string | null {
   const bare = presented?.startsWith('e2b_') ? presented.slice(4) : presented;
-  return bare !== undefined && verifyCredential(bare);
+  return bare === undefined ? null : identifyCredential(bare);
 }
 
 /** Connect streaming envelope flags: 0x00 = message, 0x02 = end of stream. */
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index 1aa4a95..1061522 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -27,13 +27,16 @@ import type { Executor } from './executor/executor';
  * The lifecycle verbs also feed the activity ring here, after the ledger
  * write — history is recorded where reality and ledger already move
  * together, so no caller can forget it. `cause` is the caller's one line of
- * context ("who did this and why"); the default names the bare move.
+ * context ("why"); `actor` is who asked (request.actor's vocabulary) — the
+ * daemon's own callers (scanner, reconciler) pass neither, and the honest
+ * defaults name the bare move and no credential.
  */
 export async function freezeSandbox(
   db: Db,
   executor: Executor,
   sandboxId: string,
   cause?: string,
+  actor?: string | null,
 ): Promise<SandboxRow> {
   await executor.freeze(sandboxId);
   const row = transition(db, sandboxId, 'frozen');
@@ -41,6 +44,7 @@ export async function freezeSandbox(
     kind: 'frozen',
     sandboxName: row.name,
     sandboxId,
+    actor,
     detail: cause ?? 'memory squeezed into swap',
   });
   return row;
@@ -51,6 +55,7 @@ export async function stopSandbox(
   executor: Executor,
   sandboxId: string,
   cause?: string,
+  actor?: string | null,
 ): Promise<SandboxRow> {
   await executor.stop(sandboxId);
   const row = transition(db, sandboxId, 'stopped');
@@ -58,6 +63,7 @@ export async function stopSandbox(
     kind: 'stopped',
     sandboxName: row.name,
     sandboxId,
+    actor,
     detail: cause ?? 'container torn down, disk kept',
   });
   return row;
@@ -81,7 +87,11 @@ export async function destroySandbox(
   executor: Executor,
   sandboxId: string,
   store: ArchiveStore | null,
-  activity: { kind: 'destroyed' | 'expired-killed'; cause: string } = {
+  activity: {
+    kind: 'destroyed' | 'expired-killed';
+    cause: string;
+    actor?: string | null;
+  } = {
     kind: 'destroyed',
     cause: 'via destroySandbox',
   },
@@ -102,6 +112,7 @@ export async function destroySandbox(
       kind: activity.kind,
       sandboxName: row.name,
       sandboxId,
+      actor: activity.actor,
       detail: `${activity.cause}; archive object deleted`,
     });
     return;
@@ -114,6 +125,7 @@ export async function destroySandbox(
       kind: activity.kind,
       sandboxName: row.name,
       sandboxId,
+      actor: activity.actor,
       detail: activity.cause,
     });
   }
@@ -133,12 +145,14 @@ export async function rebuildSandbox(
   db: Db,
   executor: Executor,
   row: SandboxRow,
+  actor?: string | null,
 ): Promise<SandboxRow> {
   await executor.removeContainer(row.id);
   recordActivity(db, {
     kind: 'rebuilt',
     sandboxName: row.name,
     sandboxId: row.id,
+    actor,
     detail:
       'shell removed, disk kept — next wake builds from the current image',
   });
@@ -153,20 +167,21 @@ export async function wakeSandbox(
   db: Db,
   executor: Executor,
   row: SandboxRow,
+  actor?: string | null,
 ): Promise<SandboxRow> {
   switch (row.state) {
     case 'active':
       return row;
     case 'frozen':
       await executor.unfreeze(row.id);
-      return awaken(db, row, 'from frozen (memory back out of swap)');
+      return awaken(db, row, 'from frozen (memory back out of swap)', actor);
     case 'stopped':
       // If the container object was pruned away, start rebuilds the shell —
       // from the template's current image, resolved here at wake time.
       await executor.start(row.id, {
         image: resolveImage(db, row.template),
       });
-      return awaken(db, row, 'cold start from the surviving disk');
+      return awaken(db, row, 'cold start from the surviving disk', actor);
     case 'archived':
     case 'restoring':
       // Every legitimate path branches to the archiver before landing here
@@ -183,7 +198,12 @@ export async function wakeSandbox(
  * so any explicit E2B pause mark is cleared along with the transition —
  * ledger honesty, not an E2B-surface concern leaking in.
  */
-function awaken(db: Db, row: SandboxRow, how: string): SandboxRow {
+function awaken(
+  db: Db,
+  row: SandboxRow,
+  how: string,
+  actor?: string | null,
+): SandboxRow {
   if (row.pausedByUser) {
     setPausedByUser(db, row.id, false);
   }
@@ -192,6 +212,7 @@ function awaken(db: Db, row: SandboxRow, how: string): SandboxRow {
     kind: 'woken',
     sandboxName: row.name,
     sandboxId: row.id,
+    actor,
     detail: how,
   });
   return { ...awake, pausedByUser: false };
diff --git a/packages/server/src/routes/api-keys.ts b/packages/server/src/routes/api-keys.ts
index f1b7ba3..a75f476 100644
--- a/packages/server/src/routes/api-keys.ts
+++ b/packages/server/src/routes/api-keys.ts
@@ -45,7 +45,7 @@ function view(row: ApiKeyRow): ApiKey {
  * requireAdminAuth (env token or console session; a live key gets an
  * honest 403), because a credential must not manage the credential ledger
  * it lives in. Verification itself lives in db/api-keys.ts and is
- * consulted by buildApp's verifyCredential closure, not here.
+ * consulted by buildApp's identifyCredential closure, not here.
  */
 export const apiKeyRoutes: FastifyPluginAsyncZod<ApiKeyRoutesOptions> = async (
   app,
@@ -71,7 +71,7 @@ export const apiKeyRoutes: FastifyPluginAsyncZod<ApiKeyRoutesOptions> = async (
           `an active API key named '${name}' already exists — revoke it first or pick another name`,
         );
       }
-      const { row, token } = createApiKey(db, name, expiresAt);
+      const { row, token } = createApiKey(db, name, expiresAt, request.actor);
       return { apiKey: view(row), token };
     },
   );
@@ -119,7 +119,7 @@ export const apiKeyRoutes: FastifyPluginAsyncZod<ApiKeyRoutesOptions> = async (
           );
         }
       }
-      return { apiKey: view(updateApiKey(db, row, patch)) };
+      return { apiKey: view(updateApiKey(db, row, patch, request.actor)) };
     },
   );
 
@@ -131,6 +131,8 @@ export const apiKeyRoutes: FastifyPluginAsyncZod<ApiKeyRoutesOptions> = async (
         response: { 200: revokeApiKeyResponseSchema },
       },
     },
-    async (request) => ({ revoked: revokeApiKey(db, request.body.id) }),
+    async (request) => ({
+      revoked: revokeApiKey(db, request.body.id, request.actor),
+    }),
   );
 };
diff --git a/packages/server/src/routes/ingress.ts b/packages/server/src/routes/ingress.ts
index 3c02f8e..478d672 100644
--- a/packages/server/src/routes/ingress.ts
+++ b/packages/server/src/routes/ingress.ts
@@ -74,6 +74,7 @@ export const ingressRoutes: FastifyPluginAsyncZod<
       ];
       recordActivity(db, {
         kind: 'ingress-updated',
+        actor: request.actor,
         detail: `${changes.join(', ') || 'domains unchanged'} — now serving ${
           domains.length ? domains.join(', ') : 'plain-HTTP IP access only'
         }`,
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index 8171d23..12d4df7 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -144,6 +144,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     policy: LifecyclePolicy,
     template: string | null,
     metadata: string | null,
+    actor: string | null,
   ): Promise<AcquireOutcome> {
     const existing = findByName(db, name);
     if (existing?.state === 'archived' || existing?.state === 'restoring') {
@@ -181,7 +182,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       // Requested template and metadata are not applied: like policy, they
       // take effect only when this acquire creates the sandbox (metadata
       // has its own update verb, updateMetadata).
-      const awake = await wakeSandbox(db, executor, existing);
+      const awake = await wakeSandbox(db, executor, existing, actor);
       return { status: 'ready', created: false, row: touch(db, awake.id) };
     }
 
@@ -215,6 +216,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         policy,
         template,
         metadata,
+        actor,
       }),
     };
   }
@@ -224,7 +226,10 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
   // is more likely a typo than an intent to build a sandbox as a side
   // effect — then wake whatever cold state the sandbox is in and refresh
   // its idle clock. Must be called while holding the key's queue slot.
-  async function wakeForUse(name: string): Promise<SandboxRow> {
+  async function wakeForUse(
+    name: string,
+    actor: string | null,
+  ): Promise<SandboxRow> {
     const existing = findByName(db, name);
     if (!existing) {
       throw httpError(404, `no sandbox named "${name}" — acquire it first`);
@@ -237,7 +242,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         `sandbox "${name}" is ${existing.state} — call acquireSandbox and poll until it is ready`,
       );
     }
-    const awake = await wakeSandbox(db, executor, existing);
+    const awake = await wakeSandbox(db, executor, existing, actor);
     return touch(db, awake.id);
   }
 
@@ -300,6 +305,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
           policy,
           template ?? null,
           serializeMetadata(metadata),
+          request.actor,
         ),
       );
       if (outcome.status === 'restoring') {
@@ -506,7 +512,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       // whole duration. The heartbeat keeps the scanner away; a concurrent
       // destroy mid-exec removes the container and this exec fails with
       // the executor's honest error — accepted, not defended against.
-      const row = await locks.run(name, () => wakeForUse(name));
+      const row = await locks.run(name, () => wakeForUse(name, request.actor));
 
       const stopHeartbeat = startExecHeartbeat(
         db,
@@ -560,7 +566,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     async (request) => {
       const { name, files } = request.body;
       return locks.run(name, async () => {
-        const row = await wakeForUse(name);
+        const row = await wakeForUse(name, request.actor);
         try {
           await executor.writeFiles(
             row.id,
@@ -595,7 +601,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     async (request) => {
       const { name, path, contentBase64 } = request.body;
       return locks.run(name, async () => {
-        const row = await wakeForUse(name);
+        const row = await wakeForUse(name, request.actor);
         try {
           await executor.writeFiles(row.id, [
             { path, content: Buffer.from(contentBase64, 'base64') },
@@ -620,7 +626,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     async (request) => {
       const { name, path } = request.body;
       return locks.run(name, async () => {
-        const row = await wakeForUse(name);
+        const row = await wakeForUse(name, request.actor);
         let content: Buffer;
         try {
           content = await executor.readFile(row.id, path);
@@ -650,7 +656,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     async (request) => {
       const { name, paths } = request.body;
       return locks.run(name, async () => {
-        const row = await wakeForUse(name);
+        const row = await wakeForUse(name, request.actor);
         const files: { path: string; contentBase64: string }[] = [];
         let totalBytes = 0;
         for (const path of paths) {
@@ -706,7 +712,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
             `sandbox "${name}" is ${existing.state} — it has no container to rebuild`,
           );
         }
-        const row = await rebuildSandbox(db, executor, existing);
+        const row = await rebuildSandbox(db, executor, existing, request.actor);
         return { sandbox: toSandbox(row, endpoint) };
       });
     },
@@ -792,6 +798,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
             kind: 'policy-changed',
             sandboxName: name,
             sandboxId: row.id,
+            actor: request.actor,
             detail: changed
               .map(
                 (knob) =>
@@ -837,6 +844,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
           kind: 'metadata-changed',
           sandboxName: name,
           sandboxId: updated.id,
+          actor: request.actor,
           detail:
             Object.entries(metadata)
               .map(([key, value]) => `${key}=${value}`)
@@ -880,6 +888,11 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
           executor,
           existing.id,
           archiver?.store ?? null,
+          {
+            kind: 'destroyed',
+            cause: 'via destroySandbox',
+            actor: request.actor,
+          },
         );
         return { destroyed: true };
       });
diff --git a/packages/server/src/routes/upgrade.ts b/packages/server/src/routes/upgrade.ts
index ac9670d..6998f91 100644
--- a/packages/server/src/routes/upgrade.ts
+++ b/packages/server/src/routes/upgrade.ts
@@ -47,11 +47,12 @@ export const upgradeRoutes: FastifyPluginAsyncZod<
         response: { 200: applyUpgradeResponseSchema },
       },
     },
-    async () => {
+    async (request) => {
       await updater.apply();
       const current = updater.current;
       recordActivity(db, {
         kind: 'upgrade-started',
+        actor: request.actor,
         detail: `one-click upgrade launched${current ? ` from ${current.commit}` : ''} (systemd unit dormice-upgrade)`,
       });
       return { started: true as const };
diff --git a/packages/shared/src/activity.ts b/packages/shared/src/activity.ts
index 21d6ea7..af1cf89 100644
--- a/packages/shared/src/activity.ts
+++ b/packages/shared/src/activity.ts
@@ -52,6 +52,45 @@ export const ACTIVITY_KINDS = [
 export const activityKindSchema = z.enum(ACTIVITY_KINDS);
 export type ActivityKind = z.infer<typeof activityKindSchema>;
 
+/**
+ * Attribution: which credential asked for the recorded action. A closed
+ * vocabulary, built and parsed only here so the string shapes cannot drift
+ * between the daemon (which writes them) and the console (which displays
+ * them):
+ *
+ *   'env-token'    — the bootstrap credential (DORMICE_API_TOKEN).
+ *   'console'      — a console session; the human at the web console.
+ *   'apikey:<id>'  — a ledger API key. By id, not name: names became
+ *                    renameable, ids are the stable handle (the sandbox
+ *                    name/id doctrine), and revoked rows are never deleted,
+ *                    so an id always resolves back to a display name.
+ *   null           — no credential asked: the daemon's own actors (idle
+ *                    scanner, reconciler, archiver, startup) and data-plane
+ *                    wakes that carry no ledger credential (the sandbox
+ *                    port proxy, envd operations). Rows written before
+ *                    attribution existed are also null; the ring prunes
+ *                    them away within days.
+ *
+ * This attributes the explanation window, nothing more: lifecycle verbs
+ * name their actor, but exec and file traffic never enter the ring (they
+ * would flush it in minutes), so "which key ran what command" needs a real
+ * audit log, which this deliberately is not.
+ */
+export const ENV_TOKEN_ACTOR = 'env-token';
+export const CONSOLE_ACTOR = 'console';
+const APIKEY_ACTOR_PREFIX = 'apikey:';
+
+export function apiKeyActor(id: string): string {
+  return `${APIKEY_ACTOR_PREFIX}${id}`;
+}
+
+/** The id inside an 'apikey:<id>' actor, null for every other actor shape. */
+export function apiKeyActorId(actor: string | null): string | null {
+  return actor?.startsWith(APIKEY_ACTOR_PREFIX)
+    ? actor.slice(APIKEY_ACTOR_PREFIX.length)
+    : null;
+}
+
 export const activityEventSchema = z.object({
   /** Ring position; monotonically increasing, newest is largest. */
   id: z.number().int(),
@@ -65,7 +104,9 @@ export const activityEventSchema = z.object({
    */
   sandboxName: z.string().nullable(),
   sandboxId: z.string().nullable(),
-  /** One short line of context: which actor, which threshold, what was repaired. */
+  /** Who asked — the closed actor vocabulary above; null = the daemon itself. */
+  actor: z.string().nullable(),
+  /** One short line of context: which threshold, what was repaired, what changed. */
   detail: z.string(),
 });
 
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
index 3d43e4f..faadb6d 100644
--- a/website/content/docs/console.mdx
+++ b/website/content/docs/console.mdx
@@ -105,8 +105,11 @@ Three more pages round out the operator view:
 
 - **Activity** — the daemon's recent history (who was created, frozen,
   destroyed, what the reconciler repaired, which API key was minted or
-  revoked), filterable by event kind and sandbox key. A bounded window,
-  not an audit log.
+  revoked), each event attributed to the credential that asked — an API
+  key by name, the env token, a console session, or "system" for the
+  daemon's own moves. Filterable by event kind, actor, and sandbox
+  name: filtering by a key is how you read a leaked key's blast radius
+  before revoking it. A bounded window, not an audit log.
 - **Domains** — bind domains to the daemon's front door (the managed
   reverse proxy), with a copyable DNS record guide and a live per-domain
   probe that shows DNS and certificate progress until each one turns
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
index d5cff4a..54d5f4c 100644
--- a/website/content/docs/http-api.mdx
+++ b/website/content/docs/http-api.mdx
@@ -54,7 +54,7 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | `POST /getSandboxMetrics` | one sandbox's live CPU/memory/disk sample; `sample` is `null` when nothing is running | 404 unknown name |
 | `POST /listSandboxMetrics` | every measurable sandbox's sample in one answer | — |
 | `POST /listSandboxImages` | each sandbox's born image vs its template's current one | — |
-| `POST /listActivity` | the daemon's recent history, newest first — a bounded ring, not an audit log | — |
+| `POST /listActivity` | the daemon's recent history with per-event [attribution](#who-did-what), newest first — a bounded ring, not an audit log | — |
 | `POST /getConfig` | effective configuration, read-only; secrets reported present-or-absent, value never sent | — |
 | `POST /getIngress` | domains bound on the daemon's managed reverse proxy, with live DNS and certificate probes | — |
 | `POST /setIngress` | rewrite the managed proxy config to exactly this domain list (empty list unbinds all) | 400 when the daemon manages no proxy |
@@ -136,6 +136,22 @@ the row as rotation history, and is the only one that frees the name
 for reuse. Each key row carries `lastUsedAt` (written with 60-second
 granularity), and revoked rows stay in `listApiKeys` forever.
 
+## Who did what
+
+Every `listActivity` event carries an `actor`: `"env-token"` (the
+bootstrap credential), `"console"` (a console session), `"apikey:<id>"`
+(that key — by `id`, since names are renameable; resolve it through
+`listApiKeys`, where the row lives forever), or `null` when no
+credential asked — the idle scanner freezing, the reconciler repairing,
+the archiver archiving.
+
+This is what turns key hygiene into incident response: suspect a leak,
+disable the key to stop the bleeding, filter the activity ring by that
+key to see what it created and destroyed, then revoke and rotate. The
+ring attributes lifecycle verbs only — commands and file traffic never
+enter it (they would flush its 1000 entries in minutes), so "which key
+ran what" needs a real audit system, which this deliberately is not.
+
 ## Commands and files on the wire
 
 `execCommand` takes `{ name, command, timeoutSeconds?, cwd?, env? }`

From d5ceb841bb409c7d221d38b5401a5c2df8baf4fa Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 18 Jul 2026 00:18:55 +0800
Subject: [PATCH 102/133] =?UTF-8?q?Sandboxes=20table=20learns=20to=20fit?=
 =?UTF-8?q?=20on=20one=20screen:=20the=20policy=20and=20label=20columns=20?=
 =?UTF-8?q?are=20gone=20(policy=20is=20low-frequency=20config=20and=20was?=
 =?UTF-8?q?=20the=20only=20wrapping=20column=20=E2=80=94=20it=20belongs=20?=
 =?UTF-8?q?on=20the=20detail=20page;=20labels=20exist=20for=20group-filter?=
 =?UTF-8?q?ing,=20and=20the=20filter=20menu=20stays),=20so=20every=20row?=
 =?UTF-8?q?=20is=20a=20single=20line=20and=20the=20table=20never=20scrolls?=
 =?UTF-8?q?=20sideways.=20The=20three=20resource=20columns=20now=20read=20?=
 =?UTF-8?q?used=20/=20cap=20=E2=80=94=20a=20bare=20number=20without=20its?=
 =?UTF-8?q?=20denominator=20carries=20no=20information:=201.2=20GiB=20is?=
 =?UTF-8?q?=20nearly=20full=20on=20a=202=20GiB=20sandbox=20and=20nearly=20?=
 =?UTF-8?q?empty=20on=20an=208=20GiB=20one=20=E2=80=94=20with=20a=20fixed-?=
 =?UTF-8?q?width=20mini=20meter=20underneath=20(fixed=20so=20the=20three?=
 =?UTF-8?q?=20bars=20are=20comparable=20across=20columns)=20sharing=20the?=
 =?UTF-8?q?=20same=2075/90=20warning=20thresholds=20as=20the=20text=20colo?=
 =?UTF-8?q?r.=20The=20Meter=20component=20graduates=20from=20overview/=20t?=
 =?UTF-8?q?o=20components/=20as=20the=20site-wide=20single=20source,=20ret?=
 =?UTF-8?q?iring=20the=20hand-copied=20twin=20inside=20MetricsPanel=20befo?=
 =?UTF-8?q?re=20a=20third=20copy=20could=20appear.=20Template=20names=20li?=
 =?UTF-8?q?nk=20to=20the=20templates=20page,=20and=20a=20sortable=20create?=
 =?UTF-8?q?d=20column=20joins=20idle=20=E2=80=94=20created=20wears=20a=20t?=
 =?UTF-8?q?railing=20=E5=89=8D=20so=20a=20bare=20duration=20isn't=20misrea?=
 =?UTF-8?q?d=20as=20liveness,=20while=20idle=20stays=20bare=20because=20it?=
 =?UTF-8?q?=20is=20a=20still-counting=20duration=20and=20the=20lifecycle?=
 =?UTF-8?q?=20engine's=20actual=20clock.=20Row=20height=20is=20pinned=20at?=
 =?UTF-8?q?=20h-13=20for=20header=20and=20body=20alike=20in=20the=20one=20?=
 =?UTF-8?q?table-chrome=20definition=20(height=20in=20tables=20is=20a=20fl?=
 =?UTF-8?q?oor,=20not=20a=20clamp=20=E2=80=94=20oversized=20content=20stil?=
 =?UTF-8?q?l=20stretches=20honestly),=20folding=20in=20the=20three=20hand-?=
 =?UTF-8?q?written=20h-13=20classes=20the=20api-keys=20page=20had=20alread?=
 =?UTF-8?q?y=20reached=20for.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/console/src/components/DataTable.tsx |   6 +-
 .../overview => }/components/Meter.tsx        |   0
 .../overview/components/FleetStatCards.tsx    |   2 +-
 .../overview/components/HostHealthCard.tsx    |   2 +-
 .../overview/components/SandboxDisksCard.tsx  |   2 +-
 .../sandboxes/components/MetricsPanel.tsx     |  20 +--
 .../sandboxes/pages/SandboxesPage.tsx         | 117 ++++++++++--------
 7 files changed, 70 insertions(+), 79 deletions(-)
 rename packages/console/src/{features/overview => }/components/Meter.tsx (100%)

diff --git a/packages/console/src/components/DataTable.tsx b/packages/console/src/components/DataTable.tsx
index 81c3727..ac5a1f1 100644
--- a/packages/console/src/components/DataTable.tsx
+++ b/packages/console/src/components/DataTable.tsx
@@ -4,11 +4,13 @@ import { Table } from '@/components/ui/table';
 import { cn } from '@/lib/utils';
 
 // 表格皮的唯一定义(参考 openasi 表格,2026-07-15 用户拍板):
-// - 表头 h-12、单元格 px-4 py-2.5,首末列 24px 边距 — 内容离卡面圆角有喘息
+// - 行定高 h-13,表头表行同高(2026-07-18 拍板)— 行高不随内容深浅
+//   跳动;表格里 height 是下限,超高内容仍会诚实撑开而不是被裁
+// - 单元格 px-4 py-2.5,首末列 24px 边距 — 内容离卡面圆角有喘息
 // - 吸顶表头 bg-card 与卡面同色,滚动不穿帮;短表贴不到顶,无害
 // - 行动画一律关闭:2 秒轮询重渲下 transition-colors 会微闪
 const TABLE_CHROME =
-  '[&_tr]:transition-none [&_th]:h-12 [&_th]:px-4 [&_td]:px-4 [&_td]:py-2.5 [&_th:first-child]:pl-6 [&_td:first-child]:pl-6 [&_th:last-child]:pr-6 [&_td:last-child]:pr-6 [&_thead]:sticky [&_thead]:top-0 [&_thead]:z-10 [&_thead]:bg-card';
+  '[&_tr]:transition-none [&_tr]:h-13 [&_th]:px-4 [&_td]:px-4 [&_td]:py-2.5 [&_th:first-child]:pl-6 [&_td:first-child]:pl-6 [&_th:last-child]:pr-6 [&_td:last-child]:pr-6 [&_thead]:sticky [&_thead]:top-0 [&_thead]:z-10 [&_thead]:bg-card';
 
 /**
  * 数据表外壳:卡面(bg-card + 大圆角 + ring)包一层滚动容器,再套统一
diff --git a/packages/console/src/features/overview/components/Meter.tsx b/packages/console/src/components/Meter.tsx
similarity index 100%
rename from packages/console/src/features/overview/components/Meter.tsx
rename to packages/console/src/components/Meter.tsx
diff --git a/packages/console/src/features/overview/components/FleetStatCards.tsx b/packages/console/src/features/overview/components/FleetStatCards.tsx
index aed593c..a6c2320 100644
--- a/packages/console/src/features/overview/components/FleetStatCards.tsx
+++ b/packages/console/src/features/overview/components/FleetStatCards.tsx
@@ -1,3 +1,4 @@
+import { Meter } from '@/components/Meter';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import { pctOf } from '@/lib/format';
 import { fullClock } from '../format';
@@ -7,7 +8,6 @@ import {
   useFleetTimeline,
 } from '../hooks/useFleetTimeline';
 import { useHostMetrics } from '../hooks/useHostMetrics';
-import { Meter } from './Meter';
 import { SandboxDisksCard } from './SandboxDisksCard';
 import { Sparkline } from './Sparkline';
 import { StatCard, StatCardSkeleton } from './StatCard';
diff --git a/packages/console/src/features/overview/components/HostHealthCard.tsx b/packages/console/src/features/overview/components/HostHealthCard.tsx
index 5567f09..6a74ff2 100644
--- a/packages/console/src/features/overview/components/HostHealthCard.tsx
+++ b/packages/console/src/features/overview/components/HostHealthCard.tsx
@@ -6,6 +6,7 @@ import {
 } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
 import type { ReactNode } from 'react';
+import { Meter } from '@/components/Meter';
 import {
   Card,
   CardContent,
@@ -17,7 +18,6 @@ import { Skeleton } from '@/components/ui/skeleton';
 import { formatBytes, pctOf } from '@/lib/format';
 import { cn } from '@/lib/utils';
 import { useHostMetrics } from '../hooks/useHostMetrics';
-import { Meter } from './Meter';
 
 function HostRow({
   icon,
diff --git a/packages/console/src/features/overview/components/SandboxDisksCard.tsx b/packages/console/src/features/overview/components/SandboxDisksCard.tsx
index 1df7ec1..b7afd34 100644
--- a/packages/console/src/features/overview/components/SandboxDisksCard.tsx
+++ b/packages/console/src/features/overview/components/SandboxDisksCard.tsx
@@ -1,7 +1,7 @@
+import { Meter } from '@/components/Meter';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import { formatBytes, pctOf } from '@/lib/format';
 import { useHostMetrics } from '../hooks/useHostMetrics';
-import { Meter } from './Meter';
 import { StatCard, StatCardSkeleton } from './StatCard';
 
 /**
diff --git a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
index c04e3a0..979d47a 100644
--- a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
@@ -7,6 +7,7 @@ import {
 import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
 import { useState } from 'react';
 import { CartesianGrid, Line, LineChart, XAxis, YAxis } from 'recharts';
+import { Meter } from '@/components/Meter';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import { Card, CardContent } from '@/components/ui/card';
 import {
@@ -25,31 +26,12 @@ import { Spinner } from '@/components/ui/spinner';
 import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
 import { withGapBreaks } from '@/lib/chart-gaps';
 import { formatBytes, pctOf } from '@/lib/format';
-import { cn } from '@/lib/utils';
 import { since } from '../format';
 import {
   useSandboxMetrics,
   useSandboxMetricsHistory,
 } from '../hooks/useSandboxes';
 
-function Meter({ pct }: { pct: number }) {
-  const clamped = Math.min(100, Math.max(0, pct));
-  const [fill, track] =
-    clamped >= 90
-      ? ['bg-red-500', 'bg-red-500/15']
-      : clamped >= 75
-        ? ['bg-amber-500', 'bg-amber-500/15']
-        : ['bg-primary', 'bg-primary/10'];
-  return (
-    <div className={cn('h-1.5 w-full overflow-hidden rounded-full', track)}>
-      <div
-        className={cn('h-full rounded-full', fill)}
-        style={{ width: `${clamped}%` }}
-      />
-    </div>
-  );
-}
-
 function MetricCard({
   icon,
   label,
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index 30e4848..0973892 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -14,6 +14,7 @@ import { useMemo, useState } from 'react';
 import { toast } from 'sonner';
 import { DataTable } from '@/components/DataTable';
 import { FilterMenu } from '@/components/FilterMenu';
+import { Meter } from '@/components/Meter';
 import { paginate, TablePager } from '@/components/TablePager';
 import { Alert, AlertDescription } from '@/components/ui/alert';
 import {
@@ -27,7 +28,6 @@ import {
   AlertDialogTitle,
   AlertDialogTrigger,
 } from '@/components/ui/alert-dialog';
-import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Checkbox } from '@/components/ui/checkbox';
 import {
@@ -64,7 +64,7 @@ import { CreateSandboxDialog } from '../components/CreateSandboxDialog';
 import { DestroySandboxDialog } from '../components/DestroySandboxButton';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
 import { UpgradableBadge } from '../components/UpgradableBadge';
-import { policyLine, STATE_LABELS, since } from '../format';
+import { STATE_LABELS, since } from '../format';
 import {
   useFleetMetrics,
   useSandboxes,
@@ -82,42 +82,35 @@ const STATE_FILTERS: Array<SandboxState> = [
 const PAGE_SIZE = 50;
 
 /** 可排序的列:字符串比较对 name 和 ISO 时间戳同样成立。 */
-type SortKey = 'name' | 'lastActiveAt';
+type SortKey = 'name' | 'createdAt' | 'lastActiveAt';
 type Sort = { key: SortKey; dir: 1 | -1 };
 
-/** 一个沙箱的标签摊平成 "key=value" 串 — 筛选项与展示共用同一拼法。 */
+/**
+ * 一个沙箱的标签摊平成 "key=value" 串,供筛选。标签列刻意不设
+ * (2026-07-17 用户拍板):标签的用途是分组筛选,不是逐行阅读 —
+ * chips 会 flex-wrap 撑高行,单个沙箱的标签去详情页看。
+ */
 function labelPairs(sandbox: Sandbox): string[] {
   return Object.entries(sandbox.metadata).map(
     ([key, value]) => `${key}=${value}`,
   );
 }
 
-/** 标签列的一格:小 chips,长值截断、全文挂 hover;没标签就空着不占眼睛。 */
-function MetadataChips({ sandbox }: { sandbox: Sandbox }) {
-  const pairs = labelPairs(sandbox);
-  if (pairs.length === 0) return null;
-  return (
-    // 上限收着点:列要在 max-w-6xl 里一屏放下,肥列多一寸,「操作」列
-    // 就被挤出视野一寸(2026-07-16 实测过溢出)。truncate 放内层 span:
-    // Badge 是 flex 容器,直接截自己会从两侧裁字、省略号不出现。
-    <span className="inline-flex max-w-[13rem] flex-wrap gap-1">
-      {pairs.map((pair) => (
-        <Badge
-          key={pair}
-          variant="outline"
-          className="max-w-[6.5rem] font-mono text-xs font-normal text-muted-foreground"
-          title={pair}
-        >
-          <span className="truncate">{pair}</span>
-        </Badge>
-      ))}
-    </span>
-  );
+/**
+ * 上限一侧的字节数:去掉小数尾零 — 上限几乎都是整数,「4.00 GiB」
+ * 的尾零是噪音;用量一侧保留 formatBytes 原样,精度在那儿是信息。
+ */
+function formatCap(bytes: number): string {
+  return formatBytes(bytes)
+    .replace(/(\.\d*?)0+(?= )/, '$1')
+    .replace(/\.(?= )/, '');
 }
 
 /**
- * 资源列的一格:数值紧凑,细节挂 hover;占比过线换警示色,和指标 tab
- * 的 Meter 同一套阈值。value 为 null = 这行没被测到(没有容器可测)。
+ * 资源列的一格:写成「用量 / 上限」— 不带分母的数字没有信息量,
+ * 1.2 GiB 对 2 GiB 的沙箱是快满,对 8 GiB 的是很空。占比过线换警示色,
+ * 和指标 tab 的 Meter 同一套阈值。value 为 null = 这行没被测到
+ * (没有容器可测)。
  */
 function UsageCell({
   value,
@@ -146,6 +139,11 @@ function UsageCell({
       title={title}
     >
       {value}
+      {/* 迷你条:数字给精度,条给一眼的量感。宽度钉死不随列宽漂 —
+          三列的条一样长,长短才可比。 */}
+      <div className="mt-1 ml-auto w-16">
+        <Meter pct={pct} />
+      </div>
     </TableCell>
   );
 }
@@ -485,12 +483,22 @@ export function SandboxesPage() {
               </TableHead>
               <TableHead>状态</TableHead>
               <TableHead>模板</TableHead>
-              <TableHead>标签</TableHead>
               <TableHead className="text-right">CPU</TableHead>
               <TableHead className="text-right">内存</TableHead>
               <TableHead className="text-right">磁盘</TableHead>
               <TableHead>
-                {/* 升序 = 最久没动的排最前:回收磁盘时先看这里。 */}
+                <SortableHead
+                  label="创建"
+                  sortKey="createdAt"
+                  sort={sort}
+                  onSort={toggleSort}
+                />
+              </TableHead>
+              <TableHead>
+                {/* 升序 = 最久没动的排最前:回收磁盘时先看这里 — 生命
+                    周期策略从最后活动起算,这列才是"谁快被降温"的信号。
+                    「策略」列刻意不设(2026-07-17 版式取舍):低频配置、
+                    还是唯一会折行撑高行的列,归详情页。全表单行,不横滚。 */}
                 <SortableHead
                   label="空闲"
                   sortKey="lastActiveAt"
@@ -498,8 +506,6 @@ export function SandboxesPage() {
                   onSort={toggleSort}
                 />
               </TableHead>
-              {/* 短表头:6 个字的表头会把列最小宽钉死,行内容才是主角。 */}
-              <TableHead title="生命周期策略">策略</TableHead>
               <TableHead className="text-right">操作</TableHead>
             </TableRow>
           </TableHeader>
@@ -531,13 +537,21 @@ export function SandboxesPage() {
                 </TableCell>
                 <TableCell className="text-muted-foreground">
                   <span className="inline-flex items-center gap-1.5">
-                    {sandbox.template ?? '基础镜像'}
+                    {/* 链接指向模板列表页(没有逐模板详情页);基础镜像
+                        不是模板,没有可去处,保持纯文本。 */}
+                    {sandbox.template ? (
+                      <Link
+                        to="/templates"
+                        className="hover:text-foreground hover:underline"
+                      >
+                        {sandbox.template}
+                      </Link>
+                    ) : (
+                      '基础镜像'
+                    )}
                     <UpgradableBadge lineage={lineageOf.get(sandbox.name)} />
                   </span>
                 </TableCell>
-                <TableCell>
-                  <MetadataChips sandbox={sandbox} />
-                </TableCell>
                 {(() => {
                   const m = metricsOf.get(sandbox.name);
                   if (!m) {
@@ -552,43 +566,36 @@ export function SandboxesPage() {
                   return (
                     <>
                       <UsageCell
-                        value={`${Math.round(m.cpuUsedPct)}%`}
+                        value={`${Math.round(m.cpuUsedPct)}% / ${m.cpuCount} 核`}
                         pct={m.cpuUsedPct / m.cpuCount}
-                        title={`${m.cpuCount} 核 · 百分比按单核计`}
+                        title="百分比按单核计,多核可超 100%"
                       />
                       <UsageCell
-                        value={formatBytes(m.memUsedBytes)}
+                        value={`${formatBytes(m.memUsedBytes)} / ${formatCap(m.memTotalBytes)}`}
                         pct={pctOf(m.memUsedBytes, m.memTotalBytes)}
-                        title={`共 ${formatBytes(m.memTotalBytes)}`}
                       />
                       <UsageCell
-                        value={formatBytes(m.diskUsedBytes)}
+                        value={`${formatBytes(m.diskUsedBytes)} / ${formatCap(m.diskTotalBytes)}`}
                         pct={pctOf(m.diskUsedBytes, m.diskTotalBytes)}
-                        title={`名义 ${formatBytes(m.diskTotalBytes)}`}
+                        title="上限是名义配额:稀疏镜像,未写入不占宿主盘"
                       />
                     </>
                   );
                 })()}
+                {/* 带「前」:光秃的时长会被读成存活状态;空闲列不带 —
+                    表头已说明它是一段仍在计数的时长。 */}
+                <TableCell
+                  className="tabular-nums text-muted-foreground"
+                  title={`创建于:${new Date(sandbox.createdAt).toLocaleString()}`}
+                >
+                  {since(sandbox.createdAt)}前
+                </TableCell>
                 <TableCell
                   className="tabular-nums text-muted-foreground"
                   title={`最近活动:${new Date(sandbox.lastActiveAt).toLocaleString()}`}
                 >
                   {since(sandbox.lastActiveAt)}
                 </TableCell>
-                {/* 限宽 + 放开 nowrap(vendored TableCell 默认不换行)让长
-                    策略折行,且只在「·」分隔处断 — CJK 默认哪里都能断,
-                    会把「停止」劈成两半。「存活」列刻意不设(2026-07-16
-                    版式取舍):创建时长与空闲高度重复,详情页有它的家。 */}
-                <TableCell className="max-w-[10rem] whitespace-normal text-xs text-muted-foreground">
-                  {policyLine(sandbox.policy)
-                    .split(' · ')
-                    .map((segment, index) => (
-                      <span key={segment}>
-                        {index > 0 && ' · '}
-                        <span className="whitespace-nowrap">{segment}</span>
-                      </span>
-                    ))}
-                </TableCell>
                 <TableCell className="text-right">
                   <SandboxRowMenu name={sandbox.name} />
                 </TableCell>

From 18e56257b4cb69c5845cc7ef43b8f9d4d1497167 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 18 Jul 2026 00:23:34 +0800
Subject: [PATCH 103/133] =?UTF-8?q?The=20console=20checks=20for=20upgrades?=
 =?UTF-8?q?=20the=20moment=20an=20operator=20arrives:=20AppShell=20mounts?=
 =?UTF-8?q?=20an=20UpgradeNotice=20that=20runs=20the=20existing=20checkUpg?=
 =?UTF-8?q?rade=20query=20once=20per=20open,=20fixing=20the=20discovery=20?=
 =?UTF-8?q?loop=20the=20sidebar=20badge=20had=20been=20living=20in=20?=
 =?UTF-8?q?=E2=80=94=20it=20only=20lit=20after=20someone=20visited=20the?=
 =?UTF-8?q?=20version=20page,=20and=20only=20a=20suspicion=20of=20an=20upg?=
 =?UTF-8?q?rade=20would=20send=20anyone=20there,=20so=20the=20signal=20it?=
 =?UTF-8?q?=20existed=20to=20give=20could=20never=20arrive=20on=20its=20ow?=
 =?UTF-8?q?n.=20When=20the=20daemon=20adjudicates=20upgradable,=20a=20dial?=
 =?UTF-8?q?og=20shows=20the=20commit=20changelog=20and=20hands=20off:=20it?=
 =?UTF-8?q?=20informs,=20never=20upgrades=20=E2=80=94=20the=20version=20pa?=
 =?UTF-8?q?ge's=20UpgradeDialog=20with=20real=20progress=20remains=20the?=
 =?UTF-8?q?=20only=20upgrade=20apparatus,=20and=20checkError=20or=20a=20di?=
 =?UTF-8?q?verged=20checkout=20deliberately=20never=20pops=20the=20dialog?=
 =?UTF-8?q?=20because=20those=20situations=20need=20the=20version=20page's?=
 =?UTF-8?q?=20full=20explanation,=20not=20a=20prompt.=20"Ignore=20this=20v?=
 =?UTF-8?q?ersion"=20keys=20localStorage=20on=20the=20latest=20commit=20(t?=
 =?UTF-8?q?runk=20has=20no=20release=20tags,=20so=20a=20version=20honestly?=
 =?UTF-8?q?=20is=20a=20commit=20=E2=80=94=20a=20newer=20one=20re-prompts),?=
 =?UTF-8?q?=20plain=20close=20silences=20a=20single=20visit,=20and=20neith?=
 =?UTF-8?q?er=20touches=20the=20badge:=20ignoring=20quiets=20the=20interru?=
 =?UTF-8?q?ption,=20not=20the=20passive=20signal,=20which=20keeps=20burnin?=
 =?UTF-8?q?g=20until=20the=20upgrade=20actually=20happens.=20The=20"nothin?=
 =?UTF-8?q?g=20checks=20in=20the=20background"=20doctrine=20is=20rewritten?=
 =?UTF-8?q?=20rather=20than=20quietly=20contradicted:=20the=20privacy=20bo?=
 =?UTF-8?q?undary=20was=20never=20"no=20checks",=20it=20was=20"no=20phone-?=
 =?UTF-8?q?home=20while=20nobody=20is=20there"=20=E2=80=94=20an=20admin=20?=
 =?UTF-8?q?opening=20their=20console=20is=20a=20human=20arriving,=20and=20?=
 =?UTF-8?q?timer-driven=20checks=20stay=20forbidden.=20console.mdx=20also?=
 =?UTF-8?q?=20gains=20the=20version-page=20section=20that=20the=20settings?=
 =?UTF-8?q?/version=20page=20split=20had=20left=20undocumented.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/console/src/components/AppShell.tsx  |   4 +
 .../console/src/components/AppSidebar.tsx     |   2 +-
 .../settings/components/UpgradeNotice.tsx     | 103 ++++++++++++++++++
 .../src/features/settings/hooks/useUpgrade.ts |  14 ++-
 packages/shared/src/upgrade.ts                |   5 +-
 website/content/docs/console.mdx              |  11 +-
 6 files changed, 129 insertions(+), 10 deletions(-)
 create mode 100644 packages/console/src/features/settings/components/UpgradeNotice.tsx

diff --git a/packages/console/src/components/AppShell.tsx b/packages/console/src/components/AppShell.tsx
index 5c66b90..9dd91f6 100644
--- a/packages/console/src/components/AppShell.tsx
+++ b/packages/console/src/components/AppShell.tsx
@@ -2,11 +2,14 @@ import { Outlet } from '@tanstack/react-router';
 import type { CSSProperties } from 'react';
 import { AppSidebar } from '@/components/AppSidebar';
 import { SidebarInset, SidebarProvider } from '@/components/ui/sidebar';
+import { UpgradeNotice } from '@/features/settings/components/UpgradeNotice';
 
 /**
  * 登录后的应用外壳:侧边栏 + 页面内容。顶栏 2026-07-16 用户拍板删除:
  * 面包屑只是页面自带页头的第二份真相,⌘K 命令面板成为纯键盘入口
  * (CommandMenu),侧栏开关保留键盘位(⌘B,vendored sidebar 自带)。
+ * UpgradeNotice 也挂在这里:开台(登录后)查一次版本,可升级即弹提醒
+ * — 外壳是"人到场"的单一挂点,检查纪律见 useUpgrade.ts。
  */
 export function AppShell() {
   return (
@@ -24,6 +27,7 @@ export function AppShell() {
           <Outlet />
         </div>
       </SidebarInset>
+      <UpgradeNotice />
     </SidebarProvider>
   );
 }
diff --git a/packages/console/src/components/AppSidebar.tsx b/packages/console/src/components/AppSidebar.tsx
index e67fbbf..a6c0125 100644
--- a/packages/console/src/components/AppSidebar.tsx
+++ b/packages/console/src/components/AppSidebar.tsx
@@ -53,7 +53,7 @@ export function AppSidebar() {
   const pathname = useRouterState({
     select: (state) => state.location.pathname,
   });
-  // 只读缓存:设置页查过且有新版本才亮,角标自己绝不发请求。
+  // 只读缓存:开台检查或版本页查过且有新版本才亮,角标自己绝不发请求。
   const upgradable = useCachedUpgradable();
   const [logoutConfirmOpen, setLogoutConfirmOpen] = useState(false);
 
diff --git a/packages/console/src/features/settings/components/UpgradeNotice.tsx b/packages/console/src/features/settings/components/UpgradeNotice.tsx
new file mode 100644
index 0000000..48261cc
--- /dev/null
+++ b/packages/console/src/features/settings/components/UpgradeNotice.tsx
@@ -0,0 +1,103 @@
+import { useNavigate } from '@tanstack/react-router';
+import { useEffect, useRef, useState } from 'react';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { useCheckUpgrade } from '../hooks/useUpgrade';
+
+/**
+ * 开台升级提醒:挂在 AppShell 上,登录后查一次版本(与版本页共用
+ * ['checkUpgrade'] 缓存,侧栏角标因此从开台起就能亮)。只在 upgradable
+ * 且该版本未被忽略时弹,一次会话至多弹一次(prompted ref)——升级期间
+ * 缓存失效翻动数据是轮询回声,不许把人关掉的弹窗再弹回来。
+ *
+ * 弹窗只做告知,不做升级:「去升级」跳版本页,真进度的 UpgradeDialog
+ * 在那里,不复制第二套升级装置。checkError / 本地分叉(aheadBy>0)这些
+ * 复杂情况刻意不弹 — 留给版本页讲清楚。
+ *
+ * 「忽略此版本」按 latest commit 记 localStorage(trunk 无发版 tag,
+ * "一个版本"诚实地就是一个提交):main 上出现更新的提交即重新提醒;
+ * 右上角关闭 = 只关这次,下次开台再提醒。忽略只静音弹窗,不熄灭侧栏
+ * 角标 — 被动信号不打扰人,也不撒谎。
+ */
+const DISMISSED_KEY = 'dormice.console.dismissed-upgrade';
+
+export function UpgradeNotice() {
+  const { data } = useCheckUpgrade();
+  const navigate = useNavigate();
+  const [open, setOpen] = useState(false);
+  const prompted = useRef(false);
+
+  const check = data?.check ?? null;
+  const current = data?.current ?? null;
+  const latestCommit = check?.upgradable ? check.latest.commit : null;
+  useEffect(() => {
+    if (prompted.current || latestCommit === null) return;
+    if (localStorage.getItem(DISMISSED_KEY) === latestCommit) return;
+    prompted.current = true;
+    setOpen(true);
+  }, [latestCommit]);
+
+  if (check === null || !check.upgradable) return null;
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>有新版本可用</DialogTitle>
+          <DialogDescription>
+            {current !== null && (
+              <>
+                当前 <code className="font-mono">{current.commit}</code>,
+              </>
+            )}
+            落后 {check.behindBy} 个提交,最新{' '}
+            <code className="font-mono">{check.latest.commit}</code>
+          </DialogDescription>
+        </DialogHeader>
+        <ul className="max-h-48 overflow-y-auto rounded-md border bg-muted/30 p-3 font-mono text-xs leading-relaxed">
+          {check.commits.map((entry) => (
+            <li key={entry.commit} className="flex gap-2">
+              <span className="shrink-0 text-muted-foreground">
+                {entry.commit}
+              </span>
+              <span className="min-w-0 truncate" title={entry.title}>
+                {entry.title}
+              </span>
+            </li>
+          ))}
+          {check.behindBy > check.commits.length && (
+            <li className="text-muted-foreground">
+              还有 {check.behindBy - check.commits.length} 个更早的提交未列出
+            </li>
+          )}
+        </ul>
+        <DialogFooter>
+          <Button
+            variant="outline"
+            onClick={() => {
+              localStorage.setItem(DISMISSED_KEY, check.latest.commit);
+              setOpen(false);
+            }}
+          >
+            忽略此版本
+          </Button>
+          <Button
+            onClick={() => {
+              setOpen(false);
+              navigate({ to: '/version' });
+            }}
+          >
+            去升级
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/packages/console/src/features/settings/hooks/useUpgrade.ts b/packages/console/src/features/settings/hooks/useUpgrade.ts
index 2fbc043..6c2636f 100644
--- a/packages/console/src/features/settings/hooks/useUpgrade.ts
+++ b/packages/console/src/features/settings/hooks/useUpgrade.ts
@@ -2,9 +2,11 @@ import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import { checkUpgrade, getUpgradeStatus } from '@/lib/api';
 
 /**
- * 版本检查只在打开设置页与点按钮时发生 — 刻意不做后台轮询(检查会打
- * 远端仓库,后台跑等于 phone home);daemon 侧另有一小时缓存,反复进
- * 页面不重复走网络。检查失败是数据(checkError)不是异常,卡片如实显示。
+ * 版本检查只在"人到场"时发生 — 开台一次(AppShell 挂 UpgradeNotice,
+ * 2026-07-18 起)、打开版本页、点按钮;刻意不做定时轮询(检查会打远端
+ * 仓库,无人时后台跑才是 phone home,管理员主动打开控制台不算);
+ * daemon 侧另有一小时缓存,反复进页面不重复走网络。检查失败是数据
+ * (checkError)不是异常,卡片如实显示。
  */
 export function useCheckUpgrade() {
   return useQuery({
@@ -43,8 +45,10 @@ export function useUpgradeStatus() {
 }
 
 /**
- * 侧栏角标的只读缓存视图:绝不自己发请求(检查只在设置页与按钮发生,
- * 角标不该成为第二个 phone-home 入口),设置页查过且可升级才亮。
+ * 侧栏角标的只读缓存视图:绝不自己发请求(开台与版本页已是仅有的
+ * 检查入口,角标不该成为第三个),查过且可升级才亮。开台检查落进
+ * 同一份缓存,所以角标从登录起就能亮;忽略提醒弹窗不熄灭它 —
+ * 被动信号不打扰人,也不撒谎。
  */
 export function useCachedUpgradable(): boolean {
   const { data } = useQuery({
diff --git a/packages/shared/src/upgrade.ts b/packages/shared/src/upgrade.ts
index 36b07d7..6ac4f25 100644
--- a/packages/shared/src/upgrade.ts
+++ b/packages/shared/src/upgrade.ts
@@ -14,8 +14,9 @@ import { z } from 'zod';
  * The check reaches the network, so failures are data, not surprises:
  * `check` is null and `checkError` says why (the getIngress probe
  * precedent — the observation succeeded, the probe inside it did not).
- * Nothing checks in the background; this verb runs when asked, with a
- * short-lived server-side cache to keep a busy console polite.
+ * Nothing checks on a timer; this verb runs when a human arrives — the
+ * console asks once per open, the version page and its button ask again
+ * — with a short-lived server-side cache to keep a busy console polite.
  */
 export const checkUpgradeRequestSchema = z.object({
   /** Bypass the server-side cache — the "check now" button. */
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
index faadb6d..f7e2b29 100644
--- a/website/content/docs/console.mdx
+++ b/website/content/docs/console.mdx
@@ -99,9 +99,9 @@ editing `/etc/dormice/env`, and it (or a console session) is also the
 only credential the key-management actions themselves accept: keys
 cannot manage keys.
 
-## Activity, domains, and settings
+## Activity, domains, settings, and version
 
-Three more pages round out the operator view:
+Four more pages round out the operator view:
 
 - **Activity** — the daemon's recent history (who was created, frozen,
   destroyed, what the reconciler repaired, which API key was minted or
@@ -118,6 +118,13 @@ Three more pages round out the operator view:
 - **Settings** — the daemon's effective configuration, read-only, with
   secrets shown as present-or-absent only. Changing configuration
   happens in `/etc/dormice/env` plus a restart, never from the browser.
+- **Version** — the build the daemon is running (a git commit — trunk
+  commit titles are the changelog) compared against the latest, with a
+  one-click [upgrade](/docs/upgrading) and live progress where the host
+  supports it. The console also checks once when you open it: if an
+  upgrade is available, a dialog shows what it would bring — dismiss it
+  for this visit, or ignore that version until a newer one appears. The
+  sidebar badge stays lit either way, until you actually upgrade.
 
 A command palette (⌘K) jumps to any page or sandbox.
 

From 516772674a880060491af1b8608f0355a3bf96c1 Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Fri, 17 Jul 2026 08:50:44 -0700
Subject: [PATCH 104/133] =?UTF-8?q?install.sh:=20persist=20only=20what=20i?=
 =?UTF-8?q?s=20ours=20=E2=80=94=20a=20firewall=20unit=20instead=20of=20ipt?=
 =?UTF-8?q?ables-persistent,=20scoped=20sysctl=20instead=20of=20--system?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The end-to-end install test (issues #4 and #5) caught the two steps
that reached beyond what is Dormice's to change on an operator's host.

The cloud-metadata step persisted its two DROP rules by installing
iptables-persistent — and apt resolves that package's conflict with
ufw by removing ufw, silently discarding the operator's firewall. The
netfilter-persistent snapshot was also always broader than our claim:
it saves the whole ruleset, operator rules and Docker's ephemeral NAT
entries included, when exactly two rules are ours to persist. Both
problems share one fix: a oneshot unit (dormice-metadata-firewall
.service), ordered after docker.service and before dormice.service,
re-adds the rules idempotently at boot — identical on every host, no
package dependency, no hand in anyone's firewall. It is started at
install time too, because a unit that has never run is an unproven
promise. Hosts persisted the old way keep their rules.v4 untouched;
doctor accepts either form and its fix line now points at install.sh.

The swappiness step applied its one-line file with `sysctl --system`,
which replays every sysctl source on the host mid-install. On the test
host that re-applied a dormant net.ipv4.ip_forward=0 from
/etc/sysctl.conf and cut Docker networking, surfacing two steps later
as an apt failure inside the base-image build with no visible
connection to sysctl. The step (now "kernel parameters") writes both
vm.swappiness=100 and net.ipv4.ip_forward=1 to 99-dormice.conf,
applies it scoped with sysctl -p, and proves boot-order effectiveness
explicitly instead: systemd-sysctl --cat-config yields the real
application order, and the last setter of each key must be our file —
which also catches the /etc/sysctl.conf-via-99-sysctl.conf symlink
that always outsorts 99-dormice.conf, and names the offending file and
value when it dies.

ip_forward gains persistence because dockerd only masks the problem:
it flips the flag on at every daemon start, so a boot config saying 0
stays invisible until the next config replay cuts every sandbox's
networking. That is also why the new doctor check is the one allowed
to read boot config — the effective value can never expose this
hazard. Effective 0 fails (sandboxes are cut right now); effective 1
with a boot winner of 0 warns and names the file.

Closes #4. Closes #5.
---
 .changeset/metal-donkeys-refuse.md            |  5 +
 deploy/install.sh                             | 99 +++++++++++++++----
 packages/cli/src/doctor.test.ts               | 93 ++++++++++++++++-
 packages/cli/src/doctor.ts                    | 94 ++++++++++++++++--
 .../console/src/features/doctor/fixtures.ts   |  8 +-
 website/content/docs/doctor.mdx               | 16 ++-
 6 files changed, 282 insertions(+), 33 deletions(-)
 create mode 100644 .changeset/metal-donkeys-refuse.md

diff --git a/.changeset/metal-donkeys-refuse.md b/.changeset/metal-donkeys-refuse.md
new file mode 100644
index 0000000..e220e20
--- /dev/null
+++ b/.changeset/metal-donkeys-refuse.md
@@ -0,0 +1,5 @@
+---
+'@dormice/cli': patch
+---
+
+`dor doctor` gains a `net.ipv4.ip_forward` check: fail when forwarding is off (sandboxes have no network right now), warn when it is on but the boot config would turn it off at the next sysctl replay — naming the offending file. The firewall-persistence check now recognizes the `dormice-metadata-firewall` systemd unit that install.sh writes instead of `iptables-persistent` (hosts persisted the old way still pass), and the swappiness fix no longer suggests `sysctl --system`, which replays unrelated operator settings.
diff --git a/deploy/install.sh b/deploy/install.sh
index 52401e6..d36d13d 100644
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -276,20 +276,50 @@ else
   note "created a ${SWAP_GB} GiB /swapfile, persisted in /etc/fstab"
 fi
 
-# ---- vm.swappiness = 100 ----------------------------------------------------
-# gVisor holds sandbox memory as shared memory, which the kernel refuses to
-# swap below swappiness 100 (measured at 60: 0 bytes reclaimed). The file is
-# named to sort after cloud-vendor sysctl.d files that ship swappiness=0.
-log 'vm.swappiness = 100'
-if [ "$(cat /proc/sys/vm/swappiness)" = 100 ]; then
-  note '[skip] effective value is already 100'
+# ---- kernel parameters (sysctl) ----------------------------------------------
+# vm.swappiness=100: gVisor holds sandbox memory as shared memory, which the
+# kernel refuses to swap below swappiness 100 (measured at 60: 0 bytes
+# reclaimed). net.ipv4.ip_forward=1: bridge networking dies without it, and
+# although dockerd flips it on at every daemon start, a boot config that says
+# 0 comes back at the next config replay and silently cuts every sandbox's
+# network. The file is named to sort after cloud-vendor sysctl.d files that
+# ship swappiness=0. Applied scoped — `sysctl --system` here would replay
+# every operator setting mid-install (an ip_forward=0 in /etc/sysctl.conf did
+# exactly that and killed the base-image build two steps later). Boot-order
+# effectiveness is verified against systemd-sysctl's own application order:
+# the winning value of each key must be the one we need. The value, not the
+# file — a host may legitimately set ip_forward=1 in its own later-sorting
+# config (the test host does), and that is agreement, not a conflict.
+log 'kernel parameters (vm.swappiness = 100, net.ipv4.ip_forward = 1)'
+SYSCTL_FILE=/etc/sysctl.d/99-dormice.conf
+sysctl_wanted='# Managed by Dormice install.sh — rewritten on every run.
+vm.swappiness=100
+net.ipv4.ip_forward=1'
+if [ "$(cat "$SYSCTL_FILE" 2>/dev/null)" = "$sysctl_wanted" ]; then
+  note "[skip] $SYSCTL_FILE is in place"
 else
-  echo 'vm.swappiness=100' >/etc/sysctl.d/99-dormice.conf
-  sysctl --system >/dev/null
-  [ "$(cat /proc/sys/vm/swappiness)" = 100 ] \
-    || die 'wrote /etc/sysctl.d/99-dormice.conf but the effective value still is not 100 — something later in sysctl order overrides it'
-  note 'set via /etc/sysctl.d/99-dormice.conf (survives reboot)'
+  printf '%s\n' "$sysctl_wanted" >"$SYSCTL_FILE"
+  note "wrote $SYSCTL_FILE (survives reboot)"
 fi
+sysctl -p "$SYSCTL_FILE" >/dev/null
+systemd_sysctl=/usr/lib/systemd/systemd-sysctl
+[ -x "$systemd_sysctl" ] || systemd_sysctl=/lib/systemd/systemd-sysctl
+[ -x "$systemd_sysctl" ] \
+  || die 'cannot find systemd-sysctl to verify the sysctl boot order — non-systemd hosts are not supported'
+for kv in vm.swappiness=100 net.ipv4.ip_forward=1; do
+  key=${kv%%=*} want=${kv#*=}
+  winner=$("$systemd_sysctl" --cat-config | awk -v key="$key" '
+    /^# \//       { file = $2; next }
+    /^[ \t]*[#;]/ { next }
+    {
+      eq = index($0, "="); if (eq == 0) next
+      k = substr($0, 1, eq - 1); gsub(/[ \t]/, "", k); sub(/^-/, "", k); gsub("/", ".", k)
+      if (k == key) { v = substr($0, eq + 1); gsub(/[ \t]/, "", v); print file " " v }
+    }' | tail -n 1)
+  [ "${winner#* }" = "$want" ] \
+    || die "$key must be $want at boot, but the sysctl boot order ends with ${winner% *} setting it to ${winner#* } — change or remove that line, then re-run"
+done
+note 'verified: the sysctl boot order ends with our values for both keys'
 
 # ---- cloud metadata firewall -------------------------------------------------
 # Sandboxes run untrusted code; on a cloud host with an attached role, one
@@ -306,16 +336,45 @@ for target in 169.254.0.0/16 100.100.100.200; do
   fi
 done
 if [ -n "$added" ]; then note "added DROP rules:$added"; else note '[skip] both DROP rules present'; fi
-if ! grep -qs 100.100.100.200 /etc/iptables/rules.v4; then
-  # Preseeded so apt never prompts; the explicit save below is what persists.
-  echo 'iptables-persistent iptables-persistent/autosave_v4 boolean true' | debconf-set-selections
-  echo 'iptables-persistent iptables-persistent/autosave_v6 boolean true' | debconf-set-selections
-  command -v netfilter-persistent >/dev/null || { apt-get update -q; apt-get install -qy iptables-persistent; }
-  netfilter-persistent save >/dev/null 2>&1
-  note 'persisted to /etc/iptables/rules.v4 (survives reboot)'
+# Persistence is our own oneshot unit that re-adds the rules after docker
+# creates the DOCKER-USER chain at boot (docker never flushes that chain
+# afterwards). Deliberately NOT iptables-persistent: installing it makes apt
+# remove ufw (the packages conflict) — silently discarding an operator's
+# firewall — and `netfilter-persistent save` snapshots the whole ruleset,
+# operator rules and Docker's ephemeral NAT entries included, when exactly
+# two rules are ours to persist. Hosts persisted the old way keep their
+# /etc/iptables/rules.v4 untouched; the -C checks make duplicates impossible.
+FIREWALL_UNIT=/etc/systemd/system/dormice-metadata-firewall.service
+firewall_unit=$(cat <<'EOF'
+# Written by Dormice install.sh — rewritten on every run. Sandboxes run
+# untrusted code; these rules keep them away from the cloud metadata service.
+[Unit]
+Description=Dormice: block cloud metadata endpoints from containers
+After=docker.service
+Requires=docker.service
+Before=dormice.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/bin/sh -c 'iptables -C DOCKER-USER -d 169.254.0.0/16 -j DROP 2>/dev/null || iptables -I DOCKER-USER -d 169.254.0.0/16 -j DROP'
+ExecStart=/bin/sh -c 'iptables -C DOCKER-USER -d 100.100.100.200 -j DROP 2>/dev/null || iptables -I DOCKER-USER -d 100.100.100.200 -j DROP'
+
+[Install]
+WantedBy=multi-user.target
+EOF
+)
+if [ "$(cat "$FIREWALL_UNIT" 2>/dev/null)" = "$firewall_unit" ]; then
+  note '[skip] persistence unit is in place'
 else
-  note '[skip] rules already persisted'
+  printf '%s\n' "$firewall_unit" >"$FIREWALL_UNIT"
+  systemctl daemon-reload
+  note "wrote $FIREWALL_UNIT (re-adds the rules after docker starts — survives reboot)"
 fi
+systemctl enable dormice-metadata-firewall >/dev/null 2>&1
+# Started now, not only at boot: a unit that has never run is an unproven
+# promise, and the start is a no-op when the rules are already in.
+systemctl restart dormice-metadata-firewall
 
 # ---- Dormice code -----------------------------------------------------------
 # Defined before the pull so the rollback in on_exit can always call it.
diff --git a/packages/cli/src/doctor.test.ts b/packages/cli/src/doctor.test.ts
index 538ebbf..865febc 100644
--- a/packages/cli/src/doctor.test.ts
+++ b/packages/cli/src/doctor.test.ts
@@ -30,6 +30,17 @@ const DF_ROOMY =
   'Filesystem 1024-blocks Used Available Capacity Mounted on\n' +
   '/dev/vda3 200000000 50000000 150000000 25% /';
 
+// systemd-sysctl --cat-config output shape: a `# /path` line opens each
+// file, then that file's lines follow. Application order = boot order.
+const CAT_CONFIG_GOOD = [
+  '# /usr/lib/sysctl.d/50-default.conf',
+  'kernel.sysrq = 0x01b6',
+  '# /etc/sysctl.d/99-dormice.conf',
+  '# Managed by Dormice install.sh — rewritten on every run.',
+  'vm.swappiness=100',
+  'net.ipv4.ip_forward=1',
+].join('\n');
+
 /**
  * A whole healthy host, faked. Tests override single facts to break one
  * check at a time — the doctor equivalent of the contract suite's "one
@@ -50,6 +61,7 @@ function fakeHost(
     '/etc/docker/daemon.json': GOOD_DAEMON_JSON,
     '/proc/meminfo': 'MemTotal: 30000000 kB\nSwapTotal: 16777212 kB',
     '/proc/sys/vm/swappiness': '100\n',
+    '/proc/sys/net/ipv4/ip_forward': '1\n',
     '/etc/iptables/rules.v4': IPTABLES_GOOD,
     '/etc/caddy/Caddyfile':
       '# Managed by Dormice — setIngress rewrites this file.\n\n:80 {\n\treverse_proxy 127.0.0.1:3676\n}\n',
@@ -61,6 +73,8 @@ function fakeHost(
       '{"runc":{"path":"runc"},"runsc":{"path":"/usr/local/bin/runsc"}}',
     ),
     'iptables -S DOCKER-USER': ok(IPTABLES_GOOD),
+    'systemctl is-enabled dormice-metadata-firewall': ok('enabled\n'),
+    '/usr/lib/systemd/systemd-sysctl --cat-config': ok(CAT_CONFIG_GOOD),
     [`docker image inspect ${IMAGE}`]: ok('[{}]'),
     'df -Pk /var/lib/dormice': ok(DF_ROOMY),
     [`docker run --rm --runtime=runsc ${IMAGE} uname -r`]:
@@ -232,15 +246,90 @@ describe('metadata firewall', () => {
 
   it('rules present but not persisted is a warning, not a failure', async () => {
     const { results, failed } = await runDoctor(
-      fakeHost({ files: { '/etc/iptables/rules.v4': undefined } }),
+      fakeHost({
+        files: { '/etc/iptables/rules.v4': undefined },
+        commands: {
+          'systemctl is-enabled dormice-metadata-firewall': boom('disabled'),
+        },
+      }),
     );
     expect(results['metadata-persisted']).toMatchObject({
       status: 'warn',
-      fix: expect.stringContaining('iptables-persistent'),
+      fix: expect.stringContaining('install.sh'),
     });
     // Warnings alone never flip the exit code.
     expect(failed).toBe(false);
   });
+
+  it('a pre-unit install persisted via iptables-persistent still passes', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        commands: {
+          'systemctl is-enabled dormice-metadata-firewall': boom(
+            'Failed to get unit file state',
+          ),
+        },
+      }),
+    );
+    expect(results['metadata-persisted']).toMatchObject({
+      status: 'pass',
+      detail: expect.stringContaining('rules.v4'),
+    });
+  });
+});
+
+describe('sandbox networking (net.ipv4.ip_forward)', () => {
+  it('an effective 0 is a hard failure — sandboxes are cut right now', async () => {
+    const { results, failed } = await runDoctor(
+      fakeHost({ files: { '/proc/sys/net/ipv4/ip_forward': '0\n' } }),
+    );
+    expect(failed).toBe(true);
+    expect(results['ip-forward']).toMatchObject({
+      status: 'fail',
+      detail: expect.stringContaining('every sandbox is cut'),
+    });
+  });
+
+  it('effective 1 with a boot config saying 0 warns and names the file', async () => {
+    // The real incident: /etc/sysctl.conf shipped ip_forward=0, applied via
+    // Debian's 99-sysctl.conf symlink — which sorts after 99-dormice.conf.
+    const { results, failed } = await runDoctor(
+      fakeHost({
+        commands: {
+          '/usr/lib/systemd/systemd-sysctl --cat-config': ok(
+            [
+              '# /etc/sysctl.d/99-dormice.conf',
+              'vm.swappiness=100',
+              'net.ipv4.ip_forward=1',
+              '# /etc/sysctl.d/99-sysctl.conf',
+              'net.ipv4.ip_forward = 0',
+            ].join('\n'),
+          ),
+        },
+      }),
+    );
+    expect(failed).toBe(false);
+    expect(results['ip-forward']).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('99-sysctl.conf'),
+    });
+  });
+
+  it('effective 1 with no boot config at all passes — dockerd re-enables it', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        commands: {
+          '/usr/lib/systemd/systemd-sysctl --cat-config': ok(
+            '# /usr/lib/sysctl.d/50-default.conf\nkernel.sysrq = 0x01b6\n',
+          ),
+        },
+      }),
+    );
+    expect(results['ip-forward']).toMatchObject({
+      status: 'pass',
+      detail: expect.stringContaining('dockerd re-enables'),
+    });
+  });
 });
 
 describe('daemon configuration', () => {
diff --git a/packages/cli/src/doctor.ts b/packages/cli/src/doctor.ts
index 1d997dd..3f82500 100644
--- a/packages/cli/src/doctor.ts
+++ b/packages/cli/src/doctor.ts
@@ -112,6 +112,34 @@ const DAEMON_JSON = '/etc/docker/daemon.json';
 const RULES_V4 = '/etc/iptables/rules.v4';
 const METADATA_IP = '100.100.100.200';
 const METADATA_RANGE = '169.254.0.0/16';
+const SYSCTL_FILE = '/etc/sysctl.d/99-dormice.conf';
+// Not on PATH; /lib is merged into /usr/lib on every supported target.
+const SYSTEMD_SYSCTL = '/usr/lib/systemd/systemd-sysctl';
+
+/**
+ * The file whose value for `key` wins at boot, parsed from
+ * `systemd-sysctl --cat-config` — the authoritative application order,
+ * with `# /path` lines marking each file. Last setter wins.
+ */
+function sysctlBootWinner(
+  catConfig: string,
+  key: string,
+): { file: string; value: string } | undefined {
+  let file = 'unknown';
+  let winner: { file: string; value: string } | undefined;
+  for (const line of catConfig.split('\n')) {
+    if (line.startsWith('# /')) {
+      file = line.slice(2).trim();
+      continue;
+    }
+    if (/^\s*[#;]/.test(line)) continue;
+    const eq = line.indexOf('=');
+    if (eq < 0) continue;
+    const k = line.slice(0, eq).trim().replace(/^-/, '').replaceAll('/', '.');
+    if (k === key) winner = { file, value: line.slice(eq + 1).trim() };
+  }
+  return winner;
+}
 
 async function daemonJson(
   ctx: DoctorContext,
@@ -289,10 +317,50 @@ const CHECKS: DoctorCheck[] = [
         ? pass('100 (effective value)')
         : fail(
             `effective value is ${value} — below 100 the kernel refuses to swap gVisor's shmem-held sandbox memory (measured at 60: 0 bytes reclaimed)`,
-            "echo 'vm.swappiness=100' > /etc/sysctl.d/99-dormice.conf && sysctl --system",
+            `re-run install.sh — it persists 100 in ${SYSCTL_FILE}, applies it scoped, and verifies nothing later in the sysctl boot order overrides it`,
           );
     },
   },
+  {
+    id: 'ip-forward',
+    title: 'net.ipv4.ip_forward = 1',
+    needs: ['os-linux'],
+    run: async (ctx) => {
+      const raw = await ctx.readTextFile('/proc/sys/net/ipv4/ip_forward');
+      const value = raw?.trim();
+      if (value === undefined)
+        return fail('cannot read /proc/sys/net/ipv4/ip_forward');
+      if (value !== '1') {
+        return fail(
+          `effective value is ${value} — bridge networking is off, every sandbox is cut from the network right now`,
+          `re-run install.sh — it persists 1 in ${SYSCTL_FILE}, applies it, and verifies the sysctl boot order`,
+        );
+      }
+      // 1 now proves little: dockerd flips it on at every daemon start. The
+      // hazard is a boot config that says 0 — the next config replay (some
+      // other installer's `sysctl --system`) re-applies it and cuts sandbox
+      // networking until dockerd restarts. Unlike swappiness, whose drift
+      // surfaces in the effective value after a reboot, this one can stay
+      // masked forever — so this check alone also reads the boot config, in
+      // systemd-sysctl's own application order.
+      const res = await ctx.run(SYSTEMD_SYSCTL, ['--cat-config']);
+      if (!res.ok) {
+        return pass('1 (effective value; boot config unreadable here)');
+      }
+      const winner = sysctlBootWinner(res.stdout, 'net.ipv4.ip_forward');
+      if (winner !== undefined && winner.value !== '1') {
+        return warn(
+          `1 now, but ${winner.file} sets ${winner.value} at boot — the next sysctl config replay cuts every sandbox's networking`,
+          `drop net.ipv4.ip_forward from ${winner.file}, or re-run install.sh and let it verify the boot order`,
+        );
+      }
+      return pass(
+        winner === undefined
+          ? '1 (effective value; no boot config sets it — dockerd re-enables it at every start)'
+          : `1 (effective value, persisted by ${winner.file})`,
+      );
+    },
+  },
   {
     id: 'metadata-firewall',
     title: 'cloud metadata firewall',
@@ -325,13 +393,25 @@ const CHECKS: DoctorCheck[] = [
     title: 'firewall rules persisted',
     needs: ['metadata-firewall'],
     run: async (ctx) => {
+      const unit = await ctx.run('systemctl', [
+        'is-enabled',
+        'dormice-metadata-firewall',
+      ]);
+      if (unit.ok) {
+        return pass(
+          'dormice-metadata-firewall.service re-adds the rules after docker starts',
+        );
+      }
+      // Pre-unit installs persisted via iptables-persistent — still real
+      // persistence, not drift to repair.
       const rules = await ctx.readTextFile(RULES_V4);
-      return rules?.includes(METADATA_IP) && rules.includes('169.254')
-        ? pass(`both rules in ${RULES_V4}`)
-        : warn(
-            'the DROP rules live only in memory — a reboot silently drops them',
-            'apt-get install -y iptables-persistent && netfilter-persistent save',
-          );
+      if (rules?.includes(METADATA_IP) && rules.includes('169.254')) {
+        return pass(`both rules in ${RULES_V4} (iptables-persistent)`);
+      }
+      return warn(
+        'the DROP rules live only in memory — a reboot silently drops them',
+        're-run install.sh (it writes the dormice-metadata-firewall systemd unit)',
+      );
     },
   },
   {
diff --git a/packages/console/src/features/doctor/fixtures.ts b/packages/console/src/features/doctor/fixtures.ts
index 33d9517..2400bd4 100644
--- a/packages/console/src/features/doctor/fixtures.ts
+++ b/packages/console/src/features/doctor/fixtures.ts
@@ -87,6 +87,12 @@ export const SAMPLE_DOCTOR: DoctorReport = {
       detail:
         '直读 /proc/sys/vm/swappiness 的生效值 — gVisor 的共享内存低于 100 挤不出去',
     },
+    {
+      id: 'ip-forward',
+      title: 'net.ipv4.ip_forward = 1',
+      status: 'pass',
+      detail: '生效值 1,且 /etc/sysctl.d/99-dormice.conf 在启动序中胜出',
+    },
     {
       id: 'metadata-firewall',
       title: '云元数据防火墙',
@@ -97,7 +103,7 @@ export const SAMPLE_DOCTOR: DoctorReport = {
       id: 'metadata-persisted',
       title: '防火墙规则已持久化',
       status: 'pass',
-      detail: '/etc/iptables/rules.v4 在,重启不丢',
+      detail: 'dormice-metadata-firewall.service 开机在 docker 之后补规则',
     },
     {
       id: 'api-token',
diff --git a/website/content/docs/doctor.mdx b/website/content/docs/doctor.mdx
index 95aa26c..49a1991 100644
--- a/website/content/docs/doctor.mdx
+++ b/website/content/docs/doctor.mdx
@@ -60,13 +60,23 @@ know why; the Linux terms in it are covered in
   kind of memory gVisor holds sandboxes in; measured at the default 60:
   0 bytes reclaimed. This is the check that reads the live value.
 
-## Network containment
-
+## Network
+
+- **net.ipv4.ip_forward = 1** — off, bridge networking is dead and
+  every sandbox is cut from the network right now. This is the one
+  check where the live value can lie: dockerd re-enables forwarding at
+  every daemon start, masking a boot config that says 0 until the next
+  sysctl config replay switches it back off — so it also reads the
+  boot config, in systemd-sysctl's own application order, and *warns*
+  naming the file that would turn it off.
 - **cloud metadata firewall** — `DROP` rules in the `DOCKER-USER` chain
   for `169.254.0.0/16` and `100.100.100.200`; without them a sandbox
   can steal cloud credentials from the metadata service.
 - **firewall rules persisted** — *warn*: rules living only in memory
-  silently vanish on reboot.
+  silently vanish on reboot. Persistence is the
+  `dormice-metadata-firewall` systemd unit the installer writes; a
+  host persisted by an older install via `iptables-persistent` still
+  passes.
 
 ## Configuration
 

From bb19ea25d9767a921c48f4c6c09f07983d84691e Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 18 Jul 2026 15:11:53 +0800
Subject: [PATCH 105/133] =?UTF-8?q?The=20landing=20page=20grows=20from=20a?=
 =?UTF-8?q?=20bare=20pitch=20into=20a=20four-act=20narrative,=20every=20cl?=
 =?UTF-8?q?aim=20still=20docs-backed:=20the=20hero=20goes=20asymmetric=20t?=
 =?UTF-8?q?wo-column=20=E2=80=94=20proposition,=20CTAs=20and=20a=20copyabl?=
 =?UTF-8?q?e=20one-line=20install=20on=20the=20left,=20and=20on=20the=20ri?=
 =?UTF-8?q?ght=20the=20single=20most=20characteristic=20artifact=20Dormice?=
 =?UTF-8?q?=20owns:=20the=20official=20e2b=20SDK=20snippet=20verbatim=20fr?=
 =?UTF-8?q?om=20docs/e2b-sdks.mdx,=20deliberately=20monochrome=20except=20?=
 =?UTF-8?q?for=20the=20two=20highlighted=20URL=20lines,=20because=20"2=20l?=
 =?UTF-8?q?ines=20changed"=20IS=20the=20pitch=20and=20syntax-rainbow=20wou?=
 =?UTF-8?q?ld=20bury=20it.=20The=20signature=20section=20is=20the=20coolin?=
 =?UTF-8?q?g=20ladder:=20active=20=E2=86=92=20frozen=20=E2=86=92=20stopped?=
 =?UTF-8?q?=20=E2=86=92=20archived=20as=20a=20hairline=20four-cell=20grid?=
 =?UTF-8?q?=20carrying=20the=20default=20thresholds=20(10=20min=20/=203=20?=
 =?UTF-8?q?d=20/=207=20d)=20and=20the=20real=20measured=20numbers=20(1=20G?=
 =?UTF-8?q?iB=20=E2=86=92=20~5=20MiB,=20~50=20ms=20wake)=20in=20the=20plac?=
 =?UTF-8?q?e=20they=20belong=20=E2=80=94=20a=20genuine=20sequence=20whose?=
 =?UTF-8?q?=20left-to-right=20order=20encodes=20information,=20not=20vanit?=
 =?UTF-8?q?y=20stat=20cards.=20Features=20widen=20from=20four=20cards=20to?=
 =?UTF-8?q?=20a=20six-item=20icon=20grid,=20adding=20the=20two=20different?=
 =?UTF-8?q?iators=20the=20old=20page=20left=20unsold=20(gVisor=20without?=
 =?UTF-8?q?=20KVM,=20S3=20archiving),=20and=20a=20closing=20get-started=20?=
 =?UTF-8?q?band=20restates=20the=20door.=20The=20install=20command=20becom?=
 =?UTF-8?q?es=20a=20single=20source=20(InstallCommand,=20shared=20by=20her?=
 =?UTF-8?q?o=20and=20footer=20so=20the=20literal=20can=20never=20drift=20f?=
 =?UTF-8?q?rom=20docs/installation.mdx)=20with=20the=20landing's=20only=20?=
 =?UTF-8?q?client=20island,=20a=20copy=20button.=20Flex/grid=20children=20?=
 =?UTF-8?q?that=20hold=20nowrap=20content=20get=20min-w-0=20=E2=80=94=20ve?=
 =?UTF-8?q?rified=20via=20CDP=20at=20a=20real=20390=20px=20viewport=20that?=
 =?UTF-8?q?=20body.scrollWidth=20=3D=3D=3D=20390;=20the=20earlier=20"mobil?=
 =?UTF-8?q?e=20overflow"=20turned=20out=20to=20be=20a=20headless-Chrome=20?=
 =?UTF-8?q?--window-size=20artifact,=20not=20a=20page=20bug.=20Light,=20da?=
 =?UTF-8?q?rk=20and=20mobile=20all=20screenshot-checked;=20shadcn=20tokens?=
 =?UTF-8?q?=20only,=20no=20new=20colors.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 website/src/app/page.tsx                      |   7 +-
 .../src/components/sections/CopyButton.tsx    |  28 ++++
 website/src/components/sections/Features.tsx  |  96 +++++++++----
 .../src/components/sections/GetStarted.tsx    |  40 ++++++
 website/src/components/sections/Hero.tsx      | 132 ++++++++++++++----
 .../components/sections/InstallCommand.tsx    |  28 ++++
 website/src/components/sections/Lifecycle.tsx |  83 +++++++++++
 7 files changed, 358 insertions(+), 56 deletions(-)
 create mode 100644 website/src/components/sections/CopyButton.tsx
 create mode 100644 website/src/components/sections/GetStarted.tsx
 create mode 100644 website/src/components/sections/InstallCommand.tsx
 create mode 100644 website/src/components/sections/Lifecycle.tsx

diff --git a/website/src/app/page.tsx b/website/src/app/page.tsx
index 431a767..f9d250e 100644
--- a/website/src/app/page.tsx
+++ b/website/src/app/page.tsx
@@ -1,13 +1,18 @@
 import { Features } from '@/components/sections/Features';
+import { GetStarted } from '@/components/sections/GetStarted';
 import { Hero } from '@/components/sections/Hero';
+import { Lifecycle } from '@/components/sections/Lifecycle';
 
-// Landing narrative: hero (pitch + install command) → feature cards.
+// Landing narrative: hero (pitch + E2B migration panel + install command)
+// → lifecycle ladder (the differentiator) → feature grid → closing CTA.
 // Site chrome (header, footer) lives in the root layout.
 export default function HomePage() {
   return (
     <main className="flex-1">
       <Hero />
+      <Lifecycle />
       <Features />
+      <GetStarted />
     </main>
   );
 }
diff --git a/website/src/components/sections/CopyButton.tsx b/website/src/components/sections/CopyButton.tsx
new file mode 100644
index 0000000..3c43810
--- /dev/null
+++ b/website/src/components/sections/CopyButton.tsx
@@ -0,0 +1,28 @@
+'use client';
+
+import { Copy01Icon, Tick02Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useState } from 'react';
+import { Button } from '@/components/ui/button';
+
+// Clipboard needs the browser, so this is the one client island in the
+// landing sections. The tick reverts on a timer; overlapping clicks just
+// extend the confirmation, which is the behavior a user expects.
+export function CopyButton({ text }: { text: string }) {
+  const [copied, setCopied] = useState(false);
+
+  return (
+    <Button
+      variant="ghost"
+      size="icon-sm"
+      aria-label="Copy command"
+      onClick={async () => {
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+      }}
+    >
+      <HugeiconsIcon icon={copied ? Tick02Icon : Copy01Icon} />
+    </Button>
+  );
+}
diff --git a/website/src/components/sections/Features.tsx b/website/src/components/sections/Features.tsx
index 9616c06..1774b84 100644
--- a/website/src/components/sections/Features.tsx
+++ b/website/src/components/sections/Features.tsx
@@ -1,33 +1,42 @@
-import type { ReactNode } from 'react';
 import {
-  Card,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from '@/components/ui/card';
+  ApiIcon,
+  CloudUploadIcon,
+  Database01Icon,
+  Moon02Icon,
+  RepeatIcon,
+  Shield01Icon,
+} from '@hugeicons/core-free-icons';
+import type { IconSvgElement } from '@hugeicons/react';
+import { HugeiconsIcon } from '@hugeicons/react';
+import type { ReactNode } from 'react';
 
-const features: { title: string; body: ReactNode }[] = [
+// Every claim here is docs-backed (quickstart, lifecycle, architecture,
+// e2b-sdks, archiving) — the landing page never outruns the docs.
+const features: { icon: IconSvgElement; title: string; body: ReactNode }[] = [
   {
-    title: 'Sandboxes are permanent',
+    icon: RepeatIcon,
+    title: 'One name, one sandbox',
     body: (
       <>
         <code>acquireSandbox(name)</code> is the entire mental model — the same
-        key always comes back to the same sandbox: created, woken or restarted
-        as needed.
+        name always comes back to the same sandbox: created, woken, restarted or
+        restored as needed.
       </>
     ),
   },
   {
+    icon: Moon02Icon,
     title: 'Idle is free',
     body: (
       <>
-        Sandboxes cool down on their own, one rung at a time. Measured on real
-        hardware: 1 GiB of sandbox memory freezes down to ~5 MiB, and waking
-        takes ~50 ms — with every process still running.
+        Sandboxes cool down on their own, one step at a time, and any acquire
+        brings them back. Freeze, stop and archive thresholds are per-sandbox
+        knobs — <code>null</code> means never.
       </>
     ),
   },
   {
+    icon: Database01Icon,
     title: 'Deploys like a single binary',
     body: (
       <>
@@ -37,11 +46,33 @@ const features: { title: string; body: ReactNode }[] = [
     ),
   },
   {
+    icon: ApiIcon,
     title: 'E2B compatible',
     body: (
       <>
-        The official <code>e2b</code> SDK runs against Dormice by changing two
-        URLs — commands, files, PTY, signed URLs, watch, metrics.
+        The official <code>e2b</code> SDKs — JavaScript and Python — run against
+        Dormice unmodified: commands, files, PTY, signed URLs, watch, metrics.
+      </>
+    ),
+  },
+  {
+    icon: Shield01Icon,
+    title: 'gVisor isolation, no KVM',
+    body: (
+      <>
+        Every sandbox runs behind gVisor&apos;s userspace kernel, so Dormice
+        works on ordinary cloud VMs where hardware virtualization is not
+        available.
+      </>
+    ),
+  },
+  {
+    icon: CloudUploadIcon,
+    title: 'Archives to S3',
+    body: (
+      <>
+        Long-idle sandboxes compress into any S3-compatible bucket and restore
+        on demand with real progress reporting — off unless you configure it.
       </>
     ),
   },
@@ -49,15 +80,32 @@ const features: { title: string; body: ReactNode }[] = [
 
 export function Features() {
   return (
-    <section className="mx-auto grid w-full max-w-4xl gap-4 px-4 pb-16 text-left sm:grid-cols-2 sm:pb-24">
-      {features.map((feature) => (
-        <Card key={feature.title}>
-          <CardHeader>
-            <CardTitle>{feature.title}</CardTitle>
-            <CardDescription>{feature.body}</CardDescription>
-          </CardHeader>
-        </Card>
-      ))}
+    <section className="mx-auto w-full max-w-6xl px-4 py-16 sm:py-20">
+      <p className="font-mono text-xs tracking-widest text-muted-foreground uppercase">
+        Platform
+      </p>
+      <h2 className="mt-3 text-2xl font-semibold tracking-tight sm:text-3xl">
+        One daemon, a full sandbox platform
+      </h2>
+      <p className="mt-3 max-w-2xl text-muted-foreground">
+        Native API, the official E2B SDKs, a CLI and a web console — all talking
+        to the same single process on your machine.
+      </p>
+
+      <div className="mt-10 grid gap-x-8 gap-y-10 sm:grid-cols-2 lg:grid-cols-3">
+        {features.map((feature) => (
+          <div key={feature.title}>
+            <div className="flex size-9 items-center justify-center rounded-lg border bg-muted/50">
+              <HugeiconsIcon
+                icon={feature.icon}
+                className="size-4.5 text-foreground"
+              />
+            </div>
+            <h3 className="mt-4 font-medium">{feature.title}</h3>
+            <p className="mt-2 text-sm text-muted-foreground">{feature.body}</p>
+          </div>
+        ))}
+      </div>
     </section>
   );
 }
diff --git a/website/src/components/sections/GetStarted.tsx b/website/src/components/sections/GetStarted.tsx
new file mode 100644
index 0000000..929efc9
--- /dev/null
+++ b/website/src/components/sections/GetStarted.tsx
@@ -0,0 +1,40 @@
+import Link from 'next/link';
+import { InstallCommand } from '@/components/sections/InstallCommand';
+import { Button } from '@/components/ui/button';
+import { GITHUB_URL } from '@/lib/site';
+
+// Closing restatement of the hero's call to action: by the time a reader
+// is here they've seen the pitch, so this section is just the door.
+export function GetStarted() {
+  return (
+    <section className="border-t">
+      <div className="mx-auto flex w-full max-w-6xl flex-col items-center px-4 py-16 text-center sm:py-20">
+        <h2 className="text-2xl font-semibold tracking-tight sm:text-3xl">
+          Self-host it in one command
+        </h2>
+        <p className="mt-3 max-w-xl text-muted-foreground">
+          The installer sets up Docker, gVisor and the daemon on a bare Linux
+          host, and running it again upgrades in place.
+        </p>
+        <InstallCommand className="mt-8" />
+        <div className="mt-8 flex items-center gap-3">
+          <Button
+            size="lg"
+            nativeButton={false}
+            render={<Link href="/docs/quickstart" />}
+          >
+            Read the quickstart
+          </Button>
+          <Button
+            size="lg"
+            variant="outline"
+            nativeButton={false}
+            render={<a href={GITHUB_URL} />}
+          >
+            Star on GitHub
+          </Button>
+        </div>
+      </div>
+    </section>
+  );
+}
diff --git a/website/src/components/sections/Hero.tsx b/website/src/components/sections/Hero.tsx
index 8e50ceb..ea49da9 100644
--- a/website/src/components/sections/Hero.tsx
+++ b/website/src/components/sections/Hero.tsx
@@ -1,42 +1,112 @@
 import Link from 'next/link';
+import { InstallCommand } from '@/components/sections/InstallCommand';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { GITHUB_URL } from '@/lib/site';
+import { cn } from '@/lib/utils';
+
+// The snippet from docs/e2b-sdks.mdx, verbatim. `changed` marks the only
+// two lines that differ from stock E2B code — the highlight IS the pitch,
+// so the rest of the code stays deliberately monochrome.
+const migrationLines: { id: string; text: string; changed?: boolean }[] = [
+  { id: 'import', text: "import { Sandbox } from 'e2b';" },
+  { id: 'blank-1', text: '' },
+  { id: 'create', text: 'const sbx = await Sandbox.create({' },
+  {
+    id: 'api-key',
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: displayed source code, not an interpolation bug
+    text: '  apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`,',
+  },
+  {
+    id: 'api-url',
+    text: "  apiUrl: 'http://127.0.0.1:3676/e2b/api',",
+    changed: true,
+  },
+  {
+    id: 'sandbox-url',
+    text: "  sandboxUrl: 'http://127.0.0.1:3676/e2b/envd',",
+    changed: true,
+  },
+  { id: 'close', text: '});' },
+  { id: 'blank-2', text: '' },
+  { id: 'run', text: "await sbx.commands.run('echo hello');" },
+];
 
 export function Hero() {
   return (
-    <section className="flex flex-col items-center px-4 py-16 text-center sm:py-24">
-      <Badge variant="secondary">Early development</Badge>
-      <h1 className="mt-4 max-w-3xl text-4xl font-semibold tracking-tight text-balance sm:text-5xl">
-        The SQLite of agent sandboxes
-      </h1>
-      <p className="mt-6 max-w-2xl text-lg text-muted-foreground">
-        A self-hosted sandbox platform for AI agents. One machine, sandboxes
-        that live forever, idle costs nothing.
-      </p>
-      <div className="mt-8 flex items-center gap-3">
-        <Button size="lg" nativeButton={false} render={<Link href="/docs" />}>
-          Get started
-        </Button>
-        <Button
-          size="lg"
-          variant="outline"
-          nativeButton={false}
-          render={<a href={GITHUB_URL} />}
-        >
-          GitHub
-        </Button>
+    <section className="border-b">
+      <div className="mx-auto grid w-full max-w-6xl items-center gap-12 px-4 py-16 sm:py-20 lg:grid-cols-[1fr_minmax(0,30rem)] lg:gap-16 lg:py-24">
+        <div className="flex min-w-0 flex-col items-start">
+          <div className="flex items-center gap-2">
+            <span className="font-mono text-xs tracking-widest text-muted-foreground uppercase">
+              Self-hosted · Apache-2.0
+            </span>
+            <Badge variant="secondary">Early development</Badge>
+          </div>
+          <h1 className="mt-4 text-4xl font-semibold tracking-tight text-balance sm:text-5xl">
+            The SQLite of agent sandboxes
+          </h1>
+          <p className="mt-5 max-w-xl text-lg text-pretty text-muted-foreground">
+            A sandbox platform for AI agents that runs on your own machine. One
+            daemon, sandboxes that live forever, idle costs nothing.
+          </p>
+          <div className="mt-8 flex items-center gap-3">
+            <Button
+              size="lg"
+              nativeButton={false}
+              render={<Link href="/docs/quickstart" />}
+            >
+              Get started
+            </Button>
+            <Button
+              size="lg"
+              variant="outline"
+              nativeButton={false}
+              render={<a href={GITHUB_URL} />}
+            >
+              GitHub
+            </Button>
+          </div>
+          <InstallCommand className="mt-8" />
+          <p className="mt-3 text-xs text-muted-foreground">
+            Works end to end against real infrastructure, not production-ready
+            yet.
+          </p>
+        </div>
+
+        <figure className="w-full min-w-0">
+          <div className="overflow-hidden rounded-xl border bg-card shadow-sm">
+            <div className="flex items-center justify-between border-b px-4 py-2.5">
+              <span className="font-mono text-xs text-muted-foreground">
+                agent.ts
+              </span>
+              <Badge variant="outline" className="font-mono text-[11px]">
+                2 lines changed
+              </Badge>
+            </div>
+            <pre className="overflow-x-auto py-4 font-mono text-[13px] leading-6">
+              <code>
+                {migrationLines.map((line) => (
+                  <div
+                    key={line.id}
+                    className={cn(
+                      'w-fit min-w-full whitespace-pre px-4',
+                      line.changed &&
+                        'border-l-2 border-primary bg-primary/10 pl-3.5',
+                    )}
+                  >
+                    {line.text || ' '}
+                  </div>
+                ))}
+              </code>
+            </pre>
+          </div>
+          <figcaption className="mt-3 text-center text-xs text-muted-foreground">
+            The official <code>e2b</code> SDK, unmodified — point two URLs at
+            your own machine.
+          </figcaption>
+        </figure>
       </div>
-      <p className="mt-4 text-xs text-muted-foreground">
-        Works end to end against real infrastructure, not production-ready yet.
-      </p>
-      <pre className="mt-10 max-w-full overflow-x-auto rounded-lg border bg-card px-5 py-4 text-left text-sm">
-        <code>
-          curl -fsSL
-          https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh
-          | bash
-        </code>
-      </pre>
     </section>
   );
 }
diff --git a/website/src/components/sections/InstallCommand.tsx b/website/src/components/sections/InstallCommand.tsx
new file mode 100644
index 0000000..38fbdee
--- /dev/null
+++ b/website/src/components/sections/InstallCommand.tsx
@@ -0,0 +1,28 @@
+import { CopyButton } from '@/components/sections/CopyButton';
+import { cn } from '@/lib/utils';
+
+// The same literal as docs/installation.mdx — the landing page must never
+// advertise a command the docs don't stand behind.
+const INSTALL_COMMAND =
+  'curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash';
+
+// One-line install prompt, shared by the hero and the closing section so
+// the command can never drift between the two.
+export function InstallCommand({ className }: { className?: string }) {
+  return (
+    <div
+      className={cn(
+        'flex w-full max-w-xl items-center gap-1 rounded-lg border bg-card py-1.5 pr-1.5 pl-4 font-mono text-[13px] shadow-xs',
+        className,
+      )}
+    >
+      <span aria-hidden className="select-none text-muted-foreground">
+        $
+      </span>
+      <code className="min-w-0 flex-1 overflow-x-auto whitespace-nowrap px-2 py-1">
+        {INSTALL_COMMAND}
+      </code>
+      <CopyButton text={INSTALL_COMMAND} />
+    </div>
+  );
+}
diff --git a/website/src/components/sections/Lifecycle.tsx b/website/src/components/sections/Lifecycle.tsx
new file mode 100644
index 0000000..e7b0a0f
--- /dev/null
+++ b/website/src/components/sections/Lifecycle.tsx
@@ -0,0 +1,83 @@
+import Link from 'next/link';
+
+// The four states and every number below come from docs/lifecycle.mdx —
+// measured on real hardware, not aspirational. The ladder is a genuine
+// sequence, so the left-to-right structure carries real information.
+const stages = [
+  {
+    state: 'active',
+    when: 'in use',
+    body: 'The container is running, normally. Full RAM, full speed.',
+    cost: 'full resources',
+  },
+  {
+    state: 'frozen',
+    when: 'after 10 min idle',
+    body: 'Every process is suspended and its memory pushed out to swap — 1 GiB of sandbox memory drops to about 5 MiB.',
+    cost: '~5 MiB RAM · wakes in ~50 ms',
+  },
+  {
+    state: 'stopped',
+    when: 'after 3 days',
+    body: 'The container is shut down; only the disk remains. Waking is a cold start — files survive, processes do not.',
+    cost: 'disk only · cold start in seconds',
+  },
+  {
+    state: 'archived',
+    when: 'after 7 days',
+    body: 'The disk is compressed and shipped to your S3-compatible bucket; nothing remains on the host.',
+    cost: 'S3 only · restores on acquire',
+  },
+];
+
+export function Lifecycle() {
+  return (
+    <section className="border-b bg-muted/40">
+      <div className="mx-auto w-full max-w-6xl px-4 py-16 sm:py-20">
+        <p className="font-mono text-xs tracking-widest text-muted-foreground uppercase">
+          Lifecycle
+        </p>
+        <h2 className="mt-3 text-2xl font-semibold tracking-tight sm:text-3xl">
+          Idle sandboxes cool themselves down
+        </h2>
+        <p className="mt-3 max-w-2xl text-muted-foreground">
+          The longer a sandbox sits idle, the colder — and cheaper — it gets,
+          one step at a time. <code>acquireSandbox</code> brings it back from
+          any state, files intact.
+        </p>
+
+        <div className="mt-10 grid gap-px overflow-hidden rounded-xl border bg-border sm:grid-cols-2 lg:grid-cols-4">
+          {stages.map((stage) => (
+            <div key={stage.state} className="flex flex-col gap-3 bg-card p-5">
+              <div className="flex items-baseline justify-between gap-2">
+                <span className="font-mono text-sm font-medium">
+                  {stage.state}
+                </span>
+                <span className="font-mono text-[11px] text-muted-foreground">
+                  {stage.when}
+                </span>
+              </div>
+              <p className="flex-1 text-sm text-muted-foreground">
+                {stage.body}
+              </p>
+              <p className="font-mono text-xs text-muted-foreground">
+                {stage.cost}
+              </p>
+            </div>
+          ))}
+        </div>
+
+        <p className="mt-4 text-xs text-muted-foreground">
+          Default thresholds shown — each one is a per-sandbox knob, and{' '}
+          <code>null</code> means never.{' '}
+          <Link
+            href="/docs/lifecycle"
+            className="underline underline-offset-4 transition-colors hover:text-foreground"
+          >
+            Read about the lifecycle
+          </Link>
+        </p>
+      </div>
+    </section>
+  );
+}

From bbb3655eebad803aaaa7041f8dc9924b943eb876 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 18 Jul 2026 16:43:37 +0800
Subject: [PATCH 106/133] =?UTF-8?q?=E6=B2=99=E7=AE=B1=E8=AF=A6=E6=83=85?=
 =?UTF-8?q?=E9=A1=B5=E6=89=94=E6=8E=89=E5=85=AD=E4=B8=AA=20tab,=E9=87=8D?=
 =?UTF-8?q?=E6=8E=92=E6=88=90=E4=B8=80=E5=8F=B0=E7=9C=9F=E7=94=B5=E8=84=91?=
 =?UTF-8?q?=E7=9A=84=E5=9D=90=E5=A7=BF:=E5=B7=A6=E6=89=8B=E6=96=87?=
 =?UTF-8?q?=E4=BB=B6=E6=A0=91=E3=80=81=E6=AD=A3=E4=B8=AD=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E9=A2=84=E8=A7=88=E5=8E=8B=E7=9D=80=E7=BB=88=E7=AB=AF=E3=80=81?=
 =?UTF-8?q?=E5=8F=B3=E4=BE=A7=E7=9B=91=E8=A7=86=E6=A0=8F=E5=B8=B8=E9=A9=BB?=
 =?UTF-8?q?=E2=80=94=E2=80=94=E5=88=87=E6=8D=A2=E4=B8=8D=E6=98=AF=E8=A2=AB?=
 =?UTF-8?q?=E4=BC=98=E5=8C=96=E4=BA=86,=E6=98=AF=E6=B6=88=E5=A4=B1?=
 =?UTF-8?q?=E4=BA=86=E3=80=82tabs=20=E7=9A=84=E7=97=85=E6=A0=B9=E6=9C=89?=
 =?UTF-8?q?=E4=BA=8C:=E7=BB=88=E7=AB=AF=E4=BC=9A=E8=AF=9D=E6=B4=BB?=
 =?UTF-8?q?=E5=9C=A8=20effect=20=E9=87=8C,=E5=88=87=E8=B5=B0=E5=8D=B3?=
 =?UTF-8?q?=E6=9D=80=20shell,=E6=9F=A5=E4=B8=80=E7=9C=BC=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E5=9B=9E=E6=9D=A5=20scrollback=20=E5=85=A8=E6=B2=A1;=E6=83=B3?=
 =?UTF-8?q?=E7=9E=84=E4=B8=80=E7=9C=BC=20CPU=20=E4=B9=9F=E5=BE=97=E6=95=B4?=
 =?UTF-8?q?=E9=A1=B5=E5=88=87=E8=B5=B0=E3=80=82=E7=9B=91=E8=A7=86=E6=A0=8F?=
 =?UTF-8?q?=E6=8A=8A=E7=94=9F=E5=91=BD=E5=91=A8=E6=9C=9F=E3=80=81=E4=B8=89?=
 =?UTF-8?q?=E5=BC=A0=20vitals=20=E5=8D=A1(5=20=E7=A7=92=E5=BD=93=E5=89=8D?=
 =?UTF-8?q?=E5=80=BC+1=20=E5=B0=8F=E6=97=B6=E5=8E=86=E5=8F=B2=20sparkline,?=
 =?UTF-8?q?=E5=A4=8D=E7=94=A8=E6=80=BB=E8=A7=88=E9=A1=B5=20Sparkline=20?=
 =?UTF-8?q?=E4=B8=8E=E5=85=B1=E4=BA=AB=20Meter)=E3=80=81=E8=BF=9B=E7=A8=8B?=
 =?UTF-8?q?=E3=80=81=E6=9C=80=E8=BF=91=E6=B4=BB=E5=8A=A8=E3=80=81=E8=BA=AB?=
 =?UTF-8?q?=E4=BB=BD=E4=BF=A1=E6=81=AF=E6=91=86=E6=88=90=E5=B8=B8=E9=A9=BB?=
 =?UTF-8?q?=E4=BB=AA=E8=A1=A8=E2=80=94=E2=80=94=E8=BF=99=E4=B8=80=E6=A0=8F?=
 =?UTF-8?q?=E5=85=A8=E6=98=AF=E6=9C=8D=E5=8A=A1=E7=AB=AF=E5=88=BB=E6=84=8F?=
 =?UTF-8?q?=E4=B8=8D=E5=94=A4=E9=86=92=E7=9A=84=E5=8F=AA=E8=AF=BB=E8=A7=82?=
 =?UTF-8?q?=E5=AF=9F(=E6=8C=87=E6=A0=87=E4=B8=8D=20wake=E3=80=81Process/Li?=
 =?UTF-8?q?st=20=E4=B8=8D=20wake=E3=80=81=E6=B4=BB=E5=8A=A8=E8=AF=BB?=
 =?UTF-8?q?=E8=B4=A6=E6=9C=AC),=E6=8C=82=E4=B8=80=E5=A4=A9=E4=B9=9F?=
 =?UTF-8?q?=E4=B8=8D=E8=BF=9D=E5=8F=8D"=E7=9C=8B=E4=B8=8D=E8=A7=A3?=
 =?UTF-8?q?=E5=86=BB";=E3=80=8C=E5=AE=8C=E6=95=B4=E8=B5=B0=E5=8A=BF?=
 =?UTF-8?q?=E3=80=8D=E5=BC=80=E5=BC=B9=E7=AA=97=E5=8E=9F=E6=A0=B7=E5=A4=8D?=
 =?UTF-8?q?=E7=94=A8=20MetricsPanel,1h/24h/7d=20=E4=B8=89=E5=9B=BE?=
 =?UTF-8?q?=E9=9B=B6=E6=96=B0=E4=BB=A3=E7=A0=81=E3=80=82=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E9=9D=A2=E4=BB=8E=E9=9D=A2=E5=8C=85=E5=B1=91=E8=A1=A8=E6=A0=BC?=
 =?UTF-8?q?=E6=8D=A2=E6=88=90=E6=87=92=E5=8A=A0=E8=BD=BD=E6=A0=91:?=
 =?UTF-8?q?=E4=B8=80=E5=B1=82=E7=9B=AE=E5=BD=95=E4=B8=80=E4=B8=AA=20query?=
 =?UTF-8?q?=E3=80=81=E6=8A=98=E5=8F=A0=E5=8D=B3=E4=B8=8D=E5=8F=91=E8=AF=B7?=
 =?UTF-8?q?=E6=B1=82,mutation=20=E7=9A=84=E5=89=8D=E7=BC=80=E5=A4=B1?=
 =?UTF-8?q?=E6=95=88=E8=AE=A9=E5=85=A8=E6=A0=91=E8=87=AA=E5=8A=A8=E8=B7=9F?=
 =?UTF-8?q?=E4=B8=8A;=E3=80=8C=E7=84=A6=E7=82=B9=E7=9B=AE=E5=BD=95?=
 =?UTF-8?q?=E3=80=8D=E6=98=AF=E5=94=AF=E4=B8=80=E7=9A=84=E8=90=BD=E7=82=B9?=
 =?UTF-8?q?=E8=A3=81=E5=86=B3=E2=80=94=E2=80=94=E7=82=B9=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E9=80=89=E4=B8=AD=E5=B9=B6=E8=81=9A=E7=84=A6=E5=85=B6=E7=88=B6?=
 =?UTF-8?q?=E7=9B=AE=E5=BD=95,=E7=82=B9=E7=9B=AE=E5=BD=95=E5=B1=95?=
 =?UTF-8?q?=E5=BC=80=E5=B9=B6=E8=81=9A=E7=84=A6=E8=87=AA=E8=BA=AB,?=
 =?UTF-8?q?=E4=B8=8A=E4=BC=A0/=E6=96=B0=E5=BB=BA/=E6=8B=96=E6=8B=BD/watch?=
 =?UTF-8?q?=20=E5=B8=83=E9=98=B2=E5=9B=9B=E8=80=85=E5=85=A8=E8=90=BD?=
 =?UTF-8?q?=E7=84=A6=E7=82=B9=E7=9B=AE=E5=BD=95,=E8=A7=84=E5=88=99?=
 =?UTF-8?q?=E5=8F=AA=E6=9C=89=E4=B8=80=E6=9D=A1,=E7=A9=BA=E7=9B=AE?=
 =?UTF-8?q?=E5=BD=95=E4=B9=9F=E8=83=BD=E5=BD=93=E4=B8=8A=E4=BC=A0=E7=9B=AE?=
 =?UTF-8?q?=E6=A0=87;watch=20=E8=B7=9F=E9=9A=8F=E7=84=A6=E7=82=B9=E5=8F=AA?=
 =?UTF-8?q?=E5=B8=83=E4=B8=80=E4=B8=AA=20watcher,=E4=B8=8D=E7=BB=99?=
 =?UTF-8?q?=E6=AF=8F=E4=B8=AA=E5=B1=95=E5=BC=80=E7=9B=AE=E5=BD=95=E5=90=84?=
 =?UTF-8?q?=E5=85=BB=E4=B8=80=E4=B8=AA=20inotifywait=E3=80=82=E9=A2=84?=
 =?UTF-8?q?=E8=A7=88=E7=BC=96=E8=BE=91=E4=BB=8E=E5=BC=B9=E7=AA=97=E5=86=85?=
 =?UTF-8?q?=E8=81=94=E6=88=90=E5=B8=B8=E9=A9=BB=E7=AA=97=E6=A0=BC,?=
 =?UTF-8?q?=E5=86=85=E5=AE=B9=E6=98=AF"=E6=89=93=E5=BC=80=E6=97=B6?=
 =?UTF-8?q?=E5=BF=AB=E7=85=A7+=E6=89=8B=E5=8A=A8=E5=88=B7=E6=96=B0",?=
 =?UTF-8?q?=E5=88=BB=E6=84=8F=E4=B8=8D=E8=B7=9F=20watch=20=E8=87=AA?=
 =?UTF-8?q?=E5=8A=A8=E9=87=8D=E8=AF=BB=E2=80=94=E2=80=94agent=20=E6=AF=8F?=
 =?UTF-8?q?=E7=A7=92=E8=BF=BD=E5=86=99=E6=97=A5=E5=BF=97=E4=BC=9A=E5=86=B2?=
 =?UTF-8?q?=E6=8E=89=E6=AD=A3=E5=9C=A8=E7=BC=96=E8=BE=91=E7=9A=84=E8=8D=89?=
 =?UTF-8?q?=E7=A8=BF,=E5=BF=AB=E7=85=A7=E8=AF=AD=E4=B9=89=E6=89=8D?=
 =?UTF-8?q?=E7=BC=96=E8=BE=91=E5=BE=97=E5=AE=89=E7=A8=B3=E3=80=82=E7=BB=88?=
 =?UTF-8?q?=E7=AB=AF=E4=B8=8E=E6=96=87=E4=BB=B6=E6=A0=91=E7=9A=84=E5=94=A4?=
 =?UTF-8?q?=E9=86=92=E9=97=B8=E9=97=A8=E5=8E=9F=E8=AF=AD=E4=B9=89=E4=BF=9D?=
 =?UTF-8?q?=E7=95=99(=E6=98=BE=E5=BC=8F=E7=82=B9=E5=87=BB=E6=89=8D?=
 =?UTF-8?q?=E8=BF=9E/=E6=89=8D=E5=88=97,=E6=96=AD=E5=BC=80=E5=8D=B3?=
 =?UTF-8?q?=E6=9D=80=20shell=20=E4=B8=8D=E7=95=99=E5=AD=A4=E5=84=BF),?=
 =?UTF-8?q?=E6=B2=A1=E6=9C=89=E4=B8=AD=E5=A4=AE=E9=97=B8=E9=97=A8,?=
 =?UTF-8?q?=E6=AF=8F=E4=B8=AA=E7=AA=97=E6=A0=BC=E8=87=AA=E5=B7=B1=E8=A3=81?=
 =?UTF-8?q?=E5=86=B3=E3=80=82=E5=B7=A5=E4=BD=9C=E5=8F=B0=E6=88=90=E4=B8=BA?=
 =?UTF-8?q?=20max-w-6xl=20=E7=9A=84=E5=94=AF=E4=B8=80=E5=85=A8=E5=AE=BD?=
 =?UTF-8?q?=E4=BE=8B=E5=A4=96=E5=B9=B6=E9=94=81=E8=A7=86=E5=8F=A3:?=
 =?UTF-8?q?=E5=88=97=E8=A1=A8=E9=A1=B5=E6=98=AF"=E8=AF=BB",=E9=99=90?=
 =?UTF-8?q?=E5=AE=BD=E5=88=A9=E4=BA=8E=E6=89=AB=E8=AF=BB;=E5=B7=A5?=
 =?UTF-8?q?=E4=BD=9C=E5=8F=B0=E6=98=AF"=E5=B9=B2=E6=B4=BB",=E5=AE=BD?=
 =?UTF-8?q?=E5=BA=A6=E5=8D=B3=E7=94=9F=E4=BA=A7=E5=8A=9B;=E7=AA=84?=
 =?UTF-8?q?=E5=B1=8F=E9=80=80=E5=8C=96=E4=B8=BA=E7=BA=B5=E5=90=91=E6=BB=9A?=
 =?UTF-8?q?=E5=8A=A8=E6=B5=81,=E5=8F=AF=E6=8B=96=E5=88=86=E6=A0=8F?=
 =?UTF-8?q?=E5=9C=A8=E8=A7=A6=E5=B1=8F=E4=B8=8A=E6=9C=AC=E6=9D=A5=E5=B0=B1?=
 =?UTF-8?q?=E4=B8=8D=E6=88=90=E7=AB=8B=E3=80=82tab=20=E4=BB=8E=20URL=20?=
 =?UTF-8?q?=E9=87=8C=E6=B6=88=E5=A4=B1(=E6=97=A7=20=3Ftab=3D=20=E9=93=BE?=
 =?UTF-8?q?=E6=8E=A5=E8=A2=AB=E6=97=A0=E5=AE=B3=E5=BF=BD=E7=95=A5),/activi?=
 =?UTF-8?q?ty=20=E5=8F=8D=E8=80=8C=E5=A4=9A=E4=BA=86=E5=8F=AF=E9=80=89=20?=
 =?UTF-8?q?=3Fsandbox=3D=20=E2=80=94=E2=80=94=E5=8F=B3=E6=A0=8F=E3=80=8C?=
 =?UTF-8?q?=E6=9F=A5=E7=9C=8B=E5=85=A8=E9=83=A8=E3=80=8D=E5=B8=A6=E7=9D=80?=
 =?UTF-8?q?=E5=90=8D=E5=AD=97=E8=B7=B3=E8=BF=87=E5=8E=BB=E8=90=BD=E5=9C=B0?=
 =?UTF-8?q?=E5=8D=B3=E9=A2=84=E7=AD=9B=E3=80=82console.mdx=20=E7=9A=84?=
 =?UTF-8?q?=E5=85=AD=20bullet=20=E6=94=B9=E5=86=99=E4=B8=BA=E5=B7=A5?=
 =?UTF-8?q?=E4=BD=9C=E5=8F=B0=E5=8F=99=E8=BF=B0,=E9=A1=BA=E6=89=8B?=
 =?UTF-8?q?=E4=BF=AE=E6=AD=A3=20Metrics=20=E6=9D=A1=20"the=20daemon=20keep?=
 =?UTF-8?q?s=20no=20history"=20=E7=9A=84=E9=99=88=E6=97=A7=E8=B0=8E?=
 =?UTF-8?q?=E8=A8=80=E2=80=94=E2=80=94=E6=8C=87=E6=A0=87=E5=8E=86=E5=8F=B2?=
 =?UTF-8?q?=E6=97=A9=E5=B7=B2=E8=90=BD=E5=BA=93=E3=80=82=E6=97=A7=20FilesP?=
 =?UTF-8?q?anel/FilePreviewDialog/ProcessesPanel/HistoryPanel/SandboxTermi?=
 =?UTF-8?q?nal=20=E4=BA=94=E4=BB=B6=E5=B9=B3=E7=A7=BB=E5=90=8E=E5=88=A0?=
 =?UTF-8?q?=E9=99=A4;=E6=96=B9=E6=A1=88=E7=BB=8F=20temp=20=E7=94=BB?=
 =?UTF-8?q?=E5=BB=8A=E4=B8=89=E6=96=B9=E6=A1=88=E6=AF=94=E7=A8=BF=E6=8B=8D?=
 =?UTF-8?q?=E6=9D=BF(monitor),=E7=94=BB=E5=BB=8A=E6=8C=89"=E6=8B=8D?=
 =?UTF-8?q?=E6=9D=BF=E5=8D=B3=E5=88=A0"=E6=B8=85=E5=9C=BA=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../console/src/components/CommandMenu.tsx    |   1 -
 .../features/activity/pages/ActivityPage.tsx  |   8 +-
 .../components/FilePreviewDialog.tsx          | 196 -------
 .../sandboxes/components/FilesPanel.tsx       | 528 ------------------
 .../sandboxes/components/HistoryPanel.tsx     | 124 ----
 .../sandboxes/components/ProcessesPanel.tsx   | 167 ------
 .../components/workbench/FilePreviewPane.tsx  | 240 ++++++++
 .../components/workbench/FileTreePane.tsx     | 466 ++++++++++++++++
 .../components/workbench/MonitorRail.tsx      | 464 +++++++++++++++
 .../TerminalPane.tsx}                         |  89 +--
 .../components/workbench/file-dialogs.tsx     | 207 +++++++
 .../sandboxes/pages/SandboxDetailPage.tsx     | 277 ++++-----
 .../sandboxes/pages/SandboxesPage.tsx         |   1 -
 packages/console/src/routes/_app/activity.tsx |   9 +
 .../src/routes/_app/sandboxes/$name.tsx       |  13 +-
 website/content/docs/console.mdx              |  45 +-
 16 files changed, 1588 insertions(+), 1247 deletions(-)
 delete mode 100644 packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx
 delete mode 100644 packages/console/src/features/sandboxes/components/FilesPanel.tsx
 delete mode 100644 packages/console/src/features/sandboxes/components/HistoryPanel.tsx
 delete mode 100644 packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
 create mode 100644 packages/console/src/features/sandboxes/components/workbench/FilePreviewPane.tsx
 create mode 100644 packages/console/src/features/sandboxes/components/workbench/FileTreePane.tsx
 create mode 100644 packages/console/src/features/sandboxes/components/workbench/MonitorRail.tsx
 rename packages/console/src/features/sandboxes/components/{SandboxTerminal.tsx => workbench/TerminalPane.tsx} (54%)
 create mode 100644 packages/console/src/features/sandboxes/components/workbench/file-dialogs.tsx

diff --git a/packages/console/src/components/CommandMenu.tsx b/packages/console/src/components/CommandMenu.tsx
index 32f5cd4..b72ad50 100644
--- a/packages/console/src/components/CommandMenu.tsx
+++ b/packages/console/src/components/CommandMenu.tsx
@@ -73,7 +73,6 @@ export function CommandMenu() {
     void navigate({
       to: '/sandboxes/$name',
       params: { name },
-      search: { tab: 'overview' },
     });
   };
 
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index 73f71af..85663bf 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -1,7 +1,7 @@
 import type { ActivityKind } from '@dormice/shared';
 import { Search01Icon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
-import { Link } from '@tanstack/react-router';
+import { Link, useSearch } from '@tanstack/react-router';
 import { useMemo, useState } from 'react';
 import { DataTable } from '@/components/DataTable';
 import { FilterMenu } from '@/components/FilterMenu';
@@ -52,7 +52,10 @@ export function ActivityPage() {
   const { data, isPending, isError, error } = useActivity();
   // 只为把 apikey:<id> 翻译回名字;密钥页共用一份缓存。
   const apiKeys = useApiKeys().data?.apiKeys;
-  const [search, setSearch] = useState('');
+  // ?sandbox= 是沙箱工作台「查看全部」带来的预筛,只当搜索框的一次性
+  // 种子 — 落地后搜索框归用户,不做双向同步。
+  const { sandbox: sandboxParam } = useSearch({ from: '/_app/activity' });
+  const [search, setSearch] = useState(() => sandboxParam ?? '');
   const [kindFilter, setKindFilter] = useState<'all' | ActivityKind>('all');
   const [actorFilter, setActorFilter] = useState('');
   const [page, setPage] = useState(1);
@@ -201,7 +204,6 @@ export function ActivityPage() {
                     <Link
                       to="/sandboxes/$name"
                       params={{ name: event.sandboxName }}
-                      search={{ tab: 'overview' as const }}
                       className="font-mono hover:underline"
                     >
                       {event.sandboxName}
diff --git a/packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx b/packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx
deleted file mode 100644
index 5a5a633..0000000
--- a/packages/console/src/features/sandboxes/components/FilePreviewDialog.tsx
+++ /dev/null
@@ -1,196 +0,0 @@
-import { Download01Icon } from '@hugeicons/core-free-icons';
-import { HugeiconsIcon } from '@hugeicons/react';
-import { useQuery } from '@tanstack/react-query';
-import { useEffect, useState } from 'react';
-import { toast } from 'sonner';
-import { Button } from '@/components/ui/button';
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogFooter,
-  DialogHeader,
-  DialogTitle,
-} from '@/components/ui/dialog';
-import {
-  Empty,
-  EmptyContent,
-  EmptyDescription,
-  EmptyHeader,
-  EmptyTitle,
-} from '@/components/ui/empty';
-import { Spinner } from '@/components/ui/spinner';
-import { Textarea } from '@/components/ui/textarea';
-import { formatBytes } from '@/lib/format';
-import { downloadFile, type EnvdAuth, type EnvdEntry } from '../envd-client';
-import { useFileMutations } from '../hooks/useEnvd';
-
-/**
- * 在线看得过来的才在线看:预览上限之上只给下载 — 编辑器不是给日志
- * 大文件准备的。上限取 1 MiB:够看配置、代码、多数日志尾巴,又不至于
- * 把整段内存交给一个 textarea。
- */
-const PREVIEW_CAP_BYTES = 1024 * 1024;
-
-/**
- * 文本判定:头 8 KiB 里出现 NUL 字节即视为二进制。与 git 同一招 —
- * 不猜编码不读魔数,便宜且几乎不会冤枉文本文件。
- */
-function looksBinary(bytes: Uint8Array): boolean {
-  const head = bytes.subarray(0, 8192);
-  return head.includes(0);
-}
-
-/**
- * 点开文件先看内容,小文本顺手改完保存 — 排查 agent 产物最高频的动作,
- * 不该绕道"下载到本地再打开"。读写都走 envd 的文件面(与官方 e2b SDK
- * 同一条 wire):读是 GET /files,存是同路径的整文件覆写上传。
- */
-export function FilePreviewDialog({
-  auth,
-  entry,
-  onClose,
-}: {
-  auth: EnvdAuth | undefined;
-  /** 正在预览的文件;null = 关闭。 */
-  entry: EnvdEntry | null;
-  onClose: () => void;
-}) {
-  const [draft, setDraft] = useState('');
-  const mutations = useFileMutations(auth);
-  const tooLarge = entry !== null && Number(entry.size) > PREVIEW_CAP_BYTES;
-
-  const content = useQuery({
-    queryKey: ['envdFileContent', auth?.sandboxId, entry?.path],
-    queryFn: async () => {
-      if (!auth || !entry) throw new Error('缺少 envd 凭证');
-      const blob = await downloadFile(auth, entry.path);
-      const bytes = new Uint8Array(await blob.arrayBuffer());
-      if (looksBinary(bytes)) return { binary: true as const };
-      return { binary: false as const, text: new TextDecoder().decode(bytes) };
-    },
-    enabled: entry !== null && !tooLarge && auth !== undefined,
-    // 文件内容随沙箱里的进程随时在变,每次打开都重读,不吃缓存。
-    gcTime: 0,
-    staleTime: 0,
-    retry: false,
-  });
-
-  // 读到文本后灌入编辑区;依赖 entry.path 使换文件时必然重灌。
-  useEffect(() => {
-    if (content.data && !content.data.binary) {
-      setDraft(content.data.text);
-    }
-  }, [content.data]);
-
-  const dirty =
-    content.data !== undefined &&
-    !content.data.binary &&
-    draft !== content.data.text;
-
-  const download = () => {
-    if (!entry) return;
-    mutations.download.mutate(
-      { path: entry.path, name: entry.name },
-      { onError: (error) => toast.error(error.message) },
-    );
-  };
-
-  const save = () => {
-    if (!entry) return;
-    mutations.upload.mutate(
-      { path: entry.path, file: new File([draft], entry.name) },
-      {
-        onSuccess: () => {
-          toast.success(`已保存 ${entry.name}`);
-          onClose();
-        },
-        onError: (error) => toast.error(error.message),
-      },
-    );
-  };
-
-  return (
-    <Dialog
-      open={entry !== null}
-      onOpenChange={(open) => {
-        if (!open) onClose();
-      }}
-    >
-      <DialogContent className="sm:max-w-3xl">
-        <DialogHeader>
-          <DialogTitle className="font-mono">{entry?.name}</DialogTitle>
-          <DialogDescription className="font-mono text-xs">
-            {entry?.path} · {formatBytes(Number(entry?.size ?? 0))}
-          </DialogDescription>
-        </DialogHeader>
-
-        {tooLarge || content.data?.binary ? (
-          <Empty className="border border-dashed">
-            <EmptyHeader>
-              <EmptyTitle>
-                {tooLarge ? '文件太大,不在线预览' : '二进制文件,没法当文本看'}
-              </EmptyTitle>
-              <EmptyDescription>
-                {tooLarge
-                  ? `在线预览上限 ${formatBytes(PREVIEW_CAP_BYTES)} — 下载后用本地工具打开。`
-                  : '内容里有 NUL 字节 — 下载后用对应的工具打开。'}
-              </EmptyDescription>
-            </EmptyHeader>
-            <EmptyContent>
-              <Button
-                variant="outline"
-                size="sm"
-                disabled={mutations.download.isPending}
-                onClick={download}
-              >
-                <HugeiconsIcon icon={Download01Icon} />
-                下载
-              </Button>
-            </EmptyContent>
-          </Empty>
-        ) : content.isError ? (
-          <Empty className="border border-dashed">
-            <EmptyHeader>
-              <EmptyTitle>读取失败</EmptyTitle>
-              <EmptyDescription>{content.error.message}</EmptyDescription>
-            </EmptyHeader>
-          </Empty>
-        ) : content.isPending ? (
-          <div className="flex items-center gap-2 text-sm text-muted-foreground">
-            <Spinner /> 读取文件
-          </div>
-        ) : (
-          <Textarea
-            value={draft}
-            onChange={(event) => setDraft(event.target.value)}
-            spellCheck={false}
-            className="h-[55vh] resize-none font-mono text-xs leading-relaxed"
-          />
-        )}
-
-        {content.data !== undefined && !content.data.binary && (
-          <DialogFooter>
-            <Button
-              variant="outline"
-              size="sm"
-              disabled={mutations.download.isPending}
-              onClick={download}
-            >
-              <HugeiconsIcon icon={Download01Icon} />
-              下载
-            </Button>
-            <Button
-              size="sm"
-              disabled={!dirty || mutations.upload.isPending}
-              onClick={save}
-            >
-              {mutations.upload.isPending && <Spinner />}
-              保存
-            </Button>
-          </DialogFooter>
-        )}
-      </DialogContent>
-    </Dialog>
-  );
-}
diff --git a/packages/console/src/features/sandboxes/components/FilesPanel.tsx b/packages/console/src/features/sandboxes/components/FilesPanel.tsx
deleted file mode 100644
index 433c9ec..0000000
--- a/packages/console/src/features/sandboxes/components/FilesPanel.tsx
+++ /dev/null
@@ -1,528 +0,0 @@
-import type { Sandbox } from '@dormice/shared';
-import {
-  Delete02Icon,
-  Download01Icon,
-  Edit02Icon,
-  File01Icon,
-  Folder01Icon,
-  FolderAddIcon,
-  MoreVerticalIcon,
-  RefreshIcon,
-  Upload01Icon,
-} from '@hugeicons/core-free-icons';
-import { HugeiconsIcon } from '@hugeicons/react';
-import { Fragment, useRef, useState } from 'react';
-import { toast } from 'sonner';
-import { DataTable } from '@/components/DataTable';
-import { Alert, AlertDescription } from '@/components/ui/alert';
-import {
-  AlertDialog,
-  AlertDialogAction,
-  AlertDialogCancel,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogFooter,
-  AlertDialogHeader,
-  AlertDialogTitle,
-} from '@/components/ui/alert-dialog';
-import {
-  Breadcrumb,
-  BreadcrumbItem,
-  BreadcrumbList,
-  BreadcrumbPage,
-  BreadcrumbSeparator,
-} from '@/components/ui/breadcrumb';
-import { Button } from '@/components/ui/button';
-import {
-  Dialog,
-  DialogContent,
-  DialogFooter,
-  DialogHeader,
-  DialogTitle,
-} from '@/components/ui/dialog';
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from '@/components/ui/dropdown-menu';
-import {
-  Empty,
-  EmptyDescription,
-  EmptyHeader,
-  EmptyMedia,
-  EmptyTitle,
-} from '@/components/ui/empty';
-import { Input } from '@/components/ui/input';
-import { Spinner } from '@/components/ui/spinner';
-import {
-  TableBody,
-  TableCell,
-  TableHead,
-  TableHeader,
-  TableRow,
-} from '@/components/ui/table';
-import { formatBytes } from '@/lib/format';
-import { cn } from '@/lib/utils';
-import type { EnvdEntry } from '../envd-client';
-import { STATE_LABELS } from '../format';
-import {
-  useDirectory,
-  useDirectoryWatch,
-  useEnvdAuth,
-  useFileMutations,
-} from '../hooks/useEnvd';
-import { FilePreviewDialog } from './FilePreviewDialog';
-
-const HOME = '/home/user';
-
-/** /home/user 下的面包屑段;根显示为 ~。 */
-function segmentsOf(path: string): Array<{ label: string; path: string }> {
-  const crumbs = [{ label: '~', path: HOME }];
-  if (path === HOME) return crumbs;
-  let acc = HOME;
-  for (const segment of path.slice(HOME.length + 1).split('/')) {
-    acc = `${acc}/${segment}`;
-    crumbs.push({ label: segment, path: acc });
-  }
-  return crumbs;
-}
-
-function sortEntries(entries: EnvdEntry[]): EnvdEntry[] {
-  return [...entries].sort((a, b) => {
-    const aDir = a.type === 'FILE_TYPE_DIRECTORY' ? 0 : 1;
-    const bDir = b.type === 'FILE_TYPE_DIRECTORY' ? 0 : 1;
-    return aDir - bDir || a.name.localeCompare(b.name);
-  });
-}
-
-/**
- * 沙箱内 /home/user 的文件浏览器,走 envd 的 Filesystem RPC 与文件面 —
- * 与官方 e2b SDK 同一条 wire。文件动词会唤醒冻结的沙箱,所以非 active
- * 状态下第一步是一次显式的"打开"(与终端同一条纪律:看不解冻,用才解冻)。
- */
-export function FilesPanel({ sandbox }: { sandbox: Sandbox }) {
-  const [unlocked, setUnlocked] = useState(sandbox.state === 'active');
-  const [path, setPath] = useState(HOME);
-  const auth = useEnvdAuth(sandbox.id);
-  const directory = useDirectory(auth.data, path, unlocked);
-  // 沙箱里(agent、终端)动了文件,这张表 2 秒内自己跟上 — 不用手点刷新。
-  useDirectoryWatch(auth.data, path, {
-    enabled: unlocked,
-    active: sandbox.state === 'active',
-  });
-  const mutations = useFileMutations(auth.data);
-  const fileInputRef = useRef<HTMLInputElement | null>(null);
-
-  // 对话框状态:预览 / 新建文件夹 / 重命名 / 删除,一次只开一个。
-  const [viewing, setViewing] = useState<EnvdEntry | null>(null);
-  const [mkdirOpen, setMkdirOpen] = useState(false);
-  const [mkdirName, setMkdirName] = useState('');
-  const [renaming, setRenaming] = useState<EnvdEntry | null>(null);
-  const [renameTo, setRenameTo] = useState('');
-  const [deleting, setDeleting] = useState<EnvdEntry | null>(null);
-  // 拖拽悬停的视觉反馈;计数器抵消子元素间的 dragenter/dragleave 抖动。
-  const [dragDepth, setDragDepth] = useState(0);
-
-  if (!unlocked) {
-    return (
-      <Empty className="border border-dashed">
-        <EmptyHeader>
-          <EmptyMedia variant="icon">
-            <HugeiconsIcon icon={Folder01Icon} />
-          </EmptyMedia>
-          <EmptyTitle>文件浏览器</EmptyTitle>
-          <EmptyDescription>
-            沙箱当前是「{STATE_LABELS[sandbox.state]}」— 浏览文件会唤醒它
-            (冻结约 50ms,停止需要几秒冷启动)。看这一页本身不会。
-          </EmptyDescription>
-        </EmptyHeader>
-        <Button size="sm" onClick={() => setUnlocked(true)}>
-          打开文件浏览器
-        </Button>
-      </Empty>
-    );
-  }
-
-  const entries = sortEntries(directory.data ?? []);
-
-  // 逐个串行上传:一次汇报总成败,失败点名到文件。
-  const upload = async (files: File[]) => {
-    const failures: string[] = [];
-    for (const file of files) {
-      try {
-        await mutations.upload.mutateAsync({
-          path: `${path}/${file.name}`,
-          file,
-        });
-      } catch {
-        failures.push(file.name);
-      }
-    }
-    if (failures.length === 0) {
-      const only = files.length === 1 ? files[0] : undefined;
-      toast.success(
-        only ? `已上传 ${only.name}` : `已上传 ${files.length} 个文件`,
-      );
-    } else {
-      toast.error(`${failures.length} 个上传失败:${failures.join('、')}`);
-    }
-  };
-
-  return (
-    // 拖放只是「上传」按钮的增强,不是唯一入口;section 让辅助技术
-    // 知道这一块是文件工作区,而不是把版面 div 假装成控件。
-    <section
-      aria-label="文件浏览器(支持拖放上传)"
-      className={cn(
-        'flex flex-col gap-3 rounded-lg transition-shadow',
-        dragDepth > 0 && 'ring-2 ring-primary/60',
-      )}
-      // 拖文件进来直接落到当前目录 — 和上传按钮同一条路。
-      onDragOver={(event) => event.preventDefault()}
-      onDragEnter={(event) => {
-        event.preventDefault();
-        setDragDepth((depth) => depth + 1);
-      }}
-      onDragLeave={() => setDragDepth((depth) => Math.max(0, depth - 1))}
-      onDrop={(event) => {
-        event.preventDefault();
-        setDragDepth(0);
-        const files = Array.from(event.dataTransfer.files);
-        if (files.length > 0) void upload(files);
-      }}
-    >
-      <div className="flex flex-wrap items-center justify-between gap-2">
-        <Breadcrumb>
-          <BreadcrumbList>
-            {segmentsOf(path).map((crumb, index, all) => (
-              <Fragment key={crumb.path}>
-                {index > 0 && <BreadcrumbSeparator />}
-                <BreadcrumbItem>
-                  {index === all.length - 1 ? (
-                    <BreadcrumbPage className="font-mono">
-                      {crumb.label}
-                    </BreadcrumbPage>
-                  ) : (
-                    <button
-                      type="button"
-                      className="font-mono transition-colors hover:text-foreground"
-                      onClick={() => setPath(crumb.path)}
-                    >
-                      {crumb.label}
-                    </button>
-                  )}
-                </BreadcrumbItem>
-              </Fragment>
-            ))}
-          </BreadcrumbList>
-        </Breadcrumb>
-        <div className="flex items-center gap-2">
-          <input
-            ref={fileInputRef}
-            type="file"
-            multiple
-            className="hidden"
-            onChange={(event) => {
-              const files = Array.from(event.target.files ?? []);
-              if (files.length > 0) void upload(files);
-              event.target.value = '';
-            }}
-          />
-          <Button
-            variant="outline"
-            size="sm"
-            disabled={mutations.upload.isPending}
-            onClick={() => fileInputRef.current?.click()}
-          >
-            {mutations.upload.isPending ? (
-              <Spinner />
-            ) : (
-              <HugeiconsIcon icon={Upload01Icon} />
-            )}
-            上传
-          </Button>
-          <Button
-            variant="outline"
-            size="sm"
-            onClick={() => {
-              setMkdirName('');
-              setMkdirOpen(true);
-            }}
-          >
-            <HugeiconsIcon icon={FolderAddIcon} />
-            新建文件夹
-          </Button>
-          <Button
-            variant="ghost"
-            size="icon-sm"
-            aria-label="刷新"
-            onClick={() => void directory.refetch()}
-          >
-            <HugeiconsIcon icon={RefreshIcon} />
-          </Button>
-        </div>
-      </div>
-
-      {(directory.isError || auth.isError) && (
-        <Alert variant="destructive">
-          <AlertDescription>
-            {directory.error?.message ?? auth.error?.message}
-          </AlertDescription>
-        </Alert>
-      )}
-
-      {directory.isLoading && (
-        <div className="flex items-center gap-2 rounded-lg border p-4 text-sm text-muted-foreground">
-          <Spinner /> 读取目录(沉睡的沙箱会先被唤醒)
-        </div>
-      )}
-
-      {directory.isSuccess && entries.length === 0 && (
-        <Empty className="border border-dashed">
-          <EmptyHeader>
-            <EmptyTitle>空目录</EmptyTitle>
-            <EmptyDescription>
-              上传一个文件试试 — 拖进这个区域也行。
-            </EmptyDescription>
-          </EmptyHeader>
-        </Empty>
-      )}
-
-      {entries.length > 0 && (
-        <DataTable>
-          <TableHeader>
-            <TableRow>
-              <TableHead>名称</TableHead>
-              <TableHead className="text-right">大小</TableHead>
-              <TableHead>权限</TableHead>
-              <TableHead>修改时间</TableHead>
-              <TableHead className="w-12" />
-            </TableRow>
-          </TableHeader>
-          <TableBody>
-            {entries.map((entry) => {
-              const isDir = entry.type === 'FILE_TYPE_DIRECTORY';
-              return (
-                <TableRow key={entry.path}>
-                  <TableCell>
-                    {isDir ? (
-                      <button
-                        type="button"
-                        className="inline-flex items-center gap-2 font-medium hover:underline"
-                        onClick={() => setPath(entry.path)}
-                      >
-                        <HugeiconsIcon
-                          icon={Folder01Icon}
-                          className="size-4 text-sky-500"
-                        />
-                        {entry.name}
-                      </button>
-                    ) : (
-                      <button
-                        type="button"
-                        className="inline-flex items-center gap-2 hover:underline"
-                        onClick={() => setViewing(entry)}
-                      >
-                        <HugeiconsIcon
-                          icon={File01Icon}
-                          className="size-4 text-muted-foreground"
-                        />
-                        {entry.name}
-                      </button>
-                    )}
-                  </TableCell>
-                  <TableCell className="text-right tabular-nums text-muted-foreground">
-                    {isDir ? '—' : formatBytes(Number(entry.size))}
-                  </TableCell>
-                  <TableCell className="font-mono text-xs text-muted-foreground">
-                    {entry.permissions}
-                  </TableCell>
-                  <TableCell className="text-muted-foreground">
-                    {new Date(entry.modifiedTime).toLocaleString()}
-                  </TableCell>
-                  <TableCell>
-                    <DropdownMenu>
-                      <DropdownMenuTrigger
-                        render={
-                          <Button
-                            variant="ghost"
-                            size="icon-sm"
-                            aria-label={`${entry.name} 的操作`}
-                          >
-                            <HugeiconsIcon icon={MoreVerticalIcon} />
-                          </Button>
-                        }
-                      />
-                      <DropdownMenuContent align="end">
-                        {!isDir && (
-                          <DropdownMenuItem
-                            onClick={() =>
-                              mutations.download.mutate(
-                                { path: entry.path, name: entry.name },
-                                {
-                                  onError: (error) =>
-                                    toast.error(error.message),
-                                },
-                              )
-                            }
-                          >
-                            <HugeiconsIcon icon={Download01Icon} />
-                            下载
-                          </DropdownMenuItem>
-                        )}
-                        <DropdownMenuItem
-                          onClick={() => {
-                            setRenaming(entry);
-                            setRenameTo(entry.name);
-                          }}
-                        >
-                          <HugeiconsIcon icon={Edit02Icon} />
-                          重命名
-                        </DropdownMenuItem>
-                        <DropdownMenuItem
-                          variant="destructive"
-                          onClick={() => setDeleting(entry)}
-                        >
-                          <HugeiconsIcon icon={Delete02Icon} />
-                          删除
-                        </DropdownMenuItem>
-                      </DropdownMenuContent>
-                    </DropdownMenu>
-                  </TableCell>
-                </TableRow>
-              );
-            })}
-          </TableBody>
-        </DataTable>
-      )}
-
-      {/* 预览/编辑 */}
-      <FilePreviewDialog
-        auth={auth.data}
-        entry={viewing}
-        onClose={() => setViewing(null)}
-      />
-
-      {/* 新建文件夹 */}
-      <Dialog open={mkdirOpen} onOpenChange={setMkdirOpen}>
-        <DialogContent className="sm:max-w-sm">
-          <DialogHeader>
-            <DialogTitle>新建文件夹</DialogTitle>
-          </DialogHeader>
-          <form
-            onSubmit={(event) => {
-              event.preventDefault();
-              mutations.mkdir.mutate(`${path}/${mkdirName}`, {
-                onSuccess: () => setMkdirOpen(false),
-                onError: (error) => toast.error(error.message),
-              });
-            }}
-          >
-            <Input
-              autoFocus
-              value={mkdirName}
-              onChange={(event) => setMkdirName(event.target.value)}
-              placeholder="文件夹名"
-              className="font-mono"
-            />
-            <DialogFooter className="mt-4">
-              <Button
-                type="submit"
-                disabled={mkdirName === '' || mutations.mkdir.isPending}
-              >
-                {mutations.mkdir.isPending && <Spinner />}
-                创建
-              </Button>
-            </DialogFooter>
-          </form>
-        </DialogContent>
-      </Dialog>
-
-      {/* 重命名 */}
-      <Dialog
-        open={renaming !== null}
-        onOpenChange={(open) => {
-          if (!open) setRenaming(null);
-        }}
-      >
-        <DialogContent className="sm:max-w-sm">
-          <DialogHeader>
-            <DialogTitle>重命名「{renaming?.name}」</DialogTitle>
-          </DialogHeader>
-          <form
-            onSubmit={(event) => {
-              event.preventDefault();
-              if (!renaming) return;
-              mutations.move.mutate(
-                {
-                  source: renaming.path,
-                  destination: `${path}/${renameTo}`,
-                },
-                {
-                  onSuccess: () => setRenaming(null),
-                  onError: (error) => toast.error(error.message),
-                },
-              );
-            }}
-          >
-            <Input
-              autoFocus
-              value={renameTo}
-              onChange={(event) => setRenameTo(event.target.value)}
-              className="font-mono"
-            />
-            <DialogFooter className="mt-4">
-              <Button
-                type="submit"
-                disabled={
-                  renameTo === '' ||
-                  renameTo === renaming?.name ||
-                  mutations.move.isPending
-                }
-              >
-                {mutations.move.isPending && <Spinner />}
-                重命名
-              </Button>
-            </DialogFooter>
-          </form>
-        </DialogContent>
-      </Dialog>
-
-      {/* 删除 */}
-      <AlertDialog
-        open={deleting !== null}
-        onOpenChange={(open) => {
-          if (!open) setDeleting(null);
-        }}
-      >
-        <AlertDialogContent>
-          <AlertDialogHeader>
-            <AlertDialogTitle>删除「{deleting?.name}」?</AlertDialogTitle>
-            <AlertDialogDescription>
-              {deleting?.type === 'FILE_TYPE_DIRECTORY'
-                ? '整个目录连同里面的一切一起删除,'
-                : ''}
-              删了就没有了 — 沙箱里没有回收站。
-            </AlertDialogDescription>
-          </AlertDialogHeader>
-          <AlertDialogFooter>
-            <AlertDialogCancel>先留着</AlertDialogCancel>
-            <AlertDialogAction
-              variant="destructive"
-              onClick={() => {
-                if (!deleting) return;
-                mutations.remove.mutate(deleting.path, {
-                  onSuccess: () => setDeleting(null),
-                  onError: (error) => toast.error(error.message),
-                });
-              }}
-            >
-              删除
-            </AlertDialogAction>
-          </AlertDialogFooter>
-        </AlertDialogContent>
-      </AlertDialog>
-    </section>
-  );
-}
diff --git a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx b/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
deleted file mode 100644
index e01b34d..0000000
--- a/packages/console/src/features/sandboxes/components/HistoryPanel.tsx
+++ /dev/null
@@ -1,124 +0,0 @@
-import { Clock01Icon } from '@hugeicons/core-free-icons';
-import { HugeiconsIcon } from '@hugeicons/react';
-import { DataTable } from '@/components/DataTable';
-import { Badge } from '@/components/ui/badge';
-import {
-  Empty,
-  EmptyDescription,
-  EmptyHeader,
-  EmptyMedia,
-  EmptyTitle,
-} from '@/components/ui/empty';
-import { Spinner } from '@/components/ui/spinner';
-import {
-  TableBody,
-  TableCell,
-  TableHead,
-  TableHeader,
-  TableRow,
-} from '@/components/ui/table';
-import { actorLabel } from '@/features/activity/actors';
-import { useActivity } from '@/features/activity/hooks/useActivity';
-import {
-  ACTIVITY_KIND_LABELS,
-  ACTIVITY_KIND_STYLES,
-} from '@/features/activity/kinds';
-import { useApiKeys } from '@/features/api-keys/hooks/useApiKeys';
-import { cn } from '@/lib/utils';
-import { since } from '../format';
-
-/**
- * 「我的沙箱昨晚为什么停了」— 活动环里只属于这个沙箱的那几行。纯前端
- * 过滤:活动事件本来就带 name,不发明新端点;按环形表上限(1000)
- * 拉取,把这个沙箱的事件尽量捞全,再老的已经滚出环了。操作者列在这里
- * 尤其要紧:同一个沙箱被谁唤醒、被谁销毁,就是这一列的答案。
- */
-export function HistoryPanel({ name }: { name: string }) {
-  const { data, isPending, isError, error } = useActivity(1000);
-  const apiKeys = useApiKeys().data?.apiKeys;
-  const events = (data?.events ?? []).filter(
-    (event) => event.sandboxName === name,
-  );
-
-  if (isPending) {
-    return (
-      <div className="flex items-center gap-2 text-sm text-muted-foreground">
-        <Spinner /> 读取历史
-      </div>
-    );
-  }
-  if (isError) {
-    return (
-      <Empty className="border border-dashed">
-        <EmptyHeader>
-          <EmptyTitle>读取失败</EmptyTitle>
-          <EmptyDescription>{error.message}</EmptyDescription>
-        </EmptyHeader>
-      </Empty>
-    );
-  }
-  if (events.length === 0) {
-    return (
-      <Empty className="border border-dashed">
-        <EmptyHeader>
-          <EmptyMedia variant="icon">
-            <HugeiconsIcon icon={Clock01Icon} />
-          </EmptyMedia>
-          <EmptyTitle>最近没有这个沙箱的事件</EmptyTitle>
-          <EmptyDescription>
-            活动环只保留全局最近 1000 条 — 它更早的历史已经滚出去了。
-          </EmptyDescription>
-        </EmptyHeader>
-      </Empty>
-    );
-  }
-
-  return (
-    <div className="flex flex-col gap-3">
-      <DataTable>
-        <TableHeader>
-          <TableRow>
-            <TableHead className="w-28">时间</TableHead>
-            <TableHead className="w-28">事件</TableHead>
-            <TableHead className="w-32">操作者</TableHead>
-            <TableHead>详情</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody>
-          {events.map((event) => (
-            <TableRow key={event.id}>
-              <TableCell
-                className="tabular-nums text-muted-foreground"
-                title={new Date(event.at).toLocaleString()}
-              >
-                {since(event.at)}前
-              </TableCell>
-              <TableCell>
-                <Badge
-                  variant="outline"
-                  className={cn(
-                    'font-medium',
-                    ACTIVITY_KIND_STYLES[event.kind],
-                  )}
-                >
-                  {ACTIVITY_KIND_LABELS[event.kind]}
-                </Badge>
-              </TableCell>
-              <TableCell
-                className={cn(event.actor === null && 'text-muted-foreground')}
-              >
-                {actorLabel(event.actor, apiKeys)}
-              </TableCell>
-              <TableCell className="text-muted-foreground">
-                {event.detail}
-              </TableCell>
-            </TableRow>
-          ))}
-        </TableBody>
-      </DataTable>
-      <p className="text-sm text-muted-foreground">
-        销毁沙箱后 key 会重新可用 — 这里可能同时看到新旧两代沙箱的事件。
-      </p>
-    </div>
-  );
-}
diff --git a/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx b/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
deleted file mode 100644
index 2526e38..0000000
--- a/packages/console/src/features/sandboxes/components/ProcessesPanel.tsx
+++ /dev/null
@@ -1,167 +0,0 @@
-import type { Sandbox } from '@dormice/shared';
-import { ListViewIcon, MoreVerticalIcon } from '@hugeicons/core-free-icons';
-import { HugeiconsIcon } from '@hugeicons/react';
-import { toast } from 'sonner';
-import { DataTable } from '@/components/DataTable';
-import { Alert, AlertDescription } from '@/components/ui/alert';
-import { Button } from '@/components/ui/button';
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from '@/components/ui/dropdown-menu';
-import {
-  Empty,
-  EmptyDescription,
-  EmptyHeader,
-  EmptyMedia,
-  EmptyTitle,
-} from '@/components/ui/empty';
-import {
-  TableBody,
-  TableCell,
-  TableHead,
-  TableHeader,
-  TableRow,
-} from '@/components/ui/table';
-import { STATE_LABELS } from '../format';
-import { useEnvdAuth, useKillProcess, useProcesses } from '../hooks/useEnvd';
-
-/**
- * daemon 进程表的观察窗:列的是经由 E2B 进程面(SDK 的 background 命令、
- * 在线终端的 bash)启动、还活着的进程。List 在服务端刻意不唤醒 — 冻结的
- * 沙箱进程还在(SIGSTOP 挂起,唤醒续跑),这正是值得看的招牌能力。
- */
-export function ProcessesPanel({ sandbox }: { sandbox: Sandbox }) {
-  // 只有物理容器在(active/frozen)才有进程表;停机沙箱只剩磁盘。
-  const hasContainer = sandbox.state === 'active' || sandbox.state === 'frozen';
-  const auth = useEnvdAuth(sandbox.id);
-  const processes = useProcesses(auth.data, hasContainer);
-  const kill = useKillProcess(auth.data);
-
-  if (!hasContainer) {
-    return (
-      <Empty className="border border-dashed">
-        <EmptyHeader>
-          <EmptyMedia variant="icon">
-            <HugeiconsIcon icon={ListViewIcon} />
-          </EmptyMedia>
-          <EmptyTitle>没有进程表</EmptyTitle>
-          <EmptyDescription>
-            沙箱当前是「{STATE_LABELS[sandbox.state]}」— 只有磁盘还在,
-            进程要等下次唤醒才会有。
-          </EmptyDescription>
-        </EmptyHeader>
-      </Empty>
-    );
-  }
-
-  const list = processes.data ?? [];
-
-  const sendSignal = (
-    pid: number,
-    signal: 'SIGNAL_SIGTERM' | 'SIGNAL_SIGKILL',
-  ) => {
-    kill.mutate(
-      { pid, signal },
-      {
-        onSuccess: () =>
-          toast.success(
-            `已向 ${pid} 发送 ${signal === 'SIGNAL_SIGKILL' ? 'SIGKILL' : 'SIGTERM'}`,
-          ),
-        onError: (error) => toast.error(error.message),
-      },
-    );
-  };
-
-  return (
-    <div className="flex flex-col gap-3">
-      <p className="text-sm text-muted-foreground">
-        经由 E2B 进程面或在线终端启动的存活进程。冻结时进程被整体挂起、 不丢 —
-        唤醒后从暂停处继续跑。
-      </p>
-
-      {(processes.isError || auth.isError) && (
-        <Alert variant="destructive">
-          <AlertDescription>
-            {processes.error?.message ?? auth.error?.message}
-          </AlertDescription>
-        </Alert>
-      )}
-
-      {processes.isSuccess && list.length === 0 && (
-        <Empty className="border border-dashed">
-          <EmptyHeader>
-            <EmptyMedia variant="icon">
-              <HugeiconsIcon icon={ListViewIcon} />
-            </EmptyMedia>
-            <EmptyTitle>没有存活的进程</EmptyTitle>
-            <EmptyDescription>
-              用 SDK 跑一个 background 命令,或在「终端」页开一个 bash,
-              它就会出现在这里。
-            </EmptyDescription>
-          </EmptyHeader>
-        </Empty>
-      )}
-
-      {list.length > 0 && (
-        <DataTable>
-          <TableHeader>
-            <TableRow>
-              <TableHead className="w-20">PID</TableHead>
-              <TableHead>命令</TableHead>
-              <TableHead className="text-right">操作</TableHead>
-            </TableRow>
-          </TableHeader>
-          <TableBody>
-            {list.map((process) => (
-              <TableRow key={process.pid}>
-                <TableCell className="tabular-nums">{process.pid}</TableCell>
-                <TableCell className="max-w-md truncate font-mono text-xs">
-                  {[process.config.cmd, ...process.config.args].join(' ')}
-                </TableCell>
-                <TableCell className="text-right">
-                  {/* 两个信号收进「⋯」菜单:SIGTERM 是常规请求,
-                        SIGKILL 不可拒绝 — 才配 destructive 红。 */}
-                  <DropdownMenu>
-                    <DropdownMenuTrigger
-                      render={
-                        <Button
-                          variant="ghost"
-                          size="icon-sm"
-                          aria-label={`进程 ${process.pid} 的操作`}
-                        >
-                          <HugeiconsIcon icon={MoreVerticalIcon} />
-                        </Button>
-                      }
-                    />
-                    <DropdownMenuContent align="end">
-                      <DropdownMenuItem
-                        disabled={kill.isPending}
-                        onClick={() =>
-                          sendSignal(process.pid, 'SIGNAL_SIGTERM')
-                        }
-                      >
-                        发送 SIGTERM
-                      </DropdownMenuItem>
-                      <DropdownMenuItem
-                        variant="destructive"
-                        disabled={kill.isPending}
-                        onClick={() =>
-                          sendSignal(process.pid, 'SIGNAL_SIGKILL')
-                        }
-                      >
-                        发送 SIGKILL
-                      </DropdownMenuItem>
-                    </DropdownMenuContent>
-                  </DropdownMenu>
-                </TableCell>
-              </TableRow>
-            ))}
-          </TableBody>
-        </DataTable>
-      )}
-    </div>
-  );
-}
diff --git a/packages/console/src/features/sandboxes/components/workbench/FilePreviewPane.tsx b/packages/console/src/features/sandboxes/components/workbench/FilePreviewPane.tsx
new file mode 100644
index 0000000..9db0418
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/workbench/FilePreviewPane.tsx
@@ -0,0 +1,240 @@
+import type { Sandbox } from '@dormice/shared';
+import { Download01Icon, RefreshIcon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useQuery } from '@tanstack/react-query';
+import { useEffect, useState } from 'react';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import { Spinner } from '@/components/ui/spinner';
+import { Textarea } from '@/components/ui/textarea';
+import { formatBytes } from '@/lib/format';
+import { downloadFile, type EnvdEntry } from '../../envd-client';
+import { useEnvdAuth, useFileMutations } from '../../hooks/useEnvd';
+
+/**
+ * 在线看得过来的才在线看:预览上限之上只给下载 — 编辑器不是给日志
+ * 大文件准备的。上限取 1 MiB:够看配置、代码、多数日志尾巴,又不至于
+ * 把整段内存交给一个 textarea。
+ */
+const PREVIEW_CAP_BYTES = 1024 * 1024;
+
+/**
+ * 文本判定:头 8 KiB 里出现 NUL 字节即视为二进制。与 git 同一招 —
+ * 不猜编码不读魔数,便宜且几乎不会冤枉文本文件。
+ */
+function looksBinary(bytes: Uint8Array): boolean {
+  const head = bytes.subarray(0, 8192);
+  return head.includes(0);
+}
+
+/**
+ * 工作台中央的预览/编辑窗格:点开文件先看内容,小文本顺手改完保存 —
+ * 排查 agent 产物最高频的动作。读写都走 envd 的文件面(读 GET /files,
+ * 存同路径整文件覆写上传)。
+ *
+ * 内容是「打开时快照 + 手动刷新」,刻意不跟 watch 自动重读:agent 每
+ * 秒追写日志会冲掉正在编辑的草稿 — 快照语义才编辑得安稳。文件在沙箱
+ * 里被删/改名时,下一次读或刷新以诚实的错误态收场,不猜。
+ */
+export function FilePreviewPane({
+  sandbox,
+  selected,
+  onClear,
+}: {
+  sandbox: Sandbox;
+  /** 正在预览的文件;null = 空态。 */
+  selected: EnvdEntry | null;
+  /** 错误态里「清除选择」的出口。 */
+  onClear: () => void;
+}) {
+  const auth = useEnvdAuth(sandbox.id);
+  const [draft, setDraft] = useState('');
+  const mutations = useFileMutations(auth.data);
+  const tooLarge =
+    selected !== null && Number(selected.size) > PREVIEW_CAP_BYTES;
+
+  const content = useQuery({
+    queryKey: ['envdFileContent', sandbox.id, selected?.path],
+    queryFn: async () => {
+      if (!auth.data || !selected) throw new Error('缺少 envd 凭证');
+      const blob = await downloadFile(auth.data, selected.path);
+      const bytes = new Uint8Array(await blob.arrayBuffer());
+      if (looksBinary(bytes)) return { binary: true as const };
+      return { binary: false as const, text: new TextDecoder().decode(bytes) };
+    },
+    enabled: selected !== null && !tooLarge && auth.data !== undefined,
+    // 文件内容随沙箱里的进程随时在变,每次选中都重读,不吃缓存。
+    gcTime: 0,
+    staleTime: 0,
+    retry: false,
+  });
+
+  // 读到文本后灌入编辑区;依赖 content.data 使换文件/刷新时必然重灌。
+  useEffect(() => {
+    if (content.data && !content.data.binary) {
+      setDraft(content.data.text);
+    }
+  }, [content.data]);
+
+  const dirty =
+    content.data !== undefined &&
+    !content.data.binary &&
+    draft !== content.data.text;
+
+  if (selected === null) {
+    return (
+      <div className="flex h-full items-center justify-center p-4">
+        <Empty>
+          <EmptyHeader>
+            <EmptyTitle>在左侧选择一个文件</EmptyTitle>
+            <EmptyDescription>
+              文本文件在这里预览和编辑;终端就在下面,改完顺手跑。
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      </div>
+    );
+  }
+
+  const download = () =>
+    mutations.download.mutate(
+      { path: selected.path, name: selected.name },
+      { onError: (error) => toast.error(error.message) },
+    );
+
+  const save = () =>
+    mutations.upload.mutate(
+      { path: selected.path, file: new File([draft], selected.name) },
+      {
+        onSuccess: () => {
+          toast.success(`已保存 ${selected.name}`);
+          // 窗格常驻(弹窗是关了了事),重读一次把保存结果立为新基线,
+          // dirty 自然归零。
+          void content.refetch();
+        },
+        onError: (error) => toast.error(error.message),
+      },
+    );
+
+  return (
+    <div className="flex h-full min-h-0 flex-col">
+      <div className="flex shrink-0 items-center justify-between gap-2 border-b px-3 py-1.5">
+        <span
+          className="min-w-0 truncate font-mono text-xs text-muted-foreground"
+          title={selected.path}
+        >
+          <span className="font-medium text-foreground">{selected.name}</span>
+          {' · '}
+          {formatBytes(Number(selected.size))}
+        </span>
+        <div className="flex shrink-0 items-center gap-1">
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            aria-label="重新读取"
+            disabled={content.isFetching || dirty}
+            title={
+              dirty
+                ? '有未保存的修改 — 先保存或撤销,刷新会覆盖草稿'
+                : '重新读取'
+            }
+            onClick={() => void content.refetch()}
+          >
+            <HugeiconsIcon icon={RefreshIcon} />
+          </Button>
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            aria-label="下载"
+            disabled={mutations.download.isPending}
+            onClick={download}
+          >
+            <HugeiconsIcon icon={Download01Icon} />
+          </Button>
+          <Button
+            size="sm"
+            className="h-6 px-2 text-xs"
+            disabled={!dirty || mutations.upload.isPending}
+            onClick={save}
+          >
+            {mutations.upload.isPending && <Spinner />}
+            保存
+          </Button>
+        </div>
+      </div>
+
+      {tooLarge || content.data?.binary ? (
+        <div className="flex min-h-0 flex-1 items-center justify-center p-4">
+          <Empty>
+            <EmptyHeader>
+              <EmptyTitle>
+                {tooLarge ? '文件太大,不在线预览' : '二进制文件,没法当文本看'}
+              </EmptyTitle>
+              <EmptyDescription>
+                {tooLarge
+                  ? `在线预览上限 ${formatBytes(PREVIEW_CAP_BYTES)} — 下载后用本地工具打开。`
+                  : '内容里有 NUL 字节 — 下载后用对应的工具打开。'}
+              </EmptyDescription>
+            </EmptyHeader>
+            <EmptyContent>
+              <Button
+                variant="outline"
+                size="sm"
+                disabled={mutations.download.isPending}
+                onClick={download}
+              >
+                <HugeiconsIcon icon={Download01Icon} />
+                下载
+              </Button>
+            </EmptyContent>
+          </Empty>
+        </div>
+      ) : content.isError ? (
+        <div className="flex min-h-0 flex-1 items-center justify-center p-4">
+          <Empty>
+            <EmptyHeader>
+              <EmptyTitle>读取失败 — 文件可能已被删除或改名</EmptyTitle>
+              <EmptyDescription>{content.error.message}</EmptyDescription>
+            </EmptyHeader>
+            <EmptyContent>
+              <div className="flex gap-2">
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={() => void content.refetch()}
+                >
+                  重试
+                </Button>
+                <Button variant="ghost" size="sm" onClick={onClear}>
+                  清除选择
+                </Button>
+              </div>
+            </EmptyContent>
+          </Empty>
+        </div>
+      ) : content.isPending ? (
+        <div className="flex items-center gap-2 p-4 text-sm text-muted-foreground">
+          <Spinner /> 读取文件
+        </div>
+      ) : (
+        <div className="min-h-0 flex-1 p-2">
+          {/* base-ui Textarea 默认 field-sizing-content 随内容长高,
+              定高窗格必须钉死(RULES/前端.md 已知坑)。 */}
+          <Textarea
+            value={draft}
+            onChange={(event) => setDraft(event.target.value)}
+            spellCheck={false}
+            className="h-full field-sizing-fixed resize-none overflow-y-auto font-mono text-xs leading-relaxed"
+          />
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/components/workbench/FileTreePane.tsx b/packages/console/src/features/sandboxes/components/workbench/FileTreePane.tsx
new file mode 100644
index 0000000..8c778c8
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/workbench/FileTreePane.tsx
@@ -0,0 +1,466 @@
+import type { Sandbox } from '@dormice/shared';
+import {
+  ArrowDown01Icon,
+  ArrowRight01Icon,
+  Delete02Icon,
+  Download01Icon,
+  Edit02Icon,
+  File01Icon,
+  Folder01Icon,
+  FolderAddIcon,
+  MoreVerticalIcon,
+  RefreshIcon,
+  Upload01Icon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useQueryClient } from '@tanstack/react-query';
+import { useRef, useState } from 'react';
+import { toast } from 'sonner';
+import { Alert, AlertDescription } from '@/components/ui/alert';
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import {
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@/components/ui/empty';
+import { Spinner } from '@/components/ui/spinner';
+import { formatBytes } from '@/lib/format';
+import { cn } from '@/lib/utils';
+import type { EnvdAuth, EnvdEntry } from '../../envd-client';
+import { STATE_LABELS } from '../../format';
+import {
+  useDirectory,
+  useDirectoryWatch,
+  useEnvdAuth,
+  useFileMutations,
+} from '../../hooks/useEnvd';
+import { DeleteDialog, MkdirDialog, RenameDialog } from './file-dialogs';
+
+const HOME = '/home/user';
+
+/** /home/user → ~,其下路径缩写成 ~/x/y。 */
+function tildify(path: string): string {
+  return path === HOME ? '~' : `~${path.slice(HOME.length)}`;
+}
+
+function sortEntries(entries: EnvdEntry[]): EnvdEntry[] {
+  return [...entries].sort((a, b) => {
+    const aDir = a.type === 'FILE_TYPE_DIRECTORY' ? 0 : 1;
+    const bDir = b.type === 'FILE_TYPE_DIRECTORY' ? 0 : 1;
+    return aDir - bDir || a.name.localeCompare(b.name);
+  });
+}
+
+/** 递归组件间共享的树上下文 — 免得每层透传七个 props。 */
+type TreeContext = {
+  auth: EnvdAuth | undefined;
+  unlocked: boolean;
+  expanded: Set<string>;
+  selectedPath: string | null;
+  onDirClick: (entry: EnvdEntry) => void;
+  onFileClick: (entry: EnvdEntry) => void;
+  onDownload: (entry: EnvdEntry) => void;
+  onRename: (entry: EnvdEntry) => void;
+  onDelete: (entry: EnvdEntry) => void;
+};
+
+/**
+ * 树的一层 = 一个 useDirectory(query key 按路径,一层一 query)。折叠的
+ * 目录不渲染子层,也就不发请求 — 懒加载不用任何额外机制;展开过的层
+ * 折叠后缓存仍在,mutation 的前缀失效(['envdDir', id])会让全树跟上。
+ */
+function TreeLevel({
+  tree,
+  path,
+  depth,
+}: {
+  tree: TreeContext;
+  path: string;
+  depth: number;
+}) {
+  const directory = useDirectory(tree.auth, path, tree.unlocked);
+
+  if (directory.isLoading) {
+    return (
+      <div
+        className="flex items-center gap-2 px-2 py-1 text-xs text-muted-foreground"
+        style={{ paddingLeft: `${8 + depth * 14}px` }}
+      >
+        <Spinner />
+        {depth === 0 ? '读取目录(沉睡的沙箱会先被唤醒)' : '读取中'}
+      </div>
+    );
+  }
+  if (directory.isError) {
+    return (
+      <div
+        className="px-2 py-1 text-xs text-destructive"
+        style={{ paddingLeft: `${8 + depth * 14}px` }}
+        title={directory.error.message}
+      >
+        读取失败:{directory.error.message}
+      </div>
+    );
+  }
+
+  const entries = sortEntries(directory.data ?? []);
+  if (depth === 0 && entries.length === 0) {
+    return (
+      <div className="px-3 py-2 text-xs text-muted-foreground">
+        空目录 — 上传一个文件试试,拖进这个区域也行。
+      </div>
+    );
+  }
+
+  return (
+    <>
+      {entries.map((entry) => {
+        const isDir = entry.type === 'FILE_TYPE_DIRECTORY';
+        const open = isDir && tree.expanded.has(entry.path);
+        return (
+          <div key={entry.path}>
+            <div className="group flex items-center pr-1">
+              <button
+                type="button"
+                className={cn(
+                  'flex min-w-0 flex-1 items-center gap-1.5 rounded-md px-2 py-1 text-left text-sm hover:bg-muted',
+                  !isDir && tree.selectedPath === entry.path && 'bg-muted',
+                )}
+                style={{ paddingLeft: `${8 + depth * 14}px` }}
+                onClick={() =>
+                  isDir ? tree.onDirClick(entry) : tree.onFileClick(entry)
+                }
+              >
+                <span className="w-3.5 shrink-0 text-muted-foreground">
+                  {isDir && (
+                    <HugeiconsIcon
+                      icon={open ? ArrowDown01Icon : ArrowRight01Icon}
+                      className="size-3.5"
+                    />
+                  )}
+                </span>
+                <HugeiconsIcon
+                  icon={isDir ? Folder01Icon : File01Icon}
+                  className={cn(
+                    'size-4 shrink-0',
+                    isDir ? 'text-sky-500' : 'text-muted-foreground',
+                  )}
+                />
+                <span className="truncate" title={entry.name}>
+                  {entry.name}
+                </span>
+                {!isDir && (
+                  <span className="ml-auto shrink-0 pl-2 text-xs tabular-nums text-muted-foreground">
+                    {formatBytes(Number(entry.size))}
+                  </span>
+                )}
+              </button>
+              <DropdownMenu>
+                <DropdownMenuTrigger
+                  render={
+                    <Button
+                      variant="ghost"
+                      size="icon-sm"
+                      aria-label={`${entry.name} 的操作`}
+                      className="opacity-0 group-hover:opacity-100 focus-visible:opacity-100 data-popup-open:opacity-100"
+                    >
+                      <HugeiconsIcon icon={MoreVerticalIcon} />
+                    </Button>
+                  }
+                />
+                <DropdownMenuContent align="end">
+                  {!isDir && (
+                    <DropdownMenuItem onClick={() => tree.onDownload(entry)}>
+                      <HugeiconsIcon icon={Download01Icon} />
+                      下载
+                    </DropdownMenuItem>
+                  )}
+                  <DropdownMenuItem onClick={() => tree.onRename(entry)}>
+                    <HugeiconsIcon icon={Edit02Icon} />
+                    重命名
+                  </DropdownMenuItem>
+                  <DropdownMenuItem
+                    variant="destructive"
+                    onClick={() => tree.onDelete(entry)}
+                  >
+                    <HugeiconsIcon icon={Delete02Icon} />
+                    删除
+                  </DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            </div>
+            {open && (
+              <TreeLevel tree={tree} path={entry.path} depth={depth + 1} />
+            )}
+          </div>
+        );
+      })}
+    </>
+  );
+}
+
+/**
+ * 工作台左栏:/home/user 的懒加载文件树,走 envd 的 Filesystem RPC —
+ * 与官方 e2b SDK 同一条 wire。文件动词会唤醒冻结的沙箱,所以非 active
+ * 状态下第一步是一次显式的"打开"(与终端同一条纪律:看不解冻,用才解冻)。
+ *
+ * 「焦点目录」是唯一的落点裁决:点文件 = 选中它 + 焦点到其父目录;点
+ * 目录 = 展开/折叠 + 焦点到它。上传按钮、拖拽、新建文件夹、watch 布防
+ * 全部落在焦点目录 — 规则只有一条,空目录也能当上传目标(点它即聚焦)。
+ */
+export function FileTreePane({
+  sandbox,
+  selected,
+  onSelect,
+}: {
+  sandbox: Sandbox;
+  selected: EnvdEntry | null;
+  onSelect: (entry: EnvdEntry | null) => void;
+}) {
+  const [unlocked, setUnlocked] = useState(sandbox.state === 'active');
+  const [expanded, setExpanded] = useState<Set<string>>(new Set());
+  const [focusDir, setFocusDir] = useState(HOME);
+  const [mkdirOpen, setMkdirOpen] = useState(false);
+  const [renaming, setRenaming] = useState<EnvdEntry | null>(null);
+  const [deleting, setDeleting] = useState<EnvdEntry | null>(null);
+  // 拖拽悬停的视觉反馈;计数器抵消子元素间的 dragenter/dragleave 抖动。
+  const [dragDepth, setDragDepth] = useState(0);
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+
+  const auth = useEnvdAuth(sandbox.id);
+  const mutations = useFileMutations(auth.data);
+  const queryClient = useQueryClient();
+  // watch 跟随焦点:只在焦点目录布一个 watcher(hook 以 path 为依赖,
+  // 焦点切换自拆自装),不逐展开目录布防 — 布防要容器里起 inotifywait,
+  // N 个展开目录 N 个进程不值得。
+  useDirectoryWatch(auth.data, focusDir, {
+    enabled: unlocked,
+    active: sandbox.state === 'active',
+  });
+
+  // 删除/重命名后的状态收敛:命中选中文件(或其祖先目录)就清掉/跟上,
+  // 展开集与焦点目录同步剪枝 — 不留指向已不存在路径的悬挂状态。
+  const pruneUnder = (path: string) => {
+    setExpanded(
+      (prev) =>
+        new Set(
+          [...prev].filter((p) => p !== path && !p.startsWith(`${path}/`)),
+        ),
+    );
+    setFocusDir((dir) =>
+      dir === path || dir.startsWith(`${path}/`) ? HOME : dir,
+    );
+  };
+  const handleDeleted = (path: string) => {
+    if (
+      selected &&
+      (selected.path === path || selected.path.startsWith(`${path}/`))
+    ) {
+      onSelect(null);
+    }
+    pruneUnder(path);
+  };
+  const handleRenamed = (source: string, destination: string) => {
+    if (selected?.path === source) {
+      onSelect({
+        ...selected,
+        name: destination.slice(destination.lastIndexOf('/') + 1),
+        path: destination,
+      });
+    } else if (selected?.path.startsWith(`${source}/`)) {
+      // 选中文件藏在被改名的目录里,旧路径作废 — 诚实清空,胜过猜新路径。
+      onSelect(null);
+    }
+    pruneUnder(source);
+  };
+
+  // 逐个串行上传到焦点目录:一次汇报总成败,失败点名到文件。
+  const upload = async (files: File[]) => {
+    const failures: string[] = [];
+    for (const file of files) {
+      try {
+        await mutations.upload.mutateAsync({
+          path: `${focusDir}/${file.name}`,
+          file,
+        });
+      } catch {
+        failures.push(file.name);
+      }
+    }
+    if (failures.length === 0) {
+      const only = files.length === 1 ? files[0] : undefined;
+      toast.success(
+        only ? `已上传 ${only.name}` : `已上传 ${files.length} 个文件`,
+      );
+    } else {
+      toast.error(`${failures.length} 个上传失败:${failures.join('、')}`);
+    }
+  };
+
+  if (!unlocked) {
+    return (
+      <div className="flex h-full items-center justify-center p-4">
+        <Empty>
+          <EmptyHeader>
+            <EmptyMedia variant="icon">
+              <HugeiconsIcon icon={Folder01Icon} />
+            </EmptyMedia>
+            <EmptyTitle>文件浏览器</EmptyTitle>
+            <EmptyDescription>
+              沙箱当前是「{STATE_LABELS[sandbox.state]}」— 浏览文件会唤醒它
+              (冻结约 50ms,停止需要几秒冷启动)。看这一页本身不会。
+            </EmptyDescription>
+          </EmptyHeader>
+          <Button size="sm" onClick={() => setUnlocked(true)}>
+            打开文件浏览器
+          </Button>
+        </Empty>
+      </div>
+    );
+  }
+
+  return (
+    // 拖放只是「上传」按钮的增强,不是唯一入口;section 让辅助技术
+    // 知道这一块是文件工作区,而不是把版面 div 假装成控件。
+    <section
+      aria-label="文件树(支持拖放上传到焦点目录)"
+      className={cn(
+        'flex h-full min-h-0 flex-col transition-shadow',
+        dragDepth > 0 && 'ring-2 ring-inset ring-primary/60',
+      )}
+      onDragOver={(event) => event.preventDefault()}
+      onDragEnter={(event) => {
+        event.preventDefault();
+        setDragDepth((depth) => depth + 1);
+      }}
+      onDragLeave={() => setDragDepth((depth) => Math.max(0, depth - 1))}
+      onDrop={(event) => {
+        event.preventDefault();
+        setDragDepth(0);
+        const files = Array.from(event.dataTransfer.files);
+        if (files.length > 0) void upload(files);
+      }}
+    >
+      <div className="flex shrink-0 items-center gap-1 border-b px-2 py-1.5">
+        <span
+          className="min-w-0 flex-1 truncate font-mono text-xs text-muted-foreground"
+          title={`焦点目录 ${focusDir} — 上传/新建落在这里`}
+        >
+          {tildify(focusDir)}
+        </span>
+        <input
+          ref={fileInputRef}
+          type="file"
+          multiple
+          className="hidden"
+          onChange={(event) => {
+            const files = Array.from(event.target.files ?? []);
+            if (files.length > 0) void upload(files);
+            event.target.value = '';
+          }}
+        />
+        <Button
+          variant="ghost"
+          size="icon-sm"
+          aria-label="上传到焦点目录"
+          disabled={mutations.upload.isPending}
+          onClick={() => fileInputRef.current?.click()}
+        >
+          {mutations.upload.isPending ? (
+            <Spinner />
+          ) : (
+            <HugeiconsIcon icon={Upload01Icon} />
+          )}
+        </Button>
+        <Button
+          variant="ghost"
+          size="icon-sm"
+          aria-label="在焦点目录新建文件夹"
+          onClick={() => setMkdirOpen(true)}
+        >
+          <HugeiconsIcon icon={FolderAddIcon} />
+        </Button>
+        <Button
+          variant="ghost"
+          size="icon-sm"
+          aria-label="刷新"
+          onClick={() =>
+            // 前缀失效 = 全树重扫;比逐层 refetch 省心,也和 mutation
+            // 成功后的失效走同一条路。
+            void queryClient.invalidateQueries({
+              queryKey: ['envdDir', sandbox.id],
+            })
+          }
+        >
+          <HugeiconsIcon icon={RefreshIcon} />
+        </Button>
+      </div>
+
+      {auth.isError && (
+        <Alert variant="destructive" className="m-2">
+          <AlertDescription>{auth.error.message}</AlertDescription>
+        </Alert>
+      )}
+
+      <div className="min-h-0 flex-1 overflow-auto py-1.5 pl-1.5">
+        <TreeLevel
+          tree={{
+            auth: auth.data,
+            unlocked,
+            expanded,
+            selectedPath: selected?.path ?? null,
+            onDirClick: (entry) => {
+              setExpanded((prev) => {
+                const next = new Set(prev);
+                if (next.has(entry.path)) next.delete(entry.path);
+                else next.add(entry.path);
+                return next;
+              });
+              setFocusDir(entry.path);
+            },
+            onFileClick: (entry) => {
+              onSelect(entry);
+              setFocusDir(entry.path.slice(0, entry.path.lastIndexOf('/')));
+            },
+            onDownload: (entry) =>
+              mutations.download.mutate(
+                { path: entry.path, name: entry.name },
+                { onError: (error) => toast.error(error.message) },
+              ),
+            onRename: setRenaming,
+            onDelete: setDeleting,
+          }}
+          path={HOME}
+          depth={0}
+        />
+      </div>
+
+      <MkdirDialog
+        open={mkdirOpen}
+        onOpenChange={setMkdirOpen}
+        dir={focusDir}
+        mkdir={mutations.mkdir}
+      />
+      <RenameDialog
+        entry={renaming}
+        onClose={() => setRenaming(null)}
+        move={mutations.move}
+        onRenamed={handleRenamed}
+      />
+      <DeleteDialog
+        entry={deleting}
+        onClose={() => setDeleting(null)}
+        remove={mutations.remove}
+        onDeleted={handleDeleted}
+      />
+    </section>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/components/workbench/MonitorRail.tsx b/packages/console/src/features/sandboxes/components/workbench/MonitorRail.tsx
new file mode 100644
index 0000000..b89f7e6
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/workbench/MonitorRail.tsx
@@ -0,0 +1,464 @@
+import type { Sandbox } from '@dormice/shared';
+import {
+  ChartLineData01Icon,
+  Copy01Icon,
+  CpuIcon,
+  HardDriveIcon,
+  MoreVerticalIcon,
+  RamMemoryIcon,
+} from '@hugeicons/core-free-icons';
+import { HugeiconsIcon, type HugeiconsProps } from '@hugeicons/react';
+import { Link } from '@tanstack/react-router';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { Meter } from '@/components/Meter';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent } from '@/components/ui/card';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { actorLabel } from '@/features/activity/actors';
+import { useActivity } from '@/features/activity/hooks/useActivity';
+import {
+  ACTIVITY_KIND_LABELS,
+  ACTIVITY_KIND_STYLES,
+} from '@/features/activity/kinds';
+import { useApiKeys } from '@/features/api-keys/hooks/useApiKeys';
+import { Sparkline } from '@/features/overview/components/Sparkline';
+import { copyText } from '@/lib/copy';
+import { formatBytes, pctOf } from '@/lib/format';
+import { cn } from '@/lib/utils';
+import { policyLine, since } from '../../format';
+import { useEnvdAuth, useKillProcess, useProcesses } from '../../hooks/useEnvd';
+import {
+  useSandboxImages,
+  useSandboxMetrics,
+  useSandboxMetricsHistory,
+} from '../../hooks/useSandboxes';
+import { LifecycleCountdown } from '../LifecycleCountdown';
+import { MetricsPanel } from '../MetricsPanel';
+import { SandboxStateBadge } from '../SandboxStateBadge';
+import { UpgradableBadge } from '../UpgradableBadge';
+
+/**
+ * 工作台右栏:一眼看全这台"机器"的仪表 — 生命周期、资源水位、进程、
+ * 最近活动、身份信息,全部常驻不进 tab。栏里全是只读观察(指标不 wake、
+ * Process/List 服务端刻意不唤醒、活动读 daemon 账本),挂着不违反
+ * "看不解冻"纪律;唯一的写动作 kill 站在显式点击后面。
+ */
+
+function RailCard({
+  title,
+  action,
+  children,
+}: {
+  title: string;
+  action?: React.ReactNode;
+  children: React.ReactNode;
+}) {
+  return (
+    <Card size="sm" className="shrink-0">
+      <CardContent className="flex flex-col gap-2">
+        <div className="flex items-center justify-between">
+          <span className="text-sm text-muted-foreground">{title}</span>
+          {action}
+        </div>
+        {children}
+      </CardContent>
+    </Card>
+  );
+}
+
+function LifecycleCard({ sandbox }: { sandbox: Sandbox }) {
+  return (
+    <RailCard
+      title="生命周期"
+      action={<SandboxStateBadge state={sandbox.state} />}
+    >
+      <LifecycleCountdown sandbox={sandbox} />
+      <div className="text-xs text-muted-foreground">
+        {policyLine(sandbox.policy)}
+      </div>
+    </RailCard>
+  );
+}
+
+function VitalCard({
+  icon,
+  label,
+  value,
+  hint,
+  pct,
+  spark,
+}: {
+  icon: NonNullable<HugeiconsProps['icon']>;
+  label: string;
+  value: string;
+  hint: string;
+  pct: number | null;
+  spark: number[];
+}) {
+  return (
+    <Card size="sm" className="shrink-0">
+      <CardContent className="flex flex-col gap-1.5">
+        <div className="flex items-center justify-between">
+          <span className="flex items-center gap-1.5 text-sm text-muted-foreground">
+            <HugeiconsIcon icon={icon} className="size-4" strokeWidth={1.8} />
+            {label}
+          </span>
+          <span className="text-sm font-semibold tabular-nums">{value}</span>
+        </div>
+        {spark.length >= 2 && <Sparkline data={spark} className="h-8 w-full" />}
+        <Meter pct={pct} />
+        <div className="text-xs text-muted-foreground">{hint}</div>
+      </CardContent>
+    </Card>
+  );
+}
+
+function VitalsSection({ sandbox }: { sandbox: Sandbox }) {
+  const [chartsOpen, setChartsOpen] = useState(false);
+  const live = useSandboxMetrics(sandbox.name);
+  // 1 小时窗口喂 sparkline — 右栏只答"最近的形状",完整走势在弹窗。
+  const history = useSandboxMetricsHistory(sandbox.name, 3600_000);
+  const sample = live.data?.sample ?? null;
+  const samples = history.data?.samples ?? [];
+  // 停机沙箱当前值为 null(观察不唤醒,没有容器可测),出诚实空值;
+  // 历史照画 — 历史是历史。
+  const offlineHint = '没有容器可测 — 观察不唤醒';
+
+  return (
+    <>
+      <div className="flex shrink-0 items-center justify-between">
+        <span className="text-sm font-medium">资源</span>
+        <Button
+          variant="ghost"
+          size="sm"
+          className="h-6 gap-1 px-2 text-xs text-muted-foreground"
+          onClick={() => setChartsOpen(true)}
+        >
+          <HugeiconsIcon icon={ChartLineData01Icon} className="size-3.5" />
+          完整走势
+        </Button>
+      </div>
+      <VitalCard
+        icon={CpuIcon}
+        label="CPU"
+        value={sample ? `${Math.round(sample.cpuUsedPct)}%` : '—'}
+        hint={sample ? `${sample.cpuCount} 核 · 百分比按单核计` : offlineHint}
+        pct={sample ? sample.cpuUsedPct / sample.cpuCount : null}
+        spark={samples.map((s) => s.cpuUsedPct)}
+      />
+      <VitalCard
+        icon={RamMemoryIcon}
+        label="内存"
+        value={sample ? formatBytes(sample.memUsedBytes) : '—'}
+        hint={sample ? `共 ${formatBytes(sample.memTotalBytes)}` : offlineHint}
+        pct={sample ? pctOf(sample.memUsedBytes, sample.memTotalBytes) : null}
+        spark={samples.map((s) => s.memUsedBytes)}
+      />
+      <VitalCard
+        icon={HardDriveIcon}
+        label="磁盘"
+        value={sample ? formatBytes(sample.diskUsedBytes) : '—'}
+        hint={
+          sample ? `名义 ${formatBytes(sample.diskTotalBytes)}` : offlineHint
+        }
+        pct={sample ? pctOf(sample.diskUsedBytes, sample.diskTotalBytes) : null}
+        spark={samples.map((s) => s.diskUsedBytes)}
+      />
+      <Dialog open={chartsOpen} onOpenChange={setChartsOpen}>
+        <DialogContent className="max-h-[85vh] overflow-y-auto sm:max-w-5xl">
+          <DialogHeader>
+            <DialogTitle>指标走势 — {sandbox.name}</DialogTitle>
+            <DialogDescription>
+              当前值 5 秒刷新;历史由 daemon 采样落库,档位 1h / 24h / 7d。
+            </DialogDescription>
+          </DialogHeader>
+          <MetricsPanel sandbox={sandbox} />
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
+
+function ProcessesCard({ sandbox }: { sandbox: Sandbox }) {
+  // 只有物理容器在(active/frozen)才有进程表;停机沙箱只剩磁盘。
+  const hasContainer = sandbox.state === 'active' || sandbox.state === 'frozen';
+  const auth = useEnvdAuth(sandbox.id);
+  const processes = useProcesses(auth.data, hasContainer);
+  const kill = useKillProcess(auth.data);
+  const list = processes.data ?? [];
+
+  // kill 在服务端走 wakeForUse(发信号=用沙箱,会唤醒 frozen)——它站在
+  // 两次显式点击(⋯ → 信号)后面,合规。
+  const sendSignal = (
+    pid: number,
+    signal: 'SIGNAL_SIGTERM' | 'SIGNAL_SIGKILL',
+  ) => {
+    kill.mutate(
+      { pid, signal },
+      {
+        onSuccess: () =>
+          toast.success(
+            `已向 ${pid} 发送 ${signal === 'SIGNAL_SIGKILL' ? 'SIGKILL' : 'SIGTERM'}`,
+          ),
+        onError: (error) => toast.error(error.message),
+      },
+    );
+  };
+
+  return (
+    <RailCard
+      title="进程"
+      action={
+        hasContainer && list.length > 0 ? (
+          <span className="text-xs tabular-nums text-muted-foreground">
+            {list.length}
+          </span>
+        ) : undefined
+      }
+    >
+      {!hasContainer ? (
+        <p className="text-xs text-muted-foreground">
+          沙箱睡了,只有磁盘还在 — 进程要等下次唤醒。
+        </p>
+      ) : list.length === 0 ? (
+        <p className="text-xs text-muted-foreground">
+          没有存活的进程 — 连上终端或用 SDK 跑个 background 命令,它就会出现。
+        </p>
+      ) : (
+        <div className="flex flex-col">
+          {list.map((process) => {
+            const command = [process.config.cmd, ...process.config.args].join(
+              ' ',
+            );
+            return (
+              <div
+                key={process.pid}
+                className="group flex items-center gap-2 border-b py-1 text-xs last:border-b-0"
+              >
+                <span className="shrink-0 tabular-nums text-muted-foreground">
+                  {process.pid}
+                </span>
+                <span
+                  className="min-w-0 flex-1 truncate font-mono"
+                  title={command}
+                >
+                  {command}
+                </span>
+                <DropdownMenu>
+                  <DropdownMenuTrigger
+                    render={
+                      <Button
+                        variant="ghost"
+                        size="icon-sm"
+                        aria-label={`进程 ${process.pid} 的操作`}
+                        className="size-6 opacity-0 group-hover:opacity-100 focus-visible:opacity-100 data-popup-open:opacity-100"
+                      >
+                        <HugeiconsIcon icon={MoreVerticalIcon} />
+                      </Button>
+                    }
+                  />
+                  <DropdownMenuContent align="end">
+                    <DropdownMenuItem
+                      onClick={() => sendSignal(process.pid, 'SIGNAL_SIGTERM')}
+                    >
+                      发送 SIGTERM
+                    </DropdownMenuItem>
+                    <DropdownMenuItem
+                      variant="destructive"
+                      onClick={() => sendSignal(process.pid, 'SIGNAL_SIGKILL')}
+                    >
+                      发送 SIGKILL
+                    </DropdownMenuItem>
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </RailCard>
+  );
+}
+
+/** 右栏活动卡列几条最近的;全量(带筛选与详情列)在活动页。 */
+const ACTIVITY_ROWS = 8;
+
+function ActivityCard({ sandbox }: { sandbox: Sandbox }) {
+  const { data } = useActivity(1000);
+  const apiKeys = useApiKeys().data?.apiKeys;
+  const events = (data?.events ?? []).filter(
+    (event) => event.sandboxName === sandbox.name,
+  );
+
+  return (
+    <RailCard
+      title="最近活动"
+      action={
+        <Button
+          variant="ghost"
+          size="sm"
+          className="h-6 px-2 text-xs text-muted-foreground"
+          nativeButton={false}
+          render={<Link to="/activity" search={{ sandbox: sandbox.name }} />}
+        >
+          查看全部
+        </Button>
+      }
+    >
+      {events.length === 0 ? (
+        <p className="text-xs text-muted-foreground">
+          最近没有这个沙箱的事件 — 活动环只保留全局最近 1000 条。
+        </p>
+      ) : (
+        <div className="flex flex-col">
+          {events.slice(0, ACTIVITY_ROWS).map((event) => (
+            <div
+              key={event.id}
+              className="flex items-center gap-2 border-b py-1.5 text-xs last:border-b-0"
+              title={`${new Date(event.at).toLocaleString()}${event.detail ? ` · ${event.detail}` : ''}`}
+            >
+              <Badge
+                variant="outline"
+                className={cn(
+                  'shrink-0 font-medium',
+                  ACTIVITY_KIND_STYLES[event.kind],
+                )}
+              >
+                {ACTIVITY_KIND_LABELS[event.kind]}
+              </Badge>
+              <span
+                className={cn(
+                  'min-w-0 flex-1 truncate',
+                  event.actor === null && 'text-muted-foreground',
+                )}
+              >
+                {actorLabel(event.actor, apiKeys)}
+              </span>
+              <span className="shrink-0 tabular-nums text-muted-foreground">
+                {since(event.at)}前
+              </span>
+            </div>
+          ))}
+        </div>
+      )}
+    </RailCard>
+  );
+}
+
+function InfoRow({
+  label,
+  children,
+}: {
+  label: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex items-baseline justify-between gap-4 border-b py-2 text-xs last:border-b-0">
+      <dt className="shrink-0 text-muted-foreground">{label}</dt>
+      <dd className="min-w-0 truncate text-right font-mono">{children}</dd>
+    </div>
+  );
+}
+
+function InfoCard({ sandbox }: { sandbox: Sandbox }) {
+  // 镜像血统与列表页同一份 5 秒缓存;拿不到就不显示,不挡卡片。
+  const images = useSandboxImages();
+  const lineage = images.data?.images.find(
+    (entry) => entry.sandboxName === sandbox.name,
+  );
+
+  return (
+    <RailCard
+      title="沙箱信息"
+      action={
+        <Button
+          variant="ghost"
+          size="icon-sm"
+          className="size-6"
+          aria-label="复制沙箱 ID"
+          onClick={() =>
+            copyText(sandbox.id).then(
+              () => toast.success('已复制沙箱 ID'),
+              () => toast.error('复制失败'),
+            )
+          }
+        >
+          <HugeiconsIcon icon={Copy01Icon} />
+        </Button>
+      }
+    >
+      <dl>
+        <InfoRow label="ID">
+          <span title={sandbox.id}>{sandbox.id}</span>
+        </InfoRow>
+        <InfoRow label="模板">
+          <span className="inline-flex items-center gap-1.5">
+            {sandbox.template ?? '基础镜像'}
+            <UpgradableBadge lineage={lineage} />
+          </span>
+        </InfoRow>
+        {lineage && (
+          <InfoRow label="镜像">
+            {lineage.image === null
+              ? `无容器 — 下次启动用 ${lineage.nextImage}`
+              : lineage.upgradable
+                ? `${lineage.image} → Rebuild 后 ${lineage.nextImage}`
+                : lineage.image}
+          </InfoRow>
+        )}
+        {Object.keys(sandbox.metadata).length > 0 && (
+          <InfoRow label="标签">
+            <span className="inline-flex flex-wrap justify-end gap-1">
+              {Object.entries(sandbox.metadata).map(([key, value]) => (
+                <Badge
+                  key={key}
+                  variant="outline"
+                  className="max-w-[10rem] truncate font-mono text-xs font-normal text-muted-foreground"
+                  title={`${key}=${value}`}
+                >
+                  {key}={value}
+                </Badge>
+              ))}
+            </span>
+          </InfoRow>
+        )}
+        <InfoRow label="节点">{sandbox.nodeId}</InfoRow>
+        <InfoRow label="端点">
+          <span title={sandbox.endpoint}>{sandbox.endpoint}</span>
+        </InfoRow>
+        <InfoRow label="创建于">
+          <span title={new Date(sandbox.createdAt).toLocaleString()}>
+            {since(sandbox.createdAt)}前
+          </span>
+        </InfoRow>
+        <InfoRow label="最近活动">{since(sandbox.lastActiveAt)}前</InfoRow>
+      </dl>
+    </RailCard>
+  );
+}
+
+export function MonitorRail({ sandbox }: { sandbox: Sandbox }) {
+  return (
+    <div className="flex h-full min-h-0 flex-col gap-3 overflow-y-auto bg-background/40 p-3">
+      <LifecycleCard sandbox={sandbox} />
+      <VitalsSection sandbox={sandbox} />
+      <ProcessesCard sandbox={sandbox} />
+      <ActivityCard sandbox={sandbox} />
+      <InfoCard sandbox={sandbox} />
+    </div>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx b/packages/console/src/features/sandboxes/components/workbench/TerminalPane.tsx
similarity index 54%
rename from packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
rename to packages/console/src/features/sandboxes/components/workbench/TerminalPane.tsx
index e44a372..7e003f4 100644
--- a/packages/console/src/features/sandboxes/components/SandboxTerminal.tsx
+++ b/packages/console/src/features/sandboxes/components/workbench/TerminalPane.tsx
@@ -1,23 +1,26 @@
+import type { Sandbox } from '@dormice/shared';
+import { ComputerTerminal01Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
 import { FitAddon } from '@xterm/addon-fit';
 import { Terminal } from '@xterm/xterm';
 import { useEffect, useRef, useState } from 'react';
 import { Button } from '@/components/ui/button';
 import {
-  Card,
-  CardAction,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from '@/components/ui/card';
+  Empty,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@/components/ui/empty';
 import { mintEnvdToken } from '@/lib/api';
-import { openPty, type PtySession } from '../envd-pty';
+import { openPty, type PtySession } from '../../envd-pty';
 import '@xterm/xterm/css/xterm.css';
 
 /**
  * One live terminal: an xterm bound to a PTY session in the sandbox. The
  * whole session lives inside the effect — unmounting kills the shell, so
- * navigating away never strands a bash in the process table.
+ * navigating away never strands a bash in the process table. The container
+ * fills its pane; the ResizeObserver refits on pane drag.
  */
 function LiveTerminal({ sandboxId }: { sandboxId: string }) {
   const containerRef = useRef<HTMLDivElement | null>(null);
@@ -77,14 +80,14 @@ function LiveTerminal({ sandboxId }: { sandboxId: string }) {
   }, [sandboxId, generation]);
 
   return (
-    <div className="flex flex-col gap-2">
+    <div className="flex h-full min-h-0 flex-col gap-2">
       <div
         ref={containerRef}
         // select-text:全局 select-none 下终端输出必须仍可选中复制。
-        className="h-80 w-full select-text overflow-hidden rounded-md bg-black p-2"
+        className="min-h-0 w-full flex-1 select-text overflow-hidden rounded-md bg-black p-2"
       />
       {closedReason && (
-        <div className="flex items-center justify-between rounded-md border px-3 py-2 text-sm text-muted-foreground">
+        <div className="flex shrink-0 items-center justify-between rounded-md border px-3 py-2 text-sm text-muted-foreground">
           <span>{closedReason}</span>
           <Button
             variant="outline"
@@ -103,36 +106,54 @@ function LiveTerminal({ sandboxId }: { sandboxId: string }) {
 }
 
 /**
- * The terminal lives behind an explicit click: opening one starts a bash,
- * which wakes a frozen sandbox — and merely looking at a detail page must
- * never thaw anything.
+ * 工作台的终端窗格。shell 活在显式点击后面:打开 bash 会唤醒冻结的
+ * 沙箱、重置空闲计时 — 所以哪怕沙箱正 active 也不偷跑,"看工作台"
+ * 绝不解冻、绝不续命。断开 = 卸载 LiveTerminal(effect cleanup 杀 shell,
+ * 不在进程表留孤儿)。
  */
-export function SandboxTerminalCard({ sandboxId }: { sandboxId: string }) {
-  const [open, setOpen] = useState(false);
+export function TerminalPane({ sandbox }: { sandbox: Sandbox }) {
+  const [connected, setConnected] = useState(false);
 
   return (
-    <Card>
-      <CardHeader>
-        <CardTitle>终端</CardTitle>
-        <CardDescription>
-          沙箱里的交互式 bash — 打开会唤醒沉睡的沙箱,关掉后空闲倒计时
-          恢复。看这一页本身不会解冻任何东西。
-        </CardDescription>
-        <CardAction>
+    <div className="flex h-full min-h-0 flex-col">
+      <div className="flex shrink-0 items-center justify-between gap-2 border-b px-3 py-1.5">
+        <span className="text-sm font-medium">终端</span>
+        <div className="flex items-center gap-2">
+          <span className="hidden text-xs text-muted-foreground sm:inline">
+            打开会唤醒沉睡的沙箱,关掉后空闲倒计时恢复
+          </span>
           <Button
             variant="outline"
             size="sm"
-            onClick={() => setOpen((value) => !value)}
+            className="h-6 px-2 text-xs"
+            onClick={() => setConnected((value) => !value)}
           >
-            {open ? '关闭终端' : '打开终端'}
+            {connected ? '断开' : '连接终端'}
           </Button>
-        </CardAction>
-      </CardHeader>
-      {open && (
-        <CardContent>
-          <LiveTerminal sandboxId={sandboxId} />
-        </CardContent>
+        </div>
+      </div>
+      {connected ? (
+        <div className="min-h-0 flex-1 p-2">
+          <LiveTerminal sandboxId={sandbox.id} />
+        </div>
+      ) : (
+        <div className="flex min-h-0 flex-1 items-center justify-center p-4">
+          <Empty>
+            <EmptyHeader>
+              <EmptyMedia variant="icon">
+                <HugeiconsIcon icon={ComputerTerminal01Icon} />
+              </EmptyMedia>
+              <EmptyTitle>沙箱里的交互式 bash</EmptyTitle>
+              <EmptyDescription>
+                连接会唤醒沉睡的沙箱 — 看工作台本身不会解冻任何东西。
+              </EmptyDescription>
+            </EmptyHeader>
+            <Button size="sm" onClick={() => setConnected(true)}>
+              连接终端
+            </Button>
+          </Empty>
+        </div>
       )}
-    </Card>
+    </div>
   );
 }
diff --git a/packages/console/src/features/sandboxes/components/workbench/file-dialogs.tsx b/packages/console/src/features/sandboxes/components/workbench/file-dialogs.tsx
new file mode 100644
index 0000000..29a6b9b
--- /dev/null
+++ b/packages/console/src/features/sandboxes/components/workbench/file-dialogs.tsx
@@ -0,0 +1,207 @@
+import { useEffect, useState } from 'react';
+import { toast } from 'sonner';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@/components/ui/alert-dialog';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import type { EnvdEntry } from '../../envd-client';
+import type { useFileMutations } from '../../hooks/useEnvd';
+
+/**
+ * 文件树的三个弹窗:新建文件夹 / 重命名 / 删除。受控哑组件 — mutation
+ * 由树传入(树才持有 envd auth),成功路径回调回树,让树收敛选中/展开
+ * 状态。重命名的目标目录从 entry.path 自己算 dirname,不依赖"当前
+ * 路径"概念(树没有单一当前路径,只有焦点目录)。
+ */
+type Mutations = ReturnType<typeof useFileMutations>;
+
+function dirnameOf(path: string): string {
+  return path.slice(0, path.lastIndexOf('/'));
+}
+
+export function MkdirDialog({
+  open,
+  onOpenChange,
+  dir,
+  mkdir,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** 新文件夹落在哪:树的焦点目录。 */
+  dir: string;
+  mkdir: Mutations['mkdir'];
+}) {
+  const [name, setName] = useState('');
+  useEffect(() => {
+    if (open) setName('');
+  }, [open]);
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-sm">
+        <DialogHeader>
+          <DialogTitle>新建文件夹</DialogTitle>
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            mkdir.mutate(`${dir}/${name}`, {
+              onSuccess: () => onOpenChange(false),
+              onError: (error) => toast.error(error.message),
+            });
+          }}
+        >
+          <Input
+            autoFocus
+            value={name}
+            onChange={(event) => setName(event.target.value)}
+            placeholder="文件夹名"
+            className="font-mono"
+          />
+          <DialogFooter className="mt-4">
+            <Button type="submit" disabled={name === '' || mkdir.isPending}>
+              {mkdir.isPending && <Spinner />}
+              创建
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export function RenameDialog({
+  entry,
+  onClose,
+  move,
+  onRenamed,
+}: {
+  /** 正在重命名的条目;null = 关闭。 */
+  entry: EnvdEntry | null;
+  onClose: () => void;
+  move: Mutations['move'];
+  onRenamed: (source: string, destination: string) => void;
+}) {
+  const [renameTo, setRenameTo] = useState('');
+  useEffect(() => {
+    if (entry) setRenameTo(entry.name);
+  }, [entry]);
+
+  return (
+    <Dialog
+      open={entry !== null}
+      onOpenChange={(open) => {
+        if (!open) onClose();
+      }}
+    >
+      <DialogContent className="sm:max-w-sm">
+        <DialogHeader>
+          <DialogTitle>重命名「{entry?.name}」</DialogTitle>
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            if (!entry) return;
+            const destination = `${dirnameOf(entry.path)}/${renameTo}`;
+            move.mutate(
+              { source: entry.path, destination },
+              {
+                onSuccess: () => {
+                  onRenamed(entry.path, destination);
+                  onClose();
+                },
+                onError: (error) => toast.error(error.message),
+              },
+            );
+          }}
+        >
+          <Input
+            autoFocus
+            value={renameTo}
+            onChange={(event) => setRenameTo(event.target.value)}
+            className="font-mono"
+          />
+          <DialogFooter className="mt-4">
+            <Button
+              type="submit"
+              disabled={
+                renameTo === '' || renameTo === entry?.name || move.isPending
+              }
+            >
+              {move.isPending && <Spinner />}
+              重命名
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export function DeleteDialog({
+  entry,
+  onClose,
+  remove,
+  onDeleted,
+}: {
+  /** 正在删除的条目;null = 关闭。 */
+  entry: EnvdEntry | null;
+  onClose: () => void;
+  remove: Mutations['remove'];
+  onDeleted: (path: string) => void;
+}) {
+  return (
+    <AlertDialog
+      open={entry !== null}
+      onOpenChange={(open) => {
+        if (!open) onClose();
+      }}
+    >
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>删除「{entry?.name}」?</AlertDialogTitle>
+          <AlertDialogDescription>
+            {entry?.type === 'FILE_TYPE_DIRECTORY'
+              ? '整个目录连同里面的一切一起删除,'
+              : ''}
+            删了就没有了 — 沙箱里没有回收站。
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>先留着</AlertDialogCancel>
+          <AlertDialogAction
+            variant="destructive"
+            onClick={() => {
+              if (!entry) return;
+              remove.mutate(entry.path, {
+                onSuccess: () => {
+                  onDeleted(entry.path);
+                  onClose();
+                },
+                onError: (error) => toast.error(error.message),
+              });
+            }}
+          >
+            删除
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index cb0751d..78f08c0 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -1,13 +1,6 @@
-import {
-  Link,
-  useNavigate,
-  useParams,
-  useSearch,
-} from '@tanstack/react-router';
-import type { ReactNode } from 'react';
-import { Badge } from '@/components/ui/badge';
+import { Link, useNavigate, useParams } from '@tanstack/react-router';
+import { useState } from 'react';
 import { Button } from '@/components/ui/button';
-import { Card, CardContent } from '@/components/ui/card';
 import {
   Empty,
   EmptyContent,
@@ -15,54 +8,46 @@ import {
   EmptyHeader,
   EmptyTitle,
 } from '@/components/ui/empty';
-import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from '@/components/ui/resizable';
+import { useIsMobile } from '@/hooks/use-mobile';
 import { DestroySandboxButton } from '../components/DestroySandboxButton';
 import { EditPolicyDialog } from '../components/EditPolicyDialog';
-import { FilesPanel } from '../components/FilesPanel';
-import { HistoryPanel } from '../components/HistoryPanel';
 import { LifecycleCountdown } from '../components/LifecycleCountdown';
-import { MetricsPanel } from '../components/MetricsPanel';
-import { ProcessesPanel } from '../components/ProcessesPanel';
 import { RebuildSandboxButton } from '../components/RebuildSandboxButton';
 import { RestoreCard } from '../components/RestoreCard';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
-import { SandboxTerminalCard } from '../components/SandboxTerminal';
-import { UpgradableBadge } from '../components/UpgradableBadge';
-import { formatDuration, since } from '../format';
-import { useSandbox, useSandboxImages } from '../hooks/useSandboxes';
-
-export const DETAIL_TABS = [
-  'overview',
-  'terminal',
-  'files',
-  'processes',
-  'metrics',
-  'history',
-] as const;
-export type DetailTab = (typeof DETAIL_TABS)[number];
-
-function Row({ label, children }: { label: string; children: ReactNode }) {
-  return (
-    <div className="flex items-baseline justify-between gap-6 border-b py-3 text-sm last:border-b-0">
-      <dt className="shrink-0 text-muted-foreground">{label}</dt>
-      <dd className="truncate text-right font-mono">{children}</dd>
-    </div>
-  );
-}
+import { FilePreviewPane } from '../components/workbench/FilePreviewPane';
+import { FileTreePane } from '../components/workbench/FileTreePane';
+import { MonitorRail } from '../components/workbench/MonitorRail';
+import { TerminalPane } from '../components/workbench/TerminalPane';
+import type { EnvdEntry } from '../envd-client';
+import { useSandbox } from '../hooks/useSandboxes';
 
 /**
- * 一个沙箱的工作区。基础信息仍从 2 秒轮询的列表缓存里选(列表是 daemon
- * 唯一的读,不发明第二个端点);文件/进程/终端走 envd 面 — 与官方 e2b
- * SDK 同一条 wire。tab 记在 URL 里,刷新与分享都停在原面板。
+ * 一个沙箱的工作台(2026-07-18 monitor 方案拍板,取代六 tab):左文件树、
+ * 中间预览+终端竖分、右监视栏常驻 — "真电脑"的样子,观察面不再藏进
+ * tab。基础信息仍从 2 秒轮询的列表缓存里选(列表是 daemon 唯一的读,
+ * 不发明第二个端点);文件/进程/终端走 envd 面 — 与官方 e2b SDK 同一条
+ * wire。
+ *
+ * 两条纪律撑起整个版式:
+ * - 看不解冻:右栏全是只读观察(指标/进程/活动服务端刻意不 wake),
+ *   常驻无害;文件树与终端各自把第一次使用挡在显式点击后面 — 没有
+ *   中央闸门,每个窗格自己裁决(单一裁决点)。
+ * - 工作台全宽 + 锁视口:列表页是"读",限宽利于扫读;工作台是"干活",
+ *   宽度即生产力(RULES/前端.md 容器宽度的拍板例外)。窄屏(<768px)
+ *   退化为普通纵向滚动流,可拖分栏在触屏上本来就不成立。
  */
 export function SandboxDetailPage() {
   const { name } = useParams({ from: '/_app/sandboxes/$name' });
-  const { tab } = useSearch({ from: '/_app/sandboxes/$name' });
   const navigate = useNavigate({ from: '/sandboxes/$name' });
   const { sandbox, isSuccess } = useSandbox(name);
-  // 镜像血统与列表页同一份 5 秒缓存;拿不到就不显示,不挡页面。
-  const images = useSandboxImages();
-  const lineage = images.data?.images.find((e) => e.sandboxName === name);
+  const [selected, setSelected] = useState<EnvdEntry | null>(null);
+  const isMobile = useIsMobile();
 
   if (!sandbox) {
     return isSuccess ? (
@@ -88,128 +73,98 @@ export function SandboxDetailPage() {
     ) : null;
   }
 
-  return (
-    // 工作区页:与列表页同宽限 6xl,页头随 openasi 版式(text-xl medium)。
-    <div className="mx-auto flex w-full max-w-6xl flex-col gap-4 p-4 md:p-6">
-      <header className="flex flex-wrap items-center justify-between gap-3">
-        <div className="flex items-center gap-3">
-          <h1 className="font-mono text-xl font-medium">{sandbox.name}</h1>
-          <SandboxStateBadge state={sandbox.state} />
-          <LifecycleCountdown sandbox={sandbox} />
+  const header = (
+    <header className="flex shrink-0 flex-wrap items-center justify-between gap-3">
+      <div className="flex items-center gap-3">
+        <h1 className="font-mono text-xl font-medium">{sandbox.name}</h1>
+        <SandboxStateBadge state={sandbox.state} />
+        <LifecycleCountdown sandbox={sandbox} />
+      </div>
+      <div className="flex items-center gap-2">
+        <EditPolicyDialog sandbox={sandbox} />
+        <RebuildSandboxButton name={sandbox.name} />
+        <DestroySandboxButton
+          name={sandbox.name}
+          onDestroyed={() => navigate({ to: '/sandboxes' })}
+        />
+      </div>
+    </header>
+  );
+
+  const restore = (sandbox.state === 'archived' ||
+    sandbox.state === 'restoring') && <RestoreCard sandbox={sandbox} />;
+
+  if (isMobile) {
+    // 窄屏:普通纵向滚动流,窗格装进定高框(它们全是 h-full flex-col,
+    // 装进什么高度都成立),右栏卡片自然流淌。
+    return (
+      // key=id:同名沙箱销毁重建是新的一世,选中/解锁等窗格状态全部重置。
+      <div key={sandbox.id} className="flex w-full flex-col gap-3 p-4">
+        {header}
+        {restore}
+        <div className="h-[40vh] overflow-hidden rounded-xl border bg-card">
+          <FileTreePane
+            sandbox={sandbox}
+            selected={selected}
+            onSelect={setSelected}
+          />
         </div>
-        <div className="flex items-center gap-2">
-          <EditPolicyDialog sandbox={sandbox} />
-          <RebuildSandboxButton name={sandbox.name} />
-          <DestroySandboxButton
-            name={sandbox.name}
-            onDestroyed={() => navigate({ to: '/sandboxes' })}
+        <div className="h-[50vh] overflow-hidden rounded-xl border bg-card">
+          <FilePreviewPane
+            sandbox={sandbox}
+            selected={selected}
+            onClear={() => setSelected(null)}
           />
         </div>
-      </header>
-
-      {(sandbox.state === 'archived' || sandbox.state === 'restoring') && (
-        <RestoreCard sandbox={sandbox} />
-      )}
+        <div className="h-[50vh] overflow-hidden rounded-xl border bg-card">
+          <TerminalPane sandbox={sandbox} />
+        </div>
+        <div className="overflow-hidden rounded-xl border bg-card">
+          <MonitorRail sandbox={sandbox} />
+        </div>
+      </div>
+    );
+  }
 
-      <Tabs
-        value={tab}
-        onValueChange={(next) =>
-          navigate({
-            search: { tab: next as DetailTab },
-            replace: true,
-          })
-        }
+  return (
+    <div
+      key={sandbox.id}
+      className="flex h-full min-h-0 w-full flex-col gap-3 p-4"
+    >
+      {header}
+      {restore}
+      <ResizablePanelGroup
+        orientation="horizontal"
+        className="min-h-0 flex-1 overflow-hidden rounded-xl border bg-card"
       >
-        <TabsList>
-          <TabsTrigger value="overview">概览</TabsTrigger>
-          <TabsTrigger value="terminal">终端</TabsTrigger>
-          <TabsTrigger value="files">文件</TabsTrigger>
-          <TabsTrigger value="processes">进程</TabsTrigger>
-          <TabsTrigger value="metrics">指标</TabsTrigger>
-          <TabsTrigger value="history">历史</TabsTrigger>
-        </TabsList>
-
-        <TabsContent value="overview">
-          <Card>
-            <CardContent>
-              <dl>
-                <Row label="沙箱 ID">{sandbox.id}</Row>
-                <Row label="模板">
-                  <span className="inline-flex items-center gap-1.5">
-                    {sandbox.template ?? '基础镜像'}
-                    <UpgradableBadge lineage={lineage} />
-                  </span>
-                </Row>
-                {lineage && (
-                  <Row label="镜像">
-                    {lineage.image === null
-                      ? `无容器 — 下次启动用 ${lineage.nextImage}`
-                      : lineage.upgradable
-                        ? `${lineage.image} → Rebuild 后 ${lineage.nextImage}`
-                        : lineage.image}
-                  </Row>
-                )}
-                {Object.keys(sandbox.metadata).length > 0 && (
-                  <Row label="标签">
-                    <span className="inline-flex flex-wrap justify-end gap-1">
-                      {Object.entries(sandbox.metadata).map(([key, value]) => (
-                        <Badge
-                          key={key}
-                          variant="outline"
-                          className="max-w-[14rem] truncate font-mono text-xs font-normal text-muted-foreground"
-                          title={`${key}=${value}`}
-                        >
-                          {key}={value}
-                        </Badge>
-                      ))}
-                    </span>
-                  </Row>
-                )}
-                <Row label="节点">{sandbox.nodeId}</Row>
-                <Row label="端点">{sandbox.endpoint}</Row>
-                <Row label="创建于">
-                  {new Date(sandbox.createdAt).toLocaleString()} ·{' '}
-                  {since(sandbox.createdAt)}前
-                </Row>
-                <Row label="最近活动">{since(sandbox.lastActiveAt)}前</Row>
-                <Row label="冻结阈值">
-                  空闲 {formatDuration(sandbox.policy.freezeAfterSeconds)}
-                </Row>
-                <Row label="停止阈值">
-                  {sandbox.policy.stopAfterSeconds === null
-                    ? '永不(常驻 agent)'
-                    : `空闲 ${formatDuration(sandbox.policy.stopAfterSeconds)}`}
-                </Row>
-                <Row label="归档阈值">
-                  {sandbox.policy.archiveAfterSeconds === null
-                    ? '永不'
-                    : `空闲 ${formatDuration(sandbox.policy.archiveAfterSeconds)}`}
-                </Row>
-              </dl>
-            </CardContent>
-          </Card>
-        </TabsContent>
-
-        <TabsContent value="terminal">
-          <SandboxTerminalCard sandboxId={sandbox.id} />
-        </TabsContent>
-
-        <TabsContent value="files">
-          <FilesPanel sandbox={sandbox} />
-        </TabsContent>
-
-        <TabsContent value="processes">
-          <ProcessesPanel sandbox={sandbox} />
-        </TabsContent>
-
-        <TabsContent value="metrics">
-          <MetricsPanel sandbox={sandbox} />
-        </TabsContent>
-
-        <TabsContent value="history">
-          <HistoryPanel name={sandbox.name} />
-        </TabsContent>
-      </Tabs>
+        <ResizablePanel defaultSize={17} minSize={12}>
+          <FileTreePane
+            sandbox={sandbox}
+            selected={selected}
+            onSelect={setSelected}
+          />
+        </ResizablePanel>
+        <ResizableHandle />
+        <ResizablePanel defaultSize={56} minSize={30}>
+          <ResizablePanelGroup orientation="vertical">
+            <ResizablePanel defaultSize={56} minSize={20}>
+              <FilePreviewPane
+                sandbox={sandbox}
+                selected={selected}
+                onClear={() => setSelected(null)}
+              />
+            </ResizablePanel>
+            <ResizableHandle />
+            <ResizablePanel defaultSize={44} minSize={20}>
+              <TerminalPane sandbox={sandbox} />
+            </ResizablePanel>
+          </ResizablePanelGroup>
+        </ResizablePanel>
+        <ResizableHandle />
+        <ResizablePanel defaultSize={27} minSize={20}>
+          <MonitorRail sandbox={sandbox} />
+        </ResizablePanel>
+      </ResizablePanelGroup>
     </div>
   );
 }
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index 0973892..4f9e54a 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -526,7 +526,6 @@ export function SandboxesPage() {
                   <Link
                     to="/sandboxes/$name"
                     params={{ name: sandbox.name }}
-                    search={{ tab: 'overview' }}
                     className="font-mono font-medium hover:underline"
                   >
                     {sandbox.name}
diff --git a/packages/console/src/routes/_app/activity.tsx b/packages/console/src/routes/_app/activity.tsx
index a69a966..34ace34 100644
--- a/packages/console/src/routes/_app/activity.tsx
+++ b/packages/console/src/routes/_app/activity.tsx
@@ -1,6 +1,15 @@
 import { createFileRoute } from '@tanstack/react-router';
 import { ActivityPage } from '@/features/activity/pages/ActivityPage';
 
+/**
+ * 可选的 `?sandbox=`:沙箱工作台的「查看全部活动」带着名字跳过来,
+ * 落地即预筛。只做一次性种子(灌进页内搜索框的初值),此后搜索框归
+ * 用户 — 不做双向同步。
+ */
 export const Route = createFileRoute('/_app/activity')({
+  validateSearch: (search: Record<string, unknown>): { sandbox?: string } =>
+    typeof search.sandbox === 'string' && search.sandbox !== ''
+      ? { sandbox: search.sandbox }
+      : {},
   component: ActivityPage,
 });
diff --git a/packages/console/src/routes/_app/sandboxes/$name.tsx b/packages/console/src/routes/_app/sandboxes/$name.tsx
index 928aed2..74dfeea 100644
--- a/packages/console/src/routes/_app/sandboxes/$name.tsx
+++ b/packages/console/src/routes/_app/sandboxes/$name.tsx
@@ -1,16 +1,7 @@
 import { createFileRoute } from '@tanstack/react-router';
-import {
-  DETAIL_TABS,
-  type DetailTab,
-  SandboxDetailPage,
-} from '@/features/sandboxes/pages/SandboxDetailPage';
+import { SandboxDetailPage } from '@/features/sandboxes/pages/SandboxDetailPage';
 
-// tab 进 URL:刷新、分享、返回键都停在同一个工作区面板上。
+// 工作台没有 tab,也就没有 search 参数(旧 ?tab= 链接被无害忽略)。
 export const Route = createFileRoute('/_app/sandboxes/$name')({
-  validateSearch: (search: Record<string, unknown>): { tab: DetailTab } => ({
-    tab: DETAIL_TABS.includes(search.tab as DetailTab)
-      ? (search.tab as DetailTab)
-      : 'overview',
-  }),
   component: SandboxDetailPage,
 });
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
index f7e2b29..6c41855 100644
--- a/website/content/docs/console.mdx
+++ b/website/content/docs/console.mdx
@@ -50,28 +50,31 @@ template dropdown when templates are registered. After a
 running the old image carry an "upgradable" marker next to their
 template name — rebuild them to move.
 
-A sandbox's detail page is a workspace:
-
-- **Overview** — identity, policy thresholds with a countdown to the
-  next lifecycle step, last activity; an adjust-policy dialog (the
-  console's face of
-  [`updatePolicy`](/docs/lifecycle#change-the-policy-later)), plus
-  destroy and [rebuild](/docs/persistence#rebuild-a-sandbox) buttons,
+A sandbox's detail page is a workbench laid out like a machine you're
+sitting at — file tree on the left, file preview and terminal in the
+middle, and a monitor rail on the right, with draggable dividers:
+
+- **Header** — identity, state, a countdown to the next lifecycle
+  step, and the action buttons: an adjust-policy dialog (the console's
+  face of [`updatePolicy`](/docs/lifecycle#change-the-policy-later)),
+  plus destroy and [rebuild](/docs/persistence#rebuild-a-sandbox),
   each behind a confirmation dialog.
-- **Terminal** — a real interactive shell, kept behind an explicit
-  "open" button because opening one *wakes* the sandbox. The browser
-  speaks the same wire the official E2B SDK does. Closing the terminal
-  kills its shell rather than leaving an orphan behind.
-- **Files** — browse, preview, edit, upload (drag and drop works),
-  download, rename, delete under `/home/user`, refreshing live while
-  the sandbox runs. File operations wake the sandbox too, so a cold
-  sandbox shows an explicit "open" gate first.
-- **Processes** — the E2B process table, polled without waking (a
-  stopped sandbox honestly shows none).
-- **Metrics** — the sandbox's live resource snapshot, with an
-  in-session trend chart (the browser accumulates it — the daemon
-  [keeps no history](/docs/metrics)).
-- **History** — this sandbox's recent lifecycle events.
+- **Files** — a lazy-loading tree of `/home/user`: preview and edit
+  text files inline, upload (drag and drop works), download, rename,
+  delete; the listing refreshes live while the sandbox runs. File
+  operations *wake* the sandbox, so a cold sandbox shows an explicit
+  "open" gate first — just looking at the page never thaws anything.
+- **Terminal** — a real interactive shell in the middle-bottom pane,
+  kept behind an explicit "connect" button because opening one wakes
+  the sandbox. The browser speaks the same wire the official E2B SDK
+  does. Disconnecting kills the shell rather than leaving an orphan
+  behind.
+- **Monitor rail** — always on, because everything in it observes
+  without waking: the lifecycle card, CPU/memory/disk vitals with
+  one-hour sparklines (full 1h/24h/7d trend charts from the daemon's
+  [metrics history](/docs/metrics) open in a dialog), the E2B process
+  table (a stopped sandbox honestly shows none), this sandbox's recent
+  lifecycle events, and its identity details.
 
 ## Templates
 

From 5922d3de622f5dafe101a62e6c2a9c0ae9a2aab0 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 18 Jul 2026 17:12:19 +0800
Subject: [PATCH 107/133] =?UTF-8?q?=E6=9A=82=E5=AD=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/console/vite.config.ts | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/packages/console/vite.config.ts b/packages/console/vite.config.ts
index e8ebf86..d4442c0 100644
--- a/packages/console/vite.config.ts
+++ b/packages/console/vite.config.ts
@@ -36,9 +36,18 @@ export default defineConfig({
       '/listApiKeys': 'http://127.0.0.1:3676',
       '/createApiKey': 'http://127.0.0.1:3676',
       '/revokeApiKey': 'http://127.0.0.1:3676',
+      '/updateApiKey': 'http://127.0.0.1:3676',
+      '/execCommand': 'http://127.0.0.1:3676',
+      '/writeFile': 'http://127.0.0.1:3676',
+      '/writeFiles': 'http://127.0.0.1:3676',
+      '/readFile': 'http://127.0.0.1:3676',
+      '/readFiles': 'http://127.0.0.1:3676',
       '/getHostMetrics': 'http://127.0.0.1:3676',
       '/getSandboxMetrics': 'http://127.0.0.1:3676',
+      '/getSandboxMetricsHistory': 'http://127.0.0.1:3676',
       '/listSandboxMetrics': 'http://127.0.0.1:3676',
+      '/listSandboxImages': 'http://127.0.0.1:3676',
+      '/getFleetTimeline': 'http://127.0.0.1:3676',
       '/listActivity': 'http://127.0.0.1:3676',
       '/getConfig': 'http://127.0.0.1:3676',
       '/checkUpgrade': 'http://127.0.0.1:3676',

From b33225f57685f04824924b09faf2a41ae7585283 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 18 Jul 2026 18:43:06 +0800
Subject: [PATCH 108/133] =?UTF-8?q?E2B=20=E4=B8=8B=E8=BD=BD=E9=9D=A2?=
 =?UTF-8?q?=E5=AD=A6=E4=BC=9A=E8=87=AA=E6=8A=A5=E5=AE=B6=E9=97=A8:serveFil?=
 =?UTF-8?q?eDownload=20=E4=BB=8E=E8=A3=B8=20octet-stream=20=E5=8D=87?=
 =?UTF-8?q?=E6=A0=BC=E4=B8=BA=E7=9C=9F=20envd=20=E5=90=8C=E6=AC=BE?=
 =?UTF-8?q?=E4=B8=89=E5=A4=B4=E2=80=94=E2=80=94content-type=20=E6=8C=89?=
 =?UTF-8?q?=E6=89=A9=E5=B1=95=E5=90=8D=E6=8E=A8=E7=9C=9F=E5=AE=9E=20MIME(?=
 =?UTF-8?q?=E5=86=85=E7=BD=AE=E4=B8=80=E5=BC=A0=E8=A6=86=E7=9B=96=20Office?=
 =?UTF-8?q?=20=E4=B8=89=E4=BB=B6=E5=A5=97/pdf/=E6=96=87=E6=9C=AC/=E5=9B=BE?=
 =?UTF-8?q?=E7=89=87/=E9=9F=B3=E8=A7=86=E9=A2=91/=E5=8E=8B=E7=BC=A9?=
 =?UTF-8?q?=E5=8C=85=E7=9A=84=E8=A1=A8,=E6=9C=AA=E7=9F=A5=E6=89=A9?=
 =?UTF-8?q?=E5=B1=95=E5=90=8D=E8=AF=9A=E5=AE=9E=E5=9B=9E=E9=80=80=20octet-?=
 =?UTF-8?q?stream)=E3=80=81content-disposition:=20inline;=20filename*=3Dut?=
 =?UTF-8?q?f-8''<RFC5987=20=E7=BC=96=E7=A0=81=20basename>=E3=80=81last-mod?=
 =?UTF-8?q?ified(statEntry=20=E6=9C=AC=E5=B0=B1=E5=B8=A6=20modifiedTime,?=
 =?UTF-8?q?=E7=99=BD=E6=8D=A1)=E3=80=82=E7=97=85=E6=A0=B9=E7=94=B1=20claws?=
 =?UTF-8?q?go=20=E4=BE=A7=20A/B=20=E5=AE=9E=E8=AF=81=E9=92=89=E6=AD=BB(202?=
 =?UTF-8?q?6-07-18):=E7=AD=BE=E5=90=8D=20URL=20=E7=9A=84=E6=89=A9=E5=B1=95?=
 =?UTF-8?q?=E5=90=8D=E5=9F=8B=E5=9C=A8=20query=20=E4=B8=8D=E5=9C=A8=20URL?=
 =?UTF-8?q?=20=E8=B7=AF=E5=BE=84,=E5=BE=AE=E8=BD=AF=20Office=20=E5=9C=A8?=
 =?UTF-8?q?=E7=BA=BF=E6=9F=A5=E7=9C=8B=E5=99=A8=E4=BB=8E=E8=B7=AF=E5=BE=84?=
 =?UTF-8?q?=E5=92=8C=E5=93=8D=E5=BA=94=E5=A4=B4=E9=83=BD=E5=88=A4=E4=B8=8D?=
 =?UTF-8?q?=E5=87=BA=E6=96=87=E4=BB=B6=E7=B1=BB=E5=9E=8B,=E9=A2=84?=
 =?UTF-8?q?=E6=A3=80=E7=9B=B4=E6=8E=A5=E6=8B=92=E2=80=94=E2=80=94=E5=90=8C?=
 =?UTF-8?q?=E4=B8=80=E4=BB=BD=20docx=20=E5=AD=97=E8=8A=82,=E5=A4=8D?=
 =?UTF-8?q?=E5=88=BB=20dormice=20=E5=A4=B4=E5=BD=A2=E6=80=81=E5=BF=85?=
 =?UTF-8?q?=E6=8C=82,=E6=8D=A2=E6=88=90=20envd=20=E5=90=8C=E6=AC=BE?=
 =?UTF-8?q?=E4=B8=A4=E5=A4=B4=E5=8D=B3=E6=94=BE=E8=A1=8C;=E6=98=8E?=
 =?UTF-8?q?=E6=96=87=20HTTP=E3=80=81=E5=85=AC=E7=BD=91=E5=8F=AF=E8=BE=BE?=
 =?UTF-8?q?=E6=80=A7=E3=80=81=E7=AD=BE=E5=90=8D=E6=A0=A1=E9=AA=8C=E4=B8=8E?=
 =?UTF-8?q?=E5=AD=97=E8=8A=82=E6=B5=81=E5=85=A8=E8=A2=AB=E6=8E=92=E9=99=A4?=
 =?UTF-8?q?=E3=80=82=E7=AD=BE=E5=90=8D=E4=B8=8B=E8=BD=BD=E9=9D=A2=E5=A4=8D?=
 =?UTF-8?q?=E7=94=A8=E5=90=8C=E4=B8=80=E4=B8=AA=20serveFileDownload,?=
 =?UTF-8?q?=E4=BF=AE=E4=B8=80=E5=A4=84=E4=B8=A4=E9=9D=A2=E5=8F=97=E7=9B=8A?=
 =?UTF-8?q?,=E8=BF=99=E5=90=8C=E6=97=B6=E8=A1=A5=E4=B8=8A=E5=85=BC?=
 =?UTF-8?q?=E5=AE=B9=E5=B1=82=E5=AF=B9=E7=9C=9F=20envd=20=E7=9A=84?=
 =?UTF-8?q?=E4=B8=80=E5=A4=84=E4=BF=9D=E7=9C=9F=E7=BC=BA=E5=8F=A3=E3=80=82?=
 =?UTF-8?q?=E5=88=BB=E6=84=8F=E4=B8=8D=E5=8F=91=20accept-ranges:=E7=9C=9F?=
 =?UTF-8?q?=20envd=20=E5=8F=91=E5=AE=83,=E4=BD=86=20Range=20=E8=AF=B7?=
 =?UTF-8?q?=E6=B1=82=E6=9C=AA=E5=AE=9E=E7=8E=B0,=E8=99=9A=E6=8A=A5?=
 =?UTF-8?q?=E6=94=AF=E6=8C=81=E6=98=AF=E6=92=92=E8=B0=8E=E3=80=82=E5=9B=9E?=
 =?UTF-8?q?=E5=BD=92=E9=92=89=E5=9C=A8=20compat.test:=E7=AD=BE=E5=90=8D?=
 =?UTF-8?q?=E4=B8=8B=E8=BD=BD=E3=80=8C=E6=96=87=E6=A1=A3=20report.docx?=
 =?UTF-8?q?=E3=80=8D=E6=96=AD=E8=A8=80=20Office=20=E7=9C=9F=20MIME=20?=
 =?UTF-8?q?=E4=B8=8E=20RFC=205987=20=E7=BC=96=E7=A0=81(=E4=B8=AD=E6=96=87?=
 =?UTF-8?q?=E4=B8=8E=E7=A9=BA=E6=A0=BC=E9=83=BD=E8=BF=87),.weird=20?=
 =?UTF-8?q?=E6=96=AD=E8=A8=80=E8=AF=9A=E5=AE=9E=E5=9B=9E=E9=80=80;envd=20?=
 =?UTF-8?q?=E9=9D=A2=20round-trip=20=E5=8A=A0=20txt=20=E7=9A=84=E4=B8=A4?=
 =?UTF-8?q?=E5=A4=B4=E6=96=AD=E8=A8=80=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/server/src/e2b/compat.test.ts | 37 ++++++++++++++
 packages/server/src/e2b/envd/files.ts  | 68 +++++++++++++++++++++++++-
 2 files changed, 104 insertions(+), 1 deletion(-)

diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 851cddb..57563a2 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -783,6 +783,10 @@ describe('E2B envd surface', () => {
     });
     expect(down.statusCode).toBe(200);
     expect(down.headers['content-length']).toBe(String(content.length));
+    expect(down.headers['content-type']).toBe('text/plain; charset=utf-8');
+    expect(down.headers['content-disposition']).toBe(
+      "inline; filename*=utf-8''up.txt",
+    );
     expect(down.body).toBe(content);
 
     const missing = await t.app.inject({
@@ -1636,6 +1640,39 @@ describe('signed file URLs at the daemon root', () => {
     expect(fromB.body).toBe('contents of B\n');
   });
 
+  it('downloads name the true MIME and filename — the extension lives in the query, so headers are all a preflight can read', async () => {
+    // Microsoft's Office online viewer rejects a signed docx URL served as
+    // bare octet-stream (measured 2026-07-18); real envd's typed
+    // content-type + disposition filename are what let it through.
+    const t = testApp();
+    const { sandboxID, envdAccessToken } = await createSandbox(t);
+    await putFile(t, sandboxID, '文档 report.docx', 'not really a docx');
+    await putFile(t, sandboxID, 'blob.weird', 'bytes');
+
+    const fetchSigned = (path: string) => {
+      const sig = sdkSignature({ path, operation: 'read', envdAccessToken });
+      return t.app.inject({
+        method: 'GET',
+        url: `/files?path=${encodeURIComponent(path)}&signature=${encodeURIComponent(sig)}`,
+      });
+    };
+
+    const docx = await fetchSigned('文档 report.docx');
+    expect(docx.statusCode).toBe(200);
+    expect(docx.headers['content-type']).toBe(
+      'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    );
+    // RFC 5987: non-ASCII percent-encoded, the space included.
+    expect(docx.headers['content-disposition']).toBe(
+      "inline; filename*=utf-8''%E6%96%87%E6%A1%A3%20report.docx",
+    );
+    expect(docx.headers['last-modified']).toMatch(/GMT$/);
+
+    const weird = await fetchSigned('blob.weird');
+    expect(weird.statusCode).toBe(200);
+    expect(weird.headers['content-type']).toBe('application/octet-stream');
+  });
+
   it('signed uploads: multipart carries the path in the filename, octet-stream in the query', async () => {
     const t = testApp();
     const { sandboxID, envdAccessToken } = await createSandbox(t);
diff --git a/packages/server/src/e2b/envd/files.ts b/packages/server/src/e2b/envd/files.ts
index 06353ad..37d5749 100644
--- a/packages/server/src/e2b/envd/files.ts
+++ b/packages/server/src/e2b/envd/files.ts
@@ -37,6 +37,68 @@ export function registerFileRoutes(
   );
 }
 
+/**
+ * Extension → MIME for the download face. Real envd serves the true type
+ * (Go's mime.TypeByExtension) plus a content-disposition filename; a bare
+ * octet-stream breaks consumers that read the type from headers — the
+ * signed URL keeps the path in the query, so Microsoft's Office online
+ * viewer sees neither a path extension nor a usable header and rejects
+ * docx/xlsx/pptx at preflight (A/B-measured against real envd 2026-07-18:
+ * these two headers alone flip the verdict). Unknown extensions honestly
+ * fall back to octet-stream.
+ */
+const MIME_BY_EXTENSION: Record<string, string> = {
+  txt: 'text/plain; charset=utf-8',
+  md: 'text/markdown; charset=utf-8',
+  csv: 'text/csv; charset=utf-8',
+  html: 'text/html; charset=utf-8',
+  htm: 'text/html; charset=utf-8',
+  css: 'text/css; charset=utf-8',
+  js: 'text/javascript; charset=utf-8',
+  mjs: 'text/javascript; charset=utf-8',
+  json: 'application/json',
+  xml: 'text/xml; charset=utf-8',
+  pdf: 'application/pdf',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+  webp: 'image/webp',
+  ico: 'image/x-icon',
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  zip: 'application/zip',
+  gz: 'application/gzip',
+  tar: 'application/x-tar',
+  wasm: 'application/wasm',
+};
+
+function contentTypeOf(name: string): string {
+  const dot = name.lastIndexOf('.');
+  const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : '';
+  return MIME_BY_EXTENSION[ext] ?? 'application/octet-stream';
+}
+
+/**
+ * RFC 5987 ext-value for the content-disposition filename.
+ * encodeURIComponent leaves `'()*` bare, but they are not attr-chars.
+ */
+function rfc5987(name: string): string {
+  return encodeURIComponent(name).replace(
+    /['()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
 export async function serveFileDownload(
   ctx: EnvdContext,
   sandboxId: string,
@@ -72,9 +134,13 @@ export async function serveFileDownload(
     // Size first, then stream: the SDK needs content-length (an empty
     // file is detected by `content-length: 0`), and nothing buffers here.
     reply.hijack();
+    // No accept-ranges here although real envd sends it: Range requests
+    // are not honored, and advertising bytes we won't serve is a lie.
     reply.raw.writeHead(200, {
-      'content-type': 'application/octet-stream',
+      'content-type': contentTypeOf(entry.name),
+      'content-disposition': `inline; filename*=utf-8''${rfc5987(entry.name)}`,
       'content-length': String(entry.sizeBytes),
+      'last-modified': new Date(entry.modifiedTime).toUTCString(),
     });
     await executor.readFileStream(
       row.id,

From e717634bef6fabb1d7492929c65dbe7a22d93e10 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sat, 18 Jul 2026 19:49:24 +0800
Subject: [PATCH 109/133] =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8F=B0=E9=A2=84?=
 =?UTF-8?q?=E8=A7=88=E7=AA=97=E6=A0=BC=E5=AD=A6=E4=BC=9A=E6=8C=89=E7=B1=BB?=
 =?UTF-8?q?=E5=9E=8B=E7=9C=8B=E6=96=87=E4=BB=B6:=E9=9D=9E=E6=96=87?=
 =?UTF-8?q?=E6=9C=AC=E4=B8=8D=E5=86=8D=E4=B8=80=E5=BE=8B"=E4=BA=8C?=
 =?UTF-8?q?=E8=BF=9B=E5=88=B6,=E6=B2=A1=E6=B3=95=E5=BD=93=E6=96=87?=
 =?UTF-8?q?=E6=9C=AC=E7=9C=8B"=E3=80=82=E6=96=B0=E5=BB=BA=20preview.ts=20?=
 =?UTF-8?q?=E4=BD=9C=E6=89=A9=E5=B1=95=E5=90=8D=E2=86=92=E5=BD=A2=E6=80=81?=
 =?UTF-8?q?=E7=9A=84=E5=94=AF=E4=B8=80=E8=A3=81=E5=86=B3=E7=82=B9(?=
 =?UTF-8?q?=E7=BB=84=E4=BB=B6=E7=A6=81=E6=AD=A2=E5=90=84=E8=87=AA=20endsWi?=
 =?UTF-8?q?th;=E6=9C=8D=E5=8A=A1=E7=AB=AF=20MIME=20=E8=A1=A8=E6=98=AF?=
 =?UTF-8?q?=E5=8F=82=E7=85=A7=E4=B8=8D=20import)=E3=80=82=E5=9B=BE?=
 =?UTF-8?q?=E7=89=87=E4=B8=8E=20PDF=20=E8=B5=B0=E5=8E=9F=E6=9C=89=20header?=
 =?UTF-8?q?=20=E8=AE=A4=E8=AF=81=E4=B8=8B=E8=BD=BD=E6=88=90=20Blob=20?=
 =?UTF-8?q?=E2=86=92=20object=20URL=20=E5=B0=B1=E5=9C=B0=E6=B8=B2=E6=9F=93?=
 =?UTF-8?q?=E2=80=94=E2=80=94=E5=90=8C=E6=BA=90=E3=80=81=E6=98=8E=E6=96=87?=
 =?UTF-8?q?=20HTTP=20=E7=9A=84=20IP=20=E8=AE=BF=E9=97=AE=E4=B9=9F=E8=83=BD?=
 =?UTF-8?q?=E7=94=A8,=E4=B8=8D=E7=A2=B0=E7=AD=BE=E5=90=8D;PDF=20=E4=BA=A4?=
 =?UTF-8?q?=E7=BB=99=E6=B5=8F=E8=A7=88=E5=99=A8=E5=86=85=E7=BD=AE=E6=9F=A5?=
 =?UTF-8?q?=E7=9C=8B=E5=99=A8=E4=B8=94=E5=88=BB=E6=84=8F=E4=B8=8D=20sandbo?=
 =?UTF-8?q?x(Chrome=20=E7=9A=84=20PDF=20=E6=8F=92=E4=BB=B6=E4=B8=8E=20sand?=
 =?UTF-8?q?boxed=20iframe=20=E4=BA=92=E6=96=A5,=E8=80=8C=20blob=20?=
 =?UTF-8?q?=E7=B1=BB=E5=9E=8B=E5=87=BA=E8=87=AA=E8=87=AA=E5=AE=B6=20MIME?=
 =?UTF-8?q?=20=E8=A1=A8=E6=97=A0=E5=8D=87=E6=A0=BC=E8=B7=AF=E5=BE=84),svg?=
 =?UTF-8?q?=20=E6=B0=B8=E8=BF=9C=20<img>(=E8=A7=84=E8=8C=83=E4=BF=9D?=
 =?UTF-8?q?=E8=AF=81=E4=B8=8D=E6=89=A7=E8=A1=8C=E8=84=9A=E6=9C=AC,?=
 =?UTF-8?q?=E4=B8=8D=E7=BB=99=E6=B2=99=E7=AE=B1=E6=96=87=E4=BB=B6=E5=BC=80?=
 =?UTF-8?q?=E5=8F=A3=E5=AD=90);object=20URL=20=E7=9A=84=E5=88=9B=E5=BB=BA?=
 =?UTF-8?q?=E4=B8=8E=E6=92=A4=E9=94=80=E6=88=90=E5=AF=B9=E4=BD=8F=E5=9C=A8?=
 =?UTF-8?q?=E5=90=8C=E4=B8=80=E4=B8=AA=20effect,StrictMode=20=E5=8F=8C?=
 =?UTF-8?q?=E8=B7=91=E5=AE=89=E5=85=A8,=E7=BB=9D=E4=B8=8D=E6=8C=AA?=
 =?UTF-8?q?=E8=BF=9B=20queryFn=E2=80=94=E2=80=94gcTime=200=20=E7=9A=84?=
 =?UTF-8?q?=E7=BC=93=E5=AD=98=E6=97=A0=E6=B7=98=E6=B1=B0=E5=9B=9E=E8=B0=83?=
 =?UTF-8?q?,=E6=92=A4=E9=94=80=E6=97=A0=E4=B8=BB=E5=BF=85=E6=BC=8F?=
 =?UTF-8?q?=E3=80=82Office=20=E4=B8=89=E4=BB=B6=E5=A5=97(=E5=90=AB?=
 =?UTF-8?q?=E6=97=A7=E7=89=88=20doc/xls/ppt,=E5=BE=AE=E8=BD=AF=E6=9F=A5?=
 =?UTF-8?q?=E7=9C=8B=E5=99=A8=E5=8E=9F=E7=94=9F=E6=94=AF=E6=8C=81)?=
 =?UTF-8?q?=E8=B5=B0=E5=8F=A6=E4=B8=80=E6=9D=A1=E8=B7=AF:=E6=98=BE?=
 =?UTF-8?q?=E5=BC=8F=E7=82=B9=E5=87=BB=E5=90=8E=E6=B5=8F=E8=A7=88=E5=99=A8?=
 =?UTF-8?q?=E7=94=A8=E5=B7=B2=E6=8C=81=E6=9C=89=E7=9A=84=20envdAccessToken?=
 =?UTF-8?q?=20=E5=A4=8D=E7=AE=97=E7=AD=BE=E5=90=8D=E7=9B=B4=E9=93=BE(envd-?=
 =?UTF-8?q?client=20=E6=96=B0=E5=A2=9E=20signedDownloadUrl,=E5=85=AC?=
 =?UTF-8?q?=E5=BC=8F=E4=B8=8E=20server=20signing.ts=20=E9=80=90=E5=AD=97?=
 =?UTF-8?q?=E5=AF=B9=E9=BD=90;username=20=E9=99=B7=E9=98=B1=E4=B8=A4?=
 =?UTF-8?q?=E5=A4=B4=E5=8F=AA=E8=83=BD=E7=BC=BA=E5=B8=AD=E2=80=94=E2=80=94?=
 =?UTF-8?q?query=20=E5=B8=A6=E7=A9=BA=E4=B8=B2=E8=A2=AB=20vetUsername=20?=
 =?UTF-8?q?=E6=89=93=E5=9B=9E,=E5=B8=A6=20user=20=E5=88=99=E6=9D=90?=
 =?UTF-8?q?=E6=96=99=E5=AF=B9=E4=B8=8D=E4=B8=8A),15=20=E5=88=86=E9=92=9F?=
 =?UTF-8?q?=E6=97=B6=E6=95=88=E6=AF=8F=E6=AC=A1=E7=82=B9=E5=87=BB=E9=87=8D?=
 =?UTF-8?q?=E9=93=B8,=E5=B5=8C=20view.officeapps.live.com=20=E7=9A=84=20em?=
 =?UTF-8?q?bed.aspx=20iframe(sandbox=20=E7=99=BD=E5=90=8D=E5=8D=95+no-refe?=
 =?UTF-8?q?rrer=20=E6=94=B6=E6=9D=83)=E3=80=82=E5=A4=96=E5=8F=91=E5=BF=85?=
 =?UTF-8?q?=E9=A1=BB=E7=9F=A5=E6=83=85:=E7=82=B9=E5=87=BB=E5=89=8D?=
 =?UTF-8?q?=E4=B8=AD=E6=96=87=E6=8A=AB=E9=9C=B2"=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E5=86=85=E5=AE=B9=E4=BC=9A=E7=A6=BB=E5=BC=80=E6=9C=AC=E6=9C=BA?=
 =?UTF-8?q?",=E6=98=8E=E6=96=87=20HTTP=20=E7=BB=99"=E6=94=B9=E8=B5=B0=20HT?=
 =?UTF-8?q?TPS=20=E5=9F=9F=E5=90=8D"=E7=9A=84=E8=AF=9A=E5=AE=9E=E6=8F=90?=
 =?UTF-8?q?=E7=A4=BA(crypto.subtle=20=E5=8F=AA=E5=9C=A8=E5=AE=89=E5=85=A8?=
 =?UTF-8?q?=E4=B8=8A=E4=B8=8B=E6=96=87)=E2=80=94=E2=80=94=E7=AD=BE?=
 =?UTF-8?q?=E5=90=8D=E7=A7=98=E5=AF=86=E4=BB=8E=E4=B8=8D=E5=87=BA=20daemon?=
 =?UTF-8?q?,=E9=9B=B6=E6=96=B0=E5=A2=9E=E6=9C=8D=E5=8A=A1=E7=AB=AF?=
 =?UTF-8?q?=E4=BB=A3=E7=A0=81,=E4=B8=8A=E4=B8=80=E6=8F=90=E4=BA=A4?=
 =?UTF-8?q?=E4=BF=AE=E7=9A=84=E4=B8=8B=E8=BD=BD=E5=93=8D=E5=BA=94=E5=A4=B4?=
 =?UTF-8?q?=E6=AD=A3=E6=98=AF=E8=BF=99=E6=9D=A1=E8=B7=AF=E7=9A=84=E5=9C=B0?=
 =?UTF-8?q?=E5=9F=BA=E3=80=82=E4=BF=9D=E5=AD=98=E6=8C=89=E9=92=AE=E5=AF=B9?=
 =?UTF-8?q?=E5=9B=BE=E7=89=87/PDF/Office=20=E9=9A=90=E8=97=8F:=E5=AF=B9?=
 =?UTF-8?q?=E4=B8=80=E5=BC=A0=20png"=E4=BF=9D=E5=AD=98"=E4=B8=8D=E6=98=AF?=
 =?UTF-8?q?=E6=9A=82=E4=B8=8D=E5=8F=AF=E7=94=A8,=E6=98=AF=E6=97=A0?=
 =?UTF-8?q?=E6=84=8F=E4=B9=89=E3=80=82=E8=A7=86=E9=A2=91/=E9=9F=B3?=
 =?UTF-8?q?=E9=A2=91=E5=88=BB=E6=84=8F=E4=B8=8D=E5=81=9A:=E6=9C=8D?=
 =?UTF-8?q?=E5=8A=A1=E7=AB=AF=E6=97=A0=20Range,=E6=8B=96=E4=B8=8D=E5=8A=A8?=
 =?UTF-8?q?=E8=BF=9B=E5=BA=A6=E6=9D=A1=E7=9A=84=E6=92=AD=E6=94=BE=E5=99=A8?=
 =?UTF-8?q?=E6=98=AF=E6=AE=8B=E7=96=BE=E3=80=82e2e=20=E6=96=B0=E9=92=89?=
 =?UTF-8?q?=E4=B8=80=E6=9D=A1=E7=AB=AF=E5=88=B0=E7=AB=AF:console=20?=
 =?UTF-8?q?=E9=93=B8=20token=20=E2=86=92=20=E6=B5=8F=E8=A7=88=E5=99=A8?=
 =?UTF-8?q?=E5=90=8C=E6=AC=BE=E5=85=AC=E5=BC=8F(=E7=85=A7=E6=8A=84?=
 =?UTF-8?q?=E4=B8=8D=20import,=E9=BB=91=E7=9B=92=E9=92=89=E5=85=AC?=
 =?UTF-8?q?=E5=BC=8F=E6=9C=AC=E8=BA=AB)=E7=AD=BE=20/files=20=E7=9B=B4?=
 =?UTF-8?q?=E9=93=BE=20=E2=86=92=20200=20+=20image/png=20+=20inline=20disp?=
 =?UTF-8?q?osition,=E5=B9=B6=E5=8F=8D=E5=90=91=E9=92=89=20username=3D=20?=
 =?UTF-8?q?=E5=BF=85=E8=A2=AB=E6=8B=92=E3=80=82=E6=97=A0=E5=A4=B4=20Chrome?=
 =?UTF-8?q?=20=E7=9C=9F=20UI=20=E8=B5=B0=E6=9F=A5=E5=9B=9B=E5=88=86?=
 =?UTF-8?q?=E6=94=AF=E5=90=84=E5=B0=B1=E5=90=84=E4=BD=8D,iframe=20src=20?=
 =?UTF-8?q?=E8=A7=A3=E5=87=BA=E7=9A=84=E7=9B=B4=E9=93=BE=20fetch=20200=20+?=
 =?UTF-8?q?=20=E7=9C=9F=20docx=20MIME;=E5=AE=8C=E6=95=B4=E6=B8=B2=E6=9F=93?=
 =?UTF-8?q?=E7=9A=84=E8=AF=9A=E5=AE=9E=E8=BE=B9=E7=95=8C=3D=E5=BE=AE?=
 =?UTF-8?q?=E8=BD=AF=E6=8A=93=E4=B8=8D=E5=88=B0=20127.0.0.1,=E5=BE=85?=
 =?UTF-8?q?=E7=BB=91=E5=9F=9F=E5=90=8D=E7=9A=84=E7=9C=9F=E9=83=A8=E7=BD=B2?=
 =?UTF-8?q?=E9=AA=8C=E6=94=B6=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/src/console.test.ts                       |  82 +++++
 .../components/workbench/FilePreviewPane.tsx  | 303 ++++++++++++++----
 .../src/features/sandboxes/envd-client.ts     |  52 ++-
 .../console/src/features/sandboxes/preview.ts |  40 +++
 4 files changed, 421 insertions(+), 56 deletions(-)
 create mode 100644 packages/console/src/features/sandboxes/preview.ts

diff --git a/e2e/src/console.test.ts b/e2e/src/console.test.ts
index 81e84ec..d30c187 100644
--- a/e2e/src/console.test.ts
+++ b/e2e/src/console.test.ts
@@ -157,3 +157,85 @@ describe('web console over a real daemon', () => {
     expect((await listSandboxes(cookieOf(newLogin))).status).toBe(200);
   });
 });
+
+describe('browser-side signed download URLs (the Office preview foundation)', () => {
+  // The console's preview pane recomputes the file signature in the browser
+  // (envd-client.ts signedDownloadUrl) from the token /console/envdToken
+  // hands it. This pins the whole chain end-to-end — console minting, the
+  // formula REWRITTEN here rather than imported (a black box pins the
+  // formula itself, not a shared implementation's self-consistency), and
+  // the root /files door.
+  it('a console-minted token signs a working /files URL with the browser formula', async () => {
+    // Continue the account story: re-setup with the token so this describe
+    // owns known credentials regardless of what ran before it.
+    const session = cookieOf(
+      await post('/console/auth/setup', {
+        token: inject('dormiceToken'),
+        username: 'previewer',
+        password: 'preview e2e password',
+      }),
+    );
+    const bearer = {
+      authorization: `Bearer ${inject('dormiceToken')}`,
+      'content-type': 'application/json',
+    };
+    const acquired = (await (
+      await fetch(`${endpoint()}/acquireSandbox`, {
+        method: 'POST',
+        headers: bearer,
+        body: JSON.stringify({ name: 'signed-preview' }),
+      })
+    ).json()) as { sandbox: { id: string } };
+    // A real 1x1 PNG: the download must come back image/png, not a guess.
+    const PIXEL_PNG =
+      'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
+    await fetch(`${endpoint()}/writeFiles`, {
+      method: 'POST',
+      headers: bearer,
+      body: JSON.stringify({
+        name: 'signed-preview',
+        files: [{ path: 'pixel.png', contentBase64: PIXEL_PNG }],
+      }),
+    });
+
+    // Mint the token exactly the way the browser does: cookie + console header.
+    const minted = await fetch(`${endpoint()}/console/envdToken`, {
+      method: 'POST',
+      headers: {
+        cookie: session,
+        'x-dormice-console': '1',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ sandboxId: acquired.sandbox.id }),
+    });
+    expect(minted.status).toBe(200);
+    const { envdAccessToken } = (await minted.json()) as {
+      envdAccessToken: string;
+    };
+
+    // The browser formula, verbatim: sha256("path:read::token:exp"),
+    // standard-alphabet base64, padding stripped, v1_ prefix. The username
+    // slot is the empty string and the query carries NO username param.
+    const exp = Math.floor(Date.now() / 1000) + 900;
+    const digest = await crypto.subtle.digest(
+      'SHA-256',
+      new TextEncoder().encode(`pixel.png:read::${envdAccessToken}:${exp}`),
+    );
+    const signature = `v1_${btoa(String.fromCharCode(...new Uint8Array(digest))).replace(/=+$/, '')}`;
+    const url = (extra = '') =>
+      `${endpoint()}/files?path=pixel.png${extra}&signature=${encodeURIComponent(signature)}&signature_expiration=${exp}`;
+
+    const res = await fetch(url());
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('image/png');
+    expect(res.headers.get('content-disposition')).toContain('inline');
+    expect(new Uint8Array(await res.arrayBuffer())).toEqual(
+      new Uint8Array(Buffer.from(PIXEL_PNG, 'base64')),
+    );
+
+    // The username trap, pinned in reverse: a well-meant `username=` added
+    // to the query breaks the door (vetUsername throws on the empty string,
+    // and any non-empty value falls out of the signed material).
+    expect((await fetch(url('&username='))).status).not.toBe(200);
+  });
+});
diff --git a/packages/console/src/features/sandboxes/components/workbench/FilePreviewPane.tsx b/packages/console/src/features/sandboxes/components/workbench/FilePreviewPane.tsx
index 9db0418..ffca0a2 100644
--- a/packages/console/src/features/sandboxes/components/workbench/FilePreviewPane.tsx
+++ b/packages/console/src/features/sandboxes/components/workbench/FilePreviewPane.tsx
@@ -1,5 +1,9 @@
 import type { Sandbox } from '@dormice/shared';
-import { Download01Icon, RefreshIcon } from '@hugeicons/core-free-icons';
+import {
+  Download01Icon,
+  GlobeIcon,
+  RefreshIcon,
+} from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/react';
 import { useQuery } from '@tanstack/react-query';
 import { useEffect, useState } from 'react';
@@ -15,16 +19,32 @@ import {
 import { Spinner } from '@/components/ui/spinner';
 import { Textarea } from '@/components/ui/textarea';
 import { formatBytes } from '@/lib/format';
-import { downloadFile, type EnvdEntry } from '../../envd-client';
+import {
+  downloadFile,
+  type EnvdEntry,
+  SIGNED_URL_TTL_SECONDS,
+  signedDownloadUrl,
+} from '../../envd-client';
 import { useEnvdAuth, useFileMutations } from '../../hooks/useEnvd';
+import { previewKindOf } from '../../preview';
 
 /**
  * 在线看得过来的才在线看:预览上限之上只给下载 — 编辑器不是给日志
- * 大文件准备的。上限取 1 MiB:够看配置、代码、多数日志尾巴,又不至于
+ * 大文件准备的。文本上限取 1 MiB:够看配置、代码、多数日志尾巴,又不至于
  * 把整段内存交给一个 textarea。
  */
 const PREVIEW_CAP_BYTES = 1024 * 1024;
 
+/**
+ * 图片/PDF 的 Blob 预览上限:object URL 是整块驻内存的,50 MiB 够看
+ * 截图、图表、报告 PDF;更大的下载本地看。Office 无本地上限 — 我们
+ * 不抓取字节,Microsoft 查看器超限会在 iframe 里自己报错,诚实。
+ */
+const MEDIA_CAP_BYTES = 50 * 1024 * 1024;
+
+/** Microsoft 在线查看器的 iframe 端点,src= 后接 URL 编码的签名直链。 */
+const OFFICE_VIEWER = 'https://view.officeapps.live.com/op/embed.aspx?src=';
+
 /**
  * 文本判定:头 8 KiB 里出现 NUL 字节即视为二进制。与 git 同一招 —
  * 不猜编码不读魔数,便宜且几乎不会冤枉文本文件。
@@ -34,10 +54,17 @@ function looksBinary(bytes: Uint8Array): boolean {
   return head.includes(0);
 }
 
+type PreviewData =
+  | { kind: 'text'; text: string }
+  | { kind: 'binary' }
+  | { kind: 'media'; blob: Blob };
+
 /**
- * 工作台中央的预览/编辑窗格:点开文件先看内容,小文本顺手改完保存 —
- * 排查 agent 产物最高频的动作。读写都走 envd 的文件面(读 GET /files,
- * 存同路径整文件覆写上传)。
+ * 工作台中央的预览/编辑窗格,按 previewKindOf 分流:文本就地编辑保存;
+ * 图片/PDF 走 header 认证的 Blob → object URL 就地渲染(同源,明文
+ * HTTP 的 IP 访问也能用);Office 文档在显式点击后铸短时效签名直链,
+ * 交给 Microsoft 在线查看器抓取渲染 — 内容会离开本机,所以必须是
+ * 一次带披露的点击,绝不自动外发。读写都走 envd 的文件面。
  *
  * 内容是「打开时快照 + 手动刷新」,刻意不跟 watch 自动重读:agent 每
  * 秒追写日志会冲掉正在编辑的草稿 — 快照语义才编辑得安稳。文件在沙箱
@@ -57,36 +84,92 @@ export function FilePreviewPane({
   const auth = useEnvdAuth(sandbox.id);
   const [draft, setDraft] = useState('');
   const mutations = useFileMutations(auth.data);
+
+  const previewKind = selected ? previewKindOf(selected.name) : 'other';
+  const isMedia = previewKind === 'image' || previewKind === 'pdf';
+  const capBytes = isMedia ? MEDIA_CAP_BYTES : PREVIEW_CAP_BYTES;
   const tooLarge =
-    selected !== null && Number(selected.size) > PREVIEW_CAP_BYTES;
+    selected !== null &&
+    previewKind !== 'office' &&
+    Number(selected.size) > capBytes;
 
   const content = useQuery({
     queryKey: ['envdFileContent', sandbox.id, selected?.path],
-    queryFn: async () => {
+    queryFn: async ({ signal }): Promise<PreviewData> => {
       if (!auth.data || !selected) throw new Error('缺少 envd 凭证');
-      const blob = await downloadFile(auth.data, selected.path);
+      // signal 让换文件时真取消上一个下载 — media 档 50 MiB 级别,不取消
+      // 就是白流量压着新请求。
+      const blob = await downloadFile(auth.data, selected.path, signal);
+      if (isMedia) {
+        // 类型由扩展名裁决(preview.ts 单一来源),不读字节不嗅探;
+        // blob.type 来自服务端按扩展名的 MIME 表,浏览器认它渲染。
+        return { kind: 'media', blob };
+      }
       const bytes = new Uint8Array(await blob.arrayBuffer());
-      if (looksBinary(bytes)) return { binary: true as const };
-      return { binary: false as const, text: new TextDecoder().decode(bytes) };
+      if (looksBinary(bytes)) return { kind: 'binary' };
+      return { kind: 'text', text: new TextDecoder().decode(bytes) };
     },
-    enabled: selected !== null && !tooLarge && auth.data !== undefined,
+    // Office 分支零本地抓取:浏览器渲染不了 docx,抓了也没用 — 它只铸 URL。
+    enabled:
+      selected !== null &&
+      !tooLarge &&
+      auth.data !== undefined &&
+      previewKind !== 'office',
     // 文件内容随沙箱里的进程随时在变,每次选中都重读,不吃缓存。
     gcTime: 0,
     staleTime: 0,
     retry: false,
   });
 
+  // object URL 的创建与撤销成对住在同一个 effect:换文件(data 变)、
+  // 手动刷新(新 blob)、卸载三条路都自动撤旧,StrictMode 双跑也安全。
+  // 绝不挪进 queryFn/select —— gcTime 0 的缓存没有淘汰回调,URL 归缓存
+  // 所有就是撤销无主,必漏内存。
+  const [objectUrl, setObjectUrl] = useState<string | null>(null);
+  useEffect(() => {
+    if (content.data?.kind !== 'media') return;
+    const url = URL.createObjectURL(content.data.blob);
+    setObjectUrl(url);
+    return () => {
+      URL.revokeObjectURL(url);
+      setObjectUrl(null);
+    };
+  }, [content.data]);
+
   // 读到文本后灌入编辑区;依赖 content.data 使换文件/刷新时必然重灌。
   useEffect(() => {
-    if (content.data && !content.data.binary) {
+    if (content.data?.kind === 'text') {
       setDraft(content.data.text);
     }
   }, [content.data]);
 
-  const dirty =
-    content.data !== undefined &&
-    !content.data.binary &&
-    draft !== content.data.text;
+  const dirty = content.data?.kind === 'text' && draft !== content.data.text;
+
+  // Office 的已铸直链按 path 记账:换文件后 path 对不上即自然归零,
+  // 不用重置 effect;旧条目无害(直链本就 15 分钟自灭)。
+  const [office, setOffice] = useState<{ path: string; src: string } | null>(
+    null,
+  );
+  const officeSrc =
+    office !== null && selected !== null && office.path === selected.path
+      ? office.src
+      : null;
+  const [minting, setMinting] = useState(false);
+  const mintOffice = async () => {
+    if (!auth.data || !selected) return;
+    setMinting(true);
+    try {
+      const signed = await signedDownloadUrl(auth.data, selected.path);
+      setOffice({
+        path: selected.path,
+        src: `${OFFICE_VIEWER}${encodeURIComponent(signed)}`,
+      });
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : String(error));
+    } finally {
+      setMinting(false);
+    }
+  };
 
   if (selected === null) {
     return (
@@ -95,7 +178,8 @@ export function FilePreviewPane({
           <EmptyHeader>
             <EmptyTitle>在左侧选择一个文件</EmptyTitle>
             <EmptyDescription>
-              文本文件在这里预览和编辑;终端就在下面,改完顺手跑。
+              文本在这里预览和编辑,图片、PDF、Office 文档也能看;终端就在
+              下面,改完顺手跑。
             </EmptyDescription>
           </EmptyHeader>
         </Empty>
@@ -123,6 +207,50 @@ export function FilePreviewPane({
       },
     );
 
+  const downloadButton = (
+    <Button
+      variant="outline"
+      size="sm"
+      disabled={mutations.download.isPending}
+      onClick={download}
+    >
+      <HugeiconsIcon icon={Download01Icon} />
+      下载
+    </Button>
+  );
+
+  // 刷新按各形态各表:text/media 重读内容;Office 已铸则重铸直链(新
+  // 过期时间 → 新签名 → 新 src,顺带击穿 Microsoft 按 URL 的缓存),
+  // 未铸时无物可刷,不渲染。
+  const refreshButton =
+    previewKind === 'office' ? (
+      officeSrc !== null && (
+        <Button
+          variant="ghost"
+          size="icon-sm"
+          aria-label="重新生成直链并刷新预览"
+          title="重新生成直链并刷新预览"
+          disabled={minting}
+          onClick={() => void mintOffice()}
+        >
+          <HugeiconsIcon icon={RefreshIcon} />
+        </Button>
+      )
+    ) : (
+      <Button
+        variant="ghost"
+        size="icon-sm"
+        aria-label="重新读取"
+        disabled={content.isFetching || dirty}
+        title={
+          dirty ? '有未保存的修改 — 先保存或撤销,刷新会覆盖草稿' : '重新读取'
+        }
+        onClick={() => void content.refetch()}
+      >
+        <HugeiconsIcon icon={RefreshIcon} />
+      </Button>
+    );
+
   return (
     <div className="flex h-full min-h-0 flex-col">
       <div className="flex shrink-0 items-center justify-between gap-2 border-b px-3 py-1.5">
@@ -135,20 +263,7 @@ export function FilePreviewPane({
           {formatBytes(Number(selected.size))}
         </span>
         <div className="flex shrink-0 items-center gap-1">
-          <Button
-            variant="ghost"
-            size="icon-sm"
-            aria-label="重新读取"
-            disabled={content.isFetching || dirty}
-            title={
-              dirty
-                ? '有未保存的修改 — 先保存或撤销,刷新会覆盖草稿'
-                : '重新读取'
-            }
-            onClick={() => void content.refetch()}
-          >
-            <HugeiconsIcon icon={RefreshIcon} />
-          </Button>
+          {refreshButton}
           <Button
             variant="ghost"
             size="icon-sm"
@@ -158,19 +273,86 @@ export function FilePreviewPane({
           >
             <HugeiconsIcon icon={Download01Icon} />
           </Button>
-          <Button
-            size="sm"
-            className="h-6 px-2 text-xs"
-            disabled={!dirty || mutations.upload.isPending}
-            onClick={save}
-          >
-            {mutations.upload.isPending && <Spinner />}
-            保存
-          </Button>
+          {/* 保存只对文本有意义 — 对一张 png「保存」不是暂不可用,是
+              无意义,所以隐藏而非禁用。 */}
+          {previewKind === 'other' && (
+            <Button
+              size="sm"
+              className="h-6 px-2 text-xs"
+              disabled={!dirty || mutations.upload.isPending}
+              onClick={save}
+            >
+              {mutations.upload.isPending && <Spinner />}
+              保存
+            </Button>
+          )}
         </div>
       </div>
 
-      {tooLarge || content.data?.binary ? (
+      {previewKind === 'office' ? (
+        officeSrc !== null ? (
+          // 跨域第三方内容收权:sandbox 白名单是 Microsoft 查看器自己
+          // 要的最小集(allow-same-origin 给的是它的 origin 不是我们的);
+          // no-referrer 不把控制台路径送出去。
+          <iframe
+            src={officeSrc}
+            title={selected.name}
+            sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
+            referrerPolicy="no-referrer"
+            className="min-h-0 w-full flex-1 border-0"
+          />
+        ) : (
+          <div className="flex min-h-0 flex-1 items-center justify-center p-4">
+            <Empty>
+              <EmptyHeader>
+                {window.isSecureContext ? (
+                  <>
+                    <EmptyTitle>
+                      Office 文档 — 可用 Microsoft 在线预览
+                    </EmptyTitle>
+                    <EmptyDescription>
+                      预览会为此文件生成 {SIGNED_URL_TTL_SECONDS / 60}{' '}
+                      分钟有效的签名直链,交给
+                      Microsoft(view.officeapps.live.com)的服务器抓取并渲染 —
+                      文件内容会离开本机。含敏感内容请下载后本地打开。
+                    </EmptyDescription>
+                  </>
+                ) : (
+                  <>
+                    <EmptyTitle>
+                      明文 HTTP 下无法在线预览 Office 文档
+                    </EmptyTitle>
+                    <EmptyDescription>
+                      生成签名直链要用浏览器的加密接口(仅 HTTPS 可用),且
+                      Microsoft 的预览服务只能抓取公网 HTTPS 地址 — 请改用绑定的
+                      HTTPS 域名访问控制台,或下载后本地打开。
+                    </EmptyDescription>
+                  </>
+                )}
+              </EmptyHeader>
+              <EmptyContent>
+                <div className="flex gap-2">
+                  {window.isSecureContext && (
+                    <Button
+                      size="sm"
+                      disabled={minting}
+                      onClick={() => void mintOffice()}
+                    >
+                      {minting ? (
+                        <Spinner />
+                      ) : (
+                        <HugeiconsIcon icon={GlobeIcon} />
+                      )}
+                      用 Microsoft 在线预览
+                    </Button>
+                  )}
+                  {downloadButton}
+                </div>
+              </EmptyContent>
+            </Empty>
+          </div>
+        )
+      ) : tooLarge || content.data?.kind === 'binary' ? (
         <div className="flex min-h-0 flex-1 items-center justify-center p-4">
           <Empty>
             <EmptyHeader>
@@ -179,21 +361,11 @@ export function FilePreviewPane({
               </EmptyTitle>
               <EmptyDescription>
                 {tooLarge
-                  ? `在线预览上限 ${formatBytes(PREVIEW_CAP_BYTES)} — 下载后用本地工具打开。`
+                  ? `${isMedia ? '图片/PDF' : '文本'}在线预览上限 ${formatBytes(capBytes)} — 下载后用本地工具打开。`
                   : '内容里有 NUL 字节 — 下载后用对应的工具打开。'}
               </EmptyDescription>
             </EmptyHeader>
-            <EmptyContent>
-              <Button
-                variant="outline"
-                size="sm"
-                disabled={mutations.download.isPending}
-                onClick={download}
-              >
-                <HugeiconsIcon icon={Download01Icon} />
-                下载
-              </Button>
-            </EmptyContent>
+            <EmptyContent>{downloadButton}</EmptyContent>
           </Empty>
         </div>
       ) : content.isError ? (
@@ -219,10 +391,31 @@ export function FilePreviewPane({
             </EmptyContent>
           </Empty>
         </div>
-      ) : content.isPending ? (
+      ) : content.isPending || (content.data.kind === 'media' && !objectUrl) ? (
         <div className="flex items-center gap-2 p-4 text-sm text-muted-foreground">
           <Spinner /> 读取文件
         </div>
+      ) : content.data.kind === 'media' && objectUrl ? (
+        previewKind === 'pdf' ? (
+          // 刻意不加 sandbox:Chrome 的内置 PDF 查看器在 sandboxed iframe
+          // 里拒载(插件被禁);能进这个分支的只有 .pdf 扩展名 + 自家 MIME
+          // 表给的 application/pdf,不存在"其实是 HTML"的升格路径。
+          <iframe
+            src={objectUrl}
+            title={selected.name}
+            className="min-h-0 w-full flex-1 border-0"
+          />
+        ) : (
+          <div className="min-h-0 flex-1 overflow-auto p-4">
+            {/* svg 也走 <img>:规范保证不执行脚本、不发子请求 — 换成
+                iframe/object 等于给沙箱里的文件开脚本执行口。 */}
+            <img
+              src={objectUrl}
+              alt={selected.name}
+              className="mx-auto max-w-full"
+            />
+          </div>
+        )
       ) : (
         <div className="min-h-0 flex-1 p-2">
           {/* base-ui Textarea 默认 field-sizing-content 随内容长高,
diff --git a/packages/console/src/features/sandboxes/envd-client.ts b/packages/console/src/features/sandboxes/envd-client.ts
index 99e71cb..7cdf84f 100644
--- a/packages/console/src/features/sandboxes/envd-client.ts
+++ b/packages/console/src/features/sandboxes/envd-client.ts
@@ -124,14 +124,16 @@ export const removeWatcher = (auth: EnvdAuth, watcherId: string) =>
 
 // ---- 文件本体进出(纯 HTTP 面,流式无大小上限)---------------------------
 
-/** 下载整个文件为 Blob,交给浏览器落盘。 */
+/** 下载整个文件为 Blob,交给浏览器落盘或就地预览。 */
 export async function downloadFile(
   auth: EnvdAuth,
   path: string,
+  signal?: AbortSignal,
 ): Promise<Blob> {
   const query = new URLSearchParams({ path, username: 'user' });
   const res = await fetch(`${ENVD}/files?${query}`, {
     headers: headersOf(auth),
+    signal,
   });
   if (!res.ok) {
     const detail = (await res.json().catch(() => undefined)) as
@@ -197,3 +199,51 @@ export const killProcess = (
     process: { pid },
     signal,
   });
+
+// ---- 签名直链(daemon 根 /files,给第三方抓取用)---------------------------
+
+/**
+ * 15 分钟:Microsoft 查看器加载时抓取、大文档翻页可能补抓,太短会断
+ * 查看器的懒加载;再长只是白白加宽泄露窗 — 每次点击/刷新都重铸,
+ * 过期是一次点击的事。
+ */
+export const SIGNED_URL_TTL_SECONDS = 15 * 60;
+
+/**
+ * 浏览器侧复算签名直链 — 与 server/e2b/signing.ts 的 fileSignature
+ * 逐字对齐:`"v1_" + base64标准字母表剥padding( sha256(
+ * path:read:<username>:<token>:<exp> ) )`。浏览器本就持有本沙箱的
+ * envdAccessToken(它就是签名材料,秘密 signing secret 从不出 daemon),
+ * 所以不需要新的服务端动词。
+ *
+ * username 位置是空字符串,且 URL 里绝不带 username 参数:服务端校验
+ * 材料默认 `query.username ?? ''`,但 vetUsername('') 会 throw — 带空
+ * `username=` 是 401,带 `username=user` 则材料对不上,两头只能"缺席"
+ * (e2e/console.test 反向钉着这一条)。
+ *
+ * crypto.subtle 只在安全上下文存在(明文 HTTP 的 IP 访问没有)—
+ * 调用方先闸 window.isSecureContext。
+ */
+export async function signedDownloadUrl(
+  auth: EnvdAuth,
+  path: string,
+): Promise<string> {
+  const exp = Math.floor(Date.now() / 1000) + SIGNED_URL_TTL_SECONDS;
+  const material = `${path}:read::${auth.envdAccessToken}:${exp}`;
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(material),
+  );
+  const b64 = btoa(String.fromCharCode(...new Uint8Array(digest))).replace(
+    /=+$/,
+    '',
+  );
+  const query = new URLSearchParams({
+    path,
+    signature: `v1_${b64}`,
+    signature_expiration: String(exp),
+  });
+  // daemon 根,不带 /e2b/envd 前缀 — 签名面刻意开在根上(见 server 的
+  // signed-files.ts 顶注);控制台与它同源,origin 即公网地址。
+  return `${window.location.origin}/files?${query}`;
+}
diff --git a/packages/console/src/features/sandboxes/preview.ts b/packages/console/src/features/sandboxes/preview.ts
new file mode 100644
index 0000000..09b7e8a
--- /dev/null
+++ b/packages/console/src/features/sandboxes/preview.ts
@@ -0,0 +1,40 @@
+/**
+ * 扩展名 → 预览形态的唯一裁决点(组件禁止各自 endsWith 判断)。服务端
+ * MIME 表(server/e2b/envd/files.ts 的 MIME_BY_EXTENSION)是参照不是
+ * import — 那张表管 wire 的 content-type,这里管 UI 的渲染策略,变更
+ * 节奏不同。
+ *
+ * - image/pdf:header 认证下载成 Blob,object URL 就地渲染 — 同源、
+ *   明文 HTTP 的 IP 访问也能用。svg 永远走 <img>(规范保证不执行脚本、
+ *   不发子请求;换成 iframe/object 就是给沙箱里的文件开脚本执行口)。
+ * - office:浏览器铸签名直链交给 Microsoft 在线查看器抓取渲染 — 旧版
+ *   doc/xls/ppt 一并收,查看器原生支持,砍掉反而要写"为什么不"。
+ * - 视频/音频刻意不收:服务端不支持 Range 请求,播放器拖不了进度条 —
+ *   残疾预览不如诚实只给下载;将来加了 Range 再回头。
+ */
+export type PreviewKind = 'image' | 'pdf' | 'office' | 'other';
+
+const KIND_BY_EXTENSION: Record<string, PreviewKind> = {
+  png: 'image',
+  jpg: 'image',
+  jpeg: 'image',
+  gif: 'image',
+  svg: 'image',
+  webp: 'image',
+  ico: 'image',
+  pdf: 'pdf',
+  doc: 'office',
+  docx: 'office',
+  xls: 'office',
+  xlsx: 'office',
+  ppt: 'office',
+  pptx: 'office',
+};
+
+export function previewKindOf(name: string): PreviewKind {
+  // 与服务端 contentTypeOf 同规则:最后一个 '.' 之后、点开头的隐藏文件
+  // (.env)不算有扩展名、大小写不敏感。
+  const dot = name.lastIndexOf('.');
+  const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : '';
+  return KIND_BY_EXTENSION[ext] ?? 'other';
+}

From 3750cb862d6789e0b4f240bd0d85c648213b133c Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 19 Jul 2026 01:31:40 +0800
Subject: [PATCH 110/133] =?UTF-8?q?=E6=B2=99=E7=AE=B1=E5=88=97=E8=A1=A8?=
 =?UTF-8?q?=E4=B8=80=E8=BD=AE=E8=A7=82=E6=84=9F=E6=95=B4=E4=BF=AE(2026-07-?=
 =?UTF-8?q?18=20=E9=80=90=E9=A1=B9=E4=B8=8E=E7=94=A8=E6=88=B7=E6=8B=8D?=
 =?UTF-8?q?=E6=9D=BF)=E3=80=82=E6=A0=B8=E5=BF=83=E6=98=AF=20table-fixed:?=
 =?UTF-8?q?=E5=88=97=E5=AE=BD=E7=94=B1=E8=A1=A8=E5=A4=B4=E4=B8=80=E6=AC=A1?=
 =?UTF-8?q?=E5=AE=9A=E6=AD=BB,=E3=80=8C=E5=85=A8=E8=A1=A8=E4=B8=8D?=
 =?UTF-8?q?=E6=A8=AA=E6=BB=9A=E3=80=8D=E4=BB=8E=E7=BA=A6=E5=AE=9A=E5=8D=87?=
 =?UTF-8?q?=E6=A0=BC=E4=B8=BA=E7=89=A9=E7=90=86=E4=BF=9D=E8=AF=81=E2=80=94?=
 =?UTF-8?q?=E2=80=94=E8=B6=85=E9=95=BF=E7=9A=84=E5=90=8D=E7=A7=B0/?=
 =?UTF-8?q?=E6=A8=A1=E6=9D=BF=E5=9C=A8=E8=87=AA=E5=B7=B1=E5=88=97=E5=86=85?=
 =?UTF-8?q?=E7=9C=81=E7=95=A5=E5=8F=B7=E6=94=B6=E5=9C=BA(=E5=85=A8?=
 =?UTF-8?q?=E6=96=87=E5=9C=A8=20title),=E4=B8=8D=E5=86=8D=E6=8A=8A?=
 =?UTF-8?q?=E8=A1=A8=E6=92=91=E5=87=BA=E6=A8=AA=E5=90=91=E6=BB=9A=E5=8A=A8?=
 =?UTF-8?q?=E6=9D=A1;=E5=90=8D=E7=A7=B0=E4=B8=8D=E5=AE=9A=E5=AE=BD?=
 =?UTF-8?q?=E5=90=83=E6=8E=89=E5=85=A8=E9=83=A8=E5=89=A9=E4=BD=99,?=
 =?UTF-8?q?=E5=AE=83=E6=98=AF=E8=A1=A8=E7=9A=84=E4=B8=BB=E9=94=AE,?=
 =?UTF-8?q?=E7=AA=97=E5=8F=A3=E5=8F=98=E7=AA=84=E6=97=B6=E4=B9=9F=E6=98=AF?=
 =?UTF-8?q?=E5=AE=83=E5=85=88=E5=8F=98=E7=9F=AD,=E6=95=B0=E5=AD=97?=
 =?UTF-8?q?=E5=88=97=E6=B0=B8=E4=B8=8D=E6=8C=A4=E5=8E=8B=E3=80=82=E8=B5=84?=
 =?UTF-8?q?=E6=BA=90=E4=B8=89=E5=88=97=E4=B8=BB=E6=AC=A1=E5=AF=B9=E8=B0=83?=
 =?UTF-8?q?:Meter=20=E6=9D=A1=E6=94=BE=E5=A4=A7=E5=88=B0=20w-24=20?=
 =?UTF-8?q?=E5=BD=93=E4=B8=BB=E8=A7=92,=E3=80=8C=E7=94=A8=E9=87=8F=20/=20?=
 =?UTF-8?q?=E4=B8=8A=E9=99=90=E3=80=8D=E6=95=B4=E8=A1=8C=E9=99=8D=E4=B8=BA?=
 =?UTF-8?q?=20text-xs=20=E6=B3=A8=E8=84=9A=E2=80=94=E2=80=94=E6=89=AB?=
 =?UTF-8?q?=E8=A1=A8=E8=AF=BB=E7=9A=84=E6=98=AF=E6=9D=A1=E7=9A=84=E9=95=BF?=
 =?UTF-8?q?=E7=9F=AD=E4=B8=8E=E9=A2=9C=E8=89=B2,=E6=95=B0=E5=AD=97?=
 =?UTF-8?q?=E6=98=AF=E5=81=9C=E4=B8=8B=E6=A0=B8=E5=AF=B9=E6=97=B6=E6=89=8D?=
 =?UTF-8?q?=E7=9C=8B=E7=9A=84;=E4=B8=AD=E9=80=94=E8=AF=95=E8=BF=87?=
 =?UTF-8?q?=E6=8A=8A=E4=B8=8A=E9=99=90=E6=94=B6=E8=BF=9B=E6=82=AC=E5=81=9C?=
 =?UTF-8?q?=E8=85=BE=E5=AE=BD=E5=BA=A6,=E7=94=A8=E6=88=B7=E8=A3=81?=
 =?UTF-8?q?=E5=AE=9A=E4=B8=8A=E9=99=90=E8=A6=81=E4=B8=80=E7=9C=BC=E5=8F=AF?=
 =?UTF-8?q?=E8=A7=81,=E9=81=82=E4=BB=A5=E5=B0=8F=E5=AD=97=E5=86=85?=
 =?UTF-8?q?=E8=81=94=E8=90=BD=E5=AE=9A=E3=80=82Meter(components/=20?=
 =?UTF-8?q?=E5=85=B1=E4=BA=AB=E4=BB=B6)=E4=B8=89=E6=A1=A3=E5=A1=AB?=
 =?UTF-8?q?=E5=85=85=E8=89=B2=E6=94=B9=E4=B8=BA=E4=B8=8E=E8=BA=AB=E6=97=81?=
 =?UTF-8?q?=E6=95=B0=E5=AD=97=E5=AE=8C=E5=85=A8=E5=90=8C=E6=BA=90=E7=9A=84?=
 =?UTF-8?q?=E5=AD=97=E4=BD=93=E8=89=B2=E9=98=B6:=E5=AE=89=E9=9D=99=20muted?=
 =?UTF-8?q?-foreground=E3=80=81=E2=89=A575%=20amber-600=C2=B7400=E3=80=81?=
 =?UTF-8?q?=E2=89=A590%=20red-600=C2=B7400=E2=80=94=E2=80=94=E9=98=88?=
 =?UTF-8?q?=E5=80=BC=E6=9C=AC=E5=B0=B1=E4=B8=8E=20UsageCell=20=E5=85=B1?=
 =?UTF-8?q?=E4=BA=AB,=E7=8E=B0=E5=9C=A8=E8=89=B2=E7=9B=B8=E4=B9=9F?=
 =?UTF-8?q?=E4=B8=8D=E8=AE=B8=E5=88=86=E5=AE=B6,=E6=9D=A1=E6=98=AF?=
 =?UTF-8?q?=E6=95=B0=E5=AD=97=E7=9A=84=E5=BD=B1=E5=AD=90;=E6=80=BB?=
 =?UTF-8?q?=E8=A7=88=E5=8D=A1=E7=9A=84=E5=AE=89=E9=9D=99=E6=9D=A1=E9=9A=8F?=
 =?UTF-8?q?=E4=B9=8B=E4=BB=8E=E4=B8=BB=E9=A2=98=E8=89=B2=E5=8F=98=E7=81=B0?=
 =?UTF-8?q?,=E5=85=A8=E7=AB=99=E4=B8=80=E5=A5=97=E3=80=82=E5=BE=BD?=
 =?UTF-8?q?=E7=AB=A0=E5=8E=BB=E8=BE=B9=E6=A1=86(=E7=8A=B6=E6=80=81?=
 =?UTF-8?q?=E4=BA=94=E6=80=81+=E3=80=8C=E5=8F=AF=E5=8D=87=E7=BA=A7?=
 =?UTF-8?q?=E3=80=8D):=E6=B5=85=E8=89=B2=E5=BA=95+=E5=BD=A9=E8=89=B2?=
 =?UTF-8?q?=E5=AD=97=E5=B7=B2=E4=B8=A4=E5=A3=B0=E9=83=A8=E9=BD=90=E5=94=B1?=
 =?UTF-8?q?,=E5=90=8C=E8=89=B2=E7=B3=BB=E6=8F=8F=E8=BE=B9=E6=98=AF?=
 =?UTF-8?q?=E7=AC=AC=E4=B8=89=E5=BC=A0=E5=98=B4=E8=AF=B4=E5=90=8C=E4=B8=80?=
 =?UTF-8?q?=E5=8F=A5=E8=AF=9D=E3=80=82=E7=9B=B8=E5=AF=B9=E6=97=B6=E5=88=BB?=
 =?UTF-8?q?=E5=85=A8=E7=AB=99=E6=94=B6=E6=8B=A2=E4=B8=BA=E7=B2=97=E7=B2=92?=
 =?UTF-8?q?=E5=BA=A6=20ago():=E5=88=9A=E5=88=9A/N=20=E5=88=86=E9=92=9F?=
 =?UTF-8?q?=E5=89=8D/N=20=E5=B0=8F=E6=97=B6=E5=89=8D/N=20=E5=A4=A9?=
 =?UTF-8?q?=E5=89=8D,=E5=8F=AA=E7=95=99=E4=B8=80=E6=AE=B5=E2=80=94?=
 =?UTF-8?q?=E2=80=94"3=E5=B0=8F=E6=97=B620=E5=88=86=E5=89=8D"=E7=9A=84?=
 =?UTF-8?q?=E5=90=8E=E4=B8=80=E6=AE=B5=E6=98=AF=E5=99=AA=E9=9F=B3,?=
 =?UTF-8?q?=E8=AF=BB=E8=80=85=E8=A6=81=E7=9A=84=E6=98=AF=E6=95=B0=E9=87=8F?=
 =?UTF-8?q?=E7=BA=A7;since()=20=E7=9A=84=E5=85=A8=E9=83=A8=E8=B0=83?=
 =?UTF-8?q?=E7=94=A8=E7=82=B9(=E6=B2=99=E7=AE=B1=E8=A1=A8/=E5=B7=A5?=
 =?UTF-8?q?=E4=BD=9C=E5=8F=B0=E7=9B=91=E8=A7=86=E6=A0=8F/=E6=B4=BB?=
 =?UTF-8?q?=E5=8A=A8=E9=A1=B5/=E6=A8=A1=E6=9D=BF=E9=A1=B5/API=20=E5=AF=86?=
 =?UTF-8?q?=E9=92=A5=E9=A1=B5/=E6=8C=87=E6=A0=87=E9=9D=A2=E6=9D=BF)?=
 =?UTF-8?q?=E5=90=8C=E8=AF=AD=E4=B9=89=E5=90=8C=E5=86=99=E6=B3=95=E4=B8=80?=
 =?UTF-8?q?=E6=AC=A1=E8=BF=81=E5=AE=8C,since=20=E9=80=80=E5=BD=B9,?=
 =?UTF-8?q?=E7=B2=BE=E7=A1=AE=E6=97=B6=E9=97=B4=E6=88=B3=E7=95=99=E5=9C=A8?=
 =?UTF-8?q?=20title,=E7=A7=92=E7=BA=A7=E7=B2=BE=E5=BA=A6=E7=9A=84=E5=9C=BA?=
 =?UTF-8?q?=E5=90=88(=E7=AD=96=E7=95=A5=E5=80=92=E8=AE=A1=E6=97=B6)?=
 =?UTF-8?q?=E4=BB=8D=E5=BD=92=20formatDuration=E3=80=82CPU=20=E5=8D=95?=
 =?UTF-8?q?=E4=BD=8D=E3=80=8C=E6=A0=B8=E3=80=8D=E6=94=B9=20vCPU(=E8=A1=A8?=
 =?UTF-8?q?=E6=A0=BC/=E7=9B=91=E8=A7=86=E6=A0=8F/=E6=8C=87=E6=A0=87?=
 =?UTF-8?q?=E9=9D=A2=E6=9D=BF=E4=B8=89=E5=A4=84=E5=90=8C=E6=AD=A5;?=
 =?UTF-8?q?=E6=80=BB=E8=A7=88=E5=AE=BF=E4=B8=BB=E5=81=A5=E5=BA=B7=E5=8D=A1?=
 =?UTF-8?q?=E7=9A=84=E7=89=A9=E7=90=86=E6=A0=B8=E6=95=B0=E8=AF=AD=E4=B9=89?=
 =?UTF-8?q?=E4=B8=8D=E5=90=8C,=E4=B8=8D=E5=8A=A8)=E3=80=82=E6=9D=82?=
 =?UTF-8?q?=E9=A1=B9:=E5=88=9B=E5=BB=BA=E6=B2=99=E7=AE=B1=E4=B8=8E?=
 =?UTF-8?q?=E7=AD=9B=E9=80=89=E6=8C=89=E9=92=AE=E5=9B=9E=E9=BB=98=E8=AE=A4?=
 =?UTF-8?q?=20h-8(FilterMenu=20=E6=98=AF=E5=85=B1=E4=BA=AB=E4=BB=B6,?=
 =?UTF-8?q?=E6=B4=BB=E5=8A=A8=E9=A1=B5=E7=AD=9B=E9=80=89=E4=B8=80=E5=B9=B6?=
 =?UTF-8?q?=E9=95=BF=E9=AB=98,=E4=B8=8E=E6=90=9C=E7=B4=A2=E6=A1=86?=
 =?UTF-8?q?=E9=BD=90=E5=B9=B3);=E8=A1=8C=E8=8F=9C=E5=8D=95=E7=AB=96?=
 =?UTF-8?q?=E4=B8=89=E7=82=B9=E6=8D=A2=E6=A8=AA=E4=B8=89=E7=82=B9=E3=80=81?=
 =?UTF-8?q?=E6=8C=89=E9=92=AE=E5=8D=87=E9=BB=98=E8=AE=A4=20icon=20?=
 =?UTF-8?q?=E6=A1=A3=E3=80=81=E5=9B=BE=E6=A0=87=20size-5;=E8=8F=9C?=
 =?UTF-8?q?=E5=8D=95=E9=A1=B9=20font-medium+=E5=9B=BE=E6=A0=87=20strokeWid?=
 =?UTF-8?q?th=202=20=E5=8C=B9=E9=85=8D=E5=AD=97=E9=87=8D=E3=80=82console?=
 =?UTF-8?q?=20=E7=BA=AF=E5=89=8D=E7=AB=AF=E6=94=B9=E5=8A=A8,tsc=20?=
 =?UTF-8?q?=E4=B8=8E=20Biome=20=E5=85=A8=E7=BB=BF,e2e=20=E6=97=A0=E6=B6=89?=
 =?UTF-8?q?=E8=A1=A8=E6=A0=BC=E6=96=87=E6=A1=88=E7=9A=84=E6=96=AD=E8=A8=80?=
 =?UTF-8?q?=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../console/src/components/FilterMenu.tsx     |  4 +-
 packages/console/src/components/Meter.tsx     | 15 ++-
 .../features/activity/pages/ActivityPage.tsx  |  4 +-
 .../features/api-keys/pages/ApiKeysPage.tsx   |  6 +-
 .../src/features/doctor/pages/DoctorPage.tsx  |  6 +-
 .../components/CreateSandboxDialog.tsx        |  2 +-
 .../sandboxes/components/MetricsPanel.tsx     |  8 +-
 .../components/SandboxStateBadge.tsx          | 20 ++--
 .../sandboxes/components/UpgradableBadge.tsx  |  2 +-
 .../components/workbench/MonitorRail.tsx      | 12 ++-
 .../console/src/features/sandboxes/format.ts  | 15 ++-
 .../sandboxes/pages/SandboxesPage.tsx         | 95 +++++++++++--------
 .../templates/pages/TemplatesPage.tsx         |  6 +-
 13 files changed, 115 insertions(+), 80 deletions(-)

diff --git a/packages/console/src/components/FilterMenu.tsx b/packages/console/src/components/FilterMenu.tsx
index b3c9fbc..1af0c94 100644
--- a/packages/console/src/components/FilterMenu.tsx
+++ b/packages/console/src/components/FilterMenu.tsx
@@ -40,9 +40,7 @@ export function FilterMenu({
   return (
     <DropdownMenu>
       <DropdownMenuTrigger
-        render={
-          <Button variant="outline" size="sm" className="border-dashed" />
-        }
+        render={<Button variant="outline" className="border-dashed" />}
       >
         <HugeiconsIcon
           icon={PlusSignCircleIcon}
diff --git a/packages/console/src/components/Meter.tsx b/packages/console/src/components/Meter.tsx
index e630ee1..9da40bc 100644
--- a/packages/console/src/components/Meter.tsx
+++ b/packages/console/src/components/Meter.tsx
@@ -5,15 +5,24 @@ import { cn } from '@/lib/utils';
  * red past it) and the unfilled track is a lighter step of the same color,
  * so state reads across the whole bar. Null means "no reading yet" — an
  * empty quiet track, never a fake zero fill.
+ *
+ * The three fills are the SAME tokens the usage text next to them uses
+ * (muted-foreground / amber-600·400 / red-600·400, thresholds shared at
+ * 75/90) — the bar is the number's shadow, so the two may never disagree
+ * in hue. Quiet is deliberately not bg-primary: an accent-colored bar
+ * beside gray text read as two systems.
  */
 export function Meter({ pct }: { pct: number | null }) {
   const clamped = pct === null ? 0 : Math.min(100, Math.max(0, pct));
   const [fill, track] =
     clamped >= 90
-      ? ['bg-red-500', 'bg-red-500/15']
+      ? ['bg-red-600 dark:bg-red-400', 'bg-red-600/15 dark:bg-red-400/15']
       : clamped >= 75
-        ? ['bg-amber-500', 'bg-amber-500/15']
-        : ['bg-primary', 'bg-primary/10'];
+        ? [
+            'bg-amber-600 dark:bg-amber-400',
+            'bg-amber-600/15 dark:bg-amber-400/15',
+          ]
+        : ['bg-muted-foreground', 'bg-muted-foreground/15'];
   return (
     <div className={cn('h-1.5 w-full overflow-hidden rounded-full', track)}>
       <div
diff --git a/packages/console/src/features/activity/pages/ActivityPage.tsx b/packages/console/src/features/activity/pages/ActivityPage.tsx
index 85663bf..4c4cbb1 100644
--- a/packages/console/src/features/activity/pages/ActivityPage.tsx
+++ b/packages/console/src/features/activity/pages/ActivityPage.tsx
@@ -27,7 +27,7 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { useApiKeys } from '@/features/api-keys/hooks/useApiKeys';
-import { since } from '@/features/sandboxes/format';
+import { ago } from '@/features/sandboxes/format';
 import { cn } from '@/lib/utils';
 import { actorLabel } from '../actors';
 import { useActivity } from '../hooks/useActivity';
@@ -186,7 +186,7 @@ export function ActivityPage() {
                   // 相对时间好扫读,绝对时间才对得上日志 — hover 给后者。
                   title={new Date(event.at).toLocaleString()}
                 >
-                  {since(event.at)}前
+                  {ago(event.at)}
                 </TableCell>
                 <TableCell>
                   <Badge
diff --git a/packages/console/src/features/api-keys/pages/ApiKeysPage.tsx b/packages/console/src/features/api-keys/pages/ApiKeysPage.tsx
index f022d58..bf7da5d 100644
--- a/packages/console/src/features/api-keys/pages/ApiKeysPage.tsx
+++ b/packages/console/src/features/api-keys/pages/ApiKeysPage.tsx
@@ -64,7 +64,7 @@ import {
   TableHeader,
   TableRow,
 } from '@/components/ui/table';
-import { since, until } from '@/features/sandboxes/format';
+import { ago, until } from '@/features/sandboxes/format';
 import { copyText } from '@/lib/copy';
 import {
   useApiKeys,
@@ -752,7 +752,7 @@ export function ApiKeysPage() {
                   className="tabular-nums text-muted-foreground"
                   title={new Date(apiKey.createdAt).toLocaleString()}
                 >
-                  {since(apiKey.createdAt)}前
+                  {ago(apiKey.createdAt)}
                 </TableCell>
                 <TableCell
                   className="tabular-nums text-muted-foreground"
@@ -762,7 +762,7 @@ export function ApiKeysPage() {
                       : undefined
                   }
                 >
-                  {apiKey.lastUsedAt ? `${since(apiKey.lastUsedAt)}前` : '从未'}
+                  {apiKey.lastUsedAt ? ago(apiKey.lastUsedAt) : '从未'}
                 </TableCell>
                 <TableCell
                   className={`tabular-nums ${
diff --git a/packages/console/src/features/doctor/pages/DoctorPage.tsx b/packages/console/src/features/doctor/pages/DoctorPage.tsx
index 5a43a10..f356c4c 100644
--- a/packages/console/src/features/doctor/pages/DoctorPage.tsx
+++ b/packages/console/src/features/doctor/pages/DoctorPage.tsx
@@ -20,7 +20,7 @@ import {
   TooltipContent,
   TooltipTrigger,
 } from '@/components/ui/tooltip';
-import { since } from '@/features/sandboxes/format';
+import { ago } from '@/features/sandboxes/format';
 import { MOCK_PAGES_ENABLED } from '@/lib/mock';
 import { cn } from '@/lib/utils';
 import { type DoctorStatus, SAMPLE_DOCTOR } from '../fixtures';
@@ -128,8 +128,8 @@ export function DoctorPage() {
           </Badge>
         )}
         <span className="text-muted-foreground">
-          {since(report.ranAt)}前跑完,耗时{' '}
-          {(report.durationMs / 1000).toFixed(1)}s(含 3 个真容器探针)
+          {ago(report.ranAt)}跑完,耗时 {(report.durationMs / 1000).toFixed(1)}
+          s(含 3 个真容器探针)
         </span>
       </div>
 
diff --git a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
index 1b9c2f1..0d85e89 100644
--- a/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
+++ b/packages/console/src/features/sandboxes/components/CreateSandboxDialog.tsx
@@ -112,7 +112,7 @@ export function CreateSandboxDialog() {
     >
       <DialogTrigger
         render={
-          <Button size="sm">
+          <Button>
             <HugeiconsIcon icon={Add01Icon} />
             创建沙箱
           </Button>
diff --git a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
index 979d47a..34ecd1f 100644
--- a/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
+++ b/packages/console/src/features/sandboxes/components/MetricsPanel.tsx
@@ -26,7 +26,7 @@ import { Spinner } from '@/components/ui/spinner';
 import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
 import { withGapBreaks } from '@/lib/chart-gaps';
 import { formatBytes, pctOf } from '@/lib/format';
-import { since } from '../format';
+import { ago } from '../format';
 import {
   useSandboxMetrics,
   useSandboxMetricsHistory,
@@ -244,7 +244,7 @@ export function MetricsPanel({ sandbox }: { sandbox: Sandbox }) {
             icon={CpuIcon}
             label="CPU"
             value={`${Math.round(sample.cpuUsedPct)}%`}
-            hint={`${sample.cpuCount} 核 · 百分比按单核计`}
+            hint={`${sample.cpuCount} vCPU · 百分比按单 vCPU 计`}
             pct={sample.cpuUsedPct / sample.cpuCount}
           />
           <MetricCard
@@ -314,7 +314,7 @@ export function MetricsPanel({ sandbox }: { sandbox: Sandbox }) {
             )}
             xTickFormatter={clockFor(range)}
             tickFormatter={(v) => `${v}%`}
-            valueFormatter={(v) => `${v}%(按单核计)`}
+            valueFormatter={(v) => `${v}%(按单 vCPU 计)`}
           />
           <HistoryChart
             title="内存走势"
@@ -336,7 +336,7 @@ export function MetricsPanel({ sandbox }: { sandbox: Sandbox }) {
 
       <p className="text-xs text-muted-foreground">
         {sample !== null &&
-          `当前值 5 秒刷新,本次读数取自 ${since(sample.timestamp)}前。`}
+          `当前值 5 秒刷新,本次读数取自 ${ago(sample.timestamp)}。`}
         历史由 daemon
         后台采样落库;沙箱睡着照样测(观察不唤醒),停止后曲线如实断流。
         {bucketSeconds !== null &&
diff --git a/packages/console/src/features/sandboxes/components/SandboxStateBadge.tsx b/packages/console/src/features/sandboxes/components/SandboxStateBadge.tsx
index c81b18d..46bf5c8 100644
--- a/packages/console/src/features/sandboxes/components/SandboxStateBadge.tsx
+++ b/packages/console/src/features/sandboxes/components/SandboxStateBadge.tsx
@@ -5,20 +5,22 @@ import { STATE_LABELS } from '../format';
 
 // Lifecycle rungs, coldest last — one hue per rung so the list reads at a
 // glance: green is paying for RAM, blue is parked in swap, grey is disk-only.
+// Borderless (2026-07-18): tinted fill + colored text already carry the
+// state; a same-hue outline was a third voice saying the same thing.
 const STATE_STYLES: Record<SandboxState, string> = {
-  active:
-    'border-emerald-500/40 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
-  frozen: 'border-sky-500/40 bg-sky-500/10 text-sky-600 dark:text-sky-400',
-  stopped: 'border-border bg-muted text-muted-foreground',
-  archived:
-    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
-  restoring:
-    'border-amber-500/40 bg-amber-500/10 text-amber-600 dark:text-amber-400',
+  active: 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+  frozen: 'bg-sky-500/10 text-sky-600 dark:text-sky-400',
+  stopped: 'bg-muted text-muted-foreground',
+  archived: 'bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  restoring: 'bg-amber-500/10 text-amber-600 dark:text-amber-400',
 };
 
 export function SandboxStateBadge({ state }: { state: SandboxState }) {
   return (
-    <Badge variant="outline" className={cn('font-medium', STATE_STYLES[state])}>
+    <Badge
+      variant="outline"
+      className={cn('border-transparent font-medium', STATE_STYLES[state])}
+    >
       {STATE_LABELS[state]}
     </Badge>
   );
diff --git a/packages/console/src/features/sandboxes/components/UpgradableBadge.tsx b/packages/console/src/features/sandboxes/components/UpgradableBadge.tsx
index a6eff48..bead685 100644
--- a/packages/console/src/features/sandboxes/components/UpgradableBadge.tsx
+++ b/packages/console/src/features/sandboxes/components/UpgradableBadge.tsx
@@ -14,7 +14,7 @@ export function UpgradableBadge({ lineage }: { lineage?: ImageLineage }) {
   return (
     <Badge
       variant="outline"
-      className="border-amber-500/40 bg-amber-500/10 font-medium text-amber-600 dark:text-amber-400"
+      className="border-transparent bg-amber-500/10 font-medium text-amber-600 dark:text-amber-400"
       title={`运行 ${lineage.image},模板当前 ${lineage.nextImage} — Rebuild 换新`}
     >
       可升级
diff --git a/packages/console/src/features/sandboxes/components/workbench/MonitorRail.tsx b/packages/console/src/features/sandboxes/components/workbench/MonitorRail.tsx
index b89f7e6..1e348f3 100644
--- a/packages/console/src/features/sandboxes/components/workbench/MonitorRail.tsx
+++ b/packages/console/src/features/sandboxes/components/workbench/MonitorRail.tsx
@@ -39,7 +39,7 @@ import { Sparkline } from '@/features/overview/components/Sparkline';
 import { copyText } from '@/lib/copy';
 import { formatBytes, pctOf } from '@/lib/format';
 import { cn } from '@/lib/utils';
-import { policyLine, since } from '../../format';
+import { ago, policyLine } from '../../format';
 import { useEnvdAuth, useKillProcess, useProcesses } from '../../hooks/useEnvd';
 import {
   useSandboxImages,
@@ -156,7 +156,9 @@ function VitalsSection({ sandbox }: { sandbox: Sandbox }) {
         icon={CpuIcon}
         label="CPU"
         value={sample ? `${Math.round(sample.cpuUsedPct)}%` : '—'}
-        hint={sample ? `${sample.cpuCount} 核 · 百分比按单核计` : offlineHint}
+        hint={
+          sample ? `${sample.cpuCount} vCPU · 百分比按单 vCPU 计` : offlineHint
+        }
         pct={sample ? sample.cpuUsedPct / sample.cpuCount : null}
         spark={samples.map((s) => s.cpuUsedPct)}
       />
@@ -349,7 +351,7 @@ function ActivityCard({ sandbox }: { sandbox: Sandbox }) {
                 {actorLabel(event.actor, apiKeys)}
               </span>
               <span className="shrink-0 tabular-nums text-muted-foreground">
-                {since(event.at)}前
+                {ago(event.at)}
               </span>
             </div>
           ))}
@@ -442,10 +444,10 @@ function InfoCard({ sandbox }: { sandbox: Sandbox }) {
         </InfoRow>
         <InfoRow label="创建于">
           <span title={new Date(sandbox.createdAt).toLocaleString()}>
-            {since(sandbox.createdAt)}前
+            {ago(sandbox.createdAt)}
           </span>
         </InfoRow>
-        <InfoRow label="最近活动">{since(sandbox.lastActiveAt)}前</InfoRow>
+        <InfoRow label="最近活动">{ago(sandbox.lastActiveAt)}</InfoRow>
       </dl>
     </RailCard>
   );
diff --git a/packages/console/src/features/sandboxes/format.ts b/packages/console/src/features/sandboxes/format.ts
index 2c137b5..e391789 100644
--- a/packages/console/src/features/sandboxes/format.ts
+++ b/packages/console/src/features/sandboxes/format.ts
@@ -73,9 +73,18 @@ export function durationHint(raw: string): string | null {
   return `= ${formatDuration(seconds)}`;
 }
 
-/** 距离某时刻过去了多久:"3分12秒"(调用方自己加"前")。 */
-export function since(iso: string): string {
-  return formatDuration((Date.now() - Date.parse(iso)) / 1000);
+/**
+ * 相对时刻,粗粒度:"刚刚" / "5 分钟前" / "3 小时前" / "2 天前"。
+ * 刻意只留一段 — "3小时20分前"的后一段是噪音,读者要的是数量级;
+ * 精确到秒的场合(策略倒计时)用 formatDuration,精确时刻在 title。
+ * "前"字自带:"刚刚"没有"前",由调用方拼会拼出"刚刚前"。
+ */
+export function ago(iso: string): string {
+  const s = (Date.now() - Date.parse(iso)) / 1000;
+  if (s < 60) return '刚刚';
+  if (s < 3600) return `${Math.floor(s / 60)} 分钟前`;
+  if (s < 86400) return `${Math.floor(s / 3600)} 小时前`;
+  return `${Math.floor(s / 86400)} 天前`;
 }
 
 /** 距离某时刻还有多久:"6天3小时"(调用方自己加"后");已过去则为"0秒"。 */
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index 4f9e54a..b96de2e 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -4,7 +4,7 @@ import {
   ArrowUp01Icon,
   Copy01Icon,
   Delete02Icon,
-  MoreVerticalIcon,
+  MoreHorizontalIcon,
   PackageIcon,
   Search01Icon,
 } from '@hugeicons/core-free-icons';
@@ -64,7 +64,7 @@ import { CreateSandboxDialog } from '../components/CreateSandboxDialog';
 import { DestroySandboxDialog } from '../components/DestroySandboxButton';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
 import { UpgradableBadge } from '../components/UpgradableBadge';
-import { STATE_LABELS, since } from '../format';
+import { ago, STATE_LABELS } from '../format';
 import {
   useFleetMetrics,
   useSandboxes,
@@ -107,29 +107,34 @@ function formatCap(bytes: number): string {
 }
 
 /**
- * 资源列的一格:写成「用量 / 上限」— 不带分母的数字没有信息量,
- * 1.2 GiB 对 2 GiB 的沙箱是快满,对 8 GiB 的是很空。占比过线换警示色,
- * 和指标 tab 的 Meter 同一套阈值。value 为 null = 这行没被测到
- * (没有容器可测)。
+ * 资源列的一格:Meter 条是主角,「用量 / 上限」整行 text-xs 当精度注脚
+ * (2026-07-18 用户拍板,主次对调) — 扫表时读的是条的长短与颜色,数字
+ * 是停下来核对时才看的。数字列因此瘦身,省下的宽度归名称列。占比过线
+ * 数字换警示色,和 Meter 同一套阈值同一套色。value 为 null = 这行没被
+ * 测到(没有容器可测)。
  */
 function UsageCell({
   value,
+  cap,
   pct,
   title,
 }: {
   value: string | null;
+  cap?: string;
   pct: number;
   title?: string;
 }) {
   if (value === null) {
     return (
-      <TableCell className="text-right text-muted-foreground">—</TableCell>
+      <TableCell className="text-right text-xs text-muted-foreground">
+        —
+      </TableCell>
     );
   }
   return (
     <TableCell
       className={cn(
-        'text-right tabular-nums',
+        'text-right text-xs tabular-nums',
         pct >= 90
           ? 'text-red-600 dark:text-red-400'
           : pct >= 75
@@ -139,9 +144,9 @@ function UsageCell({
       title={title}
     >
       {value}
-      {/* 迷你条:数字给精度,条给一眼的量感。宽度钉死不随列宽漂 —
-          三列的条一样长,长短才可比。 */}
-      <div className="mt-1 ml-auto w-16">
+      {cap && <> / {cap}</>}
+      {/* 条的宽度钉死不随列宽漂 — 三列的条一样长,长短才可比。 */}
+      <div className="mt-1 ml-auto w-24">
         <Meter pct={pct} />
       </div>
     </TableCell>
@@ -194,30 +199,28 @@ function SandboxRowMenu({ name }: { name: string }) {
       <DropdownMenu>
         <DropdownMenuTrigger
           render={
-            <Button
-              variant="ghost"
-              size="icon-sm"
-              aria-label={`${name} 的操作`}
-            >
-              <HugeiconsIcon icon={MoreVerticalIcon} />
+            <Button variant="ghost" size="icon" aria-label={`${name} 的操作`}>
+              <HugeiconsIcon icon={MoreHorizontalIcon} className="size-5" />
             </Button>
           }
         />
         <DropdownMenuContent align="end">
           <DropdownMenuItem
+            className="font-medium"
             onClick={async () => {
               await navigator.clipboard.writeText(name);
               toast.success('名称已复制');
             }}
           >
-            <HugeiconsIcon icon={Copy01Icon} />
+            <HugeiconsIcon icon={Copy01Icon} strokeWidth={2} />
             复制名称
           </DropdownMenuItem>
           <DropdownMenuItem
             variant="destructive"
+            className="font-medium"
             onClick={() => setConfirmOpen(true)}
           >
-            <HugeiconsIcon icon={Delete02Icon} />
+            <HugeiconsIcon icon={Delete02Icon} strokeWidth={2} />
             销毁
           </DropdownMenuItem>
         </DropdownMenuContent>
@@ -463,10 +466,15 @@ export function SandboxesPage() {
 
       {filtered.length > 0 && (
         // fill:表格占满剩余高度框内滚,表头吸顶 — 列名滚不丢。
-        <DataTable fill>
+        // table-fixed 是「全表不横滚」的物理保证:列宽由表头一次定死,
+        // 超长的名称/模板在自己列里省略号收场(全文在 title),而不是把
+        // 整张表撑出横向滚动条。定宽列按内容给宽(数字列的下限是 Meter
+        // 条的 w-16 + 边距);名称不定宽,吃掉全部剩余 — 它是表的主键,
+        // 窗口变窄时也是它先变短,数字列不挤压。
+        <DataTable fill className="table-fixed">
           <TableHeader>
             <TableRow>
-              <TableHead className="w-0">
+              <TableHead className="w-14">
                 <Checkbox
                   aria-label="全选"
                   checked={allVisibleSelected}
@@ -481,12 +489,12 @@ export function SandboxesPage() {
                   onSort={toggleSort}
                 />
               </TableHead>
-              <TableHead>状态</TableHead>
-              <TableHead>模板</TableHead>
-              <TableHead className="text-right">CPU</TableHead>
-              <TableHead className="text-right">内存</TableHead>
-              <TableHead className="text-right">磁盘</TableHead>
-              <TableHead>
+              <TableHead className="w-24">状态</TableHead>
+              <TableHead className="w-32">模板</TableHead>
+              <TableHead className="w-32 text-right">CPU</TableHead>
+              <TableHead className="w-32 text-right">内存</TableHead>
+              <TableHead className="w-32 text-right">磁盘</TableHead>
+              <TableHead className="w-26">
                 <SortableHead
                   label="创建"
                   sortKey="createdAt"
@@ -494,7 +502,7 @@ export function SandboxesPage() {
                   onSort={toggleSort}
                 />
               </TableHead>
-              <TableHead>
+              <TableHead className="w-26">
                 {/* 升序 = 最久没动的排最前:回收磁盘时先看这里 — 生命
                     周期策略从最后活动起算,这列才是"谁快被降温"的信号。
                     「策略」列刻意不设(2026-07-17 版式取舍):低频配置、
@@ -506,7 +514,7 @@ export function SandboxesPage() {
                   onSort={toggleSort}
                 />
               </TableHead>
-              <TableHead className="text-right">操作</TableHead>
+              <TableHead className="w-18 text-right">操作</TableHead>
             </TableRow>
           </TableHeader>
           <TableBody>
@@ -526,7 +534,8 @@ export function SandboxesPage() {
                   <Link
                     to="/sandboxes/$name"
                     params={{ name: sandbox.name }}
-                    className="font-mono font-medium hover:underline"
+                    className="block truncate font-mono font-medium hover:underline"
+                    title={sandbox.name}
                   >
                     {sandbox.name}
                   </Link>
@@ -535,13 +544,16 @@ export function SandboxesPage() {
                   <SandboxStateBadge state={sandbox.state} />
                 </TableCell>
                 <TableCell className="text-muted-foreground">
-                  <span className="inline-flex items-center gap-1.5">
+                  {/* Badge 自带 shrink-0:列不够宽时省略的是模板名,
+                      「可升级」标记寸步不让 — 它是行动信号,名字有 title 兜底。 */}
+                  <span className="flex items-center gap-1.5">
                     {/* 链接指向模板列表页(没有逐模板详情页);基础镜像
                         不是模板,没有可去处,保持纯文本。 */}
                     {sandbox.template ? (
                       <Link
                         to="/templates"
-                        className="hover:text-foreground hover:underline"
+                        className="truncate hover:text-foreground hover:underline"
+                        title={sandbox.template}
                       >
                         {sandbox.template}
                       </Link>
@@ -565,35 +577,38 @@ export function SandboxesPage() {
                   return (
                     <>
                       <UsageCell
-                        value={`${Math.round(m.cpuUsedPct)}% / ${m.cpuCount} 核`}
+                        value={`${Math.round(m.cpuUsedPct)}%`}
+                        cap={`${m.cpuCount} vCPU`}
                         pct={m.cpuUsedPct / m.cpuCount}
-                        title="百分比按单核计,多核可超 100%"
+                        title="百分比按单 vCPU 计,多 vCPU 可超 100%"
                       />
                       <UsageCell
-                        value={`${formatBytes(m.memUsedBytes)} / ${formatCap(m.memTotalBytes)}`}
+                        value={formatBytes(m.memUsedBytes)}
+                        cap={formatCap(m.memTotalBytes)}
                         pct={pctOf(m.memUsedBytes, m.memTotalBytes)}
                       />
                       <UsageCell
-                        value={`${formatBytes(m.diskUsedBytes)} / ${formatCap(m.diskTotalBytes)}`}
+                        value={formatBytes(m.diskUsedBytes)}
+                        cap={formatCap(m.diskTotalBytes)}
                         pct={pctOf(m.diskUsedBytes, m.diskTotalBytes)}
                         title="上限是名义配额:稀疏镜像,未写入不占宿主盘"
                       />
                     </>
                   );
                 })()}
-                {/* 带「前」:光秃的时长会被读成存活状态;空闲列不带 —
-                    表头已说明它是一段仍在计数的时长。 */}
+                {/* 两列都是粗粒度相对时刻(ago),精确时间戳在 title —
+                    扫表要的是数量级,查证才要精确到秒。 */}
                 <TableCell
                   className="tabular-nums text-muted-foreground"
                   title={`创建于:${new Date(sandbox.createdAt).toLocaleString()}`}
                 >
-                  {since(sandbox.createdAt)}前
+                  {ago(sandbox.createdAt)}
                 </TableCell>
                 <TableCell
                   className="tabular-nums text-muted-foreground"
                   title={`最近活动:${new Date(sandbox.lastActiveAt).toLocaleString()}`}
                 >
-                  {since(sandbox.lastActiveAt)}
+                  {ago(sandbox.lastActiveAt)}
                 </TableCell>
                 <TableCell className="text-right">
                   <SandboxRowMenu name={sandbox.name} />
diff --git a/packages/console/src/features/templates/pages/TemplatesPage.tsx b/packages/console/src/features/templates/pages/TemplatesPage.tsx
index 96df212..9331470 100644
--- a/packages/console/src/features/templates/pages/TemplatesPage.tsx
+++ b/packages/console/src/features/templates/pages/TemplatesPage.tsx
@@ -62,7 +62,7 @@ import {
   TableHeader,
   TableRow,
 } from '@/components/ui/table';
-import { since } from '@/features/sandboxes/format';
+import { ago } from '@/features/sandboxes/format';
 import { useSandboxes } from '@/features/sandboxes/hooks/useSandboxes';
 import {
   useRegisterTemplate,
@@ -363,7 +363,7 @@ export function TemplatesPage() {
                     )}
                   </TableCell>
                   <TableCell className="tabular-nums text-muted-foreground">
-                    {since(template.createdAt)}前
+                    {ago(template.createdAt)}
                   </TableCell>
                   {/* updatedAt 只在镜像真的换过时才走动;等于 createdAt
                       = 从没升级过,直说比重复注册时间更诚实。 */}
@@ -373,7 +373,7 @@ export function TemplatesPage() {
                   >
                     {template.updatedAt === template.createdAt
                       ? '还没升级'
-                      : `${since(template.updatedAt)}前`}
+                      : ago(template.updatedAt)}
                   </TableCell>
                   <TableCell className="text-right">
                     <TemplateRowMenu template={template} />

From e4303e0e84fb425a0259827af38fe43359ccbbb9 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 19 Jul 2026 15:21:15 +0800
Subject: [PATCH 111/133] =?UTF-8?q?=E6=B2=99=E7=AE=B1=E7=AD=96=E7=95=A5?=
 =?UTF-8?q?=E5=AD=A6=E4=BC=9A=E6=89=B9=E9=87=8F=E6=94=B9:=E5=88=97?=
 =?UTF-8?q?=E8=A1=A8=E9=A1=B5=E5=8B=BE=E9=80=89=E8=8B=A5=E5=B9=B2=E8=A1=8C?=
 =?UTF-8?q?=E5=90=8E,=E9=80=89=E4=B8=AD=E6=93=8D=E4=BD=9C=E5=8C=BA?=
 =?UTF-8?q?=E5=9C=A8=E3=80=8C=E9=94=80=E6=AF=81=E9=80=89=E4=B8=AD=E3=80=8D?=
 =?UTF-8?q?=E6=97=81=E5=A4=9A=E5=87=BA=E3=80=8C=E8=B0=83=E6=95=B4=E7=AD=96?=
 =?UTF-8?q?=E7=95=A5(N)=E3=80=8D=E3=80=82=E5=88=BB=E6=84=8F=E4=B8=8D?=
 =?UTF-8?q?=E8=AE=BE=E7=AD=96=E7=95=A5=E9=A1=B5=E2=80=94=E2=80=94=E7=AD=96?=
 =?UTF-8?q?=E7=95=A5=E4=B8=8D=E6=98=AF=E5=AE=9E=E4=BD=93,=E6=AF=8F?=
 =?UTF-8?q?=E4=B8=AA=E6=B2=99=E7=AE=B1=E8=BA=AB=E4=B8=8A=E4=B8=89=E4=B8=AA?=
 =?UTF-8?q?=E6=97=8B=E9=92=AE,=E4=B8=96=E4=B8=8A=E6=B2=A1=E6=9C=89"?=
 =?UTF-8?q?=E7=AD=96=E7=95=A5=E5=88=97=E8=A1=A8"=E5=8F=AF=E5=88=97,?=
 =?UTF-8?q?=E7=9C=9F=E5=81=9A=E4=B8=80=E9=A1=B5=E5=88=97=E5=87=BA=E6=9D=A5?=
 =?UTF-8?q?=E7=9A=84=E8=BF=98=E6=98=AF=E6=B2=99=E7=AE=B1,=E7=AD=89?=
 =?UTF-8?q?=E4=BA=8E=E5=A4=8D=E5=88=B6=E5=88=97=E8=A1=A8=E9=A1=B5;?=
 =?UTF-8?q?=E6=89=B9=E9=87=8F=E6=94=B9=E7=9C=9F=E6=AD=A3=E9=9C=80=E8=A6=81?=
 =?UTF-8?q?=E7=9A=84=E5=89=8D=E7=BD=AE=E8=83=BD=E5=8A=9B=E6=98=AF"?=
 =?UTF-8?q?=E5=9C=88=E5=AE=9A=E4=B8=80=E6=89=B9=E6=B2=99=E7=AE=B1",?=
 =?UTF-8?q?=E8=80=8C=E5=88=97=E8=A1=A8=E9=A1=B5=E7=9A=84=E6=90=9C=E7=B4=A2?=
 =?UTF-8?q?/=E7=8A=B6=E6=80=81/=E6=A0=87=E7=AD=BE=E7=AD=9B=E9=80=89+?=
 =?UTF-8?q?=E5=A4=8D=E9=80=89=E6=A1=86=E5=B0=B1=E6=98=AF=E7=8E=B0=E6=88=90?=
 =?UTF-8?q?=E7=9A=84=E5=9C=88=E5=AE=9A=E5=B7=A5=E5=85=B7,=E6=89=B9?=
 =?UTF-8?q?=E9=87=8F=E9=94=80=E6=AF=81=E5=B7=B2=E7=BB=8F=E5=9C=A8=E7=94=A8?=
 =?UTF-8?q?(=E4=B8=8E"=E5=88=86=E7=BB=84=3D=E6=89=93=E6=A0=87=E4=B8=8D?=
 =?UTF-8?q?=E5=BB=BA=20project=20=E5=AE=9E=E4=BD=93"=E5=90=8C=E4=B8=80?=
 =?UTF-8?q?=E6=9D=A1=E8=A3=81=E5=86=B3)=E3=80=82EditPolicyDialog=20?=
 =?UTF-8?q?=E4=BB=8E=E6=94=B6=E4=B8=80=E4=B8=AA=E6=B2=99=E7=AE=B1=E6=B3=9B?=
 =?UTF-8?q?=E5=8C=96=E6=88=90=E6=94=B6=E4=B8=80=E6=89=B9:=E8=AF=A6?=
 =?UTF-8?q?=E6=83=85=E9=A1=B5=E4=BC=A0=20[sandbox],=E5=88=97=E8=A1=A8?=
 =?UTF-8?q?=E9=A1=B5=E4=BC=A0=E9=80=89=E4=B8=AD=E9=9B=86,=E8=A1=A8?=
 =?UTF-8?q?=E5=8D=95/=E6=A0=A1=E9=AA=8C/=E6=8F=90=E4=BA=A4=E5=8F=AA?=
 =?UTF-8?q?=E6=B4=BB=E5=9C=A8=E8=BF=99=E4=B8=80=E5=A4=84,=E4=B8=8D?=
 =?UTF-8?q?=E4=B8=BA=E6=89=B9=E9=87=8F=E5=8F=A6=E9=80=A0=E7=AC=AC=E4=BA=8C?=
 =?UTF-8?q?=E4=BB=BD=E7=AD=96=E7=95=A5=E8=A1=A8=E5=8D=95;=E5=8E=9F=20useUp?=
 =?UTF-8?q?datePolicy=20hook=20=E5=9B=A0=E6=AD=A4=E5=A4=B1=E4=B8=9A,?=
 =?UTF-8?q?=E5=88=A0=E9=99=A4=E3=80=82=E9=A2=84=E5=A1=AB=E8=A6=81=E8=AF=9A?=
 =?UTF-8?q?=E5=AE=9E:=E5=8D=95=E4=B8=AA=E6=B2=99=E7=AE=B1=E6=88=96?=
 =?UTF-8?q?=E5=85=A8=E4=BD=93=E7=8E=B0=E5=80=BC=E4=B8=80=E8=87=B4=E6=89=8D?=
 =?UTF-8?q?=E9=A2=84=E5=A1=AB(=E7=BC=96=E8=BE=91=E7=9A=84=E6=98=AF"?=
 =?UTF-8?q?=E7=8E=B0=E5=9C=A8=E6=98=AF=E4=BB=80=E4=B9=88"),=E7=AD=96?=
 =?UTF-8?q?=E7=95=A5=E5=90=84=E5=BC=82=E6=97=B6=E9=A2=84=E5=A1=AB=E4=BB=BB?=
 =?UTF-8?q?=E4=BD=95=E4=B8=80=E4=B8=AA=E9=83=BD=E6=98=AF=E8=B0=8E=E6=8A=A5?=
 =?UTF-8?q?=E5=85=B6=E4=BD=99=E6=B2=99=E7=AE=B1=E7=9A=84=E7=8E=B0=E7=8A=B6?=
 =?UTF-8?q?,=E6=94=B9=E4=BB=8E=E7=A9=BA=E8=A1=A8=E5=8D=95=E8=B5=B7?=
 =?UTF-8?q?=E6=AD=A5=E5=B9=B6=E5=9C=A8=E6=8F=8F=E8=BF=B0=E9=87=8C=E6=98=8E?=
 =?UTF-8?q?=E8=AF=B4"=E6=8F=90=E4=BA=A4=E5=90=8E=E7=BB=9F=E4=B8=80?=
 =?UTF-8?q?=E4=B8=BA=E4=B8=8B=E9=9D=A2=E5=A1=AB=E7=9A=84=E5=80=BC"?=
 =?UTF-8?q?=E3=80=82=E6=8F=90=E4=BA=A4=E9=80=90=E4=B8=AA=E8=B0=83=20update?=
 =?UTF-8?q?Policy(daemon=20=E7=9A=84=20per-key=20=E9=94=81=E6=9C=AC?=
 =?UTF-8?q?=E6=9D=A5=E5=B0=B1=E9=80=90=E4=B8=AA=E8=A3=81=E5=86=B3),?=
 =?UTF-8?q?=E5=A4=B1=E8=B4=A5=E7=9A=84=E7=95=99=E5=9C=A8=E5=BC=B9=E7=AA=97?=
 =?UTF-8?q?=E9=87=8C=E7=82=B9=E5=90=8D+=E9=99=84=E7=AC=AC=E4=B8=80?=
 =?UTF-8?q?=E6=9D=A1=E9=94=99=E8=AF=AF=E5=8E=9F=E5=9B=A0(=E6=89=B9?=
 =?UTF-8?q?=E9=87=8F=E5=A4=B1=E8=B4=A5=E5=87=A0=E4=B9=8E=E6=80=BB=E6=98=AF?=
 =?UTF-8?q?=E5=90=8C=E4=B8=80=E4=B8=AA=E5=8E=9F=E5=9B=A0),=E5=BC=B9?=
 =?UTF-8?q?=E7=AA=97=E4=B8=8D=E5=85=B3=E2=80=94=E2=80=94=E6=94=B9=E6=88=90?=
 =?UTF-8?q?=E5=8A=9F=E7=9A=84=E5=B7=B2=E8=AE=B0=E5=85=A5=E8=B4=A6=E6=9C=AC?=
 =?UTF-8?q?,=E5=86=8D=E7=82=B9=E4=BF=9D=E5=AD=98=E6=98=AF=E5=B9=82?=
 =?UTF-8?q?=E7=AD=89=E8=A1=A5=E5=86=99=E4=B8=8D=E6=98=AF=E9=87=8D=E5=A4=8D?=
 =?UTF-8?q?=E5=8A=A8=E4=BD=9C;=E6=88=90=E8=B4=A5=E9=83=BD=E5=88=B7?=
 =?UTF-8?q?=E6=96=B0=E5=88=97=E8=A1=A8,=E9=83=A8=E5=88=86=E6=88=90?=
 =?UTF-8?q?=E5=8A=9F=E4=B9=9F=E8=A6=81=E5=A6=82=E5=AE=9E=E8=B7=9F=E4=B8=8A?=
 =?UTF-8?q?=E3=80=82=E5=8E=9F=E5=BC=B9=E7=AA=97=E8=AF=AD=E4=B9=89=E5=8E=9F?=
 =?UTF-8?q?=E6=A0=B7=E4=BF=9D=E7=95=99:=E5=8F=AA=E6=94=B9=E8=B4=A6?=
 =?UTF-8?q?=E6=9C=AC=E4=B8=8D=E5=94=A4=E9=86=92,=E6=B2=89=E7=9D=A1?=
 =?UTF-8?q?=E7=9A=84=E6=B2=99=E7=AE=B1=E4=B8=8D=E8=A2=AB=E6=89=B9=E9=87=8F?=
 =?UTF-8?q?=E6=93=8D=E4=BD=9C=E5=90=B5=E9=86=92,=E7=A9=BA=E9=97=B2?=
 =?UTF-8?q?=E8=AE=A1=E6=97=B6=E4=B8=8D=E9=87=8D=E7=BD=AE=E3=80=82=E6=94=B9?=
 =?UTF-8?q?=E5=AE=8C=E4=B8=8D=E6=B8=85=E9=80=89=E4=B8=AD=E2=80=94=E2=80=94?=
 =?UTF-8?q?=E8=A1=8C=E8=BF=98=E5=9C=A8,=E9=A1=BA=E6=89=8B=E6=A0=B8?=
 =?UTF-8?q?=E5=AF=B9=E6=88=96=E6=8E=A5=E7=9D=80=E9=94=80=E6=AF=81=E9=83=BD?=
 =?UTF-8?q?=E7=94=A8=E5=BE=97=E4=B8=8A=E8=BF=99=E6=89=B9=E5=8B=BE=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../sandboxes/components/EditPolicyDialog.tsx | 138 ++++++++++++------
 .../features/sandboxes/hooks/useSandboxes.ts  |  12 +-
 .../sandboxes/pages/SandboxDetailPage.tsx     |   2 +-
 .../sandboxes/pages/SandboxesPage.tsx         |   7 +-
 4 files changed, 102 insertions(+), 57 deletions(-)

diff --git a/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx b/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
index 1a16084..3f220d2 100644
--- a/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
+++ b/packages/console/src/features/sandboxes/components/EditPolicyDialog.tsx
@@ -24,66 +24,110 @@ import { Input } from '@/components/ui/input';
 import { Spinner } from '@/components/ui/spinner';
 import { Switch } from '@/components/ui/switch';
 import { useConfig } from '@/features/settings/hooks/useConfig';
+import { updatePolicy } from '@/lib/api';
+import { queryClient } from '@/lib/queryClient';
 import { durationHint } from '../format';
-import { useUpdatePolicy } from '../hooks/useSandboxes';
+
+/** 三旋钮逐项比:批量编辑要判断"全体现值是否一致"。 */
+function samePolicy(a: Sandbox['policy'], b: Sandbox['policy']): boolean {
+  return (
+    a.freezeAfterSeconds === b.freezeAfterSeconds &&
+    a.stopAfterSeconds === b.stopAfterSeconds &&
+    a.archiveAfterSeconds === b.archiveAfterSeconds
+  );
+}
 
 /**
  * acquire 只在创建时收策略,这个弹窗是之后的正门:updatePolicy 纯改账本,
  * 不唤醒、不重置空闲时钟 — 把跑了几天的沙箱升格成常驻 agent 不再需要
  * 销毁重建(那会销毁磁盘)。三个旋钮整体提交:界面上看到什么就写下什么,
  * 关掉"永不停止"时归档旋钮的取舍也一并说清,不留隐式合并的悬念。
+ *
+ * 收一批沙箱,一个就是详情页的单改,多个就是列表页的批量改 — 表单、
+ * 校验、提交只活在这一处,不为批量另造第二份策略表单(也不设策略页:
+ * 策略不是实体,批量的前置动作"圈定哪些沙箱"正是列表页的筛选+勾选)。
+ * updatePolicy 逐个调用(daemon 的 per-key 锁本来就逐个裁决),失败的
+ * 留在弹窗里点名,弹窗不关 — 改对了几个账本已经记下,再点一次保存是
+ * 幂等的补写,不是重复动作。
  */
-export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
+export function EditPolicyDialog({ sandboxes }: { sandboxes: Sandbox[] }) {
   const [open, setOpen] = useState(false);
   const [freezeAfter, setFreezeAfter] = useState('');
   const [neverStop, setNeverStop] = useState(false);
   const [stopAfter, setStopAfter] = useState('');
   const [neverArchive, setNeverArchive] = useState(false);
   const [archiveAfter, setArchiveAfter] = useState('');
-  const mutation = useUpdatePolicy();
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
   const archive = useConfig().data?.archive;
 
-  // 每次打开都从沙箱的现值起步 — 编辑的是"现在是什么",不是空表单。
+  const first = sandboxes[0];
+  const single = sandboxes.length === 1 ? (first ?? null) : null;
+  // 批量时的"现值"只在全体一致时存在:策略各异还预填某一个,等于
+  // 谎报其余沙箱的现状,不如从空表单起步,填什么就统一成什么。
+  const shared =
+    first && sandboxes.every((s) => samePolicy(s.policy, first.policy))
+      ? first.policy
+      : null;
+
+  // 每次打开都从现值起步(有现值时) — 编辑的是"现在是什么",不是空表单。
   const loadCurrent = () => {
-    const { policy } = sandbox;
-    setFreezeAfter(String(policy.freezeAfterSeconds));
-    setNeverStop(policy.stopAfterSeconds === null);
+    setFreezeAfter(shared ? String(shared.freezeAfterSeconds) : '');
+    setNeverStop(shared !== null && shared.stopAfterSeconds === null);
     setStopAfter(
-      policy.stopAfterSeconds === null ? '' : String(policy.stopAfterSeconds),
+      shared?.stopAfterSeconds ? String(shared.stopAfterSeconds) : '',
     );
-    setNeverArchive(policy.archiveAfterSeconds === null);
+    setNeverArchive(shared !== null && shared.archiveAfterSeconds === null);
     setArchiveAfter(
-      policy.archiveAfterSeconds === null
-        ? ''
-        : String(policy.archiveAfterSeconds),
+      shared?.archiveAfterSeconds ? String(shared.archiveAfterSeconds) : '',
     );
-    mutation.reset();
+    setError(null);
   };
 
-  const submit = () => {
-    mutation.mutate(
-      {
-        name: sandbox.name,
-        policy: {
-          freezeAfterSeconds: Number(freezeAfter),
-          stopAfterSeconds: neverStop ? null : Number(stopAfter),
-          // 永不停止连带永不归档(没停过就没得归档);归档未启用时保持
-          // 现值不动 — 一个 daemon 没资格许诺的旋钮,这里也不碰。
-          ...(archive?.enabled
-            ? {
-                archiveAfterSeconds:
-                  neverStop || neverArchive ? null : Number(archiveAfter),
-              }
-            : {}),
-        },
-      },
-      {
-        onSuccess: () => {
-          toast.success(`「${sandbox.name}」的策略已更新`);
-          setOpen(false);
-        },
-      },
-    );
+  const submit = async () => {
+    const policy = {
+      freezeAfterSeconds: Number(freezeAfter),
+      stopAfterSeconds: neverStop ? null : Number(stopAfter),
+      // 永不停止连带永不归档(没停过就没得归档);归档未启用时保持
+      // 现值不动 — 一个 daemon 没资格许诺的旋钮,这里也不碰。
+      ...(archive?.enabled
+        ? {
+            archiveAfterSeconds:
+              neverStop || neverArchive ? null : Number(archiveAfter),
+          }
+        : {}),
+    };
+    setPending(true);
+    const failures: Array<{ name: string; message: string }> = [];
+    for (const sandbox of sandboxes) {
+      try {
+        await updatePolicy(sandbox.name, policy);
+      } catch (cause) {
+        failures.push({
+          name: sandbox.name,
+          message: cause instanceof Error ? cause.message : String(cause),
+        });
+      }
+    }
+    setPending(false);
+    // 成败都刷新:部分成功也已经改了账本,列表要如实跟上。
+    void queryClient.invalidateQueries({ queryKey: ['sandboxes'] });
+    const firstFailure = failures[0];
+    if (!firstFailure) {
+      toast.success(
+        single
+          ? `「${single.name}」的策略已更新`
+          : `已更新 ${sandboxes.length} 个沙箱的策略`,
+      );
+      setOpen(false);
+    } else if (single) {
+      setError(firstFailure.message);
+    } else {
+      // 批量失败几乎总是同一个原因,点名全部+报第一条错误就够诊断。
+      setError(
+        `${failures.length} 个更新失败:${failures.map((f) => f.name).join('、')} — ${firstFailure.message}`,
+      );
+    }
   };
 
   const filled = (raw: string) => raw.trim() !== '' && Number(raw) > 0;
@@ -105,21 +149,29 @@ export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
           <Button variant="outline" size="sm">
             <HugeiconsIcon icon={Settings02Icon} />
             调整策略
+            {!single && `(${sandboxes.length})`}
           </Button>
         }
       />
       <DialogContent className="sm:max-w-md">
         <DialogHeader>
-          <DialogTitle>调整「{sandbox.name}」的生命周期策略</DialogTitle>
+          <DialogTitle>
+            {single
+              ? `调整「${single.name}」的生命周期策略`
+              : `批量调整 ${sandboxes.length} 个沙箱的策略`}
+          </DialogTitle>
           <DialogDescription>
             立即生效,只改账本 — 沉睡的沙箱不会被吵醒,空闲计时也不重置
             (新阈值按已累积的空闲时间判定)。
+            {!single &&
+              shared === null &&
+              '选中沙箱的当前策略不一致,提交后统一为下面填的值。'}
           </DialogDescription>
         </DialogHeader>
         <form
           onSubmit={(event) => {
             event.preventDefault();
-            submit();
+            void submit();
           }}
         >
           <FieldGroup>
@@ -200,13 +252,11 @@ export function EditPolicyDialog({ sandbox }: { sandbox: Sandbox }) {
                 )}
               </>
             )}
-            {mutation.isError && (
-              <FieldError>{mutation.error.message}</FieldError>
-            )}
+            {error && <FieldError>{error}</FieldError>}
           </FieldGroup>
           <DialogFooter className="mt-6">
-            <Button type="submit" disabled={!valid || mutation.isPending}>
-              {mutation.isPending && <Spinner />}
+            <Button type="submit" disabled={!valid || pending}>
+              {pending && <Spinner />}
               保存
             </Button>
           </DialogFooter>
diff --git a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
index 96980d4..73a564d 100644
--- a/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
+++ b/packages/console/src/features/sandboxes/hooks/useSandboxes.ts
@@ -1,4 +1,4 @@
-import type { AcquireRequest, LifecyclePolicyOverride } from '@dormice/shared';
+import type { AcquireRequest } from '@dormice/shared';
 import {
   keepPreviousData,
   useMutation,
@@ -14,7 +14,6 @@ import {
   listSandboxImages,
   listSandboxMetrics,
   rebuildSandbox,
-  updatePolicy,
 } from '@/lib/api';
 
 /**
@@ -115,15 +114,6 @@ export function useAcquireSandbox() {
   });
 }
 
-export function useUpdatePolicy() {
-  const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: (args: { name: string; policy: LifecyclePolicyOverride }) =>
-      updatePolicy(args.name, args.policy),
-    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['sandboxes'] }),
-  });
-}
-
 export function useRebuildSandbox() {
   const queryClient = useQueryClient();
   return useMutation({
diff --git a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
index 78f08c0..dadcfa6 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxDetailPage.tsx
@@ -81,7 +81,7 @@ export function SandboxDetailPage() {
         <LifecycleCountdown sandbox={sandbox} />
       </div>
       <div className="flex items-center gap-2">
-        <EditPolicyDialog sandbox={sandbox} />
+        <EditPolicyDialog sandboxes={[sandbox]} />
         <RebuildSandboxButton name={sandbox.name} />
         <DestroySandboxButton
           name={sandbox.name}
diff --git a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
index b96de2e..897d829 100644
--- a/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
+++ b/packages/console/src/features/sandboxes/pages/SandboxesPage.tsx
@@ -62,6 +62,7 @@ import { queryClient } from '@/lib/queryClient';
 import { cn } from '@/lib/utils';
 import { CreateSandboxDialog } from '../components/CreateSandboxDialog';
 import { DestroySandboxDialog } from '../components/DestroySandboxButton';
+import { EditPolicyDialog } from '../components/EditPolicyDialog';
 import { SandboxStateBadge } from '../components/SandboxStateBadge';
 import { UpgradableBadge } from '../components/UpgradableBadge';
 import { ago, STATE_LABELS } from '../format';
@@ -426,7 +427,11 @@ export function SandboxesPage() {
           {filtered.length} / {sandboxes.length} 个
         </span>
         {selectedVisible.length > 0 && (
-          <div className="ml-auto">
+          <div className="ml-auto flex items-center gap-2">
+            {/* 批量改策略与批量销毁同住选中操作区:圈定沙箱靠的就是
+                这页的筛选+勾选,不另设策略页(策略不是实体)。改完不清
+                选中 — 行还在,顺手核对或接着销毁都用得上这批勾。 */}
+            <EditPolicyDialog sandboxes={selectedVisible} />
             <BulkDestroyButton
               names={selectedVisible.map((s) => s.name)}
               onDone={() => setSelected(new Set())}

From b3a58b474c1e3fe823c6d04a56be435ac50966c8 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 19 Jul 2026 17:05:40 +0800
Subject: [PATCH 112/133] =?UTF-8?q?=E8=BF=90=E8=90=A5=E6=97=8B=E9=92=AE?=
 =?UTF-8?q?=E6=90=AC=E8=BF=9B=E8=B4=A6=E6=9C=AC:=E5=AE=B9=E9=87=8F?=
 =?UTF-8?q?=E4=B8=8A=E9=99=90=E3=80=81=E6=96=B0=E6=B2=99=E7=AE=B1=E9=BB=98?=
 =?UTF-8?q?=E8=AE=A4=E9=85=8D=E9=A2=9D=E3=80=81=E9=BB=98=E8=AE=A4=E7=94=9F?=
 =?UTF-8?q?=E5=91=BD=E5=91=A8=E6=9C=9F=E7=AD=96=E7=95=A5=E4=BB=8E"?=
 =?UTF-8?q?=E6=94=B9=20env=20+=20=E9=87=8D=E5=90=AF"=E5=8D=87=E6=A0=BC?=
 =?UTF-8?q?=E4=B8=BA=E7=BD=91=E9=A1=B5=E7=83=AD=E6=94=B9=E3=80=82=E5=88=86?=
 =?UTF-8?q?=E7=95=8C=E7=BA=BF=E4=B8=80=E5=8F=A5=E8=AF=9D:=E6=94=B9?=
 =?UTF-8?q?=E4=BA=86=E6=98=AF=E8=BF=90=E8=90=A5=E5=86=B3=E7=AD=96=E7=9A=84?=
 =?UTF-8?q?=E8=BF=9B=E8=B4=A6=E6=9C=AC(=E8=BF=99=E4=B8=89=E7=BB=84),?=
 =?UTF-8?q?=E6=94=B9=E4=BA=86=E7=AD=89=E4=BA=8E=E6=8D=A2=E4=B8=80=E5=8F=B0?=
 =?UTF-8?q?=20daemon=20=E7=9A=84=E7=95=99=20env(=E7=AB=AF=E5=8F=A3/token/e?=
 =?UTF-8?q?xecutor/=E6=95=B0=E6=8D=AE=E7=9B=AE=E5=BD=95/=E5=9F=9F=E5=90=8D?=
 =?UTF-8?q?/S3)=E2=80=94=E2=80=94daemon=20=E4=BE=9D=E7=84=B6=E7=BB=9D?=
 =?UTF-8?q?=E4=B8=8D=E6=94=B9=E5=86=99=E8=87=AA=E5=B7=B1=E7=9A=84=E7=8E=AF?=
 =?UTF-8?q?=E5=A2=83=E6=96=87=E4=BB=B6,=E9=82=A3=E4=B8=AA=E5=AE=89?=
 =?UTF-8?q?=E5=85=A8=E7=AD=89=E7=BA=A7=E7=9A=84=E5=86=B3=E5=AE=9A=E8=A2=AB?=
 =?UTF-8?q?=E6=95=B4=E4=B8=AA=E7=BB=95=E5=BC=80=E4=BA=86=E3=80=82=E6=96=B0?=
 =?UTF-8?q?=E8=A1=A8=20runtime=5Fsettings=20=E5=8D=95=E8=A1=8C=E5=9B=BA?=
 =?UTF-8?q?=E5=AE=9A=20id(console=5Faccount=20=E5=85=88=E4=BE=8B=E3=80=81t?=
 =?UTF-8?q?yped=20=E5=88=97=E4=B8=8D=E7=94=A8=20JSON=20blob),=E9=A6=96?=
 =?UTF-8?q?=E5=90=AF=20ensureRuntimeSettings=20=E7=94=A8=E5=90=8C=E5=90=8D?=
 =?UTF-8?q?=20env=20=E5=8F=98=E9=87=8F+shared=20=E9=BB=98=E8=AE=A4?=
 =?UTF-8?q?=E7=AD=96=E7=95=A5=E6=92=AD=E7=A7=8D(=E5=BD=92=E6=A1=A3?=
 =?UTF-8?q?=E9=BB=98=E8=AE=A4=E7=94=B1=20archiver=20=E6=98=AF=E5=90=A6?=
 =?UTF-8?q?=E5=AD=98=E5=9C=A8=E8=A3=81=E5=86=B3),=E6=AD=A4=E5=90=8E?=
 =?UTF-8?q?=E8=B4=A6=E6=9C=AC=E6=98=AF=E5=94=AF=E4=B8=80=E7=9C=9F=E7=9B=B8?=
 =?UTF-8?q?:=E5=90=8C=E5=90=8D=20env=20=E9=99=8D=E7=BA=A7=E4=B8=BA?=
 =?UTF-8?q?=E9=A6=96=E5=90=AF=E7=A7=8D=E5=AD=90,=E8=A1=8C=E5=AD=98?=
 =?UTF-8?q?=E5=9C=A8=E5=90=8E=E5=86=8D=E6=94=B9=20env=20=E5=88=BB=E6=84=8F?=
 =?UTF-8?q?=E6=97=A0=E6=95=88=E2=80=94=E2=80=94=E4=B8=80=E4=B8=AA=E6=97=8B?=
 =?UTF-8?q?=E9=92=AE=E4=B8=A4=E4=B8=AA=E6=B4=BB=E6=9D=A5=E6=BA=90=E6=98=AF?=
 =?UTF-8?q?=E5=B8=B8=E8=AE=BE=E6=AD=A7=E4=B9=89,settings.test=20=E7=94=A8"?=
 =?UTF-8?q?=E5=90=8C=E8=B4=A6=E6=9C=AC=E6=8D=A2=20env=20=E9=87=8D=E5=90=AF?=
 =?UTF-8?q?"=E9=92=89=E6=AD=BB=E8=B4=A6=E6=9C=AC=E8=B5=A2=E3=80=82?=
 =?UTF-8?q?=E8=AF=BB=E5=8D=8A=E8=BE=B9=E6=90=AD=20getConfig=20=E8=BD=A6(se?=
 =?UTF-8?q?ttings=20=E5=AF=B9=E8=B1=A1,updatedAt=20null=3D=E8=BF=98?=
 =?UTF-8?q?=E6=98=AF=E7=A7=8D=E5=AD=90=E5=8E=9F=E6=A0=B7;archive.defaultSe?=
 =?UTF-8?q?conds=20=E6=94=B9=E8=AF=BB=E8=B4=A6=E6=9C=AC=E9=BB=98=E8=AE=A4?=
 =?UTF-8?q?=E7=AD=96=E7=95=A5),=E5=86=99=E5=8D=8A=E8=BE=B9=20POST=20/updat?=
 =?UTF-8?q?eSettings:=E7=BB=99=E5=93=AA=E7=BB=84=E6=95=B4=E7=BB=84?=
 =?UTF-8?q?=E6=9B=BF=E6=8D=A2(updatePolicy=20=E7=9A=84=E8=A7=84=E7=9F=A9),?=
 =?UTF-8?q?=E7=A9=BA=20patch=20400,=E5=BD=92=E6=A1=A3=E6=9C=AA=E9=85=8D?=
 =?UTF-8?q?=E6=97=B6=20defaultPolicy=20=E6=B1=82=E5=BD=92=E6=A1=A3?=
 =?UTF-8?q?=E6=8B=92=20400=E3=80=82=E6=8C=82=E8=BF=9B=20apiKey=20=E5=90=8C?=
 =?UTF-8?q?=E4=B8=80=E4=B8=AA=20admin=20scope=E2=80=94=E2=80=94=E6=B3=84?=
 =?UTF-8?q?=E9=9C=B2=E7=9A=84=E8=87=AA=E5=8A=A8=E5=8C=96=20key=20=E4=B8=8D?=
 =?UTF-8?q?=E8=AE=B8=E6=8A=AC=E9=AB=98=E7=BA=A6=E6=9D=9F=E5=AE=83=E8=87=AA?=
 =?UTF-8?q?=E5=B7=B1=E7=9A=84=E4=B8=8A=E9=99=90,403=20=E6=96=87=E6=A1=88?=
 =?UTF-8?q?=E5=A6=82=E5=AE=9E=E6=89=A9=E4=B8=BA=20cannot=20manage=20API=20?=
 =?UTF-8?q?keys=20or=20settings(cli=20=E6=B5=8B=E8=AF=95=E6=AD=A3=E5=88=99?=
 =?UTF-8?q?=E5=90=8C=E6=AD=A5);=E6=B4=BB=E5=8A=A8=E7=8E=AF=E6=96=B0=20kind?=
 =?UTF-8?q?=20settings-updated=20=E5=B8=A6=20actor=20=E5=BD=92=E5=9B=A0,de?=
 =?UTF-8?q?tail=20=E7=82=B9=E5=90=8D=E5=8A=A8=E4=BA=86=E5=93=AA=E5=87=A0?=
 =?UTF-8?q?=E7=BB=84=E3=80=82=E7=AB=8B=E5=8D=B3=E7=94=9F=E6=95=88=E9=9D=A0?=
 =?UTF-8?q?=E6=B6=88=E8=B4=B9=E7=82=B9=E5=85=A8=E9=83=A8=E7=8E=B0=E8=AF=BB?=
 =?UTF-8?q?:acquire=20=E9=97=A8=E6=A7=9B=E4=B8=A4=E9=9D=A2(=E5=8E=9F?=
 =?UTF-8?q?=E7=94=9F+E2B,429=20=E6=96=87=E6=A1=88=E6=94=B9=E6=8C=87=20sett?=
 =?UTF-8?q?ings)=E3=80=81getHostMetrics=20=E5=AE=B9=E9=87=8F=E4=B8=8A?=
 =?UTF-8?q?=E6=8A=A5=E3=80=81resolvePolicy=20=E6=8D=A2=E7=AD=BE=E5=90=8D?=
 =?UTF-8?q?=E6=94=B6=20defaults+archiveEnabled=20=E4=B8=A4=E5=8F=82(?=
 =?UTF-8?q?=E9=BB=98=E8=AE=A4=E7=AD=96=E7=95=A5=E4=B8=8E=E5=BD=92=E6=A1=A3?=
 =?UTF-8?q?=E8=B5=84=E6=A0=BC=E6=98=AF=E4=B8=A4=E4=B8=AA=E9=97=AE=E9=A2=98?=
 =?UTF-8?q?:=E9=BB=98=E8=AE=A4=20never-archive=20=E7=9A=84=20daemon=20?=
 =?UTF-8?q?=E4=BB=8D=E6=8E=A5=E5=8F=97=E6=98=BE=E5=BC=8F=E5=BD=92=E6=A1=A3?=
 =?UTF-8?q?=20override,policy.test=20=E6=96=B0=E5=A2=9E=E4=B8=A4=E4=BE=8B?=
 =?UTF-8?q?=E9=92=89=E4=BD=8F)=E3=80=81DockerExecutor=20=E4=B8=89=E8=B5=84?=
 =?UTF-8?q?=E6=BA=90=E6=97=8B=E9=92=AE=E4=BB=8E=E6=9E=84=E9=80=A0=E6=97=B6?=
 =?UTF-8?q?=E5=AE=9A=E6=AD=BB=E6=94=B9=E4=B8=BA=20resources:=20()=20=3D>?=
 =?UTF-8?q?=20{...}=20=E6=B4=BB=E8=A7=86=E5=9B=BE=E2=80=94=E2=80=94?=
 =?UTF-8?q?=E7=9B=98=E5=9C=A8=20provisionDisk/importDisk=20=E5=87=BA?=
 =?UTF-8?q?=E7=94=9F=E6=97=B6=E8=AF=BB=E3=80=81CPU/=E5=86=85=E5=AD=98?=
 =?UTF-8?q?=E5=9C=A8=E6=AF=8F=E6=AC=A1=20launchContainer=20=E8=AF=BB,execu?=
 =?UTF-8?q?tor=20=E6=8F=A3=E4=B8=80=E4=BB=BD=E8=BF=87=E6=9C=9F=E6=8B=B7?=
 =?UTF-8?q?=E8=B4=9D=E5=B0=B1=E6=98=AF=E7=AC=AC=E4=BA=8C=E7=9C=9F=E7=9B=B8?=
 =?UTF-8?q?=E3=80=82=E8=AF=AD=E4=B9=89=E8=BE=B9=E7=95=8C=E5=9C=A8=E6=AF=8F?=
 =?UTF-8?q?=E4=B8=AA=E5=BC=B9=E7=AA=97=E9=87=8C=E8=AF=B4=E7=A9=BF:?=
 =?UTF-8?q?=E5=AE=B9=E9=87=8F=E7=AE=A1=E4=B8=8B=E4=B8=80=E6=AC=A1=E5=88=9B?=
 =?UTF-8?q?=E5=BB=BA(=E8=B0=83=E5=88=B0=E7=8E=B0=E5=AD=98=E9=87=8F?=
 =?UTF-8?q?=E4=BB=A5=E4=B8=8B=E5=90=88=E6=B3=95,=E4=BA=8B=E6=95=85?=
 =?UTF-8?q?=E6=97=B6=E8=A6=81=E8=83=BD=E8=AF=B4"=E4=B8=8D=E5=87=86?=
 =?UTF-8?q?=E5=86=8D=E5=A4=9A");CPU/=E5=86=85=E5=AD=98=E7=AE=A1=E4=B8=8B?=
 =?UTF-8?q?=E4=B8=80=E6=AC=A1=E5=AE=B9=E5=99=A8=E5=87=BA=E7=94=9F,?=
 =?UTF-8?q?=E5=90=AB=E5=81=9C=E6=AD=A2=E5=90=8E=E5=86=B7=E5=90=AF=E5=8A=A8?=
 =?UTF-8?q?=E7=9A=84=E5=AD=98=E9=87=8F=E6=B2=99=E7=AE=B1;=E7=A3=81?=
 =?UTF-8?q?=E7=9B=98=E5=8F=AA=E5=9C=A8=E6=B2=99=E7=AE=B1=E7=AC=AC=E4=B8=80?=
 =?UTF-8?q?=E6=AC=A1=E5=88=9B=E5=BB=BA=E6=97=B6=E5=AE=9A=E5=9E=8B(?=
 =?UTF-8?q?=E7=9B=98=E6=98=AF=E6=9C=AC=E4=BD=93,=E6=B0=B8=E4=B8=8D?=
 =?UTF-8?q?=E5=8E=9F=E5=9C=B0=E6=94=B9=E5=B0=BA=E5=AF=B8);=E9=BB=98?=
 =?UTF-8?q?=E8=AE=A4=E7=AD=96=E7=95=A5=E5=8F=AA=E7=AE=A1=E4=B9=8B=E5=90=8E?=
 =?UTF-8?q?=E6=96=B0=E5=BB=BA,=E5=AD=98=E9=87=8F=E8=B5=B0=20updatePolicy/?=
 =?UTF-8?q?=E6=89=B9=E9=87=8F=E6=94=B9=E3=80=82console=20=E8=AE=BE?=
 =?UTF-8?q?=E7=BD=AE=E9=A1=B5=E9=95=BF=E6=88=90=E4=B8=A4=E6=AE=B5:?=
 =?UTF-8?q?=E4=B8=8A=E6=AE=B5=E8=BF=90=E8=90=A5=E6=97=8B=E9=92=AE=E5=8D=A1?=
 =?UTF-8?q?=E4=B8=89=E8=A1=8C=E4=B8=89=E5=BC=B9=E7=AA=97(RuntimeSettingsCa?=
 =?UTF-8?q?rd),=E4=B8=8B=E6=AE=B5=20env=20=E5=8F=AA=E8=AF=BB=E8=A1=A8?=
 =?UTF-8?q?=E5=8E=9F=E6=A0=B7=E3=80=81=E5=9B=9B=E4=B8=AA=E8=A2=AB=E6=8E=A5?=
 =?UTF-8?q?=E7=AE=A1=E7=9A=84=E9=94=AE=E6=B3=A8=E6=98=8E"=E9=A6=96?=
 =?UTF-8?q?=E5=90=AF=E7=A7=8D=E5=AD=90=E5=80=BC";SDK=20=E5=8A=A0=20updateS?=
 =?UTF-8?q?ettings=20=E4=BF=9D=E4=BD=8F=E5=8E=9F=E7=94=9F=E5=85=A8?=
 =?UTF-8?q?=E6=96=B9=E6=B3=95=E4=B8=8D=E5=8F=98=E9=87=8F,CLI=20=E5=88=BB?=
 =?UTF-8?q?=E6=84=8F=E4=B8=8D=E5=8A=A0(console/SDK=20=E5=B7=B2=E8=A6=86?=
 =?UTF-8?q?=E7=9B=96)=E3=80=82website=20=E4=BA=94=E9=A1=B5=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E5=90=8C=E6=AD=A5=E7=A7=8D=E5=AD=90=E8=AF=AD=E4=B9=89?=
 =?UTF-8?q?=E4=B8=8E=E6=96=B0=E5=8A=A8=E8=AF=8D=E3=80=82=E6=96=B0=E5=A2=9E?=
 =?UTF-8?q?=20settings.test=20=E5=85=AB=E4=BE=8B(=E7=A7=8D=E5=AD=90/?=
 =?UTF-8?q?=E8=B4=A6=E6=9C=AC=E8=B5=A2/=E7=83=AD=E6=94=B9=E7=AB=8B?=
 =?UTF-8?q?=E5=8D=B3=E7=94=9F=E6=95=88/=E7=BB=84=E7=8B=AC=E7=AB=8B?=
 =?UTF-8?q?=E6=9B=BF=E6=8D=A2/=E5=BD=92=E6=A1=A3=E6=8B=92=E7=BB=9D/?=
 =?UTF-8?q?=E5=9D=8F=E5=BA=8F=E6=8B=92=E7=BB=9D/=E6=B4=BB=E5=8A=A8?=
 =?UTF-8?q?=E5=BD=92=E5=9B=A0/key=20403)+sdk=20=E7=9C=9F=20HTTP=20?=
 =?UTF-8?q?=E4=B8=A4=E4=BE=8B+e2e=20=E9=BB=91=E7=9B=92=E4=B8=80=E4=BE=8B;s?=
 =?UTF-8?q?erver=20486=E3=80=81sdk=2031=E3=80=81cli=2049=E3=80=81e2e=2083?=
 =?UTF-8?q?=20=E5=85=A8=E7=BB=BF=E3=80=82docker=20=E5=90=88=E5=90=8C?=
 =?UTF-8?q?=E8=80=83=E5=8D=B7=E6=94=B9=E7=94=A8=E9=9D=99=E6=80=81=20resour?=
 =?UTF-8?q?ces=20=E9=97=AD=E5=8C=85(=E8=80=83=E5=9C=BA=E6=97=A0=20daemon?=
 =?UTF-8?q?=20=E6=97=A0=E8=B4=A6=E6=9C=AC),=E7=9C=9F=E6=9C=BA=E8=A1=A5?=
 =?UTF-8?q?=E8=80=83=E5=BE=85=E6=8E=A8=E9=80=81=E5=90=8E=E8=B7=91=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/src/native.test.ts                        |  14 +
 packages/cli/src/commands.test.ts             |   2 +-
 .../console/src/features/activity/kinds.ts    |   3 +
 .../components/RuntimeSettingsCard.tsx        | 460 +++++++++++++
 .../features/settings/pages/SettingsPage.tsx  |  26 +-
 packages/console/src/lib/api.ts               |  12 +-
 packages/sdk/src/client.test.ts               |  28 +
 packages/sdk/src/client.ts                    |  20 +
 .../server/drizzle/0014_runtime-settings.sql  |  11 +
 .../server/drizzle/meta/0014_snapshot.json    | 632 ++++++++++++++++++
 packages/server/drizzle/meta/_journal.json    |   7 +
 packages/server/src/app.test.ts               |   5 +-
 packages/server/src/app.ts                    |  18 +-
 packages/server/src/auth.ts                   |  18 +-
 packages/server/src/db/schema.ts              |  28 +
 packages/server/src/db/settings.ts            | 127 ++++
 packages/server/src/e2b/control.ts            |  22 +-
 .../src/executor/docker.contract.test.ts      |   6 +-
 packages/server/src/executor/docker.ts        |  33 +-
 packages/server/src/main.ts                   |  23 +-
 packages/server/src/policy.test.ts            |  92 ++-
 packages/server/src/policy.ts                 |  38 +-
 packages/server/src/routes/config.ts          |  61 +-
 packages/server/src/routes/host.ts            |   4 +-
 packages/server/src/routes/sandboxes.ts       |  15 +-
 packages/server/src/routes/settings.test.ts   | 221 ++++++
 packages/server/src/routes/settings.ts        |  81 +++
 packages/shared/src/activity.ts               |   2 +
 packages/shared/src/config.ts                 |  20 +-
 packages/shared/src/index.ts                  |   1 +
 packages/shared/src/settings.ts               |  77 +++
 website/content/docs/configuration.mdx        |  10 +-
 website/content/docs/console.mdx              |  10 +-
 website/content/docs/http-api.mdx             |  14 +-
 website/content/docs/metrics.mdx              |   2 +-
 website/content/docs/troubleshooting.mdx      |  11 +-
 36 files changed, 2021 insertions(+), 133 deletions(-)
 create mode 100644 packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
 create mode 100644 packages/server/drizzle/0014_runtime-settings.sql
 create mode 100644 packages/server/drizzle/meta/0014_snapshot.json
 create mode 100644 packages/server/src/db/settings.ts
 create mode 100644 packages/server/src/routes/settings.test.ts
 create mode 100644 packages/server/src/routes/settings.ts
 create mode 100644 packages/shared/src/settings.ts

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index 3951ddf..8163651 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -624,6 +624,20 @@ describe('the observability verbs over a real daemon', () => {
     });
   });
 
+  it('updateSettings moves a ledger knob with immediate effect', async () => {
+    const before = (await client().getConfig()).settings;
+    const { settings } = await client().updateSettings({
+      maxSandboxes: before.maxSandboxes + 1,
+    });
+    expect(settings.maxSandboxes).toBe(before.maxSandboxes + 1);
+    expect(settings.updatedAt).not.toBeNull();
+    expect((await client().getConfig()).settings.maxSandboxes).toBe(
+      before.maxSandboxes + 1,
+    );
+    // Restore: the exam daemon is shared by every suite in this run.
+    await client().updateSettings({ maxSandboxes: before.maxSandboxes });
+  });
+
   it('getSandboxMetrics samples a live sandbox and 404s after destroy', async () => {
     await client().acquireSandbox('obs-metrics-key');
     const sample = await client().getSandboxMetrics('obs-metrics-key');
diff --git a/packages/cli/src/commands.test.ts b/packages/cli/src/commands.test.ts
index d9fd9b7..319590d 100644
--- a/packages/cli/src/commands.test.ts
+++ b/packages/cli/src/commands.test.ts
@@ -293,7 +293,7 @@ describe('apikey commands over real HTTP', () => {
     expect(token).toMatch(/^[0-9a-f]{64}$/);
     const keyed = new Dormice({ endpoint, token });
     await expect(apikeyLs(keyed)).rejects.toThrow(
-      /cannot manage API keys — use DORMICE_API_TOKEN or the console/,
+      /cannot manage API keys or settings — use DORMICE_API_TOKEN or the console/,
     );
   });
 });
diff --git a/packages/console/src/features/activity/kinds.ts b/packages/console/src/features/activity/kinds.ts
index 041af9b..a9d8105 100644
--- a/packages/console/src/features/activity/kinds.ts
+++ b/packages/console/src/features/activity/kinds.ts
@@ -21,6 +21,7 @@ export const ACTIVITY_KIND_LABELS: Record<ActivityKind, string> = {
   'metadata-changed': '标签调整',
   'daemon-started': 'daemon 启动',
   'ingress-updated': '域名配置',
+  'settings-updated': '设置调整',
   'apikey-created': '密钥创建',
   'apikey-updated': '密钥调整',
   'apikey-disabled': '密钥停用',
@@ -60,6 +61,8 @@ export const ACTIVITY_KIND_STYLES: Record<ActivityKind, string> = {
   'daemon-started': 'border-border bg-muted text-muted-foreground',
   'ingress-updated':
     'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
+  'settings-updated':
+    'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
   'apikey-created':
     'border-violet-500/40 bg-violet-500/10 text-violet-600 dark:text-violet-400',
   'apikey-updated':
diff --git a/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx b/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
new file mode 100644
index 0000000..d85daca
--- /dev/null
+++ b/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
@@ -0,0 +1,460 @@
+import type {
+  GetConfigResponse,
+  RuntimeSettings,
+  UpdateSettingsRequest,
+} from '@dormice/shared';
+import { PencilEdit02Icon } from '@hugeicons/core-free-icons';
+import { HugeiconsIcon } from '@hugeicons/react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@/components/ui/dialog';
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+} from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { Spinner } from '@/components/ui/spinner';
+import { Switch } from '@/components/ui/switch';
+import { durationHint, policyLine } from '@/features/sandboxes/format';
+import { updateSettings } from '@/lib/api';
+import { queryClient } from '@/lib/queryClient';
+
+/**
+ * 运营旋钮的编辑区:值住在账本里(env 同名变量只是首次启动的种子),
+ * updateSettings 一改立即生效 — 不重启 daemon、不碰任何沙箱。三组各配
+ * 一个弹窗,给哪组就整组替换(updatePolicy 的规矩:界面上看到什么就写
+ * 下什么)。改的是"之后"不是"已经":容量上限管下一次创建,默认配额管
+ * 下一次出生的磁盘/容器,默认策略管下一次 acquire 创建的沙箱 — 存量
+ * 沙箱一根汗毛都不动,这句话在每个弹窗里都说清。
+ */
+
+function useSubmit(onDone: () => void) {
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const submit = async (patch: UpdateSettingsRequest, done: string) => {
+    setPending(true);
+    setError(null);
+    try {
+      await updateSettings(patch);
+      // 设置页读 config;总览的容量卡走 getHostMetrics 自己的轮询。
+      void queryClient.invalidateQueries({ queryKey: ['config'] });
+      toast.success(done);
+      onDone();
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      setPending(false);
+    }
+  };
+  return { pending, error, setError, submit };
+}
+
+function EditRow({
+  label,
+  value,
+  dialog,
+}: {
+  label: string;
+  value: string;
+  dialog: React.ReactNode;
+}) {
+  return (
+    <div className="flex items-center justify-between gap-3 px-4 py-3">
+      <div className="min-w-0">
+        <div className="text-sm font-medium">{label}</div>
+        <div className="truncate text-sm text-muted-foreground" title={value}>
+          {value}
+        </div>
+      </div>
+      {dialog}
+    </div>
+  );
+}
+
+function EditTrigger() {
+  return (
+    <DialogTrigger
+      render={
+        <Button variant="outline" size="sm">
+          <HugeiconsIcon icon={PencilEdit02Icon} />
+          编辑
+        </Button>
+      }
+    />
+  );
+}
+
+function MaxSandboxesDialog({ settings }: { settings: RuntimeSettings }) {
+  const [open, setOpen] = useState(false);
+  const [value, setValue] = useState('');
+  const { pending, error, setError, submit } = useSubmit(() => setOpen(false));
+
+  const valid =
+    value.trim() !== '' && Number.isInteger(Number(value)) && Number(value) > 0;
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (next) {
+          setValue(String(settings.maxSandboxes));
+          setError(null);
+        }
+      }}
+    >
+      <EditTrigger />
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>调整沙箱容量上限</DialogTitle>
+          <DialogDescription>
+            只挡新建(撞上回 429),唤醒永不受限。这是一根防失控的保险丝 —
+            拔太高之后,物理磁盘就是唯一兜底,记得盯总览页的数据盘水位。
+          </DialogDescription>
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            void submit(
+              { maxSandboxes: Number(value) },
+              `容量上限已改为 ${Number(value)}`,
+            );
+          }}
+        >
+          <FieldGroup>
+            <Field>
+              <FieldLabel htmlFor="settings-max-sandboxes">
+                最多同时存在的沙箱数
+              </FieldLabel>
+              <Input
+                id="settings-max-sandboxes"
+                type="number"
+                min={1}
+                value={value}
+                onChange={(event) => setValue(event.target.value)}
+              />
+            </Field>
+            {error && <FieldError>{error}</FieldError>}
+          </FieldGroup>
+          <DialogFooter className="mt-6">
+            <Button type="submit" disabled={!valid || pending}>
+              {pending && <Spinner />}
+              保存
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function SandboxDefaultsDialog({ settings }: { settings: RuntimeSettings }) {
+  const [open, setOpen] = useState(false);
+  const [cpus, setCpus] = useState('');
+  const [memoryGb, setMemoryGb] = useState('');
+  const [diskGb, setDiskGb] = useState('');
+  const { pending, error, setError, submit } = useSubmit(() => setOpen(false));
+
+  const filled = (raw: string) => raw.trim() !== '' && Number(raw) > 0;
+  const valid = filled(cpus) && filled(memoryGb) && filled(diskGb);
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (next) {
+          setCpus(String(settings.sandboxDefaults.cpus));
+          setMemoryGb(String(settings.sandboxDefaults.memoryGb));
+          setDiskGb(String(settings.sandboxDefaults.diskGb));
+          setError(null);
+        }
+      }}
+    >
+      <EditTrigger />
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>调整新沙箱的默认配额</DialogTitle>
+          <DialogDescription>
+            CPU/内存在下一次容器出生时生效(含停止后冷启动的存量沙箱);
+            磁盘只在沙箱第一次创建时定型 — 磁盘是沙箱的本体,永不原地改 尺寸。
+          </DialogDescription>
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            void submit(
+              {
+                sandboxDefaults: {
+                  cpus: Number(cpus),
+                  memoryGb: Number(memoryGb),
+                  diskGb: Number(diskGb),
+                },
+              },
+              '新沙箱默认配额已更新',
+            );
+          }}
+        >
+          <FieldGroup>
+            <Field>
+              <FieldLabel htmlFor="settings-cpus">CPU(核)</FieldLabel>
+              <Input
+                id="settings-cpus"
+                type="number"
+                min={0.1}
+                step="any"
+                value={cpus}
+                onChange={(event) => setCpus(event.target.value)}
+              />
+            </Field>
+            <Field>
+              <FieldLabel htmlFor="settings-memory">内存(GiB)</FieldLabel>
+              <Input
+                id="settings-memory"
+                type="number"
+                min={0.1}
+                step="any"
+                value={memoryGb}
+                onChange={(event) => setMemoryGb(event.target.value)}
+              />
+              <FieldDescription>
+                沙箱内超限 OOM 会让整箱退出(对账救回),给 agent 留点余量。
+              </FieldDescription>
+            </Field>
+            <Field>
+              <FieldLabel htmlFor="settings-disk">磁盘(GiB)</FieldLabel>
+              <Input
+                id="settings-disk"
+                type="number"
+                min={1}
+                step="any"
+                value={diskGb}
+                onChange={(event) => setDiskGb(event.target.value)}
+              />
+              <FieldDescription>
+                名义配额:稀疏镜像只为真实写入付费,超卖靠数据盘水位观察。
+              </FieldDescription>
+            </Field>
+            {error && <FieldError>{error}</FieldError>}
+          </FieldGroup>
+          <DialogFooter className="mt-6">
+            <Button type="submit" disabled={!valid || pending}>
+              {pending && <Spinner />}
+              保存
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function DefaultPolicyDialog({
+  settings,
+  archiveEnabled,
+}: {
+  settings: RuntimeSettings;
+  archiveEnabled: boolean;
+}) {
+  const [open, setOpen] = useState(false);
+  const [freezeAfter, setFreezeAfter] = useState('');
+  const [neverStop, setNeverStop] = useState(false);
+  const [stopAfter, setStopAfter] = useState('');
+  const [neverArchive, setNeverArchive] = useState(false);
+  const [archiveAfter, setArchiveAfter] = useState('');
+  const { pending, error, setError, submit } = useSubmit(() => setOpen(false));
+
+  const filled = (raw: string) => raw.trim() !== '' && Number(raw) > 0;
+  const valid =
+    filled(freezeAfter) &&
+    (neverStop || filled(stopAfter)) &&
+    (!archiveEnabled || neverStop || neverArchive || filled(archiveAfter));
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (next) {
+          const p = settings.defaultPolicy;
+          setFreezeAfter(String(p.freezeAfterSeconds));
+          setNeverStop(p.stopAfterSeconds === null);
+          setStopAfter(p.stopAfterSeconds ? String(p.stopAfterSeconds) : '');
+          setNeverArchive(p.archiveAfterSeconds === null);
+          setArchiveAfter(
+            p.archiveAfterSeconds ? String(p.archiveAfterSeconds) : '',
+          );
+          setError(null);
+        }
+      }}
+    >
+      <EditTrigger />
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>调整默认生命周期策略</DialogTitle>
+          <DialogDescription>
+            只影响之后 acquire 新建的沙箱 — 存量沙箱各有各的策略,去沙箱
+            列表批量调。
+          </DialogDescription>
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            void submit(
+              {
+                defaultPolicy: {
+                  freezeAfterSeconds: Number(freezeAfter),
+                  stopAfterSeconds: neverStop ? null : Number(stopAfter),
+                  archiveAfterSeconds:
+                    !archiveEnabled || neverStop || neverArchive
+                      ? null
+                      : Number(archiveAfter),
+                },
+              },
+              '默认生命周期策略已更新',
+            );
+          }}
+        >
+          <FieldGroup>
+            <Field>
+              <FieldLabel htmlFor="settings-freeze-after">
+                空闲多久后冻结(秒)
+              </FieldLabel>
+              <Input
+                id="settings-freeze-after"
+                type="number"
+                min={1}
+                value={freezeAfter}
+                onChange={(event) => setFreezeAfter(event.target.value)}
+              />
+              <FieldDescription>
+                运行中 → 已冻结:内存挤入 swap,唤醒约 50ms。
+                {durationHint(freezeAfter) && ` ${durationHint(freezeAfter)}`}
+              </FieldDescription>
+            </Field>
+            <Field orientation="horizontal">
+              <Switch
+                id="settings-never-stop"
+                checked={neverStop}
+                onCheckedChange={setNeverStop}
+              />
+              <FieldLabel htmlFor="settings-never-stop">
+                永不停止(常驻 agent)
+              </FieldLabel>
+            </Field>
+            {!neverStop && (
+              <Field>
+                <FieldLabel htmlFor="settings-stop-after">
+                  空闲多久后停止(秒)
+                </FieldLabel>
+                <Input
+                  id="settings-stop-after"
+                  type="number"
+                  min={1}
+                  value={stopAfter}
+                  onChange={(event) => setStopAfter(event.target.value)}
+                />
+                <FieldDescription>
+                  已冻结 → 已停止:只留磁盘,唤醒是冷启动。
+                  {durationHint(stopAfter) && ` ${durationHint(stopAfter)}`}
+                </FieldDescription>
+              </Field>
+            )}
+            {archiveEnabled && !neverStop && (
+              <>
+                <Field orientation="horizontal">
+                  <Switch
+                    id="settings-never-archive"
+                    checked={neverArchive}
+                    onCheckedChange={setNeverArchive}
+                  />
+                  <FieldLabel htmlFor="settings-never-archive">
+                    永不归档
+                  </FieldLabel>
+                </Field>
+                {!neverArchive && (
+                  <Field>
+                    <FieldLabel htmlFor="settings-archive-after">
+                      空闲多久后归档(秒)
+                    </FieldLabel>
+                    <Input
+                      id="settings-archive-after"
+                      type="number"
+                      min={1}
+                      value={archiveAfter}
+                      onChange={(event) => setArchiveAfter(event.target.value)}
+                    />
+                    <FieldDescription>
+                      已停止 → 已归档:磁盘压缩上传 S3,本地零占用。
+                      {durationHint(archiveAfter) &&
+                        ` ${durationHint(archiveAfter)}`}
+                    </FieldDescription>
+                  </Field>
+                )}
+              </>
+            )}
+            {error && <FieldError>{error}</FieldError>}
+          </FieldGroup>
+          <DialogFooter className="mt-6">
+            <Button type="submit" disabled={!valid || pending}>
+              {pending && <Spinner />}
+              保存
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export function RuntimeSettingsCard({ data }: { data: GetConfigResponse }) {
+  const { settings } = data;
+  return (
+    <section className="shrink-0 overflow-hidden rounded-xl border bg-card">
+      <div className="border-b px-4 py-3">
+        <h2 className="text-sm font-medium">运营旋钮</h2>
+        <p className="mt-0.5 text-xs text-muted-foreground">
+          住在账本里,改了立即生效,不用重启 —
+          下表同名环境变量只是首次启动的种子值。
+          {settings.updatedAt
+            ? `最后修改于 ${new Date(settings.updatedAt).toLocaleString()}。`
+            : '从未改过,仍是种子值。'}
+        </p>
+      </div>
+      <div className="divide-y">
+        <EditRow
+          label="沙箱容量上限"
+          value={`${settings.maxSandboxes} 个(只挡新建,唤醒永不受限)`}
+          dialog={<MaxSandboxesDialog settings={settings} />}
+        />
+        <EditRow
+          label="新沙箱默认配额"
+          value={`${settings.sandboxDefaults.cpus} CPU · ${settings.sandboxDefaults.memoryGb} GiB 内存 · ${settings.sandboxDefaults.diskGb} GiB 磁盘`}
+          dialog={<SandboxDefaultsDialog settings={settings} />}
+        />
+        <EditRow
+          label="默认生命周期策略"
+          value={policyLine(settings.defaultPolicy)}
+          dialog={
+            <DefaultPolicyDialog
+              settings={settings}
+              archiveEnabled={data.archive.enabled}
+            />
+          }
+        />
+      </div>
+    </section>
+  );
+}
diff --git a/packages/console/src/features/settings/pages/SettingsPage.tsx b/packages/console/src/features/settings/pages/SettingsPage.tsx
index d30c14e..ff9ab30 100644
--- a/packages/console/src/features/settings/pages/SettingsPage.tsx
+++ b/packages/console/src/features/settings/pages/SettingsPage.tsx
@@ -18,6 +18,7 @@ import {
   TableRow,
 } from '@/components/ui/table';
 import { formatDuration } from '@/features/sandboxes/format';
+import { RuntimeSettingsCard } from '../components/RuntimeSettingsCard';
 import { useConfig } from '../hooks/useConfig';
 
 /**
@@ -33,16 +34,16 @@ const KEY_HINTS: Record<string, string> = {
   DORMICE_EXECUTOR: '执行器:docker 是真沙箱,fake 是内存假执行器(开发/测试用)',
   DORMICE_BASE_IMAGE: '沙箱的默认镜像;docker 模式必填',
   DORMICE_DATA_DIR: '沙箱磁盘镜像的家(disks/*.img);归档临时文件也在这里',
-  DORMICE_MAX_SANDBOXES: '创建上限(撞上回 429);唤醒永不受限 — 磁盘才是真瓶颈',
+  DORMICE_MAX_SANDBOXES: '容量上限的首启种子值 — 生效值在上方运营旋钮里',
   DORMICE_SCAN_INTERVAL_SECONDS: '空闲扫描周期:每一轮把到阈值的沙箱降一格温度',
   DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS:
     '指标采样周期:历史曲线的分辨率,总览走势与指标历史都按它落库',
   DORMICE_METRICS_RETENTION_HOURS:
     '逐沙箱指标样本的保留时长;舰队状态计数恒保 30 天,不随它走',
-  DORMICE_SANDBOX_DISK_GB: '每个沙箱磁盘的名义大小;稀疏镜像只为真实内容付费',
-  DORMICE_SANDBOX_CPUS: '每个沙箱的 CPU 配额',
+  DORMICE_SANDBOX_DISK_GB: '默认磁盘配额的首启种子值 — 生效值在上方运营旋钮里',
+  DORMICE_SANDBOX_CPUS: '默认 CPU 配额的首启种子值 — 生效值在上方运营旋钮里',
   DORMICE_SANDBOX_MEMORY_GB:
-    '每个沙箱的内存上限;沙箱内 OOM 会让 gVisor 整箱退出(对账救回)',
+    '默认内存上限的首启种子值 — 生效值在上方运营旋钮里',
   DORMICE_SANDBOX_PIDS_LIMIT: '每个沙箱的进程数上限(fork 炸弹的物理闸)',
   DORMICE_RECLAIM_TIMEOUT_SECONDS: '冻结时挤内存进 swap 的最长等待',
   DORMICE_SANDBOX_DOMAIN:
@@ -72,9 +73,12 @@ function ValueCell({ entry }: { entry: ConfigEntry }) {
 const PAGE_SIZE = 50;
 
 /**
- * daemon 生效配置的只读观察窗:回答"这台 daemon 开了哪些旋钮"。刻意
- * 只读 — 配置的真身在 /etc/dormice/env,改完重启 daemon 生效;网页里
- * 改配置意味着 daemon 要能写自己的配置文件,那是另一个安全等级的决定。
+ * 设置页两段(2026-07-19 用户拍板加运营旋钮):上面是账本里的运营旋钮
+ * — 容量上限、新沙箱默认配额、默认策略,updateSettings 网页可改、立即
+ * 生效;下面仍是 env 配置的只读观察窗 — 端口、token、executor 这些
+ * "身份与地基"改了就是另一台 daemon,真身留在 /etc/dormice/env,改完
+ * 重启生效。daemon 从不写自己的环境文件(那是另一个安全等级的决定),
+ * 运营旋钮走的是账本:env 同名变量降级为首次启动的种子值。
  */
 export function SettingsPage() {
   const { data, isPending, isError, error } = useConfig();
@@ -108,18 +112,20 @@ export function SettingsPage() {
     <div className="mx-auto flex h-full w-full max-w-6xl flex-col gap-5 p-4 md:p-6">
       <header className="shrink-0">
         <h1 className="text-xl font-medium">设置</h1>
-        {/* 这行不是装饰:配置的真身与改法只在这里说 — 页面本体是只读的。 */}
+        {/* 这行不是装饰:两类旋钮的界限与 env 的改法只在这里说。 */}
         <p className="mt-1 text-sm text-muted-foreground">
-          daemon 的生效配置,只读。改配置在主机的{' '}
+          运营旋钮在下方卡片里直接改;其余配置只读,真身在主机的{' '}
           <code className="font-mono">/etc/dormice/env</code>,改完{' '}
           <code className="font-mono">systemctl restart dormice</code>。归档:
           {data.archive.enabled
-            ? `已启用(默认停止后 ${formatDuration(data.archive.defaultSeconds ?? 0)} 归档)`
+            ? `已启用(默认${data.archive.defaultSeconds === null ? '不归档' : `停止后 ${formatDuration(data.archive.defaultSeconds)} 归档`})`
             : '未启用 — 配齐 DORMICE_S3_* 四件套后可用'}
           。
         </p>
       </header>
 
+      <RuntimeSettingsCard data={data} />
+
       <DataTable fill>
         <TableHeader>
           <TableRow>
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 9ae554f..05181ad 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -20,6 +20,8 @@ import type {
   Sandbox,
   SetIngressResponse,
   Template,
+  UpdateSettingsRequest,
+  UpdateSettingsResponse,
 } from '@dormice/shared';
 import { clearSessionMarker, hasSessionMarker } from './session';
 
@@ -163,10 +165,16 @@ export const listSandboxImages = () =>
 export const listActivity = (limit?: number) =>
   rpc<ListActivityResponse>('/listActivity', limit ? { limit } : {});
 
-// Effective configuration, read-only. Secrets come back as "set", never as
-// their value; archive.enabled is the daemon's own adjudication.
+// Effective configuration. Secrets come back as "set", never as their
+// value; archive.enabled is the daemon's own adjudication. The env entries
+// stay read-only; `settings` 是账本里的运营旋钮,写入走 updateSettings。
 export const getConfig = () => rpc<GetConfigResponse>('/getConfig');
 
+// 运营旋钮的写半边(读半边在 getConfig.settings):给哪组就整组替换,
+// 立即生效,不重启不唤醒。admin 级动词 — console 会话可调,API key 不行。
+export const updateSettings = (patch: UpdateSettingsRequest) =>
+  rpc<UpdateSettingsResponse>('/updateSettings', patch);
+
 // Is a newer Dormice available? The daemon compares its built commit
 // against the origin's main and caches the answer for an hour; force is
 // the "check now" button. A failed check is data (checkError), not a 500.
diff --git a/packages/sdk/src/client.test.ts b/packages/sdk/src/client.test.ts
index 36e4d16..50eddaf 100644
--- a/packages/sdk/src/client.test.ts
+++ b/packages/sdk/src/client.test.ts
@@ -432,6 +432,34 @@ describe('API keys over real HTTP', () => {
   });
 });
 
+describe('runtime settings over real HTTP', () => {
+  it('updates a knob and reads it back through getConfig', async () => {
+    const before = (await client.getConfig()).settings;
+    const { settings } = await client.updateSettings({
+      maxSandboxes: before.maxSandboxes + 1,
+    });
+    expect(settings.maxSandboxes).toBe(before.maxSandboxes + 1);
+    expect(settings.updatedAt).not.toBeNull();
+    expect((await client.getConfig()).settings.maxSandboxes).toBe(
+      before.maxSandboxes + 1,
+    );
+    // Restore: other suites share this daemon's ledger.
+    await client.updateSettings({ maxSandboxes: before.maxSandboxes });
+  });
+
+  it('is admin-only, like the apiKey verbs', async () => {
+    const { apiKey, token } = await client.createApiKey('sdk-settings');
+    const keyed = new Dormice({ endpoint, token });
+    await expect(
+      keyed.updateSettings({ maxSandboxes: 12345 }),
+    ).rejects.toMatchObject({
+      status: 403,
+      message: expect.stringMatching(/cannot manage API keys or settings/),
+    });
+    await client.revokeApiKey(apiKey.id);
+  });
+});
+
 describe('the observability verbs over real HTTP', () => {
   it('getConfig reports the knobs and withholds the token', async () => {
     // Source attribution is asserted server-side with injected sources;
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index be3b9e9..705dd51 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -55,9 +55,12 @@ import {
   type UpdateApiKeyResponse,
   type UpdateMetadataResponse,
   type UpdatePolicyResponse,
+  type UpdateSettingsRequest,
+  type UpdateSettingsResponse,
   updateApiKeyResponseSchema,
   updateMetadataResponseSchema,
   updatePolicyResponseSchema,
+  updateSettingsResponseSchema,
   type WriteFileResponse,
   type WriteFilesResponse,
   writeFileResponseSchema,
@@ -286,6 +289,23 @@ export class Dormice {
     return getConfigResponseSchema.parse(data);
   }
 
+  /**
+   * Rewrites the runtime settings — the operator knobs that live in the
+   * daemon's ledger instead of its environment (capacity cap, what new
+   * sandboxes get). Every provided group replaces that group whole; absent
+   * groups stay untouched. Takes effect immediately, restarts nothing and
+   * wakes nothing; existing sandboxes keep their own policy and disk size.
+   * Admin-only like the apiKey verbs: this client must be authenticated
+   * with DORMICE_API_TOKEN itself — a ledger key gets an honest 403.
+   * The read half rides on getConfig().settings.
+   */
+  async updateSettings(
+    patch: UpdateSettingsRequest,
+  ): Promise<UpdateSettingsResponse> {
+    const data = await this.rpc('updateSettings', patch);
+    return updateSettingsResponseSchema.parse(data);
+  }
+
   /**
    * Is a newer Dormice available for this daemon? Versions are git
    * commits (trunk-based, no tags yet): the commit baked into the running
diff --git a/packages/server/drizzle/0014_runtime-settings.sql b/packages/server/drizzle/0014_runtime-settings.sql
new file mode 100644
index 0000000..62844dd
--- /dev/null
+++ b/packages/server/drizzle/0014_runtime-settings.sql
@@ -0,0 +1,11 @@
+CREATE TABLE `runtime_settings` (
+	`id` integer PRIMARY KEY NOT NULL,
+	`max_sandboxes` integer NOT NULL,
+	`sandbox_cpus` real NOT NULL,
+	`sandbox_memory_gb` real NOT NULL,
+	`sandbox_disk_gb` real NOT NULL,
+	`default_freeze_after_seconds` integer NOT NULL,
+	`default_stop_after_seconds` integer,
+	`default_archive_after_seconds` integer,
+	`updated_at` text
+);
diff --git a/packages/server/drizzle/meta/0014_snapshot.json b/packages/server/drizzle/meta/0014_snapshot.json
new file mode 100644
index 0000000..45182d4
--- /dev/null
+++ b/packages/server/drizzle/meta/0014_snapshot.json
@@ -0,0 +1,632 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "0e4c8214-458c-4e2b-80bd-4db6a3739fa3",
+  "prevId": "da4ece11-991e-4828-a929-998a3b71244b",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_name": {
+          "name": "sandbox_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "actor": {
+          "name": "actor",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "api_keys": {
+      "name": "api_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "prefix": {
+          "name": "prefix",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "disabled_at": {
+          "name": "disabled_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "api_keys_key_hash_unique": {
+          "name": "api_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        },
+        "api_keys_active_name_idx": {
+          "name": "api_keys_active_name_idx",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true,
+          "where": "\"api_keys\".\"revoked_at\" IS NULL"
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "daemon_secrets": {
+      "name": "daemon_secrets",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "envd_signing_secret": {
+          "name": "envd_signing_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "fleet_snapshots": {
+      "name": "fleet_snapshots",
+      "columns": {
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active": {
+          "name": "active",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "frozen": {
+          "name": "frozen",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stopped": {
+          "name": "stopped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archived": {
+          "name": "archived",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "restoring": {
+          "name": "restoring",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "total": {
+          "name": "total",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "runtime_settings": {
+      "name": "runtime_settings",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "max_sandboxes": {
+          "name": "max_sandboxes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_cpus": {
+          "name": "sandbox_cpus",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_memory_gb": {
+          "name": "sandbox_memory_gb",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_disk_gb": {
+          "name": "sandbox_disk_gb",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "default_freeze_after_seconds": {
+          "name": "default_freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "default_stop_after_seconds": {
+          "name": "default_stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "default_archive_after_seconds": {
+          "name": "default_archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandbox_metrics_samples": {
+      "name": "sandbox_metrics_samples",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_count": {
+          "name": "cpu_count",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_used_pct": {
+          "name": "cpu_used_pct",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_used_bytes": {
+          "name": "mem_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_total_bytes": {
+          "name": "mem_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_cache_bytes": {
+          "name": "mem_cache_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_used_bytes": {
+          "name": "disk_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_total_bytes": {
+          "name": "disk_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "sandbox_metrics_samples_sandbox_at_idx": {
+          "name": "sandbox_metrics_samples_sandbox_at_idx",
+          "columns": [
+            "sandbox_id",
+            "at"
+          ],
+          "isUnique": false
+        },
+        "sandbox_metrics_samples_at_idx": {
+          "name": "sandbox_metrics_samples_at_idx",
+          "columns": [
+            "at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_name_unique": {
+          "name": "sandboxes_name_unique",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index cb770d0..7f8777e 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -99,6 +99,13 @@
       "when": 1784208918062,
       "tag": "0013_activity-actor",
       "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "6",
+      "when": 1784447916228,
+      "tag": "0014_runtime-settings",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index e5daa7b..b6443d0 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -239,13 +239,14 @@ describe('error shape', () => {
 });
 
 describe('sandbox capacity', () => {
-  it('caps creation at DORMICE_MAX_SANDBOXES with an honest 429', async () => {
+  it('caps creation at maxSandboxes with an honest 429', async () => {
+    // The env variable seeds the ledger's runtime settings at first boot.
     const { app } = testApp(undefined, { DORMICE_MAX_SANDBOXES: '1' });
     expect((await acquire(app, { name: 'alice' })).statusCode).toBe(200);
 
     const capped = await acquire(app, { name: 'bob' });
     expect(capped.statusCode).toBe(429);
-    expect(capped.json().message).toMatch(/DORMICE_MAX_SANDBOXES/);
+    expect(capped.json().message).toMatch(/maxSandboxes=1/);
 
     // Existing sandboxes always wake — the cap only guards creation.
     expect((await acquire(app, { name: 'alice' })).statusCode).toBe(200);
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index a118d7c..a101700 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -17,6 +17,7 @@ import { getConsoleAccount } from './db/account';
 import { isLiveApiKey, verifyApiKeyToken } from './db/api-keys';
 import type { Db } from './db/db';
 import { getOrCreateSigningSecret } from './db/secrets';
+import { ensureRuntimeSettings } from './db/settings';
 import { registerE2bCompat } from './e2b';
 import { ProcessTable } from './e2b/process-table';
 import { WatcherTable } from './e2b/watcher-table';
@@ -31,6 +32,7 @@ import { consoleRoutes } from './routes/console';
 import { hostRoutes } from './routes/host';
 import { ingressRoutes } from './routes/ingress';
 import { sandboxRoutes } from './routes/sandboxes';
+import { settingsRoutes } from './routes/settings';
 import { templateRoutes } from './routes/templates';
 import { upgradeRoutes } from './routes/upgrade';
 import { createSandboxProxy } from './sandbox-proxy';
@@ -119,6 +121,9 @@ export function buildApp({
   // presence: with one, new sandboxes archive after a week of idleness;
   // without one, never — and asking is a 400.
   const archiveDefaultSeconds = archiver ? ARCHIVE_DEFAULT_SECONDS : null;
+  // Idempotent get-or-seed: main.ts already ran it (the executor reads
+  // settings before buildApp), tests build the app directly and need it here.
+  ensureRuntimeSettings(db, config, archiveDefaultSeconds);
   // Always a pino instance (booleans are normalized into one): two fastify()
   // call shapes would give the instance two different types.
   const loggerInstance =
@@ -249,18 +254,25 @@ export function buildApp({
     await api.register(ingressRoutes, { db, ingress });
     await api.register(configRoutes, {
       config,
+      db,
       sources,
       archiveDefaultSeconds,
     });
     await api.register(upgradeRoutes, { updater, db });
   });
 
-  // The apiKey management verbs sit behind the stricter admin gate — their
-  // own scope, because a Fastify hook guards a whole scope and these four
-  // verbs are the only ones with a different answer to "who may call".
+  // The apiKey management verbs and updateSettings sit behind the stricter
+  // admin gate — their own scope, because a Fastify hook guards a whole
+  // scope and these verbs share a different answer to "who may call":
+  // credentials must not manage credentials, and a leaked automation key
+  // must not be able to raise the very limits that contain it.
   app.register(async (admin) => {
     admin.addHook('onRequest', adminAuth);
     await admin.register(apiKeyRoutes, { db });
+    await admin.register(settingsRoutes, {
+      db,
+      archiveEnabled: archiveDefaultSeconds !== null,
+    });
   });
 
   // The web console: account + session endpoints (open — setup and login
diff --git a/packages/server/src/auth.ts b/packages/server/src/auth.ts
index a445d2a..10cd542 100644
--- a/packages/server/src/auth.ts
+++ b/packages/server/src/auth.ts
@@ -211,13 +211,15 @@ export function requireApiAuth(
 }
 
 /**
- * The admin gate for the apiKey management verbs: only the env token
- * (Bearer) or a console session may pass. A key that is otherwise valid
- * gets an honest 403 instead of a silent 401 — key-manages-key would let
- * one leaked credential mint itself an unrevoked successor and revoke
- * every legitimate peer, so the refusal names the rule. The console-setup
- * door (routes/console.ts) rests on the same doctrine: a machine
- * credential must not escalate into managing credentials.
+ * The admin gate for the apiKey management verbs and updateSettings: only
+ * the env token (Bearer) or a console session may pass. A key that is
+ * otherwise valid gets an honest 403 instead of a silent 401 —
+ * key-manages-key would let one leaked credential mint itself an unrevoked
+ * successor and revoke every legitimate peer, and a leaked automation key
+ * must not be able to raise the very limits that contain it; the refusal
+ * names the rule. The console-setup door (routes/console.ts) rests on the
+ * same doctrine: a machine credential must not escalate into managing the
+ * daemon.
  *
  * Leg order matters twice. The isLiveApiKey lookup runs only after both
  * accepting legs failed, so a console session with a stray key header
@@ -246,7 +248,7 @@ export function requireAdminAuth(
     if (bare !== null && isLiveApiKey(bare)) {
       await reply.code(403).send({
         message:
-          'API keys cannot manage API keys — use DORMICE_API_TOKEN or the console',
+          'API keys cannot manage API keys or settings — use DORMICE_API_TOKEN or the console',
       });
       return;
     }
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index 6b16cb1..f58dcf7 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -223,6 +223,34 @@ export const daemonSecrets = sqliteTable('daemon_secrets', {
 
 export type DaemonSecretsRow = typeof daemonSecrets.$inferSelect;
 
+/**
+ * Runtime settings — the operator knobs that must be changeable from the
+ * console without shell access and a restart (shared/settings.ts draws the
+ * line). One row, fixed id — the console_account singleton pattern. Born at
+ * first boot, seeded from the env variables of the same names; from then on
+ * this row is the single truth and env edits to those knobs are ignored
+ * (two live sources for one knob is a standing ambiguity).
+ *
+ * Typed columns, not a JSON blob: the schema IS the vocabulary, and a knob
+ * that exists but is invisible to migrations would drift silently.
+ */
+export const runtimeSettings = sqliteTable('runtime_settings', {
+  id: integer('id').primaryKey(),
+  maxSandboxes: integer('max_sandboxes').notNull(),
+  sandboxCpus: real('sandbox_cpus').notNull(),
+  sandboxMemoryGb: real('sandbox_memory_gb').notNull(),
+  sandboxDiskGb: real('sandbox_disk_gb').notNull(),
+  defaultFreezeAfterSeconds: integer('default_freeze_after_seconds').notNull(),
+  /** NULL = new sandboxes default to never stopping. */
+  defaultStopAfterSeconds: integer('default_stop_after_seconds'),
+  /** NULL = never archive — forced when the daemon has no archiver. */
+  defaultArchiveAfterSeconds: integer('default_archive_after_seconds'),
+  /** Null until the first updateSettings: "still exactly the seed" is information. */
+  updatedAt: text('updated_at'),
+});
+
+export type RuntimeSettingsRow = typeof runtimeSettings.$inferSelect;
+
 /**
  * Ledger-minted API keys: full-power peers of DORMICE_API_TOKEN that exist
  * so credentials can rotate without an env edit and a restart. The env
diff --git a/packages/server/src/db/settings.ts b/packages/server/src/db/settings.ts
new file mode 100644
index 0000000..2f71bb8
--- /dev/null
+++ b/packages/server/src/db/settings.ts
@@ -0,0 +1,127 @@
+import {
+  DEFAULT_LIFECYCLE_POLICY,
+  type RuntimeSettings,
+  type UpdateSettingsRequest,
+} from '@dormice/shared';
+import { eq } from 'drizzle-orm';
+import type { Config } from '../config';
+import type { Db } from './db';
+import { type RuntimeSettingsRow, runtimeSettings } from './schema';
+
+/** The console_account fixed-id pattern: "at most one row" as a schema fact. */
+const SETTINGS_ROW_ID = 1;
+
+/**
+ * Get-or-seed, run at every boot before anything reads a knob. The seed is
+ * the env variables (and, for the default policy, the shared zero-config
+ * defaults plus the boot's archive adjudication) — so a daemon upgraded
+ * onto this schema keeps behaving exactly as its env said, and a fresh
+ * install needs no extra step. Idempotent: an existing row is the truth
+ * and the env is not consulted again.
+ *
+ * archiveDefaultSeconds is the caller's adjudication of "is the archiver
+ * configured" (null = no) — the same parameter resolvePolicy takes, decided
+ * once per boot by the archiver's presence.
+ */
+export function ensureRuntimeSettings(
+  db: Db,
+  config: Config,
+  archiveDefaultSeconds: number | null,
+): void {
+  db.insert(runtimeSettings)
+    .values({
+      id: SETTINGS_ROW_ID,
+      maxSandboxes: config.DORMICE_MAX_SANDBOXES,
+      sandboxCpus: config.DORMICE_SANDBOX_CPUS,
+      sandboxMemoryGb: config.DORMICE_SANDBOX_MEMORY_GB,
+      sandboxDiskGb: config.DORMICE_SANDBOX_DISK_GB,
+      defaultFreezeAfterSeconds: DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
+      defaultStopAfterSeconds: DEFAULT_LIFECYCLE_POLICY.stopAfterSeconds,
+      defaultArchiveAfterSeconds: archiveDefaultSeconds,
+      updatedAt: null,
+    })
+    .onConflictDoNothing()
+    .run();
+}
+
+function toView(row: RuntimeSettingsRow): RuntimeSettings {
+  return {
+    maxSandboxes: row.maxSandboxes,
+    sandboxDefaults: {
+      cpus: row.sandboxCpus,
+      memoryGb: row.sandboxMemoryGb,
+      diskGb: row.sandboxDiskGb,
+    },
+    defaultPolicy: {
+      freezeAfterSeconds: row.defaultFreezeAfterSeconds,
+      stopAfterSeconds: row.defaultStopAfterSeconds,
+      archiveAfterSeconds: row.defaultArchiveAfterSeconds,
+    },
+    updatedAt: row.updatedAt,
+  };
+}
+
+/**
+ * The knobs in force, read fresh at each use site — a better-sqlite3 point
+ * read costs microseconds, and reading live is what makes a console edit
+ * apply to the very next acquire without a restart. Throws when the row is
+ * missing: that means ensureRuntimeSettings never ran, a wiring bug worth a
+ * loud death, not a silent fallback to env.
+ */
+export function readRuntimeSettings(db: Db): RuntimeSettings {
+  const row = db
+    .select()
+    .from(runtimeSettings)
+    .where(eq(runtimeSettings.id, SETTINGS_ROW_ID))
+    .get();
+  if (!row) {
+    throw new Error(
+      'runtime settings row missing — ensureRuntimeSettings must run at boot',
+    );
+  }
+  return toView(row);
+}
+
+/**
+ * Applies an updateSettings patch: each provided group replaces that group
+ * whole, absent groups keep their stored values (shared/settings.ts is the
+ * arbiter of that contract). Validation — including the archive-without-
+ * archiver refusal — happened at the route; this is the pure write.
+ */
+export function writeRuntimeSettings(
+  db: Db,
+  patch: UpdateSettingsRequest,
+  now: Date,
+): RuntimeSettings {
+  const row = db
+    .update(runtimeSettings)
+    .set({
+      ...(patch.maxSandboxes !== undefined
+        ? { maxSandboxes: patch.maxSandboxes }
+        : {}),
+      ...(patch.sandboxDefaults !== undefined
+        ? {
+            sandboxCpus: patch.sandboxDefaults.cpus,
+            sandboxMemoryGb: patch.sandboxDefaults.memoryGb,
+            sandboxDiskGb: patch.sandboxDefaults.diskGb,
+          }
+        : {}),
+      ...(patch.defaultPolicy !== undefined
+        ? {
+            defaultFreezeAfterSeconds: patch.defaultPolicy.freezeAfterSeconds,
+            defaultStopAfterSeconds: patch.defaultPolicy.stopAfterSeconds,
+            defaultArchiveAfterSeconds: patch.defaultPolicy.archiveAfterSeconds,
+          }
+        : {}),
+      updatedAt: now.toISOString(),
+    })
+    .where(eq(runtimeSettings.id, SETTINGS_ROW_ID))
+    .returning()
+    .get();
+  if (!row) {
+    throw new Error(
+      'runtime settings row missing — ensureRuntimeSettings must run at boot',
+    );
+  }
+  return toView(row);
+}
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index 36541a5..87e4559 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -19,6 +19,7 @@ import {
   resolveWindow,
 } from '../db/metrics';
 import type { SandboxRow } from '../db/schema';
+import { readRuntimeSettings } from '../db/settings';
 import { findTemplate, resolveImage } from '../db/templates';
 import {
   destroySandbox,
@@ -199,6 +200,10 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
 
   /** What getInfo and list answer with. */
   function infoView(row: SandboxRow, state: 'running' | 'paused') {
+    // The ledger's live resource knobs, not the env seeds — CPU/memory
+    // apply at each container launch, so the current values are what a
+    // sandbox actually runs (or will run) with.
+    const { sandboxDefaults } = readRuntimeSettings(db);
     return {
       sandboxID: row.id,
       // Required by the Python SDK's models, like clientID above.
@@ -212,9 +217,9 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
       endAt:
         row.deadlineAt ??
         new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString(),
-      cpuCount: config.DORMICE_SANDBOX_CPUS,
-      memoryMB: Math.round(config.DORMICE_SANDBOX_MEMORY_GB * 1024),
-      diskSizeMB: Math.round(config.DORMICE_SANDBOX_DISK_GB * 1024),
+      cpuCount: sandboxDefaults.cpus,
+      memoryMB: Math.round(sandboxDefaults.memoryGb * 1024),
+      diskSizeMB: Math.round(sandboxDefaults.diskGb * 1024),
       envdVersion: ENVD_VERSION,
       ...domainField,
     };
@@ -328,10 +333,11 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
           );
         }
 
-        if (countSandboxes(db) >= config.DORMICE_MAX_SANDBOXES) {
+        const maxSandboxes = readRuntimeSettings(db).maxSandboxes;
+        if (countSandboxes(db) >= maxSandboxes) {
           throw apiError(
             429,
-            `sandbox limit reached (DORMICE_MAX_SANDBOXES=${config.DORMICE_MAX_SANDBOXES}) — destroy a sandbox or raise the limit`,
+            `sandbox limit reached (maxSandboxes=${maxSandboxes}) — destroy a sandbox or raise the limit in settings`,
           );
         }
         const id = randomUUID();
@@ -342,7 +348,11 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
           id,
           name,
           nodeId: config.DORMICE_NODE_ID,
-          policy: resolvePolicy(undefined, archiveDefaultSeconds),
+          policy: resolvePolicy(
+            undefined,
+            readRuntimeSettings(db).defaultPolicy,
+            archiveDefaultSeconds !== null,
+          ),
           template,
           actor: request.actor,
           metadata:
diff --git a/packages/server/src/executor/docker.contract.test.ts b/packages/server/src/executor/docker.contract.test.ts
index 615fc68..fbfddf2 100644
--- a/packages/server/src/executor/docker.contract.test.ts
+++ b/packages/server/src/executor/docker.contract.test.ts
@@ -35,9 +35,9 @@ if (process.env.DORMICE_DOCKER_CONTRACT === '1' && image) {
         baseImage: image,
         dataDir,
         // Small and fast: the contract exercises lifecycle, not capacity.
-        diskSizeGb: 1,
-        cpus: 1,
-        memoryGb: 1,
+        // A static closure, not a ledger read: the contract exam runs the
+        // executor bare, without a daemon or its settings row.
+        resources: () => ({ diskSizeGb: 1, cpus: 1, memoryGb: 1 }),
         pidsLimit: 256,
         reclaimTimeoutSeconds: 45,
       });
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index e0cbde3..8b31cfc 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -75,15 +75,27 @@ import {
  */
 export const SANDBOX_LABEL = 'dormice.sandbox';
 
+/** The per-sandbox resource knobs — runtime settings, so a live view. */
+export interface SandboxResources {
+  /** Size cap of each sandbox disk. The limit is physical: the image file simply ends. */
+  diskSizeGb: number;
+  cpus: number;
+  memoryGb: number;
+}
+
 export interface DockerExecutorOptions {
   /** Image every sandbox boots from, e.g. dormice-base:20260708. */
   baseImage: string;
   /** Sparse disk images and their mount points live under this directory. */
   dataDir: string;
-  /** Size cap of each sandbox disk. The limit is physical: the image file simply ends. */
-  diskSizeGb: number;
-  cpus: number;
-  memoryGb: number;
+  /**
+   * Live view of the resource knobs, read at each birth — a disk's at
+   * provisioning, a container's at launch — so a console edit applies to
+   * the next birth without a restart. Deliberately not three captured
+   * numbers: the knobs live in the ledger now (runtime settings), and the
+   * executor holding a stale copy would be a second truth.
+   */
+  resources: () => SandboxResources;
   pidsLimit: number;
   /** How long one memory.reclaim write may take before its subprocess is killed. */
   reclaimTimeoutSeconds: number;
@@ -459,7 +471,8 @@ export class DockerExecutor implements Executor {
     const systemDelta =
       (stats.cpu_stats?.system_cpu_usage ?? 0) -
       (stats.precpu_stats?.system_cpu_usage ?? 0);
-    const onlineCpus = stats.cpu_stats?.online_cpus || this.opts.cpus;
+    const resources = this.opts.resources();
+    const onlineCpus = stats.cpu_stats?.online_cpus || resources.cpus;
     // cgroup v2 calls the page cache inactive_file; v1 calls it cache.
     const memStats = (stats.memory_stats?.stats ?? {}) as Record<
       string,
@@ -467,14 +480,14 @@ export class DockerExecutor implements Executor {
     >;
     const disk = await statfs(this.mountDir(sandboxId));
     return {
-      cpuCount: this.opts.cpus,
+      cpuCount: resources.cpus,
       cpuUsedPct:
         systemDelta > 0 && cpuDelta > 0
           ? (cpuDelta / systemDelta) * onlineCpus * 100
           : 0,
       memUsedBytes: stats.memory_stats?.usage ?? 0,
       memTotalBytes:
-        stats.memory_stats?.limit || Math.round(this.opts.memoryGb * 1024 ** 3),
+        stats.memory_stats?.limit || Math.round(resources.memoryGb * 1024 ** 3),
       memCacheBytes: memStats.cache ?? memStats.inactive_file ?? 0,
       diskUsedBytes: (disk.blocks - disk.bfree) * disk.bsize,
       diskTotalBytes: disk.blocks * disk.bsize,
@@ -1300,8 +1313,8 @@ export class DockerExecutor implements Executor {
           Runtime: 'runsc',
           Init: true,
           SecurityOpt: ['no-new-privileges'],
-          NanoCpus: Math.round(this.opts.cpus * 1e9),
-          Memory: Math.round(this.opts.memoryGb * 1024 ** 3),
+          NanoCpus: Math.round(this.opts.resources().cpus * 1e9),
+          Memory: Math.round(this.opts.resources().memoryGb * 1024 ** 3),
           PidsLimit: this.opts.pidsLimit,
           Binds: [`${this.mountDir(sandboxId)}:/home/user`],
           // Life and death belong to the daemon's state machine; Docker
@@ -1340,7 +1353,7 @@ export class DockerExecutor implements Executor {
     await mkdir(mnt, { recursive: true });
     const file = await open(img, 'w');
     try {
-      await file.truncate(this.opts.diskSizeGb * 1024 ** 3);
+      await file.truncate(this.opts.resources().diskSizeGb * 1024 ** 3);
     } finally {
       await file.close();
     }
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 67c5208..345d2aa 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -10,12 +10,14 @@ import { recordActivity } from './db/activity';
 import { migrateDb, openDb } from './db/db';
 import { listSandboxes } from './db/ledger';
 import { acquireSingleWriterLock } from './db/lock';
+import { ensureRuntimeSettings, readRuntimeSettings } from './db/settings';
 import { DockerExecutor } from './executor/docker';
 import type { Executor } from './executor/executor';
 import { FakeExecutor } from './executor/fake';
 import { Ingress } from './ingress';
 import { KeyedQueue } from './keyed-queue';
 import { sampleOnce } from './metrics-sampler';
+import { ARCHIVE_DEFAULT_SECONDS } from './policy';
 import { reconcile } from './reconciler';
 import { scanOnce } from './scanner';
 import { locallyClaimedCount, startupGuard } from './startup-guard';
@@ -50,6 +52,15 @@ if (config.DORMICE_DB_PATH !== ':memory:') {
 const db = openDb(config.DORMICE_DB_PATH);
 migrateDb(db, fileURLToPath(new URL('../drizzle', import.meta.url)));
 
+// Seed the runtime settings before anything can read a knob (the executor
+// reads them at every disk/container birth). The archive adjudication here
+// is the same one buildApp makes: archiver exists iff S3 is configured.
+ensureRuntimeSettings(
+  db,
+  config,
+  s3Settings(config) !== null ? ARCHIVE_DEFAULT_SECONDS : null,
+);
+
 function buildExecutor(cfg: Config, log: (msg: string) => void): Executor {
   if (cfg.DORMICE_EXECUTOR === 'fake') return new FakeExecutor();
   if (!cfg.DORMICE_BASE_IMAGE) {
@@ -60,9 +71,15 @@ function buildExecutor(cfg: Config, log: (msg: string) => void): Executor {
   return new DockerExecutor({
     baseImage: cfg.DORMICE_BASE_IMAGE,
     dataDir: cfg.DORMICE_DATA_DIR,
-    diskSizeGb: cfg.DORMICE_SANDBOX_DISK_GB,
-    cpus: cfg.DORMICE_SANDBOX_CPUS,
-    memoryGb: cfg.DORMICE_SANDBOX_MEMORY_GB,
+    // Live from the ledger: a console edit reaches the next birth directly.
+    resources: () => {
+      const { sandboxDefaults } = readRuntimeSettings(db);
+      return {
+        diskSizeGb: sandboxDefaults.diskGb,
+        cpus: sandboxDefaults.cpus,
+        memoryGb: sandboxDefaults.memoryGb,
+      };
+    },
     pidsLimit: cfg.DORMICE_SANDBOX_PIDS_LIMIT,
     reclaimTimeoutSeconds: cfg.DORMICE_RECLAIM_TIMEOUT_SECONDS,
     log,
diff --git a/packages/server/src/policy.test.ts b/packages/server/src/policy.test.ts
index d2f39ad..8d23f5b 100644
--- a/packages/server/src/policy.test.ts
+++ b/packages/server/src/policy.test.ts
@@ -2,14 +2,28 @@ import { DEFAULT_LIFECYCLE_POLICY } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { ARCHIVE_DEFAULT_SECONDS, resolvePolicy } from './policy';
 
-describe('resolvePolicy without an archiver (archiveDefaultSeconds = null)', () => {
-  it('returns the global defaults when no override is given', () => {
-    expect(resolvePolicy(undefined, null)).toEqual(DEFAULT_LIFECYCLE_POLICY);
-    expect(resolvePolicy({}, null)).toEqual(DEFAULT_LIFECYCLE_POLICY);
+// The two default shapes a real boot seeds into the ledger: without an
+// archiver the archive knob is null, with one it is the 7-day seed.
+const NO_ARCHIVER_DEFAULTS = DEFAULT_LIFECYCLE_POLICY;
+const ARCHIVER_DEFAULTS = {
+  ...DEFAULT_LIFECYCLE_POLICY,
+  archiveAfterSeconds: ARCHIVE_DEFAULT_SECONDS,
+};
+
+describe('resolvePolicy without an archiver (archiveEnabled = false)', () => {
+  it('returns the defaults when no override is given', () => {
+    expect(resolvePolicy(undefined, NO_ARCHIVER_DEFAULTS, false)).toEqual(
+      DEFAULT_LIFECYCLE_POLICY,
+    );
+    expect(resolvePolicy({}, NO_ARCHIVER_DEFAULTS, false)).toEqual(
+      DEFAULT_LIFECYCLE_POLICY,
+    );
   });
 
   it('merges a partial override over the defaults', () => {
-    expect(resolvePolicy({ freezeAfterSeconds: 60 }, null)).toEqual({
+    expect(
+      resolvePolicy({ freezeAfterSeconds: 60 }, NO_ARCHIVER_DEFAULTS, false),
+    ).toEqual({
       ...DEFAULT_LIFECYCLE_POLICY,
       freezeAfterSeconds: 60,
     });
@@ -17,19 +31,24 @@ describe('resolvePolicy without an archiver (archiveDefaultSeconds = null)', ()
 
   it('keeps an explicit null for archiveAfterSeconds (never archive)', () => {
     expect(
-      resolvePolicy({ archiveAfterSeconds: null }, null).archiveAfterSeconds,
+      resolvePolicy({ archiveAfterSeconds: null }, NO_ARCHIVER_DEFAULTS, false)
+        .archiveAfterSeconds,
     ).toBeNull();
   });
 
   it('refuses an explicit archive threshold — no archiver, no promise', () => {
-    expect(() => resolvePolicy({ archiveAfterSeconds: 60 }, null)).toThrow(
-      /archiving requires S3 \(DORMICE_S3_\*\) to be configured/,
-    );
+    expect(() =>
+      resolvePolicy({ archiveAfterSeconds: 60 }, NO_ARCHIVER_DEFAULTS, false),
+    ).toThrow(/archiving requires S3 \(DORMICE_S3_\*\) to be configured/);
   });
 
   it('rejects a merged result that violates freeze <= stop', () => {
     expect(() =>
-      resolvePolicy({ freezeAfterSeconds: 61, stopAfterSeconds: 60 }, null),
+      resolvePolicy(
+        { freezeAfterSeconds: 61, stopAfterSeconds: 60 },
+        NO_ARCHIVER_DEFAULTS,
+        false,
+      ),
     ).toThrow(/freezeAfterSeconds/);
   });
 
@@ -37,14 +56,15 @@ describe('resolvePolicy without an archiver (archiveDefaultSeconds = null)', ()
     // The resident-agent policy: park frozen forever, wake in ~50ms, never
     // decay to a cold boot.
     expect(
-      resolvePolicy({ stopAfterSeconds: null }, null).stopAfterSeconds,
+      resolvePolicy({ stopAfterSeconds: null }, NO_ARCHIVER_DEFAULTS, false)
+        .stopAfterSeconds,
     ).toBeNull();
   });
 });
 
-describe('resolvePolicy with an archiver (archiveDefaultSeconds = 7 days)', () => {
-  it('defaults new sandboxes to archiving after a week', () => {
-    expect(resolvePolicy(undefined, ARCHIVE_DEFAULT_SECONDS)).toEqual({
+describe('resolvePolicy with an archiver (archiveEnabled = true)', () => {
+  it('defaults new sandboxes to archiving after the seeded week', () => {
+    expect(resolvePolicy(undefined, ARCHIVER_DEFAULTS, true)).toEqual({
       ...DEFAULT_LIFECYCLE_POLICY,
       archiveAfterSeconds: ARCHIVE_DEFAULT_SECONDS,
     });
@@ -52,7 +72,7 @@ describe('resolvePolicy with an archiver (archiveDefaultSeconds = 7 days)', () =
 
   it('keeps an explicit null for archiveAfterSeconds (never archive)', () => {
     expect(
-      resolvePolicy({ archiveAfterSeconds: null }, ARCHIVE_DEFAULT_SECONDS)
+      resolvePolicy({ archiveAfterSeconds: null }, ARCHIVER_DEFAULTS, true)
         .archiveAfterSeconds,
     ).toBeNull();
   });
@@ -62,7 +82,7 @@ describe('resolvePolicy with an archiver (archiveDefaultSeconds = 7 days)', () =
     // 7-day default left in place would be an invalid policy, so the
     // default steps aside instead of turning the override into a 400.
     expect(
-      resolvePolicy({ stopAfterSeconds: null }, ARCHIVE_DEFAULT_SECONDS),
+      resolvePolicy({ stopAfterSeconds: null }, ARCHIVER_DEFAULTS, true),
     ).toEqual({
       ...DEFAULT_LIFECYCLE_POLICY,
       stopAfterSeconds: null,
@@ -75,7 +95,7 @@ describe('resolvePolicy with an archiver (archiveDefaultSeconds = 7 days)', () =
     // 7-day archive default — archiving then begins when stopping does.
     const thirtyDays = 30 * 24 * 60 * 60;
     expect(
-      resolvePolicy({ stopAfterSeconds: thirtyDays }, ARCHIVE_DEFAULT_SECONDS),
+      resolvePolicy({ stopAfterSeconds: thirtyDays }, ARCHIVER_DEFAULTS, true),
     ).toEqual({
       ...DEFAULT_LIFECYCLE_POLICY,
       stopAfterSeconds: thirtyDays,
@@ -86,7 +106,7 @@ describe('resolvePolicy with an archiver (archiveDefaultSeconds = 7 days)', () =
   it('rejects an explicit archive threshold below the stop threshold', () => {
     // Default stopAfterSeconds is 3 days; archiving after 1s must fail.
     expect(() =>
-      resolvePolicy({ archiveAfterSeconds: 1 }, ARCHIVE_DEFAULT_SECONDS),
+      resolvePolicy({ archiveAfterSeconds: 1 }, ARCHIVER_DEFAULTS, true),
     ).toThrow(/stopAfterSeconds/);
   });
 
@@ -94,8 +114,42 @@ describe('resolvePolicy with an archiver (archiveDefaultSeconds = 7 days)', () =
     expect(() =>
       resolvePolicy(
         { stopAfterSeconds: null, archiveAfterSeconds: 60 },
-        ARCHIVE_DEFAULT_SECONDS,
+        ARCHIVER_DEFAULTS,
+        true,
       ),
     ).toThrow(/archiveAfterSeconds requires a stopAfterSeconds/);
   });
 });
+
+describe('resolvePolicy with operator-edited defaults (runtime settings)', () => {
+  it('an operator default of never-stop flows to new sandboxes', () => {
+    expect(
+      resolvePolicy(
+        undefined,
+        {
+          freezeAfterSeconds: 120,
+          stopAfterSeconds: null,
+          archiveAfterSeconds: null,
+        },
+        true,
+      ),
+    ).toEqual({
+      freezeAfterSeconds: 120,
+      stopAfterSeconds: null,
+      archiveAfterSeconds: null,
+    });
+  });
+
+  it('a never-archive default still accepts an explicit archive override', () => {
+    // The archiver exists; the operator merely changed what "asks for
+    // nothing" means. An explicit request must not be refused.
+    const week = 7 * 24 * 60 * 60;
+    expect(
+      resolvePolicy(
+        { archiveAfterSeconds: week },
+        { ...DEFAULT_LIFECYCLE_POLICY, archiveAfterSeconds: null },
+        true,
+      ).archiveAfterSeconds,
+    ).toBe(week);
+  });
+});
diff --git a/packages/server/src/policy.ts b/packages/server/src/policy.ts
index d0c819f..261bb2a 100644
--- a/packages/server/src/policy.ts
+++ b/packages/server/src/policy.ts
@@ -1,5 +1,4 @@
 import {
-  DEFAULT_LIFECYCLE_POLICY,
   type LifecyclePolicy,
   type LifecyclePolicyOverride,
   lifecyclePolicySchema,
@@ -8,7 +7,9 @@ import {
 /**
  * The default distance from stopped to archived, applied only when the
  * daemon actually has an archiver (S3 configured) — the shared default
- * stays null because a promise nobody can honor is a standing lie.
+ * stays null because a promise nobody can honor is a standing lie. Since
+ * runtime settings landed this is only the first-boot SEED of the ledger's
+ * defaultPolicy.archiveAfterSeconds; the ledger value is what acquires read.
  */
 export const ARCHIVE_DEFAULT_SECONDS = 7 * 24 * 60 * 60;
 
@@ -27,34 +28,37 @@ export class ArchiveDisabledError extends Error {
  * `null` is meaningful for stop and archive ("never take that step"), so
  * only `undefined` falls back to the default.
  *
- * archiveDefaultSeconds is the caller's adjudication of "is the archiver
- * configured" (null = no): every call site answers explicitly. With no
- * archiver, an override explicitly asking to archive is refused — and the
- * archive default is null. With one, the default yields to an explicit
- * stop rather than fighting it: a never-stop sandbox never archives (only
- * a stopped sandbox can), and a stop pushed past the archive default drags
- * the default along instead of turning a legal stop override into an
- * ordering error.
+ * `defaults` is the ledger's defaultPolicy (runtime settings — what a
+ * sandbox that asks for nothing gets). `archiveEnabled` is the caller's
+ * adjudication of "is the archiver configured", decided once per boot by
+ * the archiver's presence; it is a separate flag because a null default
+ * archive is ambiguous on its own — it means either "no archiver" or "an
+ * operator chose never-archive by default", and only the first refuses an
+ * explicit archive-asking override. The archive default yields to an
+ * explicit stop rather than fighting it: a never-stop sandbox never
+ * archives (only a stopped sandbox can), and a stop pushed past the archive
+ * default drags the default along instead of turning a legal stop override
+ * into an ordering error.
  */
 export function resolvePolicy(
   override: LifecyclePolicyOverride | undefined,
-  archiveDefaultSeconds: number | null,
+  defaults: LifecyclePolicy,
+  archiveEnabled: boolean,
 ): LifecyclePolicy {
-  if (archiveDefaultSeconds === null && override?.archiveAfterSeconds != null) {
+  if (!archiveEnabled && override?.archiveAfterSeconds != null) {
     throw new ArchiveDisabledError();
   }
   const stopAfterSeconds =
     override?.stopAfterSeconds !== undefined
       ? override.stopAfterSeconds
-      : DEFAULT_LIFECYCLE_POLICY.stopAfterSeconds;
+      : defaults.stopAfterSeconds;
   const archiveDefault =
-    archiveDefaultSeconds === null || stopAfterSeconds === null
+    defaults.archiveAfterSeconds === null || stopAfterSeconds === null
       ? null
-      : Math.max(archiveDefaultSeconds, stopAfterSeconds);
+      : Math.max(defaults.archiveAfterSeconds, stopAfterSeconds);
   return lifecyclePolicySchema.parse({
     freezeAfterSeconds:
-      override?.freezeAfterSeconds ??
-      DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
+      override?.freezeAfterSeconds ?? defaults.freezeAfterSeconds,
     stopAfterSeconds,
     archiveAfterSeconds:
       override?.archiveAfterSeconds !== undefined
diff --git a/packages/server/src/routes/config.ts b/packages/server/src/routes/config.ts
index 74a2a47..7c7e3a2 100644
--- a/packages/server/src/routes/config.ts
+++ b/packages/server/src/routes/config.ts
@@ -1,24 +1,30 @@
 import { getConfigResponseSchema } from '@dormice/shared';
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import { CONFIG_KEYS, type Config, type ConfigSources } from '../config';
+import type { Db } from '../db/db';
+import { readRuntimeSettings } from '../db/settings';
 
 export interface ConfigRoutesOptions {
   config: Config;
+  db: Db;
   sources: ConfigSources;
   /** buildApp's one adjudication of the archive default (null = no archiver). */
   archiveDefaultSeconds: number | null;
 }
 
 /**
- * The daemon's effective configuration, read-only: what is actually in
- * force, not what a config file says (doctor's discipline). Editing stays
- * on the host — /etc/dormice/env plus a restart — because a daemon that
- * rewrites its own environment is a different security decision entirely.
- * Secrets never cross the wire: set-or-unset is all anyone learns.
+ * The daemon's effective configuration: the env knobs (read-only — editing
+ * those stays on the host, /etc/dormice/env plus a restart, because a
+ * daemon that rewrites its own environment is a different security
+ * decision entirely) plus the ledger-resident runtime settings, which DO
+ * have a write verb (updateSettings, admin scope). For the knobs that
+ * moved into the ledger the env entries below are first-boot seeds;
+ * `settings` is what is in force. Secrets never cross the wire: set-or-
+ * unset is all anyone learns.
  */
 export const configRoutes: FastifyPluginAsyncZod<ConfigRoutesOptions> = async (
   app,
-  { config, sources, archiveDefaultSeconds },
+  { config, db, sources, archiveDefaultSeconds },
 ) => {
   app.post(
     '/getConfig',
@@ -27,21 +33,32 @@ export const configRoutes: FastifyPluginAsyncZod<ConfigRoutesOptions> = async (
         response: { 200: getConfigResponseSchema },
       },
     },
-    async () => ({
-      entries: (Object.keys(CONFIG_KEYS) as Array<keyof Config>).map((key) => {
-        const { sensitive } = CONFIG_KEYS[key];
-        const value = config[key];
-        return {
-          key,
-          value: sensitive || value === undefined ? null : String(value),
-          source: sources[key],
-          ...(sensitive && value !== undefined ? { redacted: true } : {}),
-        };
-      }),
-      archive: {
-        enabled: archiveDefaultSeconds !== null,
-        defaultSeconds: archiveDefaultSeconds,
-      },
-    }),
+    async () => {
+      const settings = readRuntimeSettings(db);
+      return {
+        entries: (Object.keys(CONFIG_KEYS) as Array<keyof Config>).map(
+          (key) => {
+            const { sensitive } = CONFIG_KEYS[key];
+            const value = config[key];
+            return {
+              key,
+              value: sensitive || value === undefined ? null : String(value),
+              source: sources[key],
+              ...(sensitive && value !== undefined ? { redacted: true } : {}),
+            };
+          },
+        ),
+        archive: {
+          enabled: archiveDefaultSeconds !== null,
+          // What new sandboxes actually get is the ledger's default policy
+          // — the boot constant is only its seed.
+          defaultSeconds:
+            archiveDefaultSeconds === null
+              ? null
+              : settings.defaultPolicy.archiveAfterSeconds,
+        },
+        settings,
+      };
+    },
   );
 };
diff --git a/packages/server/src/routes/host.ts b/packages/server/src/routes/host.ts
index f50ec7b..fc759e9 100644
--- a/packages/server/src/routes/host.ts
+++ b/packages/server/src/routes/host.ts
@@ -15,6 +15,7 @@ import {
   resolveBucketSeconds,
   resolveWindow,
 } from '../db/metrics';
+import { readRuntimeSettings } from '../db/settings';
 import type { Executor } from '../executor/executor';
 import { CpuSampler, readDiskSpace, readHostMemory } from '../host-metrics';
 
@@ -65,7 +66,8 @@ export const hostRoutes: FastifyPluginAsyncZod<HostRoutesOptions> = async (
           : null,
         sandboxes: {
           total,
-          maxSandboxes: config.DORMICE_MAX_SANDBOXES,
+          // The ledger's live knob, not the env seed — the console edits it.
+          maxSandboxes: readRuntimeSettings(db).maxSandboxes,
           byState,
         },
         sandboxDisks: await executor.diskUsage(),
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index 12d4df7..c8f6e60 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -59,6 +59,7 @@ import {
   resolveWindow,
 } from '../db/metrics';
 import type { SandboxRow } from '../db/schema';
+import { readRuntimeSettings } from '../db/settings';
 import { findTemplate, resolveImage } from '../db/templates';
 import { startExecHeartbeat } from '../exec-heartbeat';
 import {
@@ -189,11 +190,13 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
     // The capacity check lives at the only verb that creates — wakes of
     // existing sandboxes are never blocked. Disk is the real ceiling: every
     // sandbox holds a disk image, and unbounded creation fills the host
-    // until the ledger itself can no longer write.
-    if (countSandboxes(db) >= config.DORMICE_MAX_SANDBOXES) {
+    // until the ledger itself can no longer write. Read live from the
+    // ledger: a console edit applies to the very next create.
+    const maxSandboxes = readRuntimeSettings(db).maxSandboxes;
+    if (countSandboxes(db) >= maxSandboxes) {
       throw httpError(
         429,
-        `sandbox limit reached (DORMICE_MAX_SANDBOXES=${config.DORMICE_MAX_SANDBOXES}) — destroy a sandbox or raise the limit`,
+        `sandbox limit reached (maxSandboxes=${maxSandboxes}) — destroy a sandbox or raise the limit in settings`,
       );
     }
 
@@ -271,7 +274,11 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       // deserves a 400, not a silent ignore.
       let policy: LifecyclePolicy;
       try {
-        policy = resolvePolicy(override, archiveDefaultSeconds);
+        policy = resolvePolicy(
+          override,
+          readRuntimeSettings(db).defaultPolicy,
+          archiveDefaultSeconds !== null,
+        );
       } catch (error) {
         if (error instanceof ZodError) {
           // The override passed shape validation but the merged policy broke
diff --git a/packages/server/src/routes/settings.test.ts b/packages/server/src/routes/settings.test.ts
new file mode 100644
index 0000000..a3e3037
--- /dev/null
+++ b/packages/server/src/routes/settings.test.ts
@@ -0,0 +1,221 @@
+import { fileURLToPath } from 'node:url';
+import {
+  DEFAULT_LIFECYCLE_POLICY,
+  getConfigResponseSchema,
+  listActivityResponseSchema,
+  updateSettingsResponseSchema,
+} from '@dormice/shared';
+import { describe, expect, it } from 'vitest';
+import { buildApp } from '../app';
+import { loadConfig } from '../config';
+import { migrateDb, openDb } from '../db/db';
+import { FakeExecutor } from '../executor/fake';
+import { KeyedQueue } from '../keyed-queue';
+
+const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
+const TOKEN = 'test-token-test-token-test-token';
+const authed = { authorization: `Bearer ${TOKEN}` };
+
+function freshDb() {
+  const db = openDb(':memory:');
+  migrateDb(db, MIGRATIONS);
+  return db;
+}
+
+function appOn(
+  db: ReturnType<typeof freshDb>,
+  env: Record<string, string> = {},
+) {
+  const config = loadConfig({
+    DORMICE_DB_PATH: ':memory:',
+    DORMICE_NODE_ID: 'node-test',
+    DORMICE_API_TOKEN: TOKEN,
+    ...env,
+  });
+  return buildApp({
+    config,
+    db,
+    executor: new FakeExecutor(),
+    locks: new KeyedQueue(),
+    logger: false,
+  });
+}
+
+type App = ReturnType<typeof appOn>;
+
+function rpc(
+  app: App,
+  url: string,
+  payload: Record<string, unknown> = {},
+  headers: Record<string, string> = authed,
+) {
+  return app.inject({ method: 'POST', url, headers, payload });
+}
+
+async function settingsOf(app: App) {
+  const res = await rpc(app, '/getConfig');
+  expect(res.statusCode).toBe(200);
+  return getConfigResponseSchema.parse(res.json()).settings;
+}
+
+describe('runtime settings: seeding', () => {
+  it('seeds from the env at first boot, defaults where the env is silent', async () => {
+    const app = appOn(freshDb(), {
+      DORMICE_MAX_SANDBOXES: '7',
+      DORMICE_SANDBOX_DISK_GB: '20',
+    });
+    expect(await settingsOf(app)).toEqual({
+      maxSandboxes: 7,
+      sandboxDefaults: { cpus: 1, memoryGb: 2, diskGb: 20 },
+      // No archiver in this app, so the seeded default never archives.
+      defaultPolicy: { ...DEFAULT_LIFECYCLE_POLICY, archiveAfterSeconds: null },
+      updatedAt: null,
+    });
+  });
+
+  it('the ledger wins over a later env edit — seeds are read once', async () => {
+    const db = freshDb();
+    appOn(db, { DORMICE_MAX_SANDBOXES: '5' });
+    // Same ledger, "restarted" with a different env: the row already
+    // exists, so the new env value is deliberately ignored...
+    const rebooted = appOn(db, { DORMICE_MAX_SANDBOXES: '9' });
+    expect((await settingsOf(rebooted)).maxSandboxes).toBe(5);
+    // ...while getConfig still reports what the env says, as an entry.
+    const body = getConfigResponseSchema.parse(
+      (await rpc(rebooted, '/getConfig')).json(),
+    );
+    expect(
+      body.entries.find((e) => e.key === 'DORMICE_MAX_SANDBOXES')?.value,
+    ).toBe('9');
+  });
+});
+
+describe('updateSettings', () => {
+  it('raises maxSandboxes with immediate effect on the acquire gate', async () => {
+    const app = appOn(freshDb(), { DORMICE_MAX_SANDBOXES: '1' });
+    expect((await rpc(app, '/acquireSandbox', { name: 'a' })).statusCode).toBe(
+      200,
+    );
+    expect((await rpc(app, '/acquireSandbox', { name: 'b' })).statusCode).toBe(
+      429,
+    );
+
+    const res = await rpc(app, '/updateSettings', { maxSandboxes: 2 });
+    expect(res.statusCode).toBe(200);
+    expect(
+      updateSettingsResponseSchema.parse(res.json()).settings.maxSandboxes,
+    ).toBe(2);
+
+    // No restart, no re-read of the env: the very next create passes.
+    expect((await rpc(app, '/acquireSandbox', { name: 'b' })).statusCode).toBe(
+      200,
+    );
+    // And the observation window reports the new capacity.
+    const host = await rpc(app, '/getHostMetrics');
+    expect(host.json().sandboxes.maxSandboxes).toBe(2);
+  });
+
+  it('a new default policy applies to the next acquire, not existing sandboxes', async () => {
+    const app = appOn(freshDb());
+    const before = await rpc(app, '/acquireSandbox', { name: 'old' });
+    expect(before.json().sandbox.policy.freezeAfterSeconds).toBe(
+      DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
+    );
+
+    await rpc(app, '/updateSettings', {
+      defaultPolicy: {
+        freezeAfterSeconds: 42,
+        stopAfterSeconds: null,
+        archiveAfterSeconds: null,
+      },
+    });
+
+    const created = await rpc(app, '/acquireSandbox', { name: 'new' });
+    expect(created.json().sandbox.policy).toMatchObject({
+      freezeAfterSeconds: 42,
+      stopAfterSeconds: null,
+    });
+    // Existing sandboxes keep the policy they were born with.
+    const woken = await rpc(app, '/acquireSandbox', { name: 'old' });
+    expect(woken.json().sandbox.policy.freezeAfterSeconds).toBe(
+      DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
+    );
+  });
+
+  it('replaces provided groups whole and leaves the rest untouched', async () => {
+    const app = appOn(freshDb(), { DORMICE_SANDBOX_MEMORY_GB: '4' });
+    await rpc(app, '/updateSettings', { maxSandboxes: 50 });
+    const settings = await settingsOf(app);
+    expect(settings.maxSandboxes).toBe(50);
+    expect(settings.sandboxDefaults.memoryGb).toBe(4);
+    expect(settings.updatedAt).not.toBeNull();
+  });
+
+  it('refuses an archiving default when the daemon has no archiver', async () => {
+    const app = appOn(freshDb());
+    const res = await rpc(app, '/updateSettings', {
+      defaultPolicy: {
+        freezeAfterSeconds: 600,
+        stopAfterSeconds: 3600,
+        archiveAfterSeconds: 7200,
+      },
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().message).toMatch(/archiving requires S3/);
+  });
+
+  it('refuses an empty patch and a disordered default policy', async () => {
+    const app = appOn(freshDb());
+    expect((await rpc(app, '/updateSettings', {})).statusCode).toBe(400);
+    const disordered = await rpc(app, '/updateSettings', {
+      defaultPolicy: {
+        freezeAfterSeconds: 100,
+        stopAfterSeconds: 50,
+        archiveAfterSeconds: null,
+      },
+    });
+    expect(disordered.statusCode).toBe(400);
+  });
+
+  it('records the change in the activity ring with its actor', async () => {
+    const app = appOn(freshDb());
+    await rpc(app, '/updateSettings', { maxSandboxes: 3 });
+    const events = listActivityResponseSchema.parse(
+      (await rpc(app, '/listActivity')).json(),
+    ).events;
+    expect(events[0]).toMatchObject({
+      kind: 'settings-updated',
+      actor: 'env-token',
+      detail: 'maxSandboxes=3',
+    });
+  });
+
+  it('is admin-only: an API key gets an honest 403', async () => {
+    const app = appOn(freshDb());
+    const minted = await rpc(app, '/createApiKey', { name: 'robot' });
+    expect(minted.statusCode).toBe(200);
+    const keyToken = minted.json().token as string;
+
+    const refused = await rpc(
+      app,
+      '/updateSettings',
+      { maxSandboxes: 999 },
+      { authorization: `Bearer ${keyToken}` },
+    );
+    expect(refused.statusCode).toBe(403);
+    expect(refused.json().message).toMatch(
+      /cannot manage API keys or settings/,
+    );
+    // And the key still opens normal doors — it is the verb that refused.
+    expect(
+      (
+        await rpc(
+          app,
+          '/listSandboxes',
+          {},
+          { authorization: `Bearer ${keyToken}` },
+        )
+      ).statusCode,
+    ).toBe(200);
+  });
+});
diff --git a/packages/server/src/routes/settings.ts b/packages/server/src/routes/settings.ts
new file mode 100644
index 0000000..9f22134
--- /dev/null
+++ b/packages/server/src/routes/settings.ts
@@ -0,0 +1,81 @@
+import {
+  updateSettingsRequestSchema,
+  updateSettingsResponseSchema,
+} from '@dormice/shared';
+import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import { z } from 'zod';
+import { recordActivity } from '../db/activity';
+import type { Db } from '../db/db';
+import { writeRuntimeSettings } from '../db/settings';
+
+export interface SettingsRoutesOptions {
+  db: Db;
+  /** buildApp's one adjudication of "is the archiver configured". */
+  archiveEnabled: boolean;
+}
+
+/**
+ * updateSettings — the write half of the runtime settings (the read rides
+ * on getConfig). Registered in the ADMIN scope: env token or console
+ * session only, like the apiKey verbs — a leaked automation key must not
+ * be able to raise the very limits that contain it.
+ *
+ * A pure ledger write with immediate effect: the consumers read live
+ * (acquire's capacity gate, the executor's births, resolvePolicy's
+ * defaults), so nothing here restarts, wakes or touches any sandbox.
+ * Lowering maxSandboxes below the current total is deliberately legal —
+ * the gate only blocks creation, and refusing would leave an operator
+ * unable to say "no more" during an incident.
+ */
+export const settingsRoutes: FastifyPluginAsyncZod<
+  SettingsRoutesOptions
+> = async (app, { db, archiveEnabled }) => {
+  app.post(
+    '/updateSettings',
+    {
+      schema: {
+        body: updateSettingsRequestSchema,
+        response: {
+          200: updateSettingsResponseSchema,
+          400: z.object({ message: z.string() }),
+        },
+      },
+    },
+    async (request, reply) => {
+      const patch = request.body;
+      // The updatePolicy doctrine: a default that promises archiving on a
+      // daemon with no archiver would be a standing lie in every acquire.
+      if (
+        !archiveEnabled &&
+        patch.defaultPolicy !== undefined &&
+        patch.defaultPolicy.archiveAfterSeconds !== null
+      ) {
+        return reply.code(400).send({
+          message:
+            'invalid default policy: archiving requires S3 (DORMICE_S3_*) to be configured',
+        });
+      }
+      const settings = writeRuntimeSettings(db, patch, new Date());
+      recordActivity(db, {
+        kind: 'settings-updated',
+        actor: request.actor,
+        detail: [
+          ...(patch.maxSandboxes !== undefined
+            ? [`maxSandboxes=${patch.maxSandboxes}`]
+            : []),
+          ...(patch.sandboxDefaults !== undefined
+            ? [
+                `sandboxDefaults=${patch.sandboxDefaults.cpus}cpu/${patch.sandboxDefaults.memoryGb}GiB/${patch.sandboxDefaults.diskGb}GiB`,
+              ]
+            : []),
+          ...(patch.defaultPolicy !== undefined
+            ? [
+                `defaultPolicy=${patch.defaultPolicy.freezeAfterSeconds}s/${patch.defaultPolicy.stopAfterSeconds ?? 'never'}/${patch.defaultPolicy.archiveAfterSeconds ?? 'never'}`,
+              ]
+            : []),
+        ].join(', '),
+      });
+      return { settings };
+    },
+  );
+};
diff --git a/packages/shared/src/activity.ts b/packages/shared/src/activity.ts
index af1cf89..3d02b8c 100644
--- a/packages/shared/src/activity.ts
+++ b/packages/shared/src/activity.ts
@@ -31,6 +31,8 @@ export const ACTIVITY_KINDS = [
   'daemon-started',
   /** An operator bound or cleared the console domain through setIngress. */
   'ingress-updated',
+  /** updateSettings rewrote runtime settings; the detail names the groups that moved. */
+  'settings-updated',
   /** An operator minted an API key (createApiKey). The token itself is never logged. */
   'apikey-created',
   /** updateApiKey changed a key's name or expiry; the detail names what moved. */
diff --git a/packages/shared/src/config.ts b/packages/shared/src/config.ts
index 451a22f..753ff86 100644
--- a/packages/shared/src/config.ts
+++ b/packages/shared/src/config.ts
@@ -1,11 +1,14 @@
 import { z } from 'zod';
+import { runtimeSettingsSchema } from './settings';
 
 /**
- * getConfig() — the daemon's effective configuration, read-only: every knob
- * with the value actually in force and where it came from. The same
- * discipline as doctor: report effective values, never parrot a config
- * file. Secrets are reported as present-or-absent only — their value never
- * crosses the wire, whoever asks.
+ * getConfig() — the daemon's effective configuration: every env knob with
+ * the value actually in force and where it came from, plus the runtime
+ * settings that live in the ledger (see settings.ts — for those knobs the
+ * env entries below are first-boot seeds, and `settings` is what is in
+ * force). The same discipline as doctor: report effective values, never
+ * parrot a config file. Secrets are reported as present-or-absent only —
+ * their value never crosses the wire, whoever asks.
  */
 export const configEntrySchema = z.object({
   /** The environment variable name, e.g. DORMICE_PORT. */
@@ -33,9 +36,14 @@ export const getConfigResponseSchema = z.object({
    */
   archive: z.object({
     enabled: z.boolean(),
-    /** Null exactly when disabled: a promise nobody can honor is never made. */
+    /**
+     * Null when disabled (a promise nobody can honor is never made) — and
+     * also when the operator set the default policy to never archive.
+     */
     defaultSeconds: z.number().int().nullable(),
   }),
+  /** The ledger-resident operator knobs actually in force — see settings.ts. */
+  settings: runtimeSettingsSchema,
 });
 
 export type GetConfigResponse = z.infer<typeof getConfigResponseSchema>;
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index e1c9477..1428557 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -13,6 +13,7 @@ export * from './metrics';
 export * from './policy';
 export * from './rebuild';
 export * from './sandbox';
+export * from './settings';
 export * from './states';
 export * from './templates';
 export * from './update-metadata';
diff --git a/packages/shared/src/settings.ts b/packages/shared/src/settings.ts
new file mode 100644
index 0000000..1c41f3a
--- /dev/null
+++ b/packages/shared/src/settings.ts
@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { lifecyclePolicySchema } from './policy';
+
+/**
+ * Runtime settings — the operator knobs that live in the ledger, not the
+ * environment. The dividing line (2026-07-19): a knob belongs here exactly
+ * when changing it is an operations decision that must not require shell
+ * access and a restart (capacity, what new sandboxes get); it stays an env
+ * variable when changing it makes a different daemon (port, token,
+ * executor, data dir, domain).
+ *
+ * The env variables of the same names still exist — as first-boot seeds
+ * only. Once the ledger row exists, the ledger is the single truth and a
+ * later env edit is deliberately ignored: two live sources for one knob is
+ * a standing ambiguity, and the ledger is the daemon's one writable truth.
+ */
+export const sandboxResourceDefaultsSchema = z.object({
+  /** CPU allowance per sandbox. Applies to every container launched after the change. */
+  cpus: z.number().positive(),
+  /** Memory cap per sandbox, GiB. Same launch-time application as cpus. */
+  memoryGb: z.number().positive(),
+  /**
+   * Nominal disk size per sandbox, GiB. Consulted only when a disk is born
+   * (first create, restore-from-archive) — an existing sandbox's disk never
+   * resizes, because the disk is the sandbox's body.
+   */
+  diskGb: z.number().positive(),
+});
+
+export type SandboxResourceDefaults = z.infer<
+  typeof sandboxResourceDefaultsSchema
+>;
+
+export const runtimeSettingsSchema = z.object({
+  /** How many sandboxes may exist at once; past it, creation answers 429. Wakes are never blocked. */
+  maxSandboxes: z.number().int().positive(),
+  sandboxDefaults: sandboxResourceDefaultsSchema,
+  /** What acquire() gives a sandbox that asks for nothing. Existing sandboxes keep theirs. */
+  defaultPolicy: lifecyclePolicySchema,
+  /** ISO 8601 of the last updateSettings; null = still exactly the first-boot seed. */
+  updatedAt: z.string().nullable(),
+});
+
+export type RuntimeSettings = z.infer<typeof runtimeSettingsSchema>;
+
+/**
+ * updateSettings(patch) — every provided group replaces that group whole
+ * (the updatePolicy doctrine: what the form shows is what gets written, no
+ * field-level merge ambiguity); absent groups stay untouched. At least one
+ * group must be present — an empty patch is a caller confusion, not a no-op.
+ */
+export const updateSettingsRequestSchema = z
+  .object({
+    maxSandboxes: z.number().int().positive().optional(),
+    sandboxDefaults: sandboxResourceDefaultsSchema.optional(),
+    defaultPolicy: lifecyclePolicySchema.optional(),
+  })
+  .refine(
+    (patch) =>
+      patch.maxSandboxes !== undefined ||
+      patch.sandboxDefaults !== undefined ||
+      patch.defaultPolicy !== undefined,
+    {
+      message:
+        'updateSettings needs at least one of maxSandboxes, sandboxDefaults, defaultPolicy',
+    },
+  );
+
+export type UpdateSettingsRequest = z.input<typeof updateSettingsRequestSchema>;
+
+export const updateSettingsResponseSchema = z.object({
+  settings: runtimeSettingsSchema,
+});
+
+export type UpdateSettingsResponse = z.infer<
+  typeof updateSettingsResponseSchema
+>;
diff --git a/website/content/docs/configuration.mdx b/website/content/docs/configuration.mdx
index 4796447..149ad04 100644
--- a/website/content/docs/configuration.mdx
+++ b/website/content/docs/configuration.mdx
@@ -48,6 +48,14 @@ picks up current CPU/memory/pids values — but keeps the disk, so a
 changed disk size only applies to new sandboxes and restores from
 archive.
 
+The disk, CPU and memory variables are **first-boot seeds**: on the
+daemon's first start they are written into its database as runtime
+settings, and from then on the database value is what's in force — edit
+it live from the console's settings page (or the `updateSettings` verb),
+no restart needed. Once seeded, changing these variables in the
+environment has no effect. The same applies to `DORMICE_MAX_SANDBOXES`
+below. `DORMICE_SANDBOX_PIDS_LIMIT` stays a plain environment variable.
+
 | Variable | Default | What it does |
 | --- | --- | --- |
 | `DORMICE_SANDBOX_DISK_GB` | `10` | Size of each sandbox's disk. The quota is physical and the image is sparse — unwritten space costs nothing. |
@@ -60,7 +68,7 @@ archive.
 | Variable | Default | What it does |
 | --- | --- | --- |
 | `DORMICE_SCAN_INTERVAL_SECONDS` | `60` | How often the idle scanner runs. Each sweep moves an idle sandbox down at most one state — see [Sandbox lifecycle](/docs/lifecycle). |
-| `DORMICE_MAX_SANDBOXES` | `100` | How many sandboxes may exist at once. Past the cap, *creation* answers 429; wakes of existing sandboxes are never blocked. |
+| `DORMICE_MAX_SANDBOXES` | `100` | How many sandboxes may exist at once. Past the cap, *creation* answers 429; wakes of existing sandboxes are never blocked. First-boot seed — after that, the live value is edited in the console's settings page. |
 | `DORMICE_RECLAIM_TIMEOUT_SECONDS` | `45` | Upper bound on the memory-reclaim step of a freeze. Hitting it is expected on stubborn workloads, not a failure. |
 
 ## Sandbox network
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
index 6c41855..e6c121c 100644
--- a/website/content/docs/console.mdx
+++ b/website/content/docs/console.mdx
@@ -118,9 +118,13 @@ Four more pages round out the operator view:
   probe that shows DNS and certificate progress until each one turns
   green. See
   [Installation](/docs/installation#connect-from-another-machine).
-- **Settings** — the daemon's effective configuration, read-only, with
-  secrets shown as present-or-absent only. Changing configuration
-  happens in `/etc/dormice/env` plus a restart, never from the browser.
+- **Settings** — two halves. The operational knobs (sandbox capacity
+  cap, default resources for new sandboxes, default lifecycle policy)
+  live in the daemon's database and are edited right here, taking effect
+  immediately — no restart, no sandbox touched. Everything else is the
+  effective environment configuration, read-only, with secrets shown as
+  present-or-absent only; changing those happens in `/etc/dormice/env`
+  plus a restart, never from the browser.
 - **Version** — the build the daemon is running (a git commit — trunk
   commit titles are the changelog) compared against the latest, with a
   one-click [upgrade](/docs/upgrading) and live progress where the host
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
index 54d5f4c..add3afe 100644
--- a/website/content/docs/http-api.mdx
+++ b/website/content/docs/http-api.mdx
@@ -55,7 +55,8 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | `POST /listSandboxMetrics` | every measurable sandbox's sample in one answer | — |
 | `POST /listSandboxImages` | each sandbox's born image vs its template's current one | — |
 | `POST /listActivity` | the daemon's recent history with per-event [attribution](#who-did-what), newest first — a bounded ring, not an audit log | — |
-| `POST /getConfig` | effective configuration, read-only; secrets reported present-or-absent, value never sent | — |
+| `POST /getConfig` | effective configuration: env knobs (read-only; secrets reported present-or-absent, value never sent) plus the live runtime `settings` | — |
+| `POST /updateSettings` | rewrite the runtime settings (capacity cap, new-sandbox defaults, default policy) — immediate effect, no restart; each provided group replaces that group whole | 400 empty patch or a default policy that asks to archive with no S3 configured |
 | `POST /getIngress` | domains bound on the daemon's managed reverse proxy, with live DNS and certificate probes | — |
 | `POST /setIngress` | rewrite the managed proxy config to exactly this domain list (empty list unbinds all) | 400 when the daemon manages no proxy |
 
@@ -120,11 +121,12 @@ key), with exactly two exceptions:
 
 - **Console account setup/reset** accepts only the env token — a leaked
   machine credential must not be able to take over the human account.
-- **The four apiKey verbs themselves** (`createApiKey`, `listApiKeys`,
-  `updateApiKey`, `revokeApiKey`) accept only the env token or a console
-  session. A key that could manage keys is a self-replication ladder —
-  one leaked credential minting itself an unrevoked successor — so a
-  valid key gets an honest 403 on these routes.
+- **The four apiKey verbs and `updateSettings`** accept only the env
+  token or a console session. A key that could manage keys is a
+  self-replication ladder — one leaked credential minting itself an
+  unrevoked successor — and a leaked key must not be able to raise the
+  very limits that contain it, so a valid key gets an honest 403 on
+  these routes.
 
 Each key has two handles: `name`, the human label (renameable through
 `updateApiKey`), and `id`, the stable address `updateApiKey` and
diff --git a/website/content/docs/metrics.mdx b/website/content/docs/metrics.mdx
index 3d26058..baa72c3 100644
--- a/website/content/docs/metrics.mdx
+++ b/website/content/docs/metrics.mdx
@@ -68,7 +68,7 @@ The snapshot has four sections:
 | --- | --- |
 | `host` | CPU usage, available memory, and **swap** — the freeze mechanism's fuel. Frozen sandboxes live in swap; a full swap means "idle is free" is ending. |
 | `dataDisk` | The filesystem holding sandbox disks (`DORMICE_DATA_DIR`). This is the real capacity ceiling: past full, even the daemon's database cannot write. |
-| `sandboxes` | Totals from the daemon's records: sandbox count, the `DORMICE_MAX_SANDBOXES` cap, and a count per lifecycle state. |
+| `sandboxes` | Totals from the daemon's records: sandbox count, the capacity cap (seeded from `DORMICE_MAX_SANDBOXES`, edited live in the console's settings page), and a count per lifecycle state. |
 | `sandboxDisks` | What the sparse disk images *promise* (nominal) versus what they *occupy* (actual). The gap is your disk overcommit — watch it, because nothing else caps it. Measured on the test host: a sandbox promising 10 GiB actually occupied 68 MiB. |
 
 **Readings are honest about their limits:**
diff --git a/website/content/docs/troubleshooting.mdx b/website/content/docs/troubleshooting.mdx
index bd5986d..813a783 100644
--- a/website/content/docs/troubleshooting.mdx
+++ b/website/content/docs/troubleshooting.mdx
@@ -85,11 +85,12 @@ image probe warns about exactly this.
 
 ## `acquireSandbox` answers 429
 
-The sandbox limit (`DORMICE_MAX_SANDBOXES`, default 100) gates
-*creation* only — waking an existing sandbox is never blocked. Before
-raising it, look at the disk-overcommit figure in
-[`getHostMetrics`](/docs/metrics): disk is the real ceiling, and past
-full even the daemon's database cannot write.
+The sandbox limit (default 100, seeded from `DORMICE_MAX_SANDBOXES`)
+gates *creation* only — waking an existing sandbox is never blocked.
+Raise it live in the console's settings page (or the `updateSettings`
+verb); no restart needed. Before raising it, look at the disk-overcommit
+figure in [`getHostMetrics`](/docs/metrics): disk is the real ceiling,
+and past full even the daemon's database cannot write.
 
 ## Creating from a template fails: "image … is not on this host"
 

From 6b9968bd0bd0feaa87fe977bad8324a872dc8e8d Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 19 Jul 2026 17:24:58 +0800
Subject: [PATCH 113/133] =?UTF-8?q?=E8=87=AA=E5=AE=A1=E6=8F=AA=E5=87=BA?=
 =?UTF-8?q?=E5=B9=B6=E4=BF=AE=E6=8E=89=E8=BF=90=E8=90=A5=E6=97=8B=E9=92=AE?=
 =?UTF-8?q?=E7=9A=84=E4=B8=80=E6=9D=A1=E6=BC=82=E7=A7=BB=E8=B0=8E=E8=A8=80?=
 =?UTF-8?q?:=E5=BD=92=E6=A1=A3=E5=99=A8=E8=A2=AB=E7=A7=BB=E9=99=A4?=
 =?UTF-8?q?=E5=90=8E,=E8=B4=A6=E6=9C=AC=E9=87=8C=E6=AE=8B=E7=95=99?=
 =?UTF-8?q?=E7=9A=84=E5=BD=92=E6=A1=A3=E9=BB=98=E8=AE=A4=E5=80=BC=E4=BB=8D?=
 =?UTF-8?q?=E4=BC=9A=E6=B5=81=E8=BF=9B=E6=96=B0=E6=B2=99=E7=AE=B1=E7=9A=84?=
 =?UTF-8?q?=E7=AD=96=E7=95=A5=E3=80=82=E5=A4=8D=E7=8E=B0=E8=B7=AF=E5=BE=84?=
 =?UTF-8?q?=E5=8F=AA=E6=9C=89=E4=B8=80=E6=9D=A1=E2=80=94=E2=80=94=E9=85=8D?=
 =?UTF-8?q?=E7=9D=80=20S3=20=E6=97=B6=E6=8A=8A=E9=BB=98=E8=AE=A4=E7=AD=96?=
 =?UTF-8?q?=E7=95=A5=E6=94=B9=E6=88=90"=E5=81=9C=E6=AD=A2=E5=90=8E?=
 =?UTF-8?q?=E5=BD=92=E6=A1=A3",=E9=9A=8F=E5=90=8E=E6=8B=94=E6=8E=89=20S3?=
 =?UTF-8?q?=20=E9=87=8D=E5=90=AF:updateSettings=20=E6=8B=92=E6=94=B6?=
 =?UTF-8?q?=E6=96=B0=E7=9A=84=E5=BD=92=E6=A1=A3=E9=BB=98=E8=AE=A4=E3=80=81?=
 =?UTF-8?q?=E9=A6=96=E5=90=AF=E7=A7=8D=E5=AD=90=E4=B9=9F=E4=BC=9A=E5=86=99?=
 =?UTF-8?q?=20null,=E4=BD=86=E5=B7=B2=E5=AD=98=E7=9A=84=E8=B4=A6=E6=9C=AC?=
 =?UTF-8?q?=E8=A1=8C=E5=8E=9F=E6=A0=B7=E8=BF=87=E5=86=AC,resolvePolicy=20?=
 =?UTF-8?q?=E6=97=A7=E5=AE=9E=E7=8E=B0=E5=8F=AA=E6=8C=A1=E6=98=BE=E5=BC=8F?=
 =?UTF-8?q?=20override=20=E4=B8=8D=E6=8C=A1=E9=BB=98=E8=AE=A4=E5=80=BC,?=
 =?UTF-8?q?=E4=BA=8E=E6=98=AF=20acquire=20=E4=BC=9A=E9=93=B8=E5=87=BA=20da?=
 =?UTF-8?q?emon=20=E6=A0=B9=E6=9C=AC=E6=89=A7=E8=A1=8C=E4=B8=8D=E4=BA=86?=
 =?UTF-8?q?=E7=9A=84=E5=BD=92=E6=A1=A3=E6=89=BF=E8=AF=BA(scanner=20?=
 =?UTF-8?q?=E6=97=A0=E5=BD=92=E6=A1=A3=E5=99=A8=E6=97=B6=E4=BC=98=E9=9B=85?=
 =?UTF-8?q?=E8=B7=B3=E8=BF=87,=E6=B2=99=E7=AE=B1=E6=B0=B8=E8=BF=9C?=
 =?UTF-8?q?=E5=81=9C=E5=9C=A8=20stopped,=E7=AD=96=E7=95=A5=E5=8D=B4?=
 =?UTF-8?q?=E5=9C=A8=E6=AF=8F=E4=B8=AA=E5=93=8D=E5=BA=94=E9=87=8C=E6=92=92?=
 =?UTF-8?q?=E8=B0=8E),=E8=BF=98=E4=B8=8E=E4=B8=A4=E5=A4=84=E5=8F=A3?=
 =?UTF-8?q?=E5=BE=84=E8=87=AA=E7=9B=B8=E7=9F=9B=E7=9B=BE:=E6=98=BE?=
 =?UTF-8?q?=E5=BC=8F=20override=20=E6=B1=82=E5=BD=92=E6=A1=A3=E6=8B=92=204?=
 =?UTF-8?q?00=E3=80=81updatePolicy=20=E5=90=88=E5=B9=B6=E5=90=8E=E5=B8=A6?=
 =?UTF-8?q?=E5=BD=92=E6=A1=A3=E4=B9=9F=E6=8B=92=E3=80=82=E6=90=AC=E8=BF=9B?=
 =?UTF-8?q?=E8=B4=A6=E6=9C=AC=E5=89=8D=E4=B8=8D=E5=8F=AF=E8=83=BD=E6=9C=89?=
 =?UTF-8?q?=E8=BF=99=E7=97=85=E2=80=94=E2=80=94=E9=BB=98=E8=AE=A4=E5=80=BC?=
 =?UTF-8?q?=E6=AF=8F=E6=AC=A1=E5=BC=80=E6=9C=BA=E7=94=B1=E5=BD=92=E6=A1=A3?=
 =?UTF-8?q?=E5=99=A8=E5=9C=A8=E5=9C=BA=E4=B8=8E=E5=90=A6=E7=8E=B0=E7=AE=97?=
 =?UTF-8?q?=E3=80=82=E4=BF=AE=E6=B3=95=E4=B8=80=E8=A1=8C:resolvePolicy=20?=
 =?UTF-8?q?=E7=9A=84=E5=BD=92=E6=A1=A3=E9=BB=98=E8=AE=A4=E5=9C=A8=20!archi?=
 =?UTF-8?q?veEnabled=20=E6=97=B6=E4=B8=80=E5=B9=B6=E9=81=AE=E8=94=BD,?=
 =?UTF-8?q?=E4=B8=8E=20getConfig=20=E6=97=A9=E5=B0=B1=E5=81=9A=E5=AF=B9?=
 =?UTF-8?q?=E7=9A=84=20archive.defaultSeconds=20=E9=81=AE=E8=94=BD?=
 =?UTF-8?q?=E5=90=8C=E4=B8=80=E6=9D=A1=E9=81=93=E7=90=86;=E8=B4=A6?=
 =?UTF-8?q?=E6=9C=AC=E8=A1=8C=E5=88=BB=E6=84=8F=E4=B8=8D=E5=8A=A8=E2=80=94?=
 =?UTF-8?q?=E2=80=94=E6=93=8D=E4=BD=9C=E5=91=98=E7=9A=84=E9=80=89=E6=8B=A9?=
 =?UTF-8?q?=E7=95=99=E7=9D=80,S3=20=E5=9B=9E=E6=9D=A5=E8=87=AA=E5=8A=A8?=
 =?UTF-8?q?=E5=A4=8D=E6=B4=BB=E3=80=82=E5=9B=9E=E5=BD=92=E9=92=89=E4=B8=A4?=
 =?UTF-8?q?=E6=9E=9A:policy.test=20=E5=8D=95=E5=85=83=E4=B8=80=E4=BE=8B?=
 =?UTF-8?q?=E3=80=81settings.test=20=E4=B8=A4=E4=B8=96=E4=B8=80=E4=BE=8B(?=
 =?UTF-8?q?=E6=9C=89=E5=BD=92=E6=A1=A3=E5=99=A8=E6=94=B9=E9=BB=98=E8=AE=A4?=
 =?UTF-8?q?=E2=86=92=E6=97=A0=E5=BD=92=E6=A1=A3=E5=99=A8=E9=87=8D=E5=90=AF?=
 =?UTF-8?q?=E2=86=92=E6=96=B0=20acquire=20=E5=BF=85=E9=A1=BB=E6=8B=BF?=
 =?UTF-8?q?=E5=88=B0=20null,=E4=B8=94=E8=B4=A6=E6=9C=AC=E4=BB=8D=E8=AE=B0?=
 =?UTF-8?q?=E5=BE=97=207200)=E3=80=82=E9=A1=BA=E6=89=8B=E6=8A=8A=E9=BB=98?=
 =?UTF-8?q?=E8=AE=A4=E9=85=8D=E9=A2=9D=E5=BC=B9=E7=AA=97=E7=9A=84=E7=A3=81?=
 =?UTF-8?q?=E7=9B=98=E6=96=87=E6=A1=88=E6=94=B9=E8=AF=9A=E5=AE=9E:?=
 =?UTF-8?q?=E7=A3=81=E7=9B=98=E5=9C=A8"=E7=A3=81=E7=9B=98=E5=87=BA?=
 =?UTF-8?q?=E7=94=9F=E6=97=B6"=E5=AE=9A=E5=9E=8B=E2=80=94=E2=80=94?=
 =?UTF-8?q?=E9=A6=96=E6=AC=A1=E5=88=9B=E5=BB=BA=E4=B8=8E=E5=BD=92=E6=A1=A3?=
 =?UTF-8?q?=E6=81=A2=E5=A4=8D=E9=83=BD=E7=AE=97(importDisk=20=E8=B5=B0=20p?=
 =?UTF-8?q?rovisionDisk=20=E6=8C=89=E5=BD=93=E5=89=8D=E5=80=BC=E9=87=8D?=
 =?UTF-8?q?=E9=93=B8),=E5=8E=9F=E6=96=87=E6=A1=88"=E5=8F=AA=E5=9C=A8?=
 =?UTF-8?q?=E7=AC=AC=E4=B8=80=E6=AC=A1=E5=88=9B=E5=BB=BA=E6=97=B6"?=
 =?UTF-8?q?=E6=BC=8F=E4=BA=86=E6=81=A2=E5=A4=8D=E8=BF=99=E5=8D=8A=E5=8F=A5?=
 =?UTF-8?q?,=E5=B9=B6=E8=A1=A5=E4=B8=8A"=E8=B0=83=E5=B0=8F=E5=89=8D?=
 =?UTF-8?q?=E6=B3=A8=E6=84=8F=E5=88=AB=E5=B0=8F=E4=BA=8E=E5=BD=92=E6=A1=A3?=
 =?UTF-8?q?=E6=B2=99=E7=AE=B1=E7=9C=9F=E5=AE=9E=E5=86=85=E5=AE=B9"?=
 =?UTF-8?q?=E7=9A=84=E6=8F=90=E9=86=92=E3=80=82=E5=85=A8=E9=93=BE=E5=A4=8D?=
 =?UTF-8?q?=E9=AA=8C:build/typecheck/biome=20=E5=B9=B2=E5=87=80,server=204?=
 =?UTF-8?q?88=E3=80=81sdk=2031=E3=80=81cli=2049=E3=80=81e2e=2083=20?=
 =?UTF-8?q?=E5=85=A8=E7=BB=BF;=E5=8F=A6=E8=B5=B7=E7=9C=9F=E8=BF=9B?=
 =?UTF-8?q?=E7=A8=8B=E5=8F=8C=E4=B8=96=E7=83=9F=E6=B5=8B=E2=80=94=E2=80=94?=
 =?UTF-8?q?fake=20executor=20=E8=B5=B7=20daemon=20=E7=83=AD=E6=94=B9=207?=
 =?UTF-8?q?=E2=86=92=E6=9D=80=E8=BF=9B=E7=A8=8B=E6=8D=A2=20env=3D9=20?=
 =?UTF-8?q?=E9=87=8D=E5=90=AF,=E7=94=9F=E6=95=88=E5=80=BC=E4=BB=8D=207?=
 =?UTF-8?q?=E3=80=81env=20=E6=9D=A1=E7=9B=AE=E5=A6=82=E5=AE=9E=E6=8A=A5=20?=
 =?UTF-8?q?9,=E8=B4=A6=E6=9C=AC=E8=B5=A2=E8=BF=87=20env=20=E5=9C=A8=20main?=
 =?UTF-8?q?.js=20=E7=9C=9F=E5=AE=9E=E9=87=8D=E5=90=AF=E8=B7=AF=E5=BE=84?=
 =?UTF-8?q?=E4=B8=8A=E5=AE=9E=E8=AF=81=E6=88=90=E7=AB=8B=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../components/RuntimeSettingsCard.tsx        |  3 +-
 packages/server/src/policy.test.ts            | 11 ++++++
 packages/server/src/policy.ts                 | 19 +++++++----
 packages/server/src/routes/settings.test.ts   | 34 +++++++++++++++++++
 4 files changed, 60 insertions(+), 7 deletions(-)

diff --git a/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx b/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
index d85daca..7789405 100644
--- a/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
+++ b/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
@@ -189,7 +189,8 @@ function SandboxDefaultsDialog({ settings }: { settings: RuntimeSettings }) {
           <DialogTitle>调整新沙箱的默认配额</DialogTitle>
           <DialogDescription>
             CPU/内存在下一次容器出生时生效(含停止后冷启动的存量沙箱);
-            磁盘只在沙箱第一次创建时定型 — 磁盘是沙箱的本体,永不原地改 尺寸。
+            磁盘在磁盘出生时定型(首次创建与归档恢复) —
+            磁盘是沙箱的本体,永不原地改尺寸,调小前注意别小于归档沙箱的真实内容。
           </DialogDescription>
         </DialogHeader>
         <form
diff --git a/packages/server/src/policy.test.ts b/packages/server/src/policy.test.ts
index 8d23f5b..5bbdb8a 100644
--- a/packages/server/src/policy.test.ts
+++ b/packages/server/src/policy.test.ts
@@ -140,6 +140,17 @@ describe('resolvePolicy with operator-edited defaults (runtime settings)', () =>
     });
   });
 
+  it('masks a stored archive default when the archiver is gone', () => {
+    // Drift: the operator set an archiving default while S3 was configured,
+    // then removed S3 and rebooted. The ledger still carries the threshold
+    // (and keeps it, in case S3 returns), but honoring it would mint
+    // policies the daemon cannot execute — the resolved default must be
+    // null, same as getConfig's archive.defaultSeconds masking.
+    expect(
+      resolvePolicy(undefined, ARCHIVER_DEFAULTS, false).archiveAfterSeconds,
+    ).toBeNull();
+  });
+
   it('a never-archive default still accepts an explicit archive override', () => {
     // The archiver exists; the operator merely changed what "asks for
     // nothing" means. An explicit request must not be refused.
diff --git a/packages/server/src/policy.ts b/packages/server/src/policy.ts
index 261bb2a..c3c6d0b 100644
--- a/packages/server/src/policy.ts
+++ b/packages/server/src/policy.ts
@@ -34,11 +34,16 @@ export class ArchiveDisabledError extends Error {
  * the archiver's presence; it is a separate flag because a null default
  * archive is ambiguous on its own — it means either "no archiver" or "an
  * operator chose never-archive by default", and only the first refuses an
- * explicit archive-asking override. The archive default yields to an
- * explicit stop rather than fighting it: a never-stop sandbox never
- * archives (only a stopped sandbox can), and a stop pushed past the archive
- * default drags the default along instead of turning a legal stop override
- * into an ordering error.
+ * explicit archive-asking override. The flag also masks the DEFAULT: the
+ * ledger may carry an archive threshold set in a previous life (S3
+ * configured then, removed since — updateSettings refuses new ones, but a
+ * stored one survives the reboot), and honoring it would mint policies the
+ * daemon cannot execute; the setting stays in the ledger and resurfaces if
+ * S3 comes back. The archive default yields to an explicit stop rather
+ * than fighting it: a never-stop sandbox never archives (only a stopped
+ * sandbox can), and a stop pushed past the archive default drags the
+ * default along instead of turning a legal stop override into an ordering
+ * error.
  */
 export function resolvePolicy(
   override: LifecyclePolicyOverride | undefined,
@@ -53,7 +58,9 @@ export function resolvePolicy(
       ? override.stopAfterSeconds
       : defaults.stopAfterSeconds;
   const archiveDefault =
-    defaults.archiveAfterSeconds === null || stopAfterSeconds === null
+    !archiveEnabled ||
+    defaults.archiveAfterSeconds === null ||
+    stopAfterSeconds === null
       ? null
       : Math.max(defaults.archiveAfterSeconds, stopAfterSeconds);
   return lifecyclePolicySchema.parse({
diff --git a/packages/server/src/routes/settings.test.ts b/packages/server/src/routes/settings.test.ts
index a3e3037..bfb33fa 100644
--- a/packages/server/src/routes/settings.test.ts
+++ b/packages/server/src/routes/settings.test.ts
@@ -7,6 +7,7 @@ import {
 } from '@dormice/shared';
 import { describe, expect, it } from 'vitest';
 import { buildApp } from '../app';
+import type { Archiver } from '../archive/archiver';
 import { loadConfig } from '../config';
 import { migrateDb, openDb } from '../db/db';
 import { FakeExecutor } from '../executor/fake';
@@ -25,6 +26,7 @@ function freshDb() {
 function appOn(
   db: ReturnType<typeof freshDb>,
   env: Record<string, string> = {},
+  archiver?: Archiver,
 ) {
   const config = loadConfig({
     DORMICE_DB_PATH: ':memory:',
@@ -38,6 +40,7 @@ function appOn(
     executor: new FakeExecutor(),
     locks: new KeyedQueue(),
     logger: false,
+    archiver,
   });
 }
 
@@ -177,6 +180,37 @@ describe('updateSettings', () => {
     expect(disordered.statusCode).toBe(400);
   });
 
+  it('masks a drifted archive default: archiver removed after it was set', async () => {
+    // First life: an archiver exists, the operator sets an archiving
+    // default — legal, accepted.
+    const db = freshDb();
+    // A hollow archiver: nothing in this test archives, its presence is
+    // what flips the boot's adjudication.
+    const withArchiver = appOn(db, {}, {} as unknown as Archiver);
+    const set = await rpc(withArchiver, '/updateSettings', {
+      defaultPolicy: {
+        freezeAfterSeconds: 600,
+        stopAfterSeconds: 3600,
+        archiveAfterSeconds: 7200,
+      },
+    });
+    expect(set.statusCode).toBe(200);
+
+    // Second life: same ledger, S3 removed from the env. The stored
+    // threshold survives (and would resurface with S3), but a new acquire
+    // must not be promised an archive the daemon cannot perform.
+    const withoutArchiver = appOn(db);
+    const acquired = await rpc(withoutArchiver, '/acquireSandbox', {
+      name: 'drift',
+    });
+    expect(acquired.statusCode).toBe(200);
+    expect(acquired.json().sandbox.policy.archiveAfterSeconds).toBeNull();
+    // The ledger itself still remembers the operator's choice.
+    expect(
+      (await settingsOf(withoutArchiver)).defaultPolicy.archiveAfterSeconds,
+    ).toBe(7200);
+  });
+
   it('records the change in the activity ring with its actor', async () => {
     const app = appOn(freshDb());
     await rpc(app, '/updateSettings', { maxSandboxes: 3 });

From 27844c9622b5eaa67df963e81e2db561c388063a Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 19 Jul 2026 20:08:18 +0800
Subject: [PATCH 114/133] =?UTF-8?q?=E8=BF=90=E8=90=A5=E6=97=8B=E9=92=AE?=
 =?UTF-8?q?=E6=B7=BB=E7=AC=AC=E5=9B=9B=E9=92=AE:=E8=BF=BD=E5=8A=A0=20swap?=
 =?UTF-8?q?=20=E8=BF=9B=E8=B4=A6=E6=9C=AC,=E3=80=8Cswap=20=E4=B8=8D?=
 =?UTF-8?q?=E8=BF=9B=E8=AE=BE=E7=BD=AE=E3=80=8D=E7=9A=84=E5=BD=93=E6=97=A5?=
 =?UTF-8?q?=E6=97=A7=E8=A3=81=E5=86=B3=E8=A2=AB=E4=B8=89=E6=9D=A1=E7=BD=B2?=
 =?UTF-8?q?=E5=90=8D=E7=90=86=E7=94=B1=E6=8E=A8=E7=BF=BB=E2=80=94=E2=80=94?=
 =?UTF-8?q?swap=20=E5=AE=B9=E9=87=8F=3D=E8=83=BD=E5=90=8C=E6=97=B6?=
 =?UTF-8?q?=E5=86=AC=E7=9C=A0=E5=A4=9A=E5=B0=91=E6=B2=99=E7=AE=B1=E5=86=85?=
 =?UTF-8?q?=E5=AD=98,=E6=98=AF=E4=BA=A7=E5=93=81=E6=A0=B8=E5=BF=83?=
 =?UTF-8?q?=E8=B5=84=E6=BA=90=E4=B8=8D=E6=98=AF=E6=9D=82=E9=A1=B9=20OS=20?=
 =?UTF-8?q?=E7=8A=B6=E6=80=81;daemon=20=E6=97=A9=E5=B7=B2=E6=98=AF?=
 =?UTF-8?q?=E5=AE=BF=E4=B8=BB=E8=BF=90=E7=BB=B4=E5=91=98(setIngress=20?=
 =?UTF-8?q?=E5=86=99=20Caddy=E3=80=81=E8=87=AA=E5=8D=87=E7=BA=A7=E4=BA=A4?=
 =?UTF-8?q?=E6=A3=92=20systemd=20=E6=98=AF=E5=85=88=E4=BE=8B);=E4=B8=94?=
 =?UTF-8?q?=E3=80=8C=E8=B4=A6=E6=9C=AC=E8=AE=B0=E7=9B=AE=E6=A0=87=E3=80=81?=
 =?UTF-8?q?=E5=AF=B9=E8=B4=A6=E8=AE=A9=E7=8E=B0=E5=AE=9E=E8=B7=9F=E4=B8=8A?=
 =?UTF-8?q?=E3=80=8D=E7=9A=84=E5=BF=83=E6=99=BA=E6=A8=A1=E5=9E=8B=E6=81=B0?=
 =?UTF-8?q?=E5=A5=BD=E6=B6=88=E8=A7=A3=20swapoff=20=E7=9A=84=E5=87=B6?=
 =?UTF-8?q?=E9=99=A9=E3=80=82=E8=AF=AD=E4=B9=89=E4=B8=80=E5=88=80=E5=88=87?=
 =?UTF-8?q?=E5=9C=A8=E6=97=B6=E9=97=B4=E4=B8=8A:=E5=A2=9E=E5=AE=B9?=
 =?UTF-8?q?=E7=AB=8B=E5=8D=B3(fallocate+chmod=20600+mkswap+swapon,?=
 =?UTF-8?q?=E7=A7=92=E7=BA=A7),=E7=BC=A9=E5=AE=B9=E5=8F=AA=E5=86=99?=
 =?UTF-8?q?=E8=B4=A6=E6=9C=AC=E7=AD=89=E4=B8=8B=E6=AC=A1=E5=AE=BF=E4=B8=BB?=
 =?UTF-8?q?=E9=87=8D=E5=90=AF=E2=80=94=E2=80=94=E9=93=81=E5=BE=8B=E6=98=AF?=
 =?UTF-8?q?=E6=B4=BB=E8=B7=83=20swapfile=20=E4=B8=80=E6=AC=A1=E9=83=BD?=
 =?UTF-8?q?=E4=B8=8D=E7=A2=B0,swapoff=20=E4=BC=9A=E6=8A=8A=E6=95=B4?=
 =?UTF-8?q?=E8=88=B0=E9=98=9F=E5=86=AC=E7=9C=A0=E6=B2=99=E7=AE=B1=E7=9A=84?=
 =?UTF-8?q?=E5=86=85=E5=AD=98=E6=8B=BD=E5=9B=9E=E7=89=A9=E7=90=86=E5=86=85?=
 =?UTF-8?q?=E5=AD=98;=E8=80=8C=20swap=20=E5=86=85=E5=AE=B9=E5=A4=A9?=
 =?UTF-8?q?=E7=84=B6=E4=B8=8D=E8=BF=87=E5=A4=9C,=E9=87=8D=E5=90=AF?=
 =?UTF-8?q?=E5=90=8E=E5=BC=80=E6=9C=BA=E5=AF=B9=E8=B4=A6=E5=B0=91=E6=8C=82?=
 =?UTF-8?q?=E5=A4=9A=E5=88=A0=E8=87=AA=E5=8A=A8=E6=94=B6=E6=95=9B,?=
 =?UTF-8?q?=E3=80=8C=E7=BC=A9=E3=80=8D=E5=9B=A0=E6=AD=A4=E6=98=AF=E5=8F=97?=
 =?UTF-8?q?=E6=8E=A7=E8=B7=AF=E5=BE=84=E8=80=8C=E9=9D=9E=E6=B0=B8=E4=B9=85?=
 =?UTF-8?q?=E7=A6=81=E5=8C=BA=E3=80=82=E5=8D=95=E4=B8=80=E8=A3=81=E5=86=B3?=
 =?UTF-8?q?=E7=82=B9=3Dserver/swap.ts:=E7=BA=AF=20planSwap(=E6=B4=BB?=
 =?UTF-8?q?=E8=B7=83=E5=9D=97=E4=B8=8D=E5=8F=AF=E5=8A=A8=E4=B8=94=E8=AE=A1?=
 =?UTF-8?q?=E5=85=A5=E6=80=BB=E9=87=8F=E7=BB=9D=E4=B8=8D=E5=8F=A0=E5=9D=97?=
 =?UTF-8?q?=E3=80=81=E7=BC=BA=E5=8F=A3=E4=B8=80=E6=AC=A1=E4=B8=80=E5=9D=97?=
 =?UTF-8?q?=E3=80=81=E4=B8=8D=E6=B4=BB=E8=B7=83=E5=A4=9A=E4=BD=99=E5=9D=97?=
 =?UTF-8?q?=E5=88=A0=E6=96=87=E4=BB=B6)+=E8=96=84=E6=89=A7=E8=A1=8C?=
 =?UTF-8?q?=E5=99=A8(.tmp=20=E5=BB=BA=E5=A5=BD=E6=89=8D=20rename=3D?=
 =?UTF-8?q?=E5=AD=98=E5=9C=A8=E5=8D=B3=E5=90=88=E6=B3=95=E8=AE=BE=E5=A4=87?=
 =?UTF-8?q?,swapoff=20=E5=9C=A8=E8=AF=8D=E8=A1=A8=E9=87=8C=E6=A0=B9?=
 =?UTF-8?q?=E6=9C=AC=E4=B8=8D=E5=AD=98=E5=9C=A8),=E5=BC=80=E6=9C=BA?=
 =?UTF-8?q?=E4=B8=8E=E7=83=AD=E6=94=B9=E8=B5=B0=E5=90=8C=E4=B8=80=E4=B8=AA?=
 =?UTF-8?q?=20reconcile=E3=80=82=E5=9D=97=E4=BD=8F=20$DATA=5FDIR/swap/(dae?=
 =?UTF-8?q?mon=20=E5=8F=AA=20readdir=20disks/=20=E4=B8=8D=E6=89=AB?=
 =?UTF-8?q?=E6=95=B0=E6=8D=AE=E6=A0=B9,=E6=97=A0=E5=86=B2=E7=AA=81),?=
 =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E8=87=AA=E5=B8=A6=20swap=20=E5=BD=92=20fstab?=
 =?UTF-8?q?=20=E7=AE=A1=E8=BE=96=E3=80=81=E4=B8=8D=E8=AE=A1=E4=B8=8D?=
 =?UTF-8?q?=E7=A2=B0=E3=80=82=E8=B5=84=E6=A0=BC=3DLinux+docker=20=E6=89=A7?=
 =?UTF-8?q?=E8=A1=8C=E5=99=A8(fake=20=E6=98=AF=E6=B5=8B=E8=AF=95=E6=9B=BF?=
 =?UTF-8?q?=E8=BA=AB,e2e=20=E8=B5=B7=E7=9A=84=E7=9C=9F=20daemon=20?=
 =?UTF-8?q?=E7=BB=9D=E4=B8=8D=E8=AE=B8=E6=91=B8=E5=AE=BF=E4=B8=BB=20swap):?=
 =?UTF-8?q?=E4=B8=8D=E5=A4=9F=E6=A0=BC=20getConfig.swap=3D{supported:false?=
 =?UTF-8?q?}=E3=80=81=E5=B8=A6=20swapGb=20=E7=9A=84=20patch=20=E8=AF=9A?=
 =?UTF-8?q?=E5=AE=9E=20400;=E5=A4=9F=E6=A0=BC=E6=97=B6=20activeGb=20?=
 =?UTF-8?q?=E7=8E=B0=E8=AF=BB=20/proc/swaps,=E7=9B=AE=E6=A0=87=E2=89=A0?=
 =?UTF-8?q?=E7=8E=B0=E5=AE=9E(=E7=BC=A9=E5=AE=B9=E5=BE=85=E9=87=8D?=
 =?UTF-8?q?=E5=90=AF/=E5=A2=9E=E5=AE=B9=20ENOSPC)=E4=B8=A4=E4=B8=AA?=
 =?UTF-8?q?=E6=95=B0=E9=83=BD=E4=B8=8A=20wire,console=20=E7=9A=84=20swapLi?=
 =?UTF-8?q?ne=20=E6=8A=8A=E6=97=B6=E9=97=B4=E5=B7=AE=E6=91=86=E6=98=8E?=
 =?UTF-8?q?=E9=9D=A2;=E5=A2=9E=E5=AE=B9=E5=A4=B1=E8=B4=A5=20500=20?=
 =?UTF-8?q?=E4=BD=86=E7=9B=AE=E6=A0=87=E5=B7=B2=E5=AD=98,=E5=BC=80?=
 =?UTF-8?q?=E6=9C=BA=E4=B8=8E=E4=B8=8B=E6=AC=A1=E7=BC=96=E8=BE=91=E8=87=AA?=
 =?UTF-8?q?=E5=8A=A8=E9=87=8D=E8=AF=95=E3=80=82swapGb=20=E6=97=A0=20env=20?=
 =?UTF-8?q?=E7=A7=8D=E5=AD=90=E6=81=92=E6=92=AD=200=E2=80=94=E2=80=94insta?=
 =?UTF-8?q?ll.sh=20=E7=9A=84=E5=9F=BA=E7=A1=80=20swapfile=20=E5=B7=B2?=
 =?UTF-8?q?=E7=AD=94=E8=BF=87=E3=80=8C=E5=AE=BF=E4=B8=BB=E8=A6=81=E6=9C=89?=
 =?UTF-8?q?=20swap=E3=80=8D,=E8=BF=BD=E5=8A=A0=E6=98=AF=20console=20?=
 =?UTF-8?q?=E4=B9=8B=E4=BA=8B=E3=80=82=E5=9B=9E=E5=BD=92=E9=92=89:planner?=
 =?UTF-8?q?=20=E5=85=AD=E5=9E=8B(=E5=90=AB=E5=8D=A1=E5=9C=A8=E7=9B=AE?=
 =?UTF-8?q?=E6=A0=87=E4=B8=8A=E7=9A=84=E6=B4=BB=E8=B7=83=E5=9D=97=E4=B8=8D?=
 =?UTF-8?q?=E5=8F=A0=E5=8A=A0)=E3=80=81=E7=AE=A1=E7=90=86=E5=99=A8?=
 =?UTF-8?q?=E5=85=A8=E7=94=9F=E5=91=BD=E5=91=A8=E6=9C=9F(=E5=BB=BA?=
 =?UTF-8?q?=E2=86=92=E6=89=A9=E2=86=92=E7=BC=A9=E7=AD=89=E9=87=8D=E5=90=AF?=
 =?UTF-8?q?=E2=86=92=E9=87=8D=E5=90=AF=E6=94=B6=E6=95=9B,swapon=20?=
 =?UTF-8?q?=E5=A4=8D=E7=94=A8=E4=B8=8D=E9=87=8D=E9=93=B8)=E3=80=81?=
 =?UTF-8?q?=E8=B7=AF=E7=94=B1=E4=B8=89=E9=92=89(=E4=B8=8D=E5=A4=9F?=
 =?UTF-8?q?=E6=A0=BC=20400/=E5=AD=98=E7=9B=AE=E6=A0=87=E5=8D=B3=E5=AF=B9?=
 =?UTF-8?q?=E8=B4=A6/=E5=A4=B1=E8=B4=A5=E7=95=99=E7=9B=AE=E6=A0=87?=
 =?UTF-8?q?=E7=AD=94=20500)=E3=80=81e2e=20=E9=BB=91=E7=9B=92=E9=92=89=20fa?=
 =?UTF-8?q?ke=20=E9=9D=A2=E8=AF=9A=E5=AE=9E=E6=8B=92=E7=BB=9D=E3=80=82?=
 =?UTF-8?q?=E7=9C=9F=E6=9C=BA=E9=AA=8C=E6=94=B6(swapon=20=E8=A6=81=20root+?=
 =?UTF-8?q?Linux)=E7=95=99=E7=BB=99=E6=B5=8B=E8=AF=95=E6=9C=BA=E9=83=A8?=
 =?UTF-8?q?=E7=BD=B2=E5=90=8E=E8=A1=A5=E8=80=83=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/src/native.test.ts                        |  15 +
 .../components/RuntimeSettingsCard.tsx        | 105 ++-
 packages/server/drizzle/0015_swap-target.sql  |   1 +
 .../server/drizzle/meta/0015_snapshot.json    | 640 ++++++++++++++++++
 packages/server/drizzle/meta/_journal.json    |   7 +
 packages/server/src/app.ts                    |  10 +
 packages/server/src/db/schema.ts              |   2 +
 packages/server/src/db/settings.ts            |   5 +
 packages/server/src/main.ts                   |  24 +
 packages/server/src/routes/config.ts          |  10 +-
 packages/server/src/routes/settings.test.ts   |  63 ++
 packages/server/src/routes/settings.ts        |  34 +-
 packages/server/src/swap.test.ts              | 193 ++++++
 packages/server/src/swap.ts                   | 243 +++++++
 packages/shared/src/config.ts                 |  12 +
 packages/shared/src/settings.ts               |  19 +-
 website/content/docs/console.mdx              |  16 +-
 website/content/docs/http-api.mdx             |   2 +-
 website/content/docs/installation.mdx         |   5 +-
 19 files changed, 1391 insertions(+), 15 deletions(-)
 create mode 100644 packages/server/drizzle/0015_swap-target.sql
 create mode 100644 packages/server/drizzle/meta/0015_snapshot.json
 create mode 100644 packages/server/src/swap.test.ts
 create mode 100644 packages/server/src/swap.ts

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index 8163651..1474805 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -638,6 +638,21 @@ describe('the observability verbs over a real daemon', () => {
     await client().updateSettings({ maxSandboxes: before.maxSandboxes });
   });
 
+  it('refuses the swap knob on a host that cannot manage swap', async () => {
+    // The exam daemon runs the fake executor, so managed swap is
+    // deterministically unavailable — getConfig says so up front, and
+    // setting a target is a 400, not a silently stored dead value.
+    expect((await client().getConfig()).swap).toEqual({
+      supported: false,
+      activeGb: 0,
+    });
+    await expect(client().updateSettings({ swapGb: 8 })).rejects.toMatchObject({
+      name: 'DormiceApiError',
+      status: 400,
+      message: expect.stringMatching(/Linux host with the docker executor/),
+    });
+  });
+
   it('getSandboxMetrics samples a live sandbox and 404s after destroy', async () => {
     await client().acquireSandbox('obs-metrics-key');
     const sample = await client().getSandboxMetrics('obs-metrics-key');
diff --git a/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx b/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
index 7789405..0000495 100644
--- a/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
+++ b/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
@@ -33,11 +33,13 @@ import { queryClient } from '@/lib/queryClient';
 
 /**
  * 运营旋钮的编辑区:值住在账本里(env 同名变量只是首次启动的种子),
- * updateSettings 一改立即生效 — 不重启 daemon、不碰任何沙箱。三组各配
+ * updateSettings 一改立即生效 — 不重启 daemon、不碰任何沙箱。四组各配
  * 一个弹窗,给哪组就整组替换(updatePolicy 的规矩:界面上看到什么就写
  * 下什么)。改的是"之后"不是"已经":容量上限管下一次创建,默认配额管
  * 下一次出生的磁盘/容器,默认策略管下一次 acquire 创建的沙箱 — 存量
- * 沙箱一根汗毛都不动,这句话在每个弹窗里都说清。
+ * 沙箱一根汗毛都不动,这句话在每个弹窗里都说清。唯一的例外是 swap:
+ * 它改的是宿主不是沙箱,增容立即、缩容等重启(swapLine 负责把这个
+ * 时间差摆在明面上)。
  */
 
 function useSubmit(onDone: () => void) {
@@ -68,7 +70,8 @@ function EditRow({
 }: {
   label: string;
   value: string;
-  dialog: React.ReactNode;
+  /** 缺席 = 本宿主改不了这项(value 里说清为什么),不给一个点了报错的按钮。 */
+  dialog?: React.ReactNode;
 }) {
   return (
     <div className="flex items-center justify-between gap-3 px-4 py-3">
@@ -262,6 +265,91 @@ function SandboxDefaultsDialog({ settings }: { settings: RuntimeSettings }) {
   );
 }
 
+function SwapDialog({ settings }: { settings: RuntimeSettings }) {
+  const [open, setOpen] = useState(false);
+  const [value, setValue] = useState('');
+  const { pending, error, setError, submit } = useSubmit(() => setOpen(false));
+
+  const valid =
+    value.trim() !== '' &&
+    Number.isInteger(Number(value)) &&
+    Number(value) >= 0;
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (next) {
+          setValue(String(settings.swapGb));
+          setError(null);
+        }
+      }}
+    >
+      <EditTrigger />
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>调整追加 swap 空间</DialogTitle>
+          <DialogDescription>
+            swap 容量 ≈ 能同时冬眠多少沙箱内存(冻结把内存挤进 swap)。
+            调大立即生效;调小要等下次重启宿主 — 正在用的 swap
+            绝不强拆,那会把冬眠沙箱的内存全拽回物理内存。
+          </DialogDescription>
+        </DialogHeader>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            void submit(
+              { swapGb: Number(value) },
+              `追加 swap 目标已改为 ${Number(value)} GiB`,
+            );
+          }}
+        >
+          <FieldGroup>
+            <Field>
+              <FieldLabel htmlFor="settings-swap-gb">
+                Dormice 管理的 swap 总量(GiB)
+              </FieldLabel>
+              <Input
+                id="settings-swap-gb"
+                type="number"
+                min={0}
+                value={value}
+                onChange={(event) => setValue(event.target.value)}
+              />
+              <FieldDescription>
+                在系统自带 swap 之外追加,0 = 不追加。swap
+                文件真实占据数据盘空间(不是稀疏的),调大前看一眼总览页的数据盘水位。
+              </FieldDescription>
+            </Field>
+            {error && <FieldError>{error}</FieldError>}
+          </FieldGroup>
+          <DialogFooter className="mt-6">
+            <Button type="submit" disabled={!valid || pending}>
+              {pending && <Spinner />}
+              保存
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+/**
+ * swap 行的真话:目标与现实一致时一句话完事;缩容等重启、增容没跑完时
+ * 把两个数都摆出来 — 只报目标会在这两种时刻撒谎。
+ */
+function swapLine(targetGb: number, activeGb: number): string {
+  if (activeGb > targetGb) {
+    return `目标 ${targetGb} GiB · 当前挂载 ${activeGb} GiB — 缩容在下次重启宿主时生效`;
+  }
+  if (activeGb < targetGb) {
+    return `目标 ${targetGb} GiB · 当前挂载 ${activeGb} GiB — 增容未完成,详见 daemon 日志`;
+  }
+  return `${targetGb} GiB(系统自带 swap 另计)`;
+}
+
 function DefaultPolicyDialog({
   settings,
   archiveEnabled,
@@ -455,6 +543,17 @@ export function RuntimeSettingsCard({ data }: { data: GetConfigResponse }) {
             />
           }
         />
+        <EditRow
+          label="追加 swap 空间"
+          value={
+            data.swap.supported
+              ? swapLine(settings.swapGb, data.swap.activeGb)
+              : '本宿主不支持(需要 Linux 宿主 + docker 执行器)'
+          }
+          dialog={
+            data.swap.supported ? <SwapDialog settings={settings} /> : undefined
+          }
+        />
       </div>
     </section>
   );
diff --git a/packages/server/drizzle/0015_swap-target.sql b/packages/server/drizzle/0015_swap-target.sql
new file mode 100644
index 0000000..f217edf
--- /dev/null
+++ b/packages/server/drizzle/0015_swap-target.sql
@@ -0,0 +1 @@
+ALTER TABLE `runtime_settings` ADD `swap_gb` integer DEFAULT 0 NOT NULL;
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/0015_snapshot.json b/packages/server/drizzle/meta/0015_snapshot.json
new file mode 100644
index 0000000..50e9386
--- /dev/null
+++ b/packages/server/drizzle/meta/0015_snapshot.json
@@ -0,0 +1,640 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "6c48c760-a9db-401e-98e4-73405a8c4cac",
+  "prevId": "0e4c8214-458c-4e2b-80bd-4db6a3739fa3",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_name": {
+          "name": "sandbox_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "actor": {
+          "name": "actor",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "api_keys": {
+      "name": "api_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "prefix": {
+          "name": "prefix",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "disabled_at": {
+          "name": "disabled_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "api_keys_key_hash_unique": {
+          "name": "api_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        },
+        "api_keys_active_name_idx": {
+          "name": "api_keys_active_name_idx",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true,
+          "where": "\"api_keys\".\"revoked_at\" IS NULL"
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "daemon_secrets": {
+      "name": "daemon_secrets",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "envd_signing_secret": {
+          "name": "envd_signing_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "fleet_snapshots": {
+      "name": "fleet_snapshots",
+      "columns": {
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active": {
+          "name": "active",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "frozen": {
+          "name": "frozen",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stopped": {
+          "name": "stopped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archived": {
+          "name": "archived",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "restoring": {
+          "name": "restoring",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "total": {
+          "name": "total",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "runtime_settings": {
+      "name": "runtime_settings",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "max_sandboxes": {
+          "name": "max_sandboxes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_cpus": {
+          "name": "sandbox_cpus",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_memory_gb": {
+          "name": "sandbox_memory_gb",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_disk_gb": {
+          "name": "sandbox_disk_gb",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "default_freeze_after_seconds": {
+          "name": "default_freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "default_stop_after_seconds": {
+          "name": "default_stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "default_archive_after_seconds": {
+          "name": "default_archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "swap_gb": {
+          "name": "swap_gb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandbox_metrics_samples": {
+      "name": "sandbox_metrics_samples",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_count": {
+          "name": "cpu_count",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_used_pct": {
+          "name": "cpu_used_pct",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_used_bytes": {
+          "name": "mem_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_total_bytes": {
+          "name": "mem_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_cache_bytes": {
+          "name": "mem_cache_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_used_bytes": {
+          "name": "disk_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_total_bytes": {
+          "name": "disk_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "sandbox_metrics_samples_sandbox_at_idx": {
+          "name": "sandbox_metrics_samples_sandbox_at_idx",
+          "columns": [
+            "sandbox_id",
+            "at"
+          ],
+          "isUnique": false
+        },
+        "sandbox_metrics_samples_at_idx": {
+          "name": "sandbox_metrics_samples_at_idx",
+          "columns": [
+            "at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_name_unique": {
+          "name": "sandboxes_name_unique",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index 7f8777e..609d6fd 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -106,6 +106,13 @@
       "when": 1784447916228,
       "tag": "0014_runtime-settings",
       "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "6",
+      "when": 1784461661884,
+      "tag": "0015_swap-target",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index a101700..1acc792 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -36,6 +36,7 @@ import { settingsRoutes } from './routes/settings';
 import { templateRoutes } from './routes/templates';
 import { upgradeRoutes } from './routes/upgrade';
 import { createSandboxProxy } from './sandbox-proxy';
+import type { SwapControl } from './swap';
 import { Updater } from './updater';
 import { readBuildInfo } from './version';
 
@@ -75,6 +76,12 @@ export interface AppDeps {
    * getIngress answers { managed: false } and setIngress refuses.
    */
   ingress?: Ingress;
+  /**
+   * The managed-swap surface, present exactly when the daemon can manage
+   * swap — main.ts builds one on Linux with the docker executor. Absent,
+   * getConfig reports { supported: false } and a swapGb patch is refused.
+   */
+  swap?: SwapControl;
   /**
    * Which knobs came from the environment versus defaults, for getConfig.
    * Defaults to reading process.env — right for the daemon; tests that
@@ -109,6 +116,7 @@ export function buildApp({
   consoleDistDir,
   archiver,
   ingress,
+  swap,
   sources = configSources(),
   updater = new Updater({
     repoDir: null,
@@ -257,6 +265,7 @@ export function buildApp({
       db,
       sources,
       archiveDefaultSeconds,
+      swap,
     });
     await api.register(upgradeRoutes, { updater, db });
   });
@@ -272,6 +281,7 @@ export function buildApp({
     await admin.register(settingsRoutes, {
       db,
       archiveEnabled: archiveDefaultSeconds !== null,
+      swap,
     });
   });
 
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index f58dcf7..a2aaff1 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -245,6 +245,8 @@ export const runtimeSettings = sqliteTable('runtime_settings', {
   defaultStopAfterSeconds: integer('default_stop_after_seconds'),
   /** NULL = never archive — forced when the daemon has no archiver. */
   defaultArchiveAfterSeconds: integer('default_archive_after_seconds'),
+  /** Daemon-managed swap target, GiB (see swap.ts); 0 = manage none. */
+  swapGb: integer('swap_gb').notNull().default(0),
   /** Null until the first updateSettings: "still exactly the seed" is information. */
   updatedAt: text('updated_at'),
 });
diff --git a/packages/server/src/db/settings.ts b/packages/server/src/db/settings.ts
index 2f71bb8..0c4ec61 100644
--- a/packages/server/src/db/settings.ts
+++ b/packages/server/src/db/settings.ts
@@ -38,6 +38,9 @@ export function ensureRuntimeSettings(
       defaultFreezeAfterSeconds: DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds,
       defaultStopAfterSeconds: DEFAULT_LIFECYCLE_POLICY.stopAfterSeconds,
       defaultArchiveAfterSeconds: archiveDefaultSeconds,
+      // No env seed: managed swap is born from the console, not the env —
+      // install.sh's base swapfile already covers "a host needs swap".
+      swapGb: 0,
       updatedAt: null,
     })
     .onConflictDoNothing()
@@ -57,6 +60,7 @@ function toView(row: RuntimeSettingsRow): RuntimeSettings {
       stopAfterSeconds: row.defaultStopAfterSeconds,
       archiveAfterSeconds: row.defaultArchiveAfterSeconds,
     },
+    swapGb: row.swapGb,
     updatedAt: row.updatedAt,
   };
 }
@@ -113,6 +117,7 @@ export function writeRuntimeSettings(
             defaultArchiveAfterSeconds: patch.defaultPolicy.archiveAfterSeconds,
           }
         : {}),
+      ...(patch.swapGb !== undefined ? { swapGb: patch.swapGb } : {}),
       updatedAt: now.toISOString(),
     })
     .where(eq(runtimeSettings.id, SETTINGS_ROW_ID))
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 345d2aa..ee0cce2 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -21,6 +21,7 @@ import { ARCHIVE_DEFAULT_SECONDS } from './policy';
 import { reconcile } from './reconciler';
 import { scanOnce } from './scanner';
 import { locallyClaimedCount, startupGuard } from './startup-guard';
+import { SwapManager } from './swap';
 import { Updater } from './updater';
 import { readBuildInfo } from './version';
 
@@ -130,6 +131,28 @@ if (config.DORMICE_INGRESS_FILE) {
   log.info('ingress not managed: DORMICE_INGRESS_FILE not configured');
 }
 
+// Managed swap exists exactly where the daemon can honor it: a Linux host
+// (swapon is the kernel's) running the docker executor (the fake executor
+// is a test double — e2e boots real daemons with it, and those must never
+// touch the host's swap). The boot reconcile is what makes shrink-by-
+// reboot converge and puts grown blocks back after a restart; its failure
+// is loud but not fatal — swap is capacity, not correctness, and
+// getConfig's swap.activeGb reports the shortfall honestly.
+let swap: SwapManager | undefined;
+if (config.DORMICE_EXECUTOR === 'docker' && process.platform === 'linux') {
+  swap = new SwapManager({
+    dir: path.join(config.DORMICE_DATA_DIR, 'swap'),
+    log: (msg) => log.info(msg),
+  });
+  try {
+    await swap.reconcile(readRuntimeSettings(db).swapGb);
+  } catch (error) {
+    log.error(error, 'boot swap reconcile failed');
+  }
+} else {
+  log.info('managed swap unavailable: requires Linux + the docker executor');
+}
+
 // The web console ships beside the server in the monorepo; this file sits
 // one level under packages/server both as src/main.ts and as dist/main.js,
 // so the relative hop to packages/console/dist is the same either way. A
@@ -169,6 +192,7 @@ const app = buildApp({
   consoleDistDir: existsSync(consoleDistDir) ? consoleDistDir : undefined,
   archiver,
   ingress,
+  swap,
   updater,
 });
 
diff --git a/packages/server/src/routes/config.ts b/packages/server/src/routes/config.ts
index 7c7e3a2..19ad18a 100644
--- a/packages/server/src/routes/config.ts
+++ b/packages/server/src/routes/config.ts
@@ -3,6 +3,7 @@ import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import { CONFIG_KEYS, type Config, type ConfigSources } from '../config';
 import type { Db } from '../db/db';
 import { readRuntimeSettings } from '../db/settings';
+import type { SwapControl } from '../swap';
 
 export interface ConfigRoutesOptions {
   config: Config;
@@ -10,6 +11,8 @@ export interface ConfigRoutesOptions {
   sources: ConfigSources;
   /** buildApp's one adjudication of the archive default (null = no archiver). */
   archiveDefaultSeconds: number | null;
+  /** The managed-swap surface; absent = this host cannot manage swap. */
+  swap?: SwapControl;
 }
 
 /**
@@ -24,7 +27,7 @@ export interface ConfigRoutesOptions {
  */
 export const configRoutes: FastifyPluginAsyncZod<ConfigRoutesOptions> = async (
   app,
-  { config, db, sources, archiveDefaultSeconds },
+  { config, db, sources, archiveDefaultSeconds, swap },
 ) => {
   app.post(
     '/getConfig',
@@ -57,6 +60,11 @@ export const configRoutes: FastifyPluginAsyncZod<ConfigRoutesOptions> = async (
               ? null
               : settings.defaultPolicy.archiveAfterSeconds,
         },
+        // Read live so a pending shrink (target < mounted, waiting for a
+        // host reboot) or a failed grow is visible, not papered over.
+        swap: swap
+          ? { supported: true, activeGb: (await swap.status()).activeGb }
+          : { supported: false, activeGb: 0 },
         settings,
       };
     },
diff --git a/packages/server/src/routes/settings.test.ts b/packages/server/src/routes/settings.test.ts
index bfb33fa..66fc43f 100644
--- a/packages/server/src/routes/settings.test.ts
+++ b/packages/server/src/routes/settings.test.ts
@@ -12,6 +12,7 @@ import { loadConfig } from '../config';
 import { migrateDb, openDb } from '../db/db';
 import { FakeExecutor } from '../executor/fake';
 import { KeyedQueue } from '../keyed-queue';
+import type { SwapControl, SwapStatus } from '../swap';
 
 const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
 const TOKEN = 'test-token-test-token-test-token';
@@ -27,6 +28,7 @@ function appOn(
   db: ReturnType<typeof freshDb>,
   env: Record<string, string> = {},
   archiver?: Archiver,
+  swap?: SwapControl,
 ) {
   const config = loadConfig({
     DORMICE_DB_PATH: ':memory:',
@@ -41,9 +43,25 @@ function appOn(
     locks: new KeyedQueue(),
     logger: false,
     archiver,
+    swap,
   });
 }
 
+/** A ledger of reconcile calls standing in for the real block juggler. */
+function fakeSwap(activeGb = 0): SwapControl & { reconciled: number[] } {
+  const status = (): Promise<SwapStatus> =>
+    Promise.resolve({ activeGb, blocks: [] });
+  const control = {
+    reconciled: [] as number[],
+    status,
+    reconcile(targetGb: number) {
+      control.reconciled.push(targetGb);
+      return status();
+    },
+  };
+  return control;
+}
+
 type App = ReturnType<typeof appOn>;
 
 function rpc(
@@ -72,6 +90,8 @@ describe('runtime settings: seeding', () => {
       sandboxDefaults: { cpus: 1, memoryGb: 2, diskGb: 20 },
       // No archiver in this app, so the seeded default never archives.
       defaultPolicy: { ...DEFAULT_LIFECYCLE_POLICY, archiveAfterSeconds: null },
+      // Managed swap has no env seed — it is born from the console.
+      swapGb: 0,
       updatedAt: null,
     });
   });
@@ -211,6 +231,49 @@ describe('updateSettings', () => {
     ).toBe(7200);
   });
 
+  it('refuses a swap target where the daemon cannot manage swap', async () => {
+    // No SwapControl injected — the Mac-dev / fake-executor daemon shape.
+    const app = appOn(freshDb());
+    const res = await rpc(app, '/updateSettings', { swapGb: 32 });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().message).toMatch(/Linux host with the docker executor/);
+    // And getConfig says so up front, so the console never offers the knob.
+    const body = getConfigResponseSchema.parse(
+      (await rpc(app, '/getConfig')).json(),
+    );
+    expect(body.swap).toEqual({ supported: false, activeGb: 0 });
+  });
+
+  it('saves a swap target and reconciles it immediately', async () => {
+    const swap = fakeSwap(32);
+    const app = appOn(freshDb(), {}, undefined, swap);
+    const res = await rpc(app, '/updateSettings', { swapGb: 32 });
+    expect(res.statusCode).toBe(200);
+    expect(updateSettingsResponseSchema.parse(res.json()).settings.swapGb).toBe(
+      32,
+    );
+    expect(swap.reconciled).toEqual([32]);
+    // A patch without swapGb must not re-trigger the block juggler.
+    await rpc(app, '/updateSettings', { maxSandboxes: 9 });
+    expect(swap.reconciled).toEqual([32]);
+    const body = getConfigResponseSchema.parse(
+      (await rpc(app, '/getConfig')).json(),
+    );
+    expect(body.swap).toEqual({ supported: true, activeGb: 32 });
+  });
+
+  it('keeps the saved target and answers 500 when applying it fails', async () => {
+    // ENOSPC mid-grow: the target must survive (boot and the next edit
+    // retry it) and the error must name what happened.
+    const swap = fakeSwap();
+    swap.reconcile = () => Promise.reject(new Error('fallocate: ENOSPC'));
+    const app = appOn(freshDb(), {}, undefined, swap);
+    const res = await rpc(app, '/updateSettings', { swapGb: 512 });
+    expect(res.statusCode).toBe(500);
+    expect(res.json().message).toMatch(/target saved.*ENOSPC/);
+    expect((await settingsOf(app)).swapGb).toBe(512);
+  });
+
   it('records the change in the activity ring with its actor', async () => {
     const app = appOn(freshDb());
     await rpc(app, '/updateSettings', { maxSandboxes: 3 });
diff --git a/packages/server/src/routes/settings.ts b/packages/server/src/routes/settings.ts
index 9f22134..7994d67 100644
--- a/packages/server/src/routes/settings.ts
+++ b/packages/server/src/routes/settings.ts
@@ -7,11 +7,19 @@ import { z } from 'zod';
 import { recordActivity } from '../db/activity';
 import type { Db } from '../db/db';
 import { writeRuntimeSettings } from '../db/settings';
+import type { SwapControl } from '../swap';
 
 export interface SettingsRoutesOptions {
   db: Db;
   /** buildApp's one adjudication of "is the archiver configured". */
   archiveEnabled: boolean;
+  /**
+   * The managed-swap surface, present exactly when the daemon can manage
+   * swap (Linux host, docker executor — main.ts's adjudication). Absent,
+   * a swapGb patch is refused: an unconfigurable knob must refuse, not
+   * silently store a target nothing will ever reconcile.
+   */
+  swap?: SwapControl;
 }
 
 /**
@@ -29,7 +37,7 @@ export interface SettingsRoutesOptions {
  */
 export const settingsRoutes: FastifyPluginAsyncZod<
   SettingsRoutesOptions
-> = async (app, { db, archiveEnabled }) => {
+> = async (app, { db, archiveEnabled, swap }) => {
   app.post(
     '/updateSettings',
     {
@@ -38,6 +46,7 @@ export const settingsRoutes: FastifyPluginAsyncZod<
         response: {
           200: updateSettingsResponseSchema,
           400: z.object({ message: z.string() }),
+          500: z.object({ message: z.string() }),
         },
       },
     },
@@ -55,6 +64,12 @@ export const settingsRoutes: FastifyPluginAsyncZod<
             'invalid default policy: archiving requires S3 (DORMICE_S3_*) to be configured',
         });
       }
+      if (patch.swapGb !== undefined && swap === undefined) {
+        return reply.code(400).send({
+          message:
+            'managing swap requires a Linux host with the docker executor',
+        });
+      }
       const settings = writeRuntimeSettings(db, patch, new Date());
       recordActivity(db, {
         kind: 'settings-updated',
@@ -73,8 +88,25 @@ export const settingsRoutes: FastifyPluginAsyncZod<
                 `defaultPolicy=${patch.defaultPolicy.freezeAfterSeconds}s/${patch.defaultPolicy.stopAfterSeconds ?? 'never'}/${patch.defaultPolicy.archiveAfterSeconds ?? 'never'}`,
               ]
             : []),
+          ...(patch.swapGb !== undefined ? [`swapGb=${patch.swapGb}`] : []),
         ].join(', '),
       });
+      // Reconcile after the write: growing mounts new blocks now, shrinking
+      // defers itself (the planner never touches an active block). A failed
+      // grow — ENOSPC, most likely — leaves the target saved on purpose:
+      // the boot reconcile and the next edit retry it, and getConfig's
+      // swap.activeGb reports the divergence honestly meanwhile.
+      if (patch.swapGb !== undefined && swap !== undefined) {
+        try {
+          await swap.reconcile(patch.swapGb);
+        } catch (error) {
+          return reply.code(500).send({
+            message: `swap target saved (${patch.swapGb} GiB) but applying it failed: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          });
+        }
+      }
       return { settings };
     },
   );
diff --git a/packages/server/src/swap.test.ts b/packages/server/src/swap.test.ts
new file mode 100644
index 0000000..61b552a
--- /dev/null
+++ b/packages/server/src/swap.test.ts
@@ -0,0 +1,193 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { planSwap, type SwapBlock, SwapManager } from './swap';
+
+const block = (name: string, sizeGb: number, active: boolean): SwapBlock => ({
+  name,
+  sizeGb,
+  active,
+});
+
+describe('planSwap', () => {
+  it('does nothing at target 0 with nothing on disk', () => {
+    expect(planSwap(0, [])).toEqual({
+      activate: [],
+      remove: [],
+      createGb: null,
+      deferredGb: 0,
+    });
+  });
+
+  it('creates one block sized to the whole gap', () => {
+    expect(planSwap(100, []).createGb).toBe(100);
+  });
+
+  it('after a host reboot, keeps the target worth of files and deletes the rest', () => {
+    // Nothing is active after a reboot; the shrink written before it now
+    // converges: 48 wanted, [32, 32] on disk.
+    const plan = planSwap(48, [
+      block('block-0', 32, false),
+      block('block-1', 32, false),
+    ]);
+    expect(plan.activate).toEqual(['block-0']);
+    expect(plan.remove).toEqual(['block-1']);
+    expect(plan.createGb).toBe(16);
+    expect(plan.deferredGb).toBe(0);
+  });
+
+  it('never touches active blocks: a shrink defers instead', () => {
+    const plan = planSwap(32, [
+      block('block-0', 32, true),
+      block('block-1', 64, true),
+    ]);
+    expect(plan.activate).toEqual([]);
+    expect(plan.remove).toEqual([]);
+    expect(plan.createGb).toBeNull();
+    expect(plan.deferredGb).toBe(64);
+  });
+
+  it('grows past what is already mounted with one new block', () => {
+    const plan = planSwap(96, [block('block-0', 32, true)]);
+    expect(plan.createGb).toBe(64);
+    expect(plan.deferredGb).toBe(0);
+  });
+
+  it('counts stuck over-target actives toward the total instead of piling on', () => {
+    // Daemon restart (not reboot): 64 GiB is still mounted, target 48.
+    // Creating 16 more would make reality WORSE (80 mounted).
+    const plan = planSwap(48, [
+      block('block-0', 32, true),
+      block('block-1', 32, true),
+    ]);
+    expect(plan.createGb).toBeNull();
+    expect(plan.deferredGb).toBe(16);
+  });
+
+  it('deletes an inactive zero-size block instead of activating it', () => {
+    const plan = planSwap(4, [block('block-0', 0, false)]);
+    expect(plan.remove).toEqual(['block-0']);
+    expect(plan.createGb).toBe(4);
+  });
+});
+
+describe('SwapManager', () => {
+  let dir: string;
+  let swapDir: string;
+  let procSwaps: string;
+  let commands: string[][];
+
+  beforeEach(async () => {
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dormice-swap-'));
+    swapDir = path.join(dir, 'swap');
+    procSwaps = path.join(dir, 'proc-swaps');
+    await fs.writeFile(
+      procSwaps,
+      'Filename\t\t\t\tType\t\tSize\t\tUsed\t\tPriority\n',
+    );
+    commands = [];
+  });
+
+  afterEach(async () => {
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  // A stand-in for the three util-linux calls: fallocate materializes the
+  // file at the asked size (sparse — fine for tests), swapon registers the
+  // block in the fake /proc/swaps, mkswap is a no-op. swapoff is absent on
+  // purpose: the manager must never even try it.
+  function manager() {
+    return new SwapManager({
+      dir: swapDir,
+      log: () => {},
+      procSwapsPath: procSwaps,
+      run: async (command, args) => {
+        commands.push([command, ...args]);
+        const target = args.at(-1) ?? '';
+        if (command === 'fallocate') {
+          const bytes = Number(/^(\d+)GiB$/.exec(args[1] ?? '')?.[1]) * 2 ** 30;
+          const handle = await fs.open(target, 'w');
+          await handle.truncate(bytes);
+          await handle.close();
+        }
+        if (command === 'swapon') {
+          const real = await fs.realpath(target);
+          await fs.appendFile(procSwaps, `${real} file 1 0 -2\n`);
+        }
+        if (command === 'swapoff') {
+          throw new Error('swapoff must never be invoked');
+        }
+      },
+    });
+  }
+
+  /** Simulates a host reboot: swap never survives one. */
+  async function reboot() {
+    await fs.writeFile(
+      procSwaps,
+      'Filename\t\t\t\tType\t\tSize\t\tUsed\t\tPriority\n',
+    );
+  }
+
+  it('creates, grows, shrinks-by-reboot — the full life', async () => {
+    const swap = manager();
+
+    // Birth: one block of exactly the target.
+    expect((await swap.reconcile(3)).activeGb).toBe(3);
+    expect(commands.map((c) => c[0])).toEqual([
+      'fallocate',
+      'mkswap',
+      'swapon',
+    ]);
+    // Built under .tmp and renamed: what exists is always a valid device.
+    expect(await fs.readdir(swapDir)).toEqual(['block-0']);
+
+    // Grow: one more block for the gap, the mounted one untouched.
+    expect((await swap.reconcile(5)).activeGb).toBe(5);
+    expect((await fs.readdir(swapDir)).sort()).toEqual(['block-0', 'block-1']);
+
+    // Shrink while mounted: nothing moves, honestly reported.
+    commands = [];
+    const shrunk = await swap.reconcile(3);
+    expect(shrunk.activeGb).toBe(5);
+    expect(commands).toEqual([]);
+
+    // Reboot: the same reconcile now converges — 3 GiB mounted, rest gone.
+    await reboot();
+    const converged = await swap.reconcile(3);
+    expect(converged.activeGb).toBe(3);
+    expect(await fs.readdir(swapDir)).toEqual(['block-0']);
+  });
+
+  it('remounts existing blocks at boot without recreating them', async () => {
+    const swap = manager();
+    await swap.reconcile(4);
+    await reboot();
+    commands = [];
+    expect((await swap.reconcile(4)).activeGb).toBe(4);
+    // Only swapon — no fallocate, no mkswap: the file was already a device.
+    expect(commands.map((c) => c[0])).toEqual(['swapon']);
+  });
+
+  it('sweeps its own .tmp leftovers and leaves foreign files alone', async () => {
+    await fs.mkdir(swapDir, { recursive: true });
+    await fs.writeFile(path.join(swapDir, 'block-7.tmp'), 'crashed mid-create');
+    await fs.writeFile(path.join(swapDir, 'notes.txt'), 'not ours to judge');
+    const swap = manager();
+    await swap.reconcile(0);
+    expect((await fs.readdir(swapDir)).sort()).toEqual(['notes.txt']);
+  });
+
+  it('reports status without mutating anything', async () => {
+    const swap = manager();
+    await swap.reconcile(2);
+    commands = [];
+    const status = await swap.status();
+    expect(status.activeGb).toBe(2);
+    expect(status.blocks).toEqual([
+      { name: 'block-0', sizeGb: 2, active: true },
+    ]);
+    expect(commands).toEqual([]);
+  });
+});
diff --git a/packages/server/src/swap.ts b/packages/server/src/swap.ts
new file mode 100644
index 0000000..fc1edc2
--- /dev/null
+++ b/packages/server/src/swap.ts
@@ -0,0 +1,243 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { execa } from 'execa';
+
+/**
+ * Daemon-managed swap: block files under `$DATA_DIR/swap/`, grown and
+ * mounted so frozen sandboxes have somewhere to squeeze their memory
+ * (swap capacity ≈ how much sandbox memory can hibernate at once). The
+ * ledger's `swapGb` is the target; this class makes reality match — the
+ * same reconcile runs at boot and after every updateSettings, so there is
+ * exactly one arbiter of "what should be mounted".
+ *
+ * The one hard rule: an ACTIVE swapfile is never touched. swapoff would
+ * drag every frozen sandbox's memory back into RAM — with a fleet
+ * hibernating that can OOM the host — so shrinking only writes the
+ * target and waits: after a host reboot nothing is active (swap content
+ * never survives a reboot; neither do the frozen sandboxes' containers —
+ * the disk is the sandbox's body), the boot reconcile simply activates
+ * less and deletes the inactive leftovers. Growing is immediate and
+ * cheap: fallocate + mkswap + swapon, seconds.
+ *
+ * Blocks are append-only history, not a fixed unit: each grow adds one
+ * block sized to the missing gap, so a target of 100 GiB is one 100 GiB
+ * file, not four of 25. The host's own swap (install.sh's fstab-managed
+ * swapfile) is a different jurisdiction — never counted, never touched.
+ */
+
+/** One managed block file: `block-<n>` under the swap dir. */
+export interface SwapBlock {
+  name: string;
+  sizeGb: number;
+  /** Currently swapon'd (per /proc/swaps). */
+  active: boolean;
+}
+
+export interface SwapStatus {
+  /** GiB of managed swap actually mounted right now. */
+  activeGb: number;
+  blocks: SwapBlock[];
+}
+
+export interface SwapPlan {
+  /** Existing inactive blocks to swapon, in index order. */
+  activate: string[];
+  /** Inactive blocks beyond the target: delete the files. */
+  remove: string[];
+  /** Size of the one new block to create and mount; null = no gap. */
+  createGb: number | null;
+  /** GiB active beyond the target — untouchable until a host reboot. */
+  deferredGb: number;
+}
+
+/**
+ * The pure adjudication: given the target and what exists, decide every
+ * action. Active blocks are immovable (they all stay, wanted or not);
+ * the remaining gap is filled from inactive blocks in index order, each
+ * either activated (fits) or deleted (does not), and any gap still left
+ * becomes one new block. Deleting only what is inactive AND unwanted is
+ * what makes shrink-by-reboot converge: after a reboot nothing is
+ * active, so the same rule keeps exactly the target's worth of files.
+ */
+export function planSwap(targetGb: number, blocks: SwapBlock[]): SwapPlan {
+  const activeGb = blocks
+    .filter((b) => b.active)
+    .reduce((sum, b) => sum + b.sizeGb, 0);
+  let remaining = Math.max(0, targetGb - activeGb);
+  const activate: string[] = [];
+  const remove: string[] = [];
+  for (const block of blocks) {
+    if (block.active) continue;
+    if (block.sizeGb <= remaining && block.sizeGb > 0) {
+      activate.push(block.name);
+      remaining -= block.sizeGb;
+    } else {
+      remove.push(block.name);
+    }
+  }
+  return {
+    activate,
+    remove,
+    createGb: remaining > 0 ? remaining : null,
+    deferredGb: Math.max(0, activeGb - targetGb),
+  };
+}
+
+export interface SwapManagerOptions {
+  /** The managed directory, `$DATA_DIR/swap` — created on first use. */
+  dir: string;
+  log: (msg: string) => void;
+  /** Test seam; production shells out through execa. */
+  run?: (command: string, args: string[]) => Promise<void>;
+  /** Test seam; production reads /proc/swaps. */
+  procSwapsPath?: string;
+}
+
+/** What the routes depend on; SwapManager is the one real implementation. */
+export interface SwapControl {
+  status(): Promise<SwapStatus>;
+  reconcile(targetGb: number): Promise<SwapStatus>;
+}
+
+const BLOCK_RE = /^block-(\d+)$/;
+
+export class SwapManager implements SwapControl {
+  private readonly dir: string;
+  private readonly log: (msg: string) => void;
+  private readonly run: NonNullable<SwapManagerOptions['run']>;
+  private readonly procSwapsPath: string;
+  /** Serializes reconciles: boot and a concurrent updateSettings must not interleave. */
+  private queue: Promise<unknown> = Promise.resolve();
+
+  constructor(options: SwapManagerOptions) {
+    this.dir = options.dir;
+    this.log = options.log;
+    this.run =
+      options.run ??
+      (async (command, args) => {
+        await execa(command, args);
+      });
+    this.procSwapsPath = options.procSwapsPath ?? '/proc/swaps';
+  }
+
+  async status(): Promise<SwapStatus> {
+    const blocks = await this.listBlocks();
+    return {
+      activeGb: blocks
+        .filter((b) => b.active)
+        .reduce((sum, b) => sum + b.sizeGb, 0),
+      blocks,
+    };
+  }
+
+  async reconcile(targetGb: number): Promise<SwapStatus> {
+    const result = this.queue.then(() => this.reconcileNow(targetGb));
+    // The queue must survive a failed reconcile; the caller still sees it.
+    this.queue = result.catch(() => undefined);
+    return result;
+  }
+
+  private async reconcileNow(targetGb: number): Promise<SwapStatus> {
+    await fs.mkdir(this.dir, { recursive: true, mode: 0o700 });
+    // A crash between fallocate and the final rename leaves a .tmp — ours,
+    // incomplete, safe to sweep.
+    for (const entry of await fs.readdir(this.dir)) {
+      if (entry.endsWith('.tmp')) await fs.rm(path.join(this.dir, entry));
+    }
+    const blocks = await this.listBlocks();
+    const plan = planSwap(targetGb, blocks);
+    for (const name of plan.remove) {
+      await fs.rm(path.join(this.dir, name));
+    }
+    for (const name of plan.activate) {
+      await this.run('swapon', [path.join(this.dir, name)]);
+    }
+    if (plan.createGb !== null) {
+      const kept = blocks
+        .map((b) => BLOCK_RE.exec(b.name))
+        .filter((m): m is RegExpExecArray => m !== null)
+        .filter((m) => !plan.remove.includes(m[0]));
+      const index = kept.length
+        ? Math.max(...kept.map((m) => Number(m[1]))) + 1
+        : 0;
+      const finalPath = path.join(this.dir, `block-${index}`);
+      // Built under a .tmp name and renamed only once mkswap succeeded, so
+      // an existing block file is always a valid swap device.
+      const tmpPath = `${finalPath}.tmp`;
+      await this.run('fallocate', ['-l', `${plan.createGb}GiB`, tmpPath]);
+      // Swap holds every process's memory contents; root-only, always.
+      await fs.chmod(tmpPath, 0o600);
+      await this.run('mkswap', [tmpPath]);
+      await fs.rename(tmpPath, finalPath);
+      await this.run('swapon', [finalPath]);
+    }
+    const after = await this.status();
+    this.log(
+      `swap reconcile: target ${targetGb} GiB, active ${after.activeGb} GiB` +
+        (plan.deferredGb > 0
+          ? ` (${plan.deferredGb} GiB over target stays mounted until the next host reboot)`
+          : ''),
+    );
+    return after;
+  }
+
+  private async listBlocks(): Promise<SwapBlock[]> {
+    let entries: string[];
+    try {
+      entries = await fs.readdir(this.dir);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw error;
+    }
+    const active = await this.activePaths();
+    const blocks: SwapBlock[] = [];
+    for (const name of entries) {
+      const match = BLOCK_RE.exec(name);
+      // Anything else in the dir (stray files, .tmp mid-sweep) is not ours
+      // to judge here — never deleted by the planner.
+      if (!match) continue;
+      const filePath = path.join(this.dir, name);
+      const stat = await fs.stat(filePath);
+      blocks.push({
+        name,
+        sizeGb: Math.round(stat.size / 2 ** 30),
+        active: active.has(await realpathSafe(filePath)),
+      });
+    }
+    blocks.sort(
+      (a, b) =>
+        Number(BLOCK_RE.exec(a.name)?.[1]) - Number(BLOCK_RE.exec(b.name)?.[1]),
+    );
+    return blocks;
+  }
+
+  /** Resolved paths of every active swap device, from /proc/swaps. */
+  private async activePaths(): Promise<Set<string>> {
+    let content: string;
+    try {
+      content = await fs.readFile(this.procSwapsPath, 'utf8');
+    } catch {
+      // No /proc/swaps (or unreadable): nothing is knowably active. Only
+      // reachable in tests or on non-Linux, where the manager is not built.
+      return new Set();
+    }
+    const paths = new Set<string>();
+    for (const line of content.split('\n').slice(1)) {
+      const raw = line.split(/\s+/)[0];
+      if (!raw?.startsWith('/')) continue;
+      // The kernel escapes spaces in filenames as \040.
+      const decoded = raw.replaceAll('\\040', ' ');
+      paths.add(await realpathSafe(decoded));
+    }
+    return paths;
+  }
+}
+
+/** realpath with a fallback for paths that no longer resolve. */
+async function realpathSafe(p: string): Promise<string> {
+  try {
+    return await fs.realpath(p);
+  } catch {
+    return p;
+  }
+}
diff --git a/packages/shared/src/config.ts b/packages/shared/src/config.ts
index 753ff86..cc39001 100644
--- a/packages/shared/src/config.ts
+++ b/packages/shared/src/config.ts
@@ -42,6 +42,18 @@ export const getConfigResponseSchema = z.object({
      */
     defaultSeconds: z.number().int().nullable(),
   }),
+  /**
+   * The daemon-managed swap surface (see settings.ts `swapGb` — the
+   * target). `supported` is false where the daemon cannot manage swap
+   * (non-Linux, or the fake executor); `activeGb` is how much managed
+   * swap is actually mounted right now — it lags the target after a
+   * shrink (which waits for a host reboot) and after a failed grow, and
+   * clients surface that divergence instead of pretending.
+   */
+  swap: z.object({
+    supported: z.boolean(),
+    activeGb: z.number().nonnegative(),
+  }),
   /** The ledger-resident operator knobs actually in force — see settings.ts. */
   settings: runtimeSettingsSchema,
 });
diff --git a/packages/shared/src/settings.ts b/packages/shared/src/settings.ts
index 1c41f3a..7fef713 100644
--- a/packages/shared/src/settings.ts
+++ b/packages/shared/src/settings.ts
@@ -37,6 +37,19 @@ export const runtimeSettingsSchema = z.object({
   sandboxDefaults: sandboxResourceDefaultsSchema,
   /** What acquire() gives a sandbox that asks for nothing. Existing sandboxes keep theirs. */
   defaultPolicy: lifecyclePolicySchema,
+  /**
+   * Total daemon-managed swap, GiB, held as swapfiles on the data dir —
+   * ON TOP of whatever swap the host already has (the install-time
+   * swapfile stays fstab's business; the two never fight). Swap capacity
+   * is roughly "how much sandbox memory can hibernate at once" — freezing
+   * squeezes a sandbox's memory into swap. Growing takes effect
+   * immediately; shrinking is deferred to the next host reboot, because
+   * swapoff would drag every frozen sandbox's memory back into RAM
+   * (getConfig's `swap.activeGb` reports what is actually mounted).
+   * 0 = manage none. Ignored on hosts that cannot swap (see getConfig's
+   * `swap.supported`), where updateSettings refuses to set it.
+   */
+  swapGb: z.number().int().nonnegative(),
   /** ISO 8601 of the last updateSettings; null = still exactly the first-boot seed. */
   updatedAt: z.string().nullable(),
 });
@@ -54,15 +67,17 @@ export const updateSettingsRequestSchema = z
     maxSandboxes: z.number().int().positive().optional(),
     sandboxDefaults: sandboxResourceDefaultsSchema.optional(),
     defaultPolicy: lifecyclePolicySchema.optional(),
+    swapGb: z.number().int().nonnegative().optional(),
   })
   .refine(
     (patch) =>
       patch.maxSandboxes !== undefined ||
       patch.sandboxDefaults !== undefined ||
-      patch.defaultPolicy !== undefined,
+      patch.defaultPolicy !== undefined ||
+      patch.swapGb !== undefined,
     {
       message:
-        'updateSettings needs at least one of maxSandboxes, sandboxDefaults, defaultPolicy',
+        'updateSettings needs at least one of maxSandboxes, sandboxDefaults, defaultPolicy, swapGb',
     },
   );
 
diff --git a/website/content/docs/console.mdx b/website/content/docs/console.mdx
index e6c121c..59b8f1e 100644
--- a/website/content/docs/console.mdx
+++ b/website/content/docs/console.mdx
@@ -119,12 +119,16 @@ Four more pages round out the operator view:
   green. See
   [Installation](/docs/installation#connect-from-another-machine).
 - **Settings** — two halves. The operational knobs (sandbox capacity
-  cap, default resources for new sandboxes, default lifecycle policy)
-  live in the daemon's database and are edited right here, taking effect
-  immediately — no restart, no sandbox touched. Everything else is the
-  effective environment configuration, read-only, with secrets shown as
-  present-or-absent only; changing those happens in `/etc/dormice/env`
-  plus a restart, never from the browser.
+  cap, default resources for new sandboxes, default lifecycle policy,
+  extra managed [swap](/docs/core-concepts#swap-and-freezing)) live in
+  the daemon's database and are edited right here, taking effect
+  immediately — no restart, no sandbox touched. The swap knob is the one
+  with an asymmetry: growing mounts new swap in seconds, shrinking waits
+  for the next host reboot — active swap is never unmounted, because
+  that would drag every frozen sandbox's memory back into RAM. Everything
+  else is the effective environment configuration, read-only, with
+  secrets shown as present-or-absent only; changing those happens in
+  `/etc/dormice/env` plus a restart, never from the browser.
 - **Version** — the build the daemon is running (a git commit — trunk
   commit titles are the changelog) compared against the latest, with a
   one-click [upgrade](/docs/upgrading) and live progress where the host
diff --git a/website/content/docs/http-api.mdx b/website/content/docs/http-api.mdx
index add3afe..f991472 100644
--- a/website/content/docs/http-api.mdx
+++ b/website/content/docs/http-api.mdx
@@ -56,7 +56,7 @@ The [E2B compatibility surface](/docs/e2b-sdks) is a separate wire under
 | `POST /listSandboxImages` | each sandbox's born image vs its template's current one | — |
 | `POST /listActivity` | the daemon's recent history with per-event [attribution](#who-did-what), newest first — a bounded ring, not an audit log | — |
 | `POST /getConfig` | effective configuration: env knobs (read-only; secrets reported present-or-absent, value never sent) plus the live runtime `settings` | — |
-| `POST /updateSettings` | rewrite the runtime settings (capacity cap, new-sandbox defaults, default policy) — immediate effect, no restart; each provided group replaces that group whole | 400 empty patch or a default policy that asks to archive with no S3 configured |
+| `POST /updateSettings` | rewrite the runtime settings (capacity cap, new-sandbox defaults, default policy, managed swap) — immediate effect, no restart; each provided group replaces that group whole. Managed swap (`swapGb`) grows immediately; shrinking waits for the next host reboot (an active swapfile is never unmounted — that would drag every frozen sandbox's memory back into RAM) | 400 empty patch, a default policy that asks to archive with no S3 configured, or `swapGb` on a host that cannot manage swap |
 | `POST /getIngress` | domains bound on the daemon's managed reverse proxy, with live DNS and certificate probes | — |
 | `POST /setIngress` | rewrite the managed proxy config to exactly this domain list (empty list unbinds all) | 400 when the daemon manages no proxy |
 
diff --git a/website/content/docs/installation.mdx b/website/content/docs/installation.mdx
index 3989ec2..cefeae5 100644
--- a/website/content/docs/installation.mdx
+++ b/website/content/docs/installation.mdx
@@ -112,7 +112,10 @@ affect using Dormice.
   real hardware: 0 bytes reclaimed at the default, 99.5% reclaimed
   at 100. Some cloud images (Alibaba Cloud, for one) ship
   `vm.swappiness=0`; check the effective value with
-  `sysctl vm.swappiness`.
+  `sysctl vm.swappiness`. Swap capacity is roughly "how much sandbox
+  memory can hibernate at once" — when the installer's swapfile stops
+  being enough, add more from the console's settings page (no shell
+  needed; see [Console](/docs/console)).
 - **Network hardening.** Sandboxes run untrusted code, and a cloud
   server exposes a special internal address that hands out the
   machine's cloud credentials to anything that asks (the metadata

From fe0a761fb72e6fca7989e6a2c9806287e2ec6d90 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Sun, 19 Jul 2026 20:25:19 +0800
Subject: [PATCH 115/133] =?UTF-8?q?swap=20=E6=97=8B=E9=92=AE=E5=85=A8?=
 =?UTF-8?q?=E9=93=BE=E5=A4=8D=E6=9F=A5=E4=BF=AE=E4=B8=A4=E5=A4=84=20+=20?=
 =?UTF-8?q?=E7=9C=9F=E6=9C=BA=E4=B8=83=E5=85=B3=E8=A1=A5=E8=80=83=E5=85=A8?=
 =?UTF-8?q?=E8=BF=87:status()=20=E5=88=BB=E6=84=8F=E4=B8=8D=E6=8E=92=20rec?=
 =?UTF-8?q?oncile=20=E9=98=9F=E5=88=97(getConfig=20=E4=B8=8D=E8=AF=A5?=
 =?UTF-8?q?=E7=AD=89=20fallocate),=E4=BB=A3=E4=BB=B7=E6=98=AF=20readdir=20?=
 =?UTF-8?q?=E4=B8=8E=20stat=20=E4=B9=8B=E9=97=B4=E5=9D=97=E6=96=87?=
 =?UTF-8?q?=E4=BB=B6=E5=8F=AF=E8=83=BD=E8=A2=AB=E5=B9=B6=E5=8F=91=E5=AF=B9?=
 =?UTF-8?q?=E8=B4=A6=E5=88=A0=E6=8E=89=E2=80=94=E2=80=94ENOENT=20=E7=9A=84?=
 =?UTF-8?q?=E6=AD=A3=E7=A1=AE=E8=AF=BB=E6=B3=95=E6=98=AF=E3=80=8C=E5=AE=83?=
 =?UTF-8?q?=E5=B7=B2=E4=B8=8D=E5=86=8D=E6=98=AF=E5=9D=97=E3=80=8D,?=
 =?UTF-8?q?=E8=B7=B3=E8=BF=87=E8=80=8C=E9=9D=9E=E8=AE=A9=20getConfig=20?=
 =?UTF-8?q?=E7=82=B8=20500,=E6=82=AC=E7=A9=BA=E7=AC=A6=E5=8F=B7=E9=93=BE?=
 =?UTF-8?q?=E6=8E=A5=E5=BD=93=E7=A1=AE=E5=AE=9A=E6=80=A7=E6=9B=BF=E8=BA=AB?=
 =?UTF-8?q?=E9=92=89=E8=BF=9B=E6=B5=8B=E8=AF=95=E3=80=82console=20useSubmi?=
 =?UTF-8?q?t=20=E5=8F=AA=E5=9C=A8=E6=88=90=E5=8A=9F=E6=97=B6=E5=88=B7?=
 =?UTF-8?q?=E6=96=B0=20config,=E4=BD=86=20swap=20=E7=8B=AC=E6=9C=89?=
 =?UTF-8?q?=E7=9A=84=20500=20=E8=AF=AD=E4=B9=89=E6=98=AF=E3=80=8C=E7=9B=AE?=
 =?UTF-8?q?=E6=A0=87=E5=B7=B2=E5=AD=98=E4=BD=86=E5=BA=94=E7=94=A8=E5=A4=B1?=
 =?UTF-8?q?=E8=B4=A5=E3=80=8D=E2=80=94=E2=80=94=E8=B4=A6=E6=9C=AC=E7=9C=9F?=
 =?UTF-8?q?=E7=9A=84=E5=8F=98=E4=BA=86,=E7=95=8C=E9=9D=A2=E9=82=A3?=
 =?UTF-8?q?=E4=B8=80=E8=A1=8C=E5=8D=B4=E8=BF=98=E5=BF=B5=E6=97=A7=E8=B4=A6?=
 =?UTF-8?q?;=E5=88=B7=E6=96=B0=E6=8C=AA=E8=BF=9B=20finally,=E5=A4=B1?=
 =?UTF-8?q?=E8=B4=A5=E4=B9=9F=E7=AB=8B=E5=88=BB=E8=AF=B4=E7=9C=9F=E8=AF=9D?=
 =?UTF-8?q?=E3=80=82=E5=A4=8D=E6=9F=A5=E5=90=8C=E6=97=B6=E5=8F=8D=E8=AF=81?=
 =?UTF-8?q?=E4=BA=86=E4=B8=A4=E6=9D=A1=E6=97=A0=E7=BD=AA:=E5=B9=B6?=
 =?UTF-8?q?=E5=8F=91=20updateSettings=20=E7=9A=84=E6=94=B6=E6=95=9B?=
 =?UTF-8?q?=E6=80=A7=E6=88=90=E7=AB=8B(better-sqlite3=20=E5=86=99=E5=BA=93?=
 =?UTF-8?q?=E4=B8=8E=20reconcile=20=E5=85=A5=E9=98=9F=E5=90=8C=E5=A4=84?=
 =?UTF-8?q?=E4=B8=80=E4=B8=AA=E6=97=A0=20await=20=E7=9A=84=E5=90=8C?=
 =?UTF-8?q?=E6=AD=A5=20tick,=E9=98=9F=E5=88=97=E9=A1=BA=E5=BA=8F=E5=BF=85?=
 =?UTF-8?q?=E7=84=B6=E8=B7=9F=E9=9A=8F=E5=86=99=E5=BA=93=E9=A1=BA=E5=BA=8F?=
 =?UTF-8?q?,=E6=9C=80=E5=90=8E=E6=89=A7=E8=A1=8C=E7=9A=84=E5=AF=B9?=
 =?UTF-8?q?=E8=B4=A6=E5=BF=85=E6=90=BA=E5=B8=A6=E8=B4=A6=E6=9C=AC=E7=BB=88?=
 =?UTF-8?q?=E5=80=BC);planner=20=E9=A6=96=E9=80=82=E9=85=8D=E5=8F=AF?=
 =?UTF-8?q?=E8=83=BD=E5=88=A0=E5=A4=A7=E5=9D=97=E5=BB=BA=E5=B0=8F=E5=9D=97?=
 =?UTF-8?q?,=E6=98=AF=E7=94=A8=E4=B8=80=E6=AC=A1=20fallocate=20=E7=9A=84ch?=
 =?UTF-8?q?urn=E6=8D=A2=E3=80=8C=E7=9B=98=E4=B8=8A=E6=B0=B8=E8=BF=9C?=
 =?UTF-8?q?=E5=8F=AA=E7=95=99=E7=9B=AE=E6=A0=87=E9=82=A3=E4=B9=88=E5=A4=9A?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6=E3=80=8D=E7=9A=84=E7=AE=80=E5=8D=95=E4=B8=8D?=
 =?UTF-8?q?=E5=8F=98=E9=87=8F,=E6=8B=8D=E6=9D=BF=E4=BF=9D=E7=95=99?=
 =?UTF-8?q?=E3=80=82=E7=9C=9F=E6=9C=BA=E5=BE=AE=E8=80=83(=E6=89=8B?=
 =?UTF-8?q?=E5=86=8C=20=C2=A739):esbuild=20=E5=8D=95=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E7=9B=B4=E9=A9=B1=20SwapManager=20=E6=9C=AC=E5=B0=8A=E4=B8=8A?=
 =?UTF-8?q?=E6=B5=8B=E8=AF=95=E6=9C=BA,=E5=87=BA=E7=94=9F/=E5=A2=9E?=
 =?UTF-8?q?=E5=AE=B9/=E7=BC=A9=E5=AE=B9=E6=8C=82=E8=B5=B7/swapoff=20?=
 =?UTF-8?q?=E6=A8=A1=E6=8B=9F=E9=87=8D=E5=90=AF=E5=90=8E=E6=94=B6=E6=95=9B?=
 =?UTF-8?q?/=E5=BD=92=E9=9B=B6/=E7=B3=BB=E7=BB=9F=20swapfile=20=E6=AF=AB?=
 =?UTF-8?q?=E5=8F=91=E6=97=A0=E6=8D=9F=E4=B8=83=E5=85=B3=E5=85=A8=E8=BF=87?=
 =?UTF-8?q?=E2=80=94=E2=80=94swapon=20=E7=9C=9F=E6=8C=82=E8=BD=BD=E3=80=81?=
 =?UTF-8?q?=E8=AF=9A=E5=AE=9E=E6=97=A5=E5=BF=97=E3=80=81=E5=9D=97=E6=96=87?=
 =?UTF-8?q?=E4=BB=B6=E5=88=A0=E7=95=99=E5=85=A8=E9=83=A8=E4=B8=8E=E8=AE=BE?=
 =?UTF-8?q?=E8=AE=A1=E9=80=90=E5=AD=97=E5=AF=B9=E4=B8=8A;=E6=95=B4?=
 =?UTF-8?q?=E9=93=BE=E9=AA=8C=E6=94=B6(daemon=20=E9=83=A8=E7=BD=B2+console?=
 =?UTF-8?q?=20=E5=AE=9E=E7=82=B9+=E7=9C=9F=E9=87=8D=E5=90=AF)=E4=BB=8D?=
 =?UTF-8?q?=E7=95=99=E7=BB=99=E9=83=A8=E7=BD=B2=E5=90=8E=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../settings/components/RuntimeSettingsCard.tsx    |  6 ++++--
 packages/server/src/swap.test.ts                   | 10 ++++++++++
 packages/server/src/swap.ts                        | 14 ++++++++++++--
 3 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx b/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
index 0000495..7ddf34d 100644
--- a/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
+++ b/packages/console/src/features/settings/components/RuntimeSettingsCard.tsx
@@ -50,13 +50,15 @@ function useSubmit(onDone: () => void) {
     setError(null);
     try {
       await updateSettings(patch);
-      // 设置页读 config;总览的容量卡走 getHostMetrics 自己的轮询。
-      void queryClient.invalidateQueries({ queryKey: ['config'] });
       toast.success(done);
       onDone();
     } catch (cause) {
       setError(cause instanceof Error ? cause.message : String(cause));
     } finally {
+      // 失败也刷新:swap 的 500 语义是"目标已存但应用失败",账本真的变了,
+      // 行里必须立刻说真话。设置页读 config;总览的容量卡走 getHostMetrics
+      // 自己的轮询。
+      void queryClient.invalidateQueries({ queryKey: ['config'] });
       setPending(false);
     }
   };
diff --git a/packages/server/src/swap.test.ts b/packages/server/src/swap.test.ts
index 61b552a..3666898 100644
--- a/packages/server/src/swap.test.ts
+++ b/packages/server/src/swap.test.ts
@@ -179,6 +179,16 @@ describe('SwapManager', () => {
     expect((await fs.readdir(swapDir)).sort()).toEqual(['notes.txt']);
   });
 
+  it('skips a block path that vanishes between readdir and stat', async () => {
+    // status() bypasses the reconcile queue, so a concurrent reconcile can
+    // delete a block mid-listing. A dangling symlink is the deterministic
+    // stand-in for that race: readdir sees the name, stat gets ENOENT.
+    await fs.mkdir(swapDir, { recursive: true });
+    await fs.symlink(path.join(dir, 'gone'), path.join(swapDir, 'block-3'));
+    const status = await manager().status();
+    expect(status.blocks).toEqual([]);
+  });
+
   it('reports status without mutating anything', async () => {
     const swap = manager();
     await swap.reconcile(2);
diff --git a/packages/server/src/swap.ts b/packages/server/src/swap.ts
index fc1edc2..e966f30 100644
--- a/packages/server/src/swap.ts
+++ b/packages/server/src/swap.ts
@@ -1,4 +1,4 @@
-import { promises as fs } from 'node:fs';
+import { promises as fs, type Stats } from 'node:fs';
 import path from 'node:path';
 import { execa } from 'execa';
 
@@ -197,7 +197,17 @@ export class SwapManager implements SwapControl {
       // to judge here — never deleted by the planner.
       if (!match) continue;
       const filePath = path.join(this.dir, name);
-      const stat = await fs.stat(filePath);
+      let stat: Stats;
+      try {
+        stat = await fs.stat(filePath);
+      } catch (error) {
+        // status() deliberately bypasses the reconcile queue (getConfig
+        // must not wait behind a fallocate), so a block a concurrent
+        // reconcile just deleted can vanish between readdir and stat —
+        // then it simply is not a block anymore.
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw error;
+      }
       blocks.push({
         name,
         sizeGb: Math.round(stat.size / 2 ** 30),

From aed25e279e311dab43268b1bc15ba276771fe1aa Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Mon, 20 Jul 2026 09:56:26 +0800
Subject: [PATCH 116/133] =?UTF-8?q?=E7=AD=BE=E5=90=8D=20URL=20=E9=95=BF?=
 =?UTF-8?q?=E5=87=BA=E6=B5=8F=E8=A7=88=E5=99=A8=E7=9B=B4=E4=BC=A0=E5=BD=A2?=
 =?UTF-8?q?=E6=80=81:=E5=A4=96=E9=83=A8=20web=20=E5=BA=94=E7=94=A8?=
 =?UTF-8?q?=E7=9A=84=E9=A1=B5=E9=9D=A2=E5=8F=AF=E6=8B=BF=E5=AE=98=E6=96=B9?=
 =?UTF-8?q?=20SDK=20uploadUrl=20=E9=93=B8=E7=9A=84=20URL=20=E7=9B=B4?=
 =?UTF-8?q?=E6=8E=A5=20POST=20=E8=BF=9B=E6=B2=99=E7=AE=B1,=E4=B8=8D?=
 =?UTF-8?q?=E5=86=8D=E9=9C=80=E8=A6=81=E8=87=AA=E5=AE=B6=E6=9C=8D=E5=8A=A1?=
 =?UTF-8?q?=E5=99=A8=E4=B8=AD=E8=BD=AC=E5=AD=97=E8=8A=82=E3=80=82=E7=AD=BE?=
 =?UTF-8?q?=E5=90=8D=E9=89=B4=E6=9D=83=E6=9C=AC=E8=BA=AB=202026-07-10=20?=
 =?UTF-8?q?=E5=B0=B1=E6=9C=89=E4=B8=94=E5=B7=B2=E5=AF=B9=E9=92=89=E5=AE=98?=
 =?UTF-8?q?=E6=96=B9=E7=AE=97=E6=B3=95,=E8=BF=99=E6=AC=A1=E5=AE=9E?=
 =?UTF-8?q?=E6=B5=8B=E4=B8=8D=E9=80=9A=E7=9A=84=E7=97=85=E6=A0=B9=E6=98=AF?=
 =?UTF-8?q?=E8=B7=AF=E7=94=B1=E4=B8=8E=20CORS=20=E4=B8=A4=E5=B1=82,?=
 =?UTF-8?q?=E6=95=85=E8=A1=A5=E4=B8=89=E4=BB=B6:=E2=91=A0=E7=AB=AF?=
 =?UTF-8?q?=E5=8F=A3=E4=BB=A3=E7=90=86=E5=AF=B9=2049983(E2B=20=E7=9A=84=20?=
 =?UTF-8?q?envd=20=E5=9B=BA=E5=AE=9A=E7=AB=AF=E5=8F=A3)=E7=9A=84=20/files?=
 =?UTF-8?q?=20=E5=88=BB=E6=84=8F=E8=AE=A9=E8=B7=AF=E2=80=94=E2=80=94?=
 =?UTF-8?q?=E7=9C=9F=20E2B=20=E7=9A=84=E6=B5=8F=E8=A7=88=E5=99=A8=E7=9B=B4?=
 =?UTF-8?q?=E4=BC=A0=20URL=20=E5=B0=B1=E6=98=AF=2049983-<sandboxId>.<?=
 =?UTF-8?q?=E6=B3=9B=E5=9F=9F=E5=90=8D>/files=20=E5=BD=A2=E6=80=81,?=
 =?UTF-8?q?=E8=80=8C=E5=AE=B9=E5=99=A8=E5=86=85=E6=B2=A1=E6=9C=89=20envd(d?=
 =?UTF-8?q?aemon=20=E4=BB=A3=E8=A1=8C),=E6=8B=A8=E8=BF=9B=E5=8E=BB?=
 =?UTF-8?q?=E5=8F=AA=E8=83=BD=20502;=E8=AE=A9=E7=BB=99=E6=A0=B9=E9=97=A8?=
 =?UTF-8?q?=E7=9A=84=E5=90=8C=E6=97=B6=20Host=20=E6=A0=87=E7=AD=BE?=
 =?UTF-8?q?=E9=92=89=E6=AD=BB=E6=B2=99=E7=AE=B1=E8=BA=AB=E4=BB=BD(?=
 =?UTF-8?q?=E5=AF=B9=20A=20=E7=AD=BE=E7=9A=84=E5=90=8D=E5=BC=80=E4=B8=8D?=
 =?UTF-8?q?=E4=BA=86=20B=20=E7=9A=84=E9=97=A8,=E4=B8=8E=E6=AF=8F=E4=B8=AA?=
 =?UTF-8?q?=E7=9C=9F=20envd=20=E5=8F=AA=E8=AE=A4=E8=87=AA=E5=B7=B1=20token?=
 =?UTF-8?q?=20=E7=9A=84=E8=AF=AD=E4=B9=89=E9=80=90=E5=AD=97=E5=AF=B9?=
 =?UTF-8?q?=E9=BD=90;=E4=B8=8D=E5=AD=98=E5=9C=A8/=E5=B7=B2=E6=AD=BB?=
 =?UTF-8?q?=E6=B2=99=E7=AE=B1=E7=94=B1=E4=B8=8B=E6=B8=B8=20wake=20?=
 =?UTF-8?q?=E9=97=B8=E7=AD=94=20502),=E8=A3=B8=E5=8D=95=E5=9F=9F=E5=90=8D?=
 =?UTF-8?q?=E5=BD=A2=E6=80=81=E4=BB=8D=E7=94=B1=E7=AD=BE=E5=90=8D=E5=8F=8D?=
 =?UTF-8?q?=E6=8E=A8=E8=BA=AB=E4=BB=BD,49983=20=E7=9A=84=E5=85=B6=E4=BD=99?=
 =?UTF-8?q?=E8=B7=AF=E5=BE=84=E7=85=A7=E6=97=A7=E6=8B=A8=E5=AE=B9=E5=99=A8?=
 =?UTF-8?q?=E8=AF=9A=E5=AE=9E=20502=E3=80=82=E2=91=A1envd=20=E7=BD=91?=
 =?UTF-8?q?=E5=85=B3=20/files=20=E7=BC=BA=20X-Access-Token=20=E6=97=B6?=
 =?UTF-8?q?=E6=8E=A5=E5=8F=97=E7=AD=BE=E5=90=8D=20query(=E7=9C=9F=20envd?=
 =?UTF-8?q?=20=E6=96=87=E4=BB=B6=E8=B7=AF=E7=94=B1=E6=9C=AC=E5=B0=B1?=
 =?UTF-8?q?=E4=B8=A4=E7=A7=8D=E5=87=AD=E8=AF=81=E9=83=BD=E6=94=B6;?=
 =?UTF-8?q?=E6=9C=89=20token=20=E6=81=92=E5=88=A4=20token,=E5=AD=98?=
 =?UTF-8?q?=E9=87=8F=E8=BF=81=E7=A7=BB=E9=80=9A=E9=81=93=E5=8E=9F=E6=A0=B7?=
 =?UTF-8?q?),=E9=92=89=E5=9C=A8=20E2b-Sandbox-Id=20=E5=A4=B4=E4=B8=8A,?=
 =?UTF-8?q?=E4=BB=85=E6=96=87=E4=BB=B6=E9=9D=A2=E2=80=94=E2=80=94RPC=20?=
 =?UTF-8?q?=E9=9D=A2=E7=AD=BE=E5=90=8D=E4=B9=B0=E4=B8=8D=E5=88=B0=E4=B8=9C?=
 =?UTF-8?q?=E8=A5=BF=E3=80=82=E4=B8=89=E4=B8=AA=E9=97=A8=E5=85=B1=E7=94=A8?=
 =?UTF-8?q?=20signing.ts=20=E5=8D=95=E4=B8=80=E8=A3=81=E5=86=B3=E7=82=B9?=
 =?UTF-8?q?=20authenticateSignedQuery(=E9=92=89/=E4=B8=8D=E9=92=89?=
 =?UTF-8?q?=E4=B8=A4=E5=BD=A2=E6=80=81),=E7=BC=BA=E7=AD=BE=E5=90=8D?=
 =?UTF-8?q?=E2=86=92=E6=81=92=E6=97=B6=E6=AF=94=E5=AF=B9=E2=86=92=E8=BF=87?=
 =?UTF-8?q?=E6=9C=9F=E7=9A=84=E9=A1=BA=E5=BA=8F=E4=BF=9D=E6=8C=81=E7=9C=9F?=
 =?UTF-8?q?=20envd=20=E7=9A=84:=E4=BC=AA=E9=80=A0=E8=80=85=E4=B8=8D?=
 =?UTF-8?q?=E8=AF=A5=E4=BB=8E=E6=8A=A5=E9=94=99=E5=BE=97=E7=9F=A5=E8=87=AA?=
 =?UTF-8?q?=E5=B7=B1=E6=98=AF=E5=90=A6=E4=B9=9F=E8=BF=87=E6=9C=9F=E3=80=82?=
 =?UTF-8?q?=E2=91=A2CORS:=E4=B8=A4=E5=BD=A2=E6=80=81=20/files=20=E5=85=A8?=
 =?UTF-8?q?=E9=83=A8=E5=93=8D=E5=BA=94=E5=90=AB=20401/4xx/5xx=20=E5=B8=A6?=
 =?UTF-8?q?=20ACAO=20=E9=80=9A=E9=85=8D(URL=20=E7=AD=BE=E5=90=8D=E5=8D=B3?=
 =?UTF-8?q?=E8=83=BD=E5=8A=9B=E5=87=AD=E8=AF=81,=E4=B8=8E=20E2B=20?=
 =?UTF-8?q?=E5=AE=98=E6=96=B9=E5=90=8C=E5=8F=A3=E5=BE=84;=E9=94=99?=
 =?UTF-8?q?=E8=AF=AF=E4=B8=8D=E5=B8=A6=20ACAO=20=E6=B5=8F=E8=A7=88?=
 =?UTF-8?q?=E5=99=A8=E5=8F=AA=E8=83=BD=E6=8A=A5=E7=AC=BC=E7=BB=9F=20CORS?=
 =?UTF-8?q?=20=E5=A4=B1=E8=B4=A5=E8=AF=BB=E4=B8=8D=E5=88=B0=E7=9C=9F?=
 =?UTF-8?q?=E5=AE=9E=E6=8B=92=E5=9B=A0),OPTIONS=20=E9=A2=84=E6=A3=80?=
 =?UTF-8?q?=E6=97=A0=E6=9D=A1=E4=BB=B6=20204+methods+max-age=207200(?=
 =?UTF-8?q?=E9=A2=84=E6=A3=80=E5=A4=A9=E7=84=B6=E6=97=A0=E5=87=AD=E8=AF=81?=
 =?UTF-8?q?,=E6=B2=A1=E4=B8=9C=E8=A5=BF=E5=8F=AF=E5=88=A4;XHR=20=E6=8C=82?=
 =?UTF-8?q?=20upload.onprogress=20=E5=BF=85=E5=8F=91=E9=A2=84=E6=A3=80,?=
 =?UTF-8?q?=E8=BF=99=E6=AD=A5=E4=B8=8D=E9=80=9A=E5=85=A8=E7=9B=98=E7=9A=86?=
 =?UTF-8?q?=E8=BE=93),=E4=B8=8B=E8=BD=BD=20hijack=20=E8=A3=B8=E5=86=99?=
 =?UTF-8?q?=E5=A4=B4=E5=8D=95=E7=8B=AC=E9=87=8D=E7=94=B3=20ACAO=E3=80=82?=
 =?UTF-8?q?=E8=90=BD=E7=9B=98=E5=8F=A3=E5=BE=84=E4=B8=8D=E5=8A=A8:multipar?=
 =?UTF-8?q?t=20filename=20=E4=BC=98=E5=85=88=E3=80=81=E7=BC=BA=E5=88=99=20?=
 =?UTF-8?q?=3Fpath=3D=20=E5=85=9C=E5=BA=95,=E5=93=8D=E5=BA=94=E5=9B=9E?=
 =?UTF-8?q?=E6=8A=A5=E5=AE=9E=E9=99=85=E8=90=BD=E7=82=B9=E3=80=82=E5=9B=9E?=
 =?UTF-8?q?=E5=BD=92=E9=92=89:compat=20=E4=BA=94=E4=BE=8B(=E9=A2=84?=
 =?UTF-8?q?=E6=A3=80=E4=B8=A4=E9=97=A8/Host=20=E9=92=89=E6=B2=99=E7=AE=B1?=
 =?UTF-8?q?=E5=90=AB=E6=94=B9=20path=20=E5=8D=B3=20401/=E5=AD=90=E5=9F=9F?=
 =?UTF-8?q?=E6=8B=92=E7=BB=9D=E9=A1=BA=E5=BA=8F=E5=B8=A6=20ACAO/hijack=20?=
 =?UTF-8?q?=E4=B8=8B=E8=BD=BD=E5=B8=A6=20ACAO/=E7=BD=91=E5=85=B3=E7=AD=BE?=
 =?UTF-8?q?=E5=90=8D=E5=9B=9E=E9=80=80=E5=90=AB=20RPC=20=E9=9D=A2=E5=8F=8D?=
 =?UTF-8?q?=E8=AF=81),sandbox-proxy=20=E7=9C=9F=20socket=20=E7=AB=AF?=
 =?UTF-8?q?=E5=88=B0=E7=AB=AF=E4=B8=80=E4=BE=8B(=E7=BA=AF=E6=B5=8F?=
 =?UTF-8?q?=E8=A7=88=E5=99=A8=E5=BD=A2=E6=80=81=E9=A2=84=E6=A3=80=E2=86=92?=
 =?UTF-8?q?=E4=B8=8A=E4=BC=A0=E2=86=92=E8=90=BD=E7=82=B9=E6=A0=B8=E5=AF=B9?=
 =?UTF-8?q?,=E5=B9=B6=E5=8F=8D=E8=AF=81=E9=9D=9E=20/files=20=E4=BB=8D?=
 =?UTF-8?q?=E8=B5=B0=E4=BB=A3=E7=90=86)=E3=80=82=E7=94=9F=E4=BA=A7?=
 =?UTF-8?q?=E6=9C=BA=E5=A4=96=E5=B1=82=20Caddy=20=E6=B3=9B=E5=9F=9F?=
 =?UTF-8?q?=E5=90=8D=E5=9D=97=E6=97=A0=E9=9C=80=E5=8A=A8,daemon=20?=
 =?UTF-8?q?=E4=BE=A7=E7=89=B9=E5=88=A4=E5=8D=B3=E5=85=A8=E9=80=9A;?=
 =?UTF-8?q?=E9=83=A8=E7=BD=B2=E5=90=8E=E7=94=B1=E6=B6=88=E8=B4=B9=E6=96=B9?=
 =?UTF-8?q?=E8=84=9A=E6=9C=AC=E5=A4=8D=E9=AA=8C=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/server/src/e2b/compat.test.ts    | 244 ++++++++++++++++++++++
 packages/server/src/e2b/cors.ts           |  39 ++++
 packages/server/src/e2b/envd/files.ts     |  11 +
 packages/server/src/e2b/envd/index.ts     |  38 +++-
 packages/server/src/e2b/signed-files.ts   | 109 +++++-----
 packages/server/src/e2b/signing.ts        |  93 ++++++++-
 packages/server/src/sandbox-proxy.test.ts | 106 +++++++++-
 packages/server/src/sandbox-proxy.ts      |  26 ++-
 website/content/docs/e2b-differences.mdx  |   2 +-
 9 files changed, 594 insertions(+), 74 deletions(-)
 create mode 100644 packages/server/src/e2b/cors.ts

diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 57563a2..18f0cdb 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -1855,6 +1855,250 @@ describe('signed file URLs at the daemon root', () => {
   });
 });
 
+/**
+ * The browser-direct form: a page on any origin POSTs a signed URL of the
+ * `49983-<sandboxId>.<domain>` shape straight into the sandbox. inject()
+ * bypasses the serverFactory, so what these tests exercise is the Fastify
+ * half — the Host pin and CORS; the proxy's carve-out that delivers such
+ * requests here is sandbox-proxy.test.ts's business.
+ */
+describe('browser-direct signed files: the 49983 subdomain form and CORS', () => {
+  const DOMAIN = 'sbx.dormice.test';
+  const subdomainApp = () =>
+    testApp(new FakeExecutor(), { DORMICE_SANDBOX_DOMAIN: DOMAIN });
+
+  it('answers the preflight open and cacheable — it carries no credentials to judge', async () => {
+    const t = testApp();
+    for (const url of ['/files', '/e2b/envd/files']) {
+      const res = await t.app.inject({
+        method: 'OPTIONS',
+        url,
+        headers: {
+          origin: 'https://app.example.test',
+          'access-control-request-method': 'POST',
+        },
+      });
+      expect(res.statusCode).toBe(204);
+      expect(res.headers['access-control-allow-origin']).toBe('*');
+      expect(res.headers['access-control-allow-methods']).toContain('POST');
+      expect(res.headers['access-control-max-age']).toBe('7200');
+    }
+  });
+
+  it('the Host label pins the sandbox: its own signature opens it, another sandbox’s opens nothing', async () => {
+    const t = subdomainApp();
+    const a = await createSandbox(t);
+    const b = await createSandbox(t);
+    const path = '/home/user/probe/a.txt';
+    const upload = (host: string, envdAccessToken: string) => {
+      const exp = Math.floor(Date.now() / 1000) + 300;
+      const sig = sdkSignature({
+        path,
+        operation: 'write',
+        envdAccessToken,
+        expiration: exp,
+      });
+      const boundary = 'browser-direct-boundary';
+      const body = [
+        `--${boundary}`,
+        `Content-Disposition: form-data; name="file"; filename="${path}"`,
+        'Content-Type: text/plain',
+        '',
+        'straight from the browser\n',
+        `--${boundary}--`,
+        '',
+      ].join('\r\n');
+      return t.app.inject({
+        method: 'POST',
+        url: `/files?path=${encodeURIComponent(path)}&signature=${encodeURIComponent(sig)}&signature_expiration=${exp}`,
+        headers: {
+          host,
+          'content-type': `multipart/form-data; boundary=${boundary}`,
+        },
+        payload: body,
+      });
+    };
+
+    const ok = await upload(
+      `49983-${a.sandboxID}.${DOMAIN}`,
+      a.envdAccessToken,
+    );
+    expect(ok.statusCode).toBe(200);
+    // The response reports the true landing path (migration checks read it)
+    // and stays browser-readable.
+    expect(ok.json()).toEqual([{ name: 'a.txt', type: 'file', path }]);
+    expect(ok.headers['access-control-allow-origin']).toBe('*');
+
+    // B's signature is valid — for B. Against A's subdomain it must be
+    // refused, however many ledger rows it would match unpinned.
+    const crossed = await upload(
+      `49983-${a.sandboxID}.${DOMAIN}`,
+      b.envdAccessToken,
+    );
+    expect(crossed.statusCode).toBe(401);
+    expect(crossed.json().message).toBe('invalid signature');
+    // The refusal is browser-readable — without ACAO on the 401 a browser
+    // reports an opaque CORS failure instead of the real error.
+    expect(crossed.headers['access-control-allow-origin']).toBe('*');
+
+    // A signature over path a.txt opens no other path: the material pins it.
+    const expNow = Math.floor(Date.now() / 1000) + 300;
+    const sigA = sdkSignature({
+      path,
+      operation: 'write',
+      envdAccessToken: a.envdAccessToken,
+      expiration: expNow,
+    });
+    const swapped = await t.app.inject({
+      method: 'POST',
+      url: `/files?path=${encodeURIComponent('/home/user/probe/b.txt')}&signature=${encodeURIComponent(sigA)}&signature_expiration=${expNow}`,
+      headers: {
+        host: `49983-${a.sandboxID}.${DOMAIN}`,
+        'content-type': 'application/octet-stream',
+      },
+      payload: 'nope',
+    });
+    expect(swapped.statusCode).toBe(401);
+    expect(swapped.json().message).toBe('invalid signature');
+  });
+
+  it('refusals through the subdomain keep the envd order and carry CORS', async () => {
+    const t = subdomainApp();
+    const { sandboxID, envdAccessToken } = await createSandbox(t);
+    const host = `49983-${sandboxID}.${DOMAIN}`;
+
+    const bare = await t.app.inject({
+      method: 'POST',
+      url: '/files?path=x',
+      headers: { host, 'content-type': 'application/octet-stream' },
+      payload: 'x',
+    });
+    expect(bare.statusCode).toBe(401);
+    expect(bare.json().message).toBe('missing signature query parameter');
+    expect(bare.headers['access-control-allow-origin']).toBe('*');
+
+    // An expired signature (validly signed over the past timestamp).
+    const past = Math.floor(Date.now() / 1000) - 10;
+    const expiredSig = sdkSignature({
+      path: 'x',
+      operation: 'write',
+      envdAccessToken,
+      expiration: past,
+    });
+    const expired = await t.app.inject({
+      method: 'POST',
+      url: `/files?path=x&signature=${encodeURIComponent(expiredSig)}&signature_expiration=${past}`,
+      headers: { host, 'content-type': 'application/octet-stream' },
+      payload: 'x',
+    });
+    expect(expired.statusCode).toBe(401);
+    expect(expired.json().message).toBe('signature is already expired');
+    expect(expired.headers['access-control-allow-origin']).toBe('*');
+  });
+
+  it('a signed subdomain download streams with CORS on the hijacked head', async () => {
+    const t = subdomainApp();
+    const { sandboxID, envdAccessToken } = await createSandbox(t);
+    await putFile(t, sandboxID, 'probe/read.txt', 'readable cross-origin\n');
+    const sig = sdkSignature({
+      path: 'probe/read.txt',
+      operation: 'read',
+      envdAccessToken,
+    });
+    const res = await t.app.inject({
+      method: 'GET',
+      url: `/files?path=${encodeURIComponent('probe/read.txt')}&signature=${encodeURIComponent(sig)}`,
+      headers: { host: `49983-${sandboxID}.${DOMAIN}` },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toBe('readable cross-origin\n');
+    expect(res.headers['access-control-allow-origin']).toBe('*');
+  });
+
+  it('the envd gateway accepts the signed query when the token header is absent', async () => {
+    const t = testApp();
+    const { sandboxID, envdAccessToken } = await createSandbox(t);
+
+    // Write through the gateway with signature-only auth (real envd's file
+    // routes accept either credential).
+    const sig = sdkSignature({
+      path: 'gw.txt',
+      operation: 'write',
+      envdAccessToken,
+    });
+    const up = await t.app.inject({
+      method: 'POST',
+      url: `/e2b/envd/files?path=gw.txt&signature=${encodeURIComponent(sig)}`,
+      headers: {
+        'e2b-sandbox-id': sandboxID,
+        'content-type': 'application/octet-stream',
+      },
+      payload: 'through the gateway\n',
+    });
+    expect(up.statusCode).toBe(200);
+    expect(up.headers['access-control-allow-origin']).toBe('*');
+
+    const readSig = sdkSignature({
+      path: 'gw.txt',
+      operation: 'read',
+      envdAccessToken,
+    });
+    const back = await t.app.inject({
+      method: 'GET',
+      url: `/e2b/envd/files?path=gw.txt&signature=${encodeURIComponent(readSig)}`,
+      headers: { 'e2b-sandbox-id': sandboxID },
+    });
+    expect(back.statusCode).toBe(200);
+    expect(back.body).toBe('through the gateway\n');
+
+    // The pin is the header's sandbox: a signature for another one is
+    // refused even though it would match that other sandbox's token.
+    const other = await createSandbox(t);
+    const crossed = await t.app.inject({
+      method: 'POST',
+      url: `/e2b/envd/files?path=gw.txt&signature=${encodeURIComponent(
+        sdkSignature({
+          path: 'gw.txt',
+          operation: 'write',
+          envdAccessToken: other.envdAccessToken,
+        }),
+      )}`,
+      headers: {
+        'e2b-sandbox-id': sandboxID,
+        'content-type': 'application/octet-stream',
+      },
+      payload: 'nope',
+    });
+    expect(crossed.statusCode).toBe(401);
+    expect(crossed.json().message).toBe('invalid signature');
+    expect(crossed.headers['access-control-allow-origin']).toBe('*');
+
+    // No token and no signature keeps the standing refusal, now readable.
+    const naked = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/files?path=gw.txt',
+      headers: {
+        'e2b-sandbox-id': sandboxID,
+        'content-type': 'application/octet-stream',
+      },
+      payload: 'nope',
+    });
+    expect(naked.statusCode).toBe(401);
+    expect(naked.json().message).toBe('invalid envd access token');
+    expect(naked.headers['access-control-allow-origin']).toBe('*');
+
+    // The signed query buys nothing off the file face: a token-less RPC
+    // stays refused whatever its query says.
+    const rpc = await t.app.inject({
+      method: 'POST',
+      url: `/e2b/envd/filesystem.Filesystem/Stat?signature=${encodeURIComponent(sig)}`,
+      headers: { 'e2b-sandbox-id': sandboxID },
+      payload: { path: 'gw.txt' },
+    });
+    expect(rpc.statusCode).toBe(401);
+  });
+});
+
 describe('E2B templates', () => {
   // Registration is a native verb; the compat surface only consumes it.
   async function registerTemplate(t: TestApp, name: string, image: string) {
diff --git a/packages/server/src/e2b/cors.ts b/packages/server/src/e2b/cors.ts
new file mode 100644
index 0000000..a86cf4a
--- /dev/null
+++ b/packages/server/src/e2b/cors.ts
@@ -0,0 +1,39 @@
+import type { FastifyReply, FastifyRequest } from 'fastify';
+
+/**
+ * CORS for the browser-consumable file faces — the signed-URL door (which
+ * the 49983 subdomain form also lands on) and the envd /files face. The
+ * wildcard origin is deliberate and real E2B's own posture: the URL's
+ * signature IS the capability, no cookies ride these requests, so an
+ * origin allowlist would add nothing while breaking the legitimate
+ * consumer — a browser on some app's origin uploading straight into the
+ * sandbox without the app's server relaying bytes.
+ *
+ * Errors must carry the header too: a 401 without ACAO is unreadable to
+ * the browser, which can only report an opaque "CORS failure" instead of
+ * the real refusal.
+ */
+export function allowCorsOrigin(reply: FastifyReply): void {
+  reply.header('access-control-allow-origin', '*');
+}
+
+/**
+ * The preflight answer, real E2B's shape (204 + methods + a 2h cache).
+ * Unconditional by necessity: browsers send preflights credential-less,
+ * so there is nothing to authenticate — the POST itself is judged.
+ * Requested headers are echoed back; an XHR with upload.onprogress always
+ * preflights, so this route is the gate the whole browser flow hangs on.
+ */
+export function sendPreflight(request: FastifyRequest, reply: FastifyReply) {
+  const requested = request.headers['access-control-request-headers'];
+  return reply
+    .code(204)
+    .header('access-control-allow-origin', '*')
+    .header('access-control-allow-methods', 'GET, POST, OPTIONS')
+    .header(
+      'access-control-allow-headers',
+      typeof requested === 'string' && requested !== '' ? requested : '*',
+    )
+    .header('access-control-max-age', '7200')
+    .send();
+}
diff --git a/packages/server/src/e2b/envd/files.ts b/packages/server/src/e2b/envd/files.ts
index 37d5749..3c7571e 100644
--- a/packages/server/src/e2b/envd/files.ts
+++ b/packages/server/src/e2b/envd/files.ts
@@ -9,6 +9,7 @@ import {
   NotAFileError,
   type SandboxEntry,
 } from '../../executor/executor';
+import { sendPreflight } from '../cors';
 import { E2bError } from '../protocol';
 import {
   type EnvdContext,
@@ -28,6 +29,12 @@ export function registerFileRoutes(
   app: FastifyInstance,
   ctx: EnvdContext,
 ): void {
+  // The browser preflight (see cors.ts); the auth hook waves OPTIONS
+  // through — preflights are credential-less by spec.
+  app.options('/files', async (request, reply) =>
+    sendPreflight(request, reply),
+  );
+
   app.get('/files', async (request, reply) =>
     serveFileDownload(ctx, sandboxIdOf(request), request, reply),
   );
@@ -141,6 +148,10 @@ export async function serveFileDownload(
       'content-disposition': `inline; filename*=utf-8''${rfc5987(entry.name)}`,
       'content-length': String(entry.sizeBytes),
       'last-modified': new Date(entry.modifiedTime).toUTCString(),
+      // The hijacked head bypasses reply.header(), so the CORS promise
+      // (cors.ts: every file-face response is browser-readable) is
+      // re-stated here.
+      'access-control-allow-origin': '*',
     });
     await executor.readFileStream(
       row.id,
diff --git a/packages/server/src/e2b/envd/index.ts b/packages/server/src/e2b/envd/index.ts
index 6a4cb82..2e2295a 100644
--- a/packages/server/src/e2b/envd/index.ts
+++ b/packages/server/src/e2b/envd/index.ts
@@ -1,8 +1,10 @@
 import multipart from '@fastify/multipart';
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
 import { findById } from '../../db/ledger';
+import { allowCorsOrigin } from '../cors';
 import type { E2bDeps } from '../deps';
 import { E2bError, verifyEnvdToken } from '../protocol';
+import { authenticateSignedQuery, type SignedFileQuery } from '../signing';
 import { e2bView } from '../view';
 import { registerFileRoutes } from './files';
 import { registerFilesystemRoutes } from './filesystem';
@@ -77,14 +79,48 @@ export const e2bEnvdRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     });
   });
 
+  /** Path-only /files match; the query never changes what a URL names. */
+  const isFilesRequest = (url: string) => {
+    const q = url.indexOf('?');
+    return (q === -1 ? url : url.slice(0, q)).endsWith('/files');
+  };
+
+  // CORS rides in FRONT of auth on the file face (hooks run in
+  // registration order): a browser must be able to read the 401, or every
+  // refusal collapses into an opaque "CORS error" (see cors.ts).
+  app.addHook('onRequest', async (request, reply) => {
+    if (isFilesRequest(request.url)) allowCorsOrigin(reply);
+  });
+
   // Auth: X-Access-Token must be the HMAC minted for exactly this sandbox.
   // /health stays open like real envd's — it is how isRunning() probes.
+  // Preflights pass by necessity: browsers send them credential-less, so
+  // there is nothing to judge — the actual request is.
   app.addHook('onRequest', async (request) => {
     if (request.method === 'GET' && request.url.endsWith('/health')) return;
+    if (request.method === 'OPTIONS') return;
     const sandboxId = sandboxIdOf(request);
     const header = request.headers['x-access-token'];
     const token = Array.isArray(header) ? header[0] : header;
-    if (!token || !verifyEnvdToken(deps.envdSigningSecret, sandboxId, token)) {
+    if (!token) {
+      // Real envd's file routes accept either credential; token-less file
+      // requests may present the signed-URL query instead, judged against
+      // exactly the header's sandbox (the pin — a signature minted for
+      // another sandbox opens nothing here).
+      const query = request.query as SignedFileQuery;
+      if (isFilesRequest(request.url) && query.signature) {
+        authenticateSignedQuery({
+          db,
+          signingSecret: deps.envdSigningSecret,
+          query,
+          operation: request.method === 'GET' ? 'read' : 'write',
+          pinnedSandboxId: sandboxId,
+        });
+        return;
+      }
+      throw new E2bError(401, 'unauthenticated', 'invalid envd access token');
+    }
+    if (!verifyEnvdToken(deps.envdSigningSecret, sandboxId, token)) {
       throw new E2bError(401, 'unauthenticated', 'invalid envd access token');
     }
   });
diff --git a/packages/server/src/e2b/signed-files.ts b/packages/server/src/e2b/signed-files.ts
index 11985f6..4259627 100644
--- a/packages/server/src/e2b/signed-files.ts
+++ b/packages/server/src/e2b/signed-files.ts
@@ -1,11 +1,17 @@
 import multipart from '@fastify/multipart';
 import type { FastifyRequest } from 'fastify';
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
+import { parseSandboxHost } from '../sandbox-proxy';
+import { allowCorsOrigin, sendPreflight } from './cors';
 import type { E2bDeps } from './deps';
 import { serveFileDownload, serveFileUpload } from './envd/files';
 import { createEnvdContext, UNLIMITED_BODY_BYTES } from './envd/shared';
 import { E2bError } from './protocol';
-import { findRowBySignature, type SigningOperation } from './signing';
+import {
+  authenticateSignedQuery,
+  type SignedFileQuery,
+  type SigningOperation,
+} from './signing';
 
 /**
  * The signed-URL file surface, at the DAEMON ROOT — not under /e2b/envd.
@@ -14,7 +20,15 @@ import { findRowBySignature, type SigningOperation } from './signing';
  * whole path — the /e2b/envd prefix is stripped (verified against the SDK
  * source). The consumer is a bare browser or curl: no E2b-Sandbox-Id
  * header, no token, nothing but the query. The signature alone
- * authenticates AND identifies the sandbox (see findRowBySignature).
+ * authenticates AND identifies the sandbox (see authenticateSignedQuery).
+ *
+ * Two Host spellings land here, one door: the bare daemon origin (the URL
+ * uploadUrl mints verbatim) and — with DORMICE_SANDBOX_DOMAIN set —
+ * `49983-<sandboxId>.<domain>`, real E2B's browser-postable form, which
+ * the sandbox proxy carves out of port forwarding (see ENVD_PORT). On the
+ * subdomain form the Host label pins the sandbox: a signature minted for
+ * any other sandbox is refused, exactly as each real envd only ever
+ * accepts its own.
  *
  * Deliberately signature-only: a header token here would be a second door
  * to the same room — token-authenticated file traffic already has
@@ -58,69 +72,52 @@ export const signedFileRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     });
   });
 
+  // Browser-consumable means CORS-consumable: every response on this door,
+  // refusals included, carries the wildcard origin (see cors.ts). The
+  // hijacked download path writes its own head and re-states it there.
+  app.addHook('onRequest', async (_request, reply) => {
+    allowCorsOrigin(reply);
+  });
+
   const ctx = createEnvdContext(deps);
+  const domain = deps.config.DORMICE_SANDBOX_DOMAIN;
 
   /**
-   * Real envd's validateSigning, in its order: missing signature first,
-   * then the constant-time match (which here also recovers the sandbox),
-   * and only then the expiration — a wrong signature must never learn from
-   * the error whether it was also expired.
+   * The signature check plus, on the subdomain form, the Host pin: which
+   * sandbox the label names is which sandbox the signature must speak for.
+   * The signed username also names the execution identity; the file
+   * handler cores vet it against the image's users (a tampered username
+   * never gets that far — the signature covers it).
    */
-  function authenticate(request: FastifyRequest, operation: SigningOperation) {
-    const query = request.query as {
-      path?: string;
-      username?: string;
-      signature?: string;
-      signature_expiration?: string;
-    };
-    if (!query.signature) {
-      throw new E2bError(
-        401,
-        'unauthenticated',
-        'missing signature query parameter',
-      );
-    }
-    const expirationUnix =
-      query.signature_expiration === undefined
-        ? undefined
-        : Number(query.signature_expiration);
-    const row = findRowBySignature(
-      deps.db,
-      deps.envdSigningSecret,
-      {
-        path: query.path ?? '',
-        operation,
-        username: query.username ?? '',
-        ...(expirationUnix === undefined ? {} : { expirationUnix }),
-      },
-      query.signature,
-    );
-    if (!row) {
-      throw new E2bError(401, 'unauthenticated', 'invalid signature');
-    }
-    if (
-      expirationUnix !== undefined &&
-      expirationUnix < Math.floor(Date.now() / 1000)
-    ) {
-      throw new E2bError(
-        401,
-        'unauthenticated',
-        'signature is already expired',
-      );
-    }
-    // The signed username also names the execution identity; the file
-    // handler cores vet it against the image's users (a tampered username
-    // never gets that far — the signature covers it).
-    return row;
+  function authenticate(
+    request: FastifyRequest,
+    operation: SigningOperation,
+  ): string {
+    const pinned = domain
+      ? parseSandboxHost(request.headers.host, domain)?.sandboxId
+      : undefined;
+    return authenticateSignedQuery({
+      db: deps.db,
+      signingSecret: deps.envdSigningSecret,
+      query: request.query as SignedFileQuery,
+      operation,
+      ...(pinned === undefined ? {} : { pinnedSandboxId: pinned }),
+    });
   }
 
+  // The preflight the whole browser flow hangs on — an XHR with
+  // upload.onprogress always sends one, credential-less by spec.
+  app.options('/files', async (request, reply) =>
+    sendPreflight(request, reply),
+  );
+
   app.get('/files', async (request, reply) => {
-    const row = authenticate(request, 'read');
-    return serveFileDownload(ctx, row.id, request, reply);
+    const sandboxId = authenticate(request, 'read');
+    return serveFileDownload(ctx, sandboxId, request, reply);
   });
 
   app.post('/files', { bodyLimit: UNLIMITED_BODY_BYTES }, (request, reply) => {
-    const row = authenticate(request, 'write');
-    return serveFileUpload(ctx, row.id, request, reply);
+    const sandboxId = authenticate(request, 'write');
+    return serveFileUpload(ctx, sandboxId, request, reply);
   });
 };
diff --git a/packages/server/src/e2b/signing.ts b/packages/server/src/e2b/signing.ts
index fec3f5d..30649b8 100644
--- a/packages/server/src/e2b/signing.ts
+++ b/packages/server/src/e2b/signing.ts
@@ -2,7 +2,7 @@ import { createHash, timingSafeEqual } from 'node:crypto';
 import type { Db } from '../db/db';
 import { listSandboxes } from '../db/ledger';
 import type { SandboxRow } from '../db/schema';
-import { mintEnvdToken } from './protocol';
+import { E2bError, mintEnvdToken } from './protocol';
 import { e2bView } from './view';
 
 /**
@@ -40,6 +40,16 @@ export function fileSignature(
 
 const sha256 = (value: string) => createHash('sha256').update(value).digest();
 
+/** Constant-time: does `presented` match what this token would sign? */
+function matchesToken(
+  token: string,
+  material: SignatureMaterial,
+  presented: string,
+): boolean {
+  const expected = fileSignature(token, material);
+  return timingSafeEqual(sha256(expected), sha256(presented));
+}
+
 /**
  * Which sandbox does this signature speak for? A signed URL arrives bare —
  * no headers, no sandbox id anywhere (the SDK's fileUrl builds
@@ -52,7 +62,7 @@ const sha256 = (value: string) => createHash('sha256').update(value).digest();
  * subdomain per sandbox; the deliberate divergence is documented in the
  * protocol rules.
  */
-export function findRowBySignature(
+function findRowBySignature(
   db: Db,
   signingSecret: string,
   material: SignatureMaterial,
@@ -61,11 +71,80 @@ export function findRowBySignature(
   const now = new Date();
   for (const row of listSandboxes(db)) {
     if (e2bView(row, now) === 'dead') continue;
-    const expected = fileSignature(
-      mintEnvdToken(signingSecret, row.id),
-      material,
-    );
-    if (timingSafeEqual(sha256(expected), sha256(presented))) return row;
+    if (matchesToken(mintEnvdToken(signingSecret, row.id), material, presented))
+      return row;
   }
   return undefined;
 }
+
+/** The query half of a signed file URL, as the SDK's uploadUrl/downloadUrl mint it. */
+export interface SignedFileQuery {
+  path?: string;
+  username?: string;
+  signature?: string;
+  signature_expiration?: string;
+}
+
+/**
+ * The one adjudication of a signed file query, in real envd's
+ * validateSigning order: missing signature first, then the constant-time
+ * match, and only then the expiration — a wrong signature must never learn
+ * from the error whether it was also expired. Returns the sandbox id the
+ * signature speaks for; throws the envd-dialect 401s.
+ *
+ * Two identity sources, mirroring the two URL forms:
+ *  - pinned — the sandbox id arrived out of band (the `49983-<id>.<domain>`
+ *    Host label, or the envd surface's E2b-Sandbox-Id header). The
+ *    signature must match exactly that sandbox, real E2B's semantics: a
+ *    signature minted for sandbox A opens no other sandbox's door, whatever
+ *    else it would match. Existence/liveness is judged downstream by the
+ *    wake gate (502, like every envd verb against a dead sandbox).
+ *  - unpinned — the bare single-domain form: the signature itself is the
+ *    identity, recovered by scanning the live ledger rows.
+ */
+export function authenticateSignedQuery(opts: {
+  db: Db;
+  signingSecret: string;
+  query: SignedFileQuery;
+  operation: SigningOperation;
+  pinnedSandboxId?: string;
+}): string {
+  const { db, signingSecret, query, operation, pinnedSandboxId } = opts;
+  if (!query.signature) {
+    throw new E2bError(
+      401,
+      'unauthenticated',
+      'missing signature query parameter',
+    );
+  }
+  const expirationUnix =
+    query.signature_expiration === undefined
+      ? undefined
+      : Number(query.signature_expiration);
+  const material: SignatureMaterial = {
+    path: query.path ?? '',
+    operation,
+    username: query.username ?? '',
+    ...(expirationUnix === undefined ? {} : { expirationUnix }),
+  };
+  const sandboxId =
+    pinnedSandboxId !== undefined
+      ? matchesToken(
+          mintEnvdToken(signingSecret, pinnedSandboxId),
+          material,
+          query.signature,
+        )
+        ? pinnedSandboxId
+        : undefined
+      : findRowBySignature(db, signingSecret, material, query.signature)?.id;
+  if (sandboxId === undefined) {
+    throw new E2bError(401, 'unauthenticated', 'invalid signature');
+  }
+  if (
+    expirationUnix !== undefined &&
+    expirationUnix < Math.floor(Date.now() / 1000)
+  ) {
+    throw new E2bError(401, 'unauthenticated', 'signature is already expired');
+  }
+  return sandboxId;
+}
diff --git a/packages/server/src/sandbox-proxy.test.ts b/packages/server/src/sandbox-proxy.test.ts
index a00ae9b..b5e48f8 100644
--- a/packages/server/src/sandbox-proxy.test.ts
+++ b/packages/server/src/sandbox-proxy.test.ts
@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import http from 'node:http';
 import net from 'node:net';
 import { fileURLToPath } from 'node:url';
@@ -6,6 +7,8 @@ import { buildApp } from './app';
 import { loadConfig } from './config';
 import { migrateDb, openDb } from './db/db';
 import { findById } from './db/ledger';
+import { getOrCreateSigningSecret } from './db/secrets';
+import { mintEnvdToken } from './e2b/protocol';
 import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
 import { parseSandboxHost } from './sandbox-proxy';
@@ -48,28 +51,57 @@ describe('sandbox port proxy', () => {
     return { app, db, executor, locks, port: address.port };
   }
 
-  /** Raw GET with an explicit Host header (fetch refuses to set one). */
-  function rawGet(
+  /** Raw request with an explicit Host header (fetch refuses to set one). */
+  function rawRequest(
     port: number,
-    path: string,
-    host: string,
-  ): Promise<{ status: number; body: string }> {
+    opts: {
+      method?: string;
+      path: string;
+      host: string;
+      headers?: Record<string, string>;
+      body?: string;
+    },
+  ): Promise<{
+    status: number;
+    body: string;
+    headers: http.IncomingHttpHeaders;
+  }> {
     return new Promise((resolve, reject) => {
       const req = http.request(
-        { host: '127.0.0.1', port, path, headers: { host } },
+        {
+          host: '127.0.0.1',
+          port,
+          method: opts.method ?? 'GET',
+          path: opts.path,
+          headers: { host: opts.host, ...opts.headers },
+        },
         (res) => {
           let body = '';
           res.on('data', (chunk) => {
             body += chunk;
           });
-          res.on('end', () => resolve({ status: res.statusCode ?? 0, body }));
+          res.on('end', () =>
+            resolve({
+              status: res.statusCode ?? 0,
+              body,
+              headers: res.headers,
+            }),
+          );
         },
       );
       req.on('error', reject);
-      req.end();
+      req.end(opts.body);
     });
   }
 
+  function rawGet(
+    port: number,
+    path: string,
+    host: string,
+  ): Promise<{ status: number; body: string }> {
+    return rawRequest(port, { path, host });
+  }
+
   async function createSandbox(port: number): Promise<string> {
     const res = await fetch(`http://127.0.0.1:${port}/e2b/api/sandboxes`, {
       method: 'POST',
@@ -153,6 +185,64 @@ describe('sandbox port proxy', () => {
     expect(t.executor.stateOf(sandboxId)).toBe('running');
   });
 
+  it('carves /files on the envd port out of the proxy — browser-direct upload, end to end', async () => {
+    const t = await listeningApp();
+    const sandboxId = await createSandbox(t.port);
+    const host = `49983-${sandboxId}.${DOMAIN}`;
+
+    // The preflight reaches Fastify's open CORS answer, not a container dial.
+    const preflight = await rawRequest(t.port, {
+      method: 'OPTIONS',
+      path: '/files',
+      host,
+      headers: {
+        origin: 'https://app.example.test',
+        'access-control-request-method': 'POST',
+      },
+    });
+    expect(preflight.status).toBe(204);
+    expect(preflight.headers['access-control-allow-origin']).toBe('*');
+
+    // A signed multipart POST, exactly the URL + body shape a browser
+    // builds from the SDK's uploadUrl — no headers beyond content-type.
+    const token = mintEnvdToken(getOrCreateSigningSecret(t.db), sandboxId);
+    const path = '/home/user/probe/a.txt';
+    const exp = Math.floor(Date.now() / 1000) + 300;
+    const sig = `v1_${createHash('sha256')
+      .update([path, 'write', '', token, String(exp)].join(':'), 'utf8')
+      .digest('base64')
+      .replace(/=+$/, '')}`;
+    const boundary = 'proxy-carveout-boundary';
+    const body = [
+      `--${boundary}`,
+      `Content-Disposition: form-data; name="file"; filename="${path}"`,
+      'Content-Type: text/plain',
+      '',
+      'straight from the browser\n',
+      `--${boundary}--`,
+      '',
+    ].join('\r\n');
+    const up = await rawRequest(t.port, {
+      method: 'POST',
+      path: `/files?path=${encodeURIComponent(path)}&signature=${encodeURIComponent(sig)}&signature_expiration=${exp}`,
+      host,
+      headers: { 'content-type': `multipart/form-data; boundary=${boundary}` },
+      body,
+    });
+    expect(up.status).toBe(200);
+    expect(JSON.parse(up.body)).toEqual([
+      { name: 'a.txt', type: 'file', path },
+    ]);
+    expect(up.headers['access-control-allow-origin']).toBe('*');
+
+    // Only /files is carved out: any other path on the envd port still
+    // dials the container (the fake's echo upstream answers, proving the
+    // proxy handled it, not Fastify).
+    const other = await rawGet(t.port, '/health', host);
+    expect(other.status).toBe(200);
+    expect(JSON.parse(other.body)).toMatchObject({ sandboxId });
+  });
+
   it('passes WebSocket upgrades through, both directions', async () => {
     const t = await listeningApp();
     const sandboxId = await createSandbox(t.port);
diff --git a/packages/server/src/sandbox-proxy.ts b/packages/server/src/sandbox-proxy.ts
index 7529379..d610906 100644
--- a/packages/server/src/sandbox-proxy.ts
+++ b/packages/server/src/sandbox-proxy.ts
@@ -29,6 +29,25 @@ import { wakeSandbox } from './lifecycle';
  * reaches is only ever the sandbox's own ports.
  */
 
+/**
+ * envd's fixed port in E2B's URL grammar: `49983-<sandboxId>.<domain>`
+ * reaches the sandbox's envd, never a user process — it is how the SDK's
+ * uploadUrl/downloadUrl become browser-postable URLs. Dormice runs no envd
+ * inside the container (the daemon plays that role), so /files on this
+ * port is carved out of the proxy and lands on the daemon's signed-URL
+ * file door, with the Host label pinning which sandbox the signature must
+ * speak for. Every other path keeps the honest proxy answer: nothing
+ * listens on 49983 inside the sandbox.
+ */
+export const ENVD_PORT = 49983;
+
+/** Path-only match for the carve-out: exactly /files, query ignored. */
+function isEnvdFilesRequest(req: http.IncomingMessage): boolean {
+  const url = req.url ?? '';
+  const q = url.indexOf('?');
+  return (q === -1 ? url : url.slice(0, q)) === '/files';
+}
+
 /**
  * Host header -> { port, sandboxId }, or null when it is not sandbox
  * traffic (then the request belongs to Fastify). The port suffix of the
@@ -121,7 +140,12 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
 
   return {
     matches(req) {
-      return parseSandboxHost(req.headers.host, domain) !== null;
+      const parsed = parseSandboxHost(req.headers.host, domain);
+      if (!parsed) return false;
+      // The envd file face on its fixed port belongs to Fastify's signed
+      // door, not to a dial into the container (see ENVD_PORT).
+      if (parsed.port === ENVD_PORT && isEnvdFilesRequest(req)) return false;
+      return true;
     },
 
     handleRequest(req, res) {
diff --git a/website/content/docs/e2b-differences.mdx b/website/content/docs/e2b-differences.mdx
index 194b4f3..08bd813 100644
--- a/website/content/docs/e2b-differences.mdx
+++ b/website/content/docs/e2b-differences.mdx
@@ -23,7 +23,7 @@ daemon:
 | `commands.run` | live streaming (`onStdout` / `onStderr`), background + `connect` / `disconnect`, `sendStdin`, `kill`, `list`, per-command `envs`, `user: 'root'`; a non-zero exit raises the SDK's own `CommandExitError` |
 | `pty.*` | `create` / `sendInput` / `resize` / `kill` — a real interactive bash |
 | `files` read / write | text or bytes, streamed, no artificial size cap — the disk quota is the cap |
-| `uploadUrl()` / `downloadUrl()` | signed URLs: expiry enforced, a tampered signature is a 401 |
+| `uploadUrl()` / `downloadUrl()` | signed URLs: expiry enforced, a tampered signature is a 401; CORS-open, so a browser can POST/GET them directly — with `DORMICE_SANDBOX_DOMAIN` set, E2B's `49983-<sandboxId>.<domain>/files` form works too |
 | `files.list` / `exists` / `makeDir` / `rename` / `remove` | typed errors match the SDK's expectations |
 | `files.watchDir` | streamed events, and the polling watcher API the Python sync SDK uses |
 | `getHost(port)` | port proxy with wake-on-traffic (set `DORMICE_SANDBOX_DOMAIN`) |

From 8c381c1e315680c234649aa10ed1acccdcf25d10 Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Sun, 19 Jul 2026 18:54:49 -0700
Subject: [PATCH 117/133] Metadata firewall: the unit becomes the proven single
 rule-writer, and doctor certifies only what it verifies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

At boot the dormice-metadata-firewall oneshot races dockerd — which is
busy building its own chains at exactly that moment — for the xtables
lock. iptables without -w exits immediately when the lock is held, the
unit fails, and the host runs with the metadata service reachable from
every sandbox. Silently: the rules were present after install because
a separate inline loop had inserted them, so nothing looked wrong
until the first reboot. Every iptables call in the unit and in
install.sh now carries -w 10, a bounded wait instead of a lost race.

The inline pre-insert loop had to go for a second reason: it meant the
unit's -I path was never exercised. install.sh inserted the rules
itself and only then restarted the unit, so at install time the unit
always took the -C branch — the insert path that boot depends on ran
for the first time on a real host at the first reboot, unobserved.
That is precisely the "unproven promise" the restart existed to
prevent. With the loop deleted the unit is the only rule-writer: on a
fresh install the restart takes the -C||-I path with the rules
genuinely absent, on a re-run the -C path, and install.sh then asserts
each rule with iptables -C, dying with the target's name if the unit
ran but a rule is absent.

The endpoint list also lived in three places — the inline loop, two
hand-written ExecStart lines, doctor's constants — inviting drift.
install.sh now generates the ExecStart lines from one METADATA_TARGETS
list; the generated unit text is byte-identical across runs, so the
[skip] content comparison keeps working.

doctor's metadata-persisted check certified persistence on `systemctl
is-enabled` exiting 0 alone. Exit 0 also covers enabled-runtime,
static, alias and generated — states that do not start this unit at
the next boot. The unit path now passes only when the state is the
literal word "enabled", the unit file still drops both metadata
targets, and is-active says the last run succeeded; each failure mode
warns in its own words. Any state other than "enabled" falls through
to the legacy rules.v4 branch unchanged, so pre-unit hosts persisted
via iptables-persistent still pass. All three new tests were run
against the old check first and all three went red — each one catches
a real false-pass.

`systemctl enable >/dev/null 2>&1` became `systemctl -q enable`: the
old form swallowed the error text, and under set -e the script died
with no diagnostics at all.

Closes #8.
---
 .changeset/witty-badgers-guard.md |  5 +++
 deploy/install.sh                 | 50 ++++++++++++++++---------
 packages/cli/src/doctor.test.ts   | 62 +++++++++++++++++++++++++++++++
 packages/cli/src/doctor.ts        | 42 ++++++++++++++++++++-
 4 files changed, 139 insertions(+), 20 deletions(-)
 create mode 100644 .changeset/witty-badgers-guard.md

diff --git a/.changeset/witty-badgers-guard.md b/.changeset/witty-badgers-guard.md
new file mode 100644
index 0000000..4048f83
--- /dev/null
+++ b/.changeset/witty-badgers-guard.md
@@ -0,0 +1,5 @@
+---
+'@dormice/cli': patch
+---
+
+`dor doctor`'s firewall-persistence check now believes only what it can verify: `systemctl is-enabled` must say exactly `enabled` (exit 0 alone also covers `enabled-runtime`, `static`, `alias` and `generated`, none of which re-add the rules at the next boot), the `dormice-metadata-firewall` unit file must still drop both metadata targets, and the unit's last run must have succeeded — each failure mode gets its own warning naming what broke. Hosts persisted the pre-unit way via `iptables-persistent` still pass. Alongside, install.sh's unit now waits for the xtables lock (`iptables -w 10`), so losing the boot-time lock race against dockerd can no longer silently drop the metadata firewall.
diff --git a/deploy/install.sh b/deploy/install.sh
index d36d13d..d75aeef 100644
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -326,26 +326,26 @@ note 'verified: the sysctl boot order ends with our values for both keys'
 # curl to the metadata service steals live credentials. gVisor blocks kernel
 # attack surface, not network reachability — this must be firewalled.
 log 'cloud metadata firewall (DOCKER-USER chain)'
-docker_user=$(iptables -S DOCKER-USER 2>/dev/null) \
+iptables -w 10 -S DOCKER-USER >/dev/null 2>&1 \
   || die 'the DOCKER-USER chain is missing — is dockerd running?'
-added=''
-for target in 169.254.0.0/16 100.100.100.200; do
-  if ! printf '%s\n' "$docker_user" | grep -q -- "-d ${target%/*}\(/[0-9]*\)\? .*-j DROP"; then
-    iptables -I DOCKER-USER -d "$target" -j DROP
-    added="$added $target"
-  fi
-done
-if [ -n "$added" ]; then note "added DROP rules:$added"; else note '[skip] both DROP rules present'; fi
-# Persistence is our own oneshot unit that re-adds the rules after docker
-# creates the DOCKER-USER chain at boot (docker never flushes that chain
-# afterwards). Deliberately NOT iptables-persistent: installing it makes apt
+# One list, one writer: the oneshot unit below is the only mechanism that
+# inserts the rules — after docker creates the DOCKER-USER chain at boot
+# (docker never flushes that chain afterwards), and right here via the
+# restart. Deliberately NOT iptables-persistent: installing it makes apt
 # remove ufw (the packages conflict) — silently discarding an operator's
 # firewall — and `netfilter-persistent save` snapshots the whole ruleset,
 # operator rules and Docker's ephemeral NAT entries included, when exactly
 # two rules are ours to persist. Hosts persisted the old way keep their
 # /etc/iptables/rules.v4 untouched; the -C checks make duplicates impossible.
+# Every iptables call waits for the xtables lock (-w 10): at boot the unit
+# races dockerd for that lock, and without -w a lost race fails the unit
+# and silently leaves the metadata service reachable.
+METADATA_TARGETS='169.254.0.0/16 100.100.100.200'
 FIREWALL_UNIT=/etc/systemd/system/dormice-metadata-firewall.service
-firewall_unit=$(cat <<'EOF'
+firewall_exec=$(for target in $METADATA_TARGETS; do
+  printf "ExecStart=/bin/sh -c 'iptables -w 10 -C DOCKER-USER -d %s -j DROP 2>/dev/null || iptables -w 10 -I DOCKER-USER -d %s -j DROP'\n" "$target" "$target"
+done)
+firewall_unit=$(cat <<EOF
 # Written by Dormice install.sh — rewritten on every run. Sandboxes run
 # untrusted code; these rules keep them away from the cloud metadata service.
 [Unit]
@@ -357,8 +357,7 @@ Before=dormice.service
 [Service]
 Type=oneshot
 RemainAfterExit=yes
-ExecStart=/bin/sh -c 'iptables -C DOCKER-USER -d 169.254.0.0/16 -j DROP 2>/dev/null || iptables -I DOCKER-USER -d 169.254.0.0/16 -j DROP'
-ExecStart=/bin/sh -c 'iptables -C DOCKER-USER -d 100.100.100.200 -j DROP 2>/dev/null || iptables -I DOCKER-USER -d 100.100.100.200 -j DROP'
+$firewall_exec
 
 [Install]
 WantedBy=multi-user.target
@@ -371,10 +370,25 @@ else
   systemctl daemon-reload
   note "wrote $FIREWALL_UNIT (re-adds the rules after docker starts — survives reboot)"
 fi
-systemctl enable dormice-metadata-firewall >/dev/null 2>&1
-# Started now, not only at boot: a unit that has never run is an unproven
-# promise, and the start is a no-op when the rules are already in.
+systemctl -q enable dormice-metadata-firewall
+missing_before=''
+for target in $METADATA_TARGETS; do
+  iptables -w 10 -C DOCKER-USER -d "$target" -j DROP 2>/dev/null \
+    || missing_before="$missing_before $target"
+done
+# Restarted now, not only at boot: the unit is the only rule-writer, so this
+# restart IS the mechanism — a fresh install exercises the -C||-I insert
+# path (rules absent), a re-run the -C path, and -C keeps it idempotent.
 systemctl restart dormice-metadata-firewall
+for target in $METADATA_TARGETS; do
+  iptables -w 10 -C DOCKER-USER -d "$target" -j DROP 2>/dev/null \
+    || die "the unit ran but the rule for $target is absent — journalctl -u dormice-metadata-firewall has the story"
+done
+if [ -n "$missing_before" ]; then
+  note "the unit added DROP rules:$missing_before"
+else
+  note '[skip] both DROP rules were in place — the unit re-confirmed them'
+fi
 
 # ---- Dormice code -----------------------------------------------------------
 # Defined before the pull so the rollback in on_exit can always call it.
diff --git a/packages/cli/src/doctor.test.ts b/packages/cli/src/doctor.test.ts
index 865febc..7b20efc 100644
--- a/packages/cli/src/doctor.test.ts
+++ b/packages/cli/src/doctor.test.ts
@@ -26,6 +26,15 @@ const IPTABLES_GOOD = [
   '-A DOCKER-USER -j RETURN',
 ].join('\n');
 
+const FIREWALL_UNIT_PATH =
+  '/etc/systemd/system/dormice-metadata-firewall.service';
+const FIREWALL_UNIT_GOOD = [
+  '[Service]',
+  'Type=oneshot',
+  "ExecStart=/bin/sh -c 'iptables -w 10 -C DOCKER-USER -d 169.254.0.0/16 -j DROP 2>/dev/null || iptables -w 10 -I DOCKER-USER -d 169.254.0.0/16 -j DROP'",
+  "ExecStart=/bin/sh -c 'iptables -w 10 -C DOCKER-USER -d 100.100.100.200 -j DROP 2>/dev/null || iptables -w 10 -I DOCKER-USER -d 100.100.100.200 -j DROP'",
+].join('\n');
+
 const DF_ROOMY =
   'Filesystem 1024-blocks Used Available Capacity Mounted on\n' +
   '/dev/vda3 200000000 50000000 150000000 25% /';
@@ -63,6 +72,7 @@ function fakeHost(
     '/proc/sys/vm/swappiness': '100\n',
     '/proc/sys/net/ipv4/ip_forward': '1\n',
     '/etc/iptables/rules.v4': IPTABLES_GOOD,
+    [FIREWALL_UNIT_PATH]: FIREWALL_UNIT_GOOD,
     '/etc/caddy/Caddyfile':
       '# Managed by Dormice — setIngress rewrites this file.\n\n:80 {\n\treverse_proxy 127.0.0.1:3676\n}\n',
     ...overrides.files,
@@ -74,6 +84,7 @@ function fakeHost(
     ),
     'iptables -S DOCKER-USER': ok(IPTABLES_GOOD),
     'systemctl is-enabled dormice-metadata-firewall': ok('enabled\n'),
+    'systemctl is-active dormice-metadata-firewall': ok('active\n'),
     '/usr/lib/systemd/systemd-sysctl --cat-config': ok(CAT_CONFIG_GOOD),
     [`docker image inspect ${IMAGE}`]: ok('[{}]'),
     'df -Pk /var/lib/dormice': ok(DF_ROOMY),
@@ -276,6 +287,57 @@ describe('metadata firewall', () => {
       detail: expect.stringContaining('rules.v4'),
     });
   });
+
+  it("is-enabled exiting 0 with 'enabled-runtime' is not persistence", async () => {
+    // is-enabled exits 0 for enabled-runtime, static, alias and generated
+    // too — none of which start this unit at the next boot.
+    const { results, failed } = await runDoctor(
+      fakeHost({
+        files: { '/etc/iptables/rules.v4': undefined },
+        commands: {
+          'systemctl is-enabled dormice-metadata-firewall':
+            ok('enabled-runtime\n'),
+        },
+      }),
+    );
+    expect(results['metadata-persisted']).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('enabled-runtime'),
+      fix: expect.stringContaining('install.sh'),
+    });
+    expect(failed).toBe(false);
+  });
+
+  it('an enabled unit whose file lost a DROP target warns and names it', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        files: {
+          [FIREWALL_UNIT_PATH]:
+            "[Service]\nExecStart=/bin/sh -c 'iptables -w 10 -C DOCKER-USER -d 169.254.0.0/16 -j DROP 2>/dev/null || iptables -w 10 -I DOCKER-USER -d 169.254.0.0/16 -j DROP'",
+        },
+      }),
+    );
+    expect(results['metadata-persisted']).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('100.100.100.200'),
+      fix: expect.stringContaining('install.sh'),
+    });
+  });
+
+  it('an enabled unit whose last run failed warns — boot may come up bare', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        commands: {
+          'systemctl is-active dormice-metadata-firewall': boom('failed'),
+        },
+      }),
+    );
+    expect(results['metadata-persisted']).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('last run failed'),
+      fix: expect.stringContaining('install.sh'),
+    });
+  });
 });
 
 describe('sandbox networking (net.ipv4.ip_forward)', () => {
diff --git a/packages/cli/src/doctor.ts b/packages/cli/src/doctor.ts
index 3f82500..48b1d6c 100644
--- a/packages/cli/src/doctor.ts
+++ b/packages/cli/src/doctor.ts
@@ -110,6 +110,7 @@ const skip = (detail: string): CheckResult => ({ status: 'skip', detail });
 
 const DAEMON_JSON = '/etc/docker/daemon.json';
 const RULES_V4 = '/etc/iptables/rules.v4';
+const FIREWALL_UNIT = '/etc/systemd/system/dormice-metadata-firewall.service';
 const METADATA_IP = '100.100.100.200';
 const METADATA_RANGE = '169.254.0.0/16';
 const SYSCTL_FILE = '/etc/sysctl.d/99-dormice.conf';
@@ -393,11 +394,42 @@ const CHECKS: DoctorCheck[] = [
     title: 'firewall rules persisted',
     needs: ['metadata-firewall'],
     run: async (ctx) => {
-      const unit = await ctx.run('systemctl', [
+      const enabled = await ctx.run('systemctl', [
         'is-enabled',
         'dormice-metadata-firewall',
       ]);
-      if (unit.ok) {
+      // Exit 0 alone is not the fact we need: is-enabled also exits 0 for
+      // enabled-runtime, static, alias and generated — states that do not
+      // start this unit at the next boot. Only the word "enabled" does.
+      if (enabled.stdout.trim() === 'enabled') {
+        const unitText = await ctx.readTextFile(FIREWALL_UNIT);
+        const missingTargets = [METADATA_RANGE, METADATA_IP].filter(
+          (target) => !unitText?.includes(target),
+        );
+        if (unitText === undefined) {
+          return warn(
+            `the unit is enabled but ${FIREWALL_UNIT} is missing or unreadable — what it re-adds at boot cannot be verified`,
+            're-run install.sh (it rewrites the dormice-metadata-firewall systemd unit)',
+          );
+        }
+        if (missingTargets.length > 0) {
+          return warn(
+            `the unit is enabled but ${FIREWALL_UNIT} does not drop ${missingTargets.join(' or ')} — the next boot re-adds an incomplete firewall`,
+            're-run install.sh (it rewrites the dormice-metadata-firewall systemd unit)',
+          );
+        }
+        // A failed last run means the boot-time insert path is broken —
+        // the rules present now came from install time, not from the unit.
+        const active = await ctx.run('systemctl', [
+          'is-active',
+          'dormice-metadata-firewall',
+        ]);
+        if (!active.ok) {
+          return warn(
+            'the unit is enabled but its last run failed — the next boot may come up without the rules',
+            're-run install.sh (`journalctl -u dormice-metadata-firewall` has why the run failed)',
+          );
+        }
         return pass(
           'dormice-metadata-firewall.service re-adds the rules after docker starts',
         );
@@ -408,6 +440,12 @@ const CHECKS: DoctorCheck[] = [
       if (rules?.includes(METADATA_IP) && rules.includes('169.254')) {
         return pass(`both rules in ${RULES_V4} (iptables-persistent)`);
       }
+      if (enabled.ok) {
+        return warn(
+          `systemctl calls the unit "${enabled.stdout.trim()}", not "enabled" — that state does not re-add the rules at the next boot`,
+          're-run install.sh (it enables the dormice-metadata-firewall systemd unit)',
+        );
+      }
       return warn(
         'the DROP rules live only in memory — a reboot silently drops them',
         're-run install.sh (it writes the dormice-metadata-firewall systemd unit)',

From 30dbe630c103471576c8568d0ff07ca37566f82d Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Sun, 19 Jul 2026 18:58:40 -0700
Subject: [PATCH 118/133] sysctl verification learns the second replay order,
 and its two parsers now agree
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The boot-order check modeled only systemd-sysctl: a global sort across
the sysctl.d dirs, last setter wins. But the named hazard was procps
`sysctl --system`, and that tool has different semantics: it reads
/etc/sysctl.conf LAST, after every sysctl.d file, and reads it whether
or not the Debian 99-sysctl.conf symlink exists. Two escapes follow: a
host without the symlink passed the systemd-only check while carrying
an ip_forward=0 in /etc/sysctl.conf that the next replay would apply
over us; and a host where a later-sorting sysctl.d file won the
systemd order still loses the procps order to sysctl.conf. install.sh
and doctor now verify both orders: the systemd winner must be the
wanted value, and if /etc/sysctl.conf sets the key at all, its last
value must agree too. Judged by value, not file, in both orders — an
operator file that sets our value is agreement, not a conflict.

Running install.sh's awk and doctor's TS on identical input showed the
two hand-rolled parsers had drifted apart, each wrong its own way.
Both took any comment starting with "# /" for a --cat-config file
marker — and the stock /etc/sysctl.conf header ("# /etc/sysctl.conf -
Configuration file ...") is exactly such a comment, so a warning could
blame the header text instead of the real file. Only the awk knew the
"- key = value" ignore-error form; the TS missed that setter entirely.
The awk gsub-stripped ALL whitespace from values, mangling multi-value
keys like ping_group_range, and neither shed CRLF — a sysctl.conf
edited on Windows made install.sh die on a healthy host, and an empty
awk winner produced a garbled die instead of naming the parse failure.
There is now one parser semantics, mirrored in awk and TS with
kept-in-sync-by-hand comments both ways (the ingress Caddyfile
convention): a file marker is a comment that IS a path and nothing
else; keys shed all whitespace, a leading "-", and "/" separators;
values trim their edges, keep internal content, and shed CRLF.
install.sh defines the awk once, runs --cat-config once, and derives
the verify list from $sysctl_wanted instead of enumerating the pairs
three times.

doctor's binary probe now matches install.sh (/usr/lib then /lib), and
an unreadable boot config warns for ip_forward instead of silently
passing: dockerd re-enables forwarding at every start, so this is the
one key whose boot-config hazard the live value can never expose — a
pass on "could not check" claims exactly what was not checked.
swappiness keeps passing on its live value when the boot config is
unreadable, because nothing masks swappiness drift: a boot config
saying otherwise surfaces in the live value after the next reboot. It
does gain the same conflict warn when the boot config is readable and
disagrees — that drift is real, just not yet visible.

Closes #9.
---
 .changeset/lucid-geese-verify.md |   5 ++
 deploy/install.sh                |  63 ++++++++++----
 packages/cli/src/doctor.test.ts  | 142 +++++++++++++++++++++++++++++++
 packages/cli/src/doctor.ts       | 136 ++++++++++++++++++++++-------
 website/content/docs/doctor.mdx  |   6 +-
 5 files changed, 304 insertions(+), 48 deletions(-)
 create mode 100644 .changeset/lucid-geese-verify.md

diff --git a/.changeset/lucid-geese-verify.md b/.changeset/lucid-geese-verify.md
new file mode 100644
index 0000000..9ecb89c
--- /dev/null
+++ b/.changeset/lucid-geese-verify.md
@@ -0,0 +1,5 @@
+---
+'@dormice/cli': patch
+---
+
+`dor doctor`'s sysctl checks now verify both orders that can replay the boot config: systemd-sysctl's boot order, and procps `sysctl --system`, which applies `/etc/sysctl.conf` last — even without the 99-sysctl.conf symlink. The `--cat-config` parser no longer mistakes comments that merely start with `# /` for file markers (the stock sysctl.conf header is one, so a warning could blame a comment instead of the real file), recognizes the `- key = value` ignore-error form, tolerates CRLF line endings, and probes /lib/systemd like install.sh does; an unreadable boot config is a warn now, not a silent pass — that hazard is exactly the one the live value cannot expose. `vm.swappiness` gains the same boot-order coverage: 100 now with a boot config saying otherwise warns naming the file.
diff --git a/deploy/install.sh b/deploy/install.sh
index d75aeef..c83dfda 100644
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -285,11 +285,14 @@ fi
 # network. The file is named to sort after cloud-vendor sysctl.d files that
 # ship swappiness=0. Applied scoped — `sysctl --system` here would replay
 # every operator setting mid-install (an ip_forward=0 in /etc/sysctl.conf did
-# exactly that and killed the base-image build two steps later). Boot-order
-# effectiveness is verified against systemd-sysctl's own application order:
-# the winning value of each key must be the one we need. The value, not the
-# file — a host may legitimately set ip_forward=1 in its own later-sorting
-# config (the test host does), and that is agreement, not a conflict.
+# exactly that and killed the base-image build two steps later). Two replays
+# can overwrite these keys later, and both are verified: systemd-sysctl's
+# boot order (a global sort across the sysctl.d dirs, last setter wins), and
+# procps `sysctl --system`, which reads /etc/sysctl.conf LAST — even without
+# the 99-sysctl.conf symlink. In each order the winning value of every key
+# must be the one we need. The value, not the file — a host may legitimately
+# set ip_forward=1 in its own later-sorting config (the test host does), and
+# that is agreement, not a conflict.
 log 'kernel parameters (vm.swappiness = 100, net.ipv4.ip_forward = 1)'
 SYSCTL_FILE=/etc/sysctl.d/99-dormice.conf
 sysctl_wanted='# Managed by Dormice install.sh — rewritten on every run.
@@ -306,20 +309,48 @@ systemd_sysctl=/usr/lib/systemd/systemd-sysctl
 [ -x "$systemd_sysctl" ] || systemd_sysctl=/lib/systemd/systemd-sysctl
 [ -x "$systemd_sysctl" ] \
   || die 'cannot find systemd-sysctl to verify the sysctl boot order — non-systemd hosts are not supported'
-for kv in vm.swappiness=100 net.ipv4.ip_forward=1; do
-  key=${kv%%=*} want=${kv#*=}
-  winner=$("$systemd_sysctl" --cat-config | awk -v key="$key" '
-    /^# \//       { file = $2; next }
-    /^[ \t]*[#;]/ { next }
+# Last setter of `$1` in a sysctl config stream (stdin, or the file `$2`),
+# printed as
+# `file|value`. A file marker is a comment that IS a path and nothing else
+# (`# /path`) — `--cat-config` emits one before each file's lines; a comment
+# merely starting with `# /` (the stock sysctl.conf header is one) is
+# skipped like any other; `$2`, when given, is a marker-less file to read
+# and the name to report for it. Keys
+# tolerate the `- key` ignore-error form and `/` as the separator; values
+# keep internal whitespace and shed CRLF. Kept in sync by hand with
+# sysctlBootWinner in packages/cli/src/doctor.ts.
+sysctl_winner() {
+  awk -v key="$1" -v file="${2:-unknown}" '
+    /^# \// && NF == 2 { file = $2; next }
+    /^[ \t\r]*[#;]/    { next }
     {
       eq = index($0, "="); if (eq == 0) next
-      k = substr($0, 1, eq - 1); gsub(/[ \t]/, "", k); sub(/^-/, "", k); gsub("/", ".", k)
-      if (k == key) { v = substr($0, eq + 1); gsub(/[ \t]/, "", v); print file " " v }
-    }' | tail -n 1)
-  [ "${winner#* }" = "$want" ] \
-    || die "$key must be $want at boot, but the sysctl boot order ends with ${winner% *} setting it to ${winner#* } — change or remove that line, then re-run"
+      k = substr($0, 1, eq - 1); gsub(/[ \t\r]/, "", k); sub(/^-/, "", k); gsub("/", ".", k)
+      if (k != key) next
+      v = substr($0, eq + 1); sub(/^[ \t\r]+/, "", v); sub(/[ \t\r]+$/, "", v)
+      print file "|" v
+    }' ${2:+"$2"} | tail -n 1
+}
+cat_config=$("$systemd_sysctl" --cat-config)
+for kv in $(printf '%s\n' "$sysctl_wanted" | grep -v '^#'); do
+  key=${kv%%=*} want=${kv#*=}
+  winner=$(printf '%s\n' "$cat_config" | sysctl_winner "$key")
+  [ -n "$winner" ] \
+    || die "could not find $key anywhere in systemd-sysctl --cat-config output — expected at least $SYSCTL_FILE to appear; parse failure"
+  [ "${winner#*|}" = "$want" ] \
+    || die "$key must be $want at boot, but the sysctl boot order ends with ${winner%%|*} setting it to ${winner#*|} — change or remove that line, then re-run"
+  # procps `sysctl --system` (other installers run it) applies
+  # /etc/sysctl.conf after every sysctl.d file, symlink or not — a
+  # disagreeing value there overrides us at the very next replay even when
+  # the systemd boot order ends with ours.
+  if [ -f /etc/sysctl.conf ]; then
+    conf_value=$(sysctl_winner "$key" /etc/sysctl.conf)
+    conf_value=${conf_value#*|}
+    [ -z "$conf_value" ] || [ "$conf_value" = "$want" ] \
+      || die "$key must be $want, but /etc/sysctl.conf sets it to $conf_value — procps sysctl --system applies that file last, so the next config replay overrides us; change or remove that line, then re-run"
+  fi
 done
-note 'verified: the sysctl boot order ends with our values for both keys'
+note 'verified: both keys survive the sysctl boot order and a procps sysctl --system replay'
 
 # ---- cloud metadata firewall -------------------------------------------------
 # Sandboxes run untrusted code; on a cloud host with an attached role, one
diff --git a/packages/cli/src/doctor.test.ts b/packages/cli/src/doctor.test.ts
index 7b20efc..f7f7137 100644
--- a/packages/cli/src/doctor.test.ts
+++ b/packages/cli/src/doctor.test.ts
@@ -71,6 +71,11 @@ function fakeHost(
     '/proc/meminfo': 'MemTotal: 30000000 kB\nSwapTotal: 16777212 kB',
     '/proc/sys/vm/swappiness': '100\n',
     '/proc/sys/net/ipv4/ip_forward': '1\n',
+    // The stock Debian/Ubuntu file: a header comment that starts with
+    // `# /` but is not a file marker, and no keys. procps `sysctl
+    // --system` reads this file last; doctor checks it agrees.
+    '/etc/sysctl.conf':
+      '# /etc/sysctl.conf - Configuration file for setting system variables\n# See /etc/sysctl.d/ for additional settings\n',
     '/etc/iptables/rules.v4': IPTABLES_GOOD,
     [FIREWALL_UNIT_PATH]: FIREWALL_UNIT_GOOD,
     '/etc/caddy/Caddyfile':
@@ -212,6 +217,31 @@ describe('freezing prerequisites', () => {
       detail: expect.stringContaining('nowhere to push'),
     });
   });
+
+  it('effective 100 with a later boot file saying 0 warns and names the file', async () => {
+    // 100 right now, but a cloud vendor's file sorting after ours takes it
+    // back at the next reboot — the live value alone cannot see this yet.
+    const { results, failed } = await runDoctor(
+      fakeHost({
+        commands: {
+          '/usr/lib/systemd/systemd-sysctl --cat-config': ok(
+            [
+              '# /etc/sysctl.d/99-dormice.conf',
+              'vm.swappiness=100',
+              'net.ipv4.ip_forward=1',
+              '# /etc/sysctl.d/zz-cloud.conf',
+              'vm.swappiness = 0',
+            ].join('\n'),
+          ),
+        },
+      }),
+    );
+    expect(failed).toBe(false);
+    expect(results.swappiness).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('zz-cloud.conf sets 0 at boot'),
+    });
+  });
 });
 
 describe('docker configuration', () => {
@@ -392,6 +422,118 @@ describe('sandbox networking (net.ipv4.ip_forward)', () => {
       detail: expect.stringContaining('dockerd re-enables'),
     });
   });
+
+  it('a comment starting with "# /" is not a file marker — the warn names the real file', async () => {
+    // Stock /etc/sysctl.conf opens with `# /etc/sysctl.conf - Configuration
+    // file ...`, and --cat-config inlines it under the Debian 99-sysctl.conf
+    // symlink marker. A parser that takes any `# /` comment for a marker
+    // attributes the conflict to the comment text.
+    const { results } = await runDoctor(
+      fakeHost({
+        commands: {
+          '/usr/lib/systemd/systemd-sysctl --cat-config': ok(
+            [
+              '# /etc/sysctl.d/99-dormice.conf',
+              'vm.swappiness=100',
+              'net.ipv4.ip_forward=1',
+              '# /etc/sysctl.d/99-sysctl.conf',
+              '# /etc/sysctl.conf - Configuration file for setting system variables',
+              'net.ipv4.ip_forward = 0',
+            ].join('\n'),
+          ),
+        },
+      }),
+    );
+    expect(results['ip-forward']).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('/etc/sysctl.d/99-sysctl.conf sets 0'),
+    });
+  });
+
+  it('the "- key = value" ignore-error form is a setter like any other', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        commands: {
+          '/usr/lib/systemd/systemd-sysctl --cat-config': ok(
+            [
+              '# /etc/sysctl.d/99-dormice.conf',
+              'vm.swappiness=100',
+              'net.ipv4.ip_forward=1',
+              '# /etc/sysctl.d/zz-operator.conf',
+              '- net.ipv4.ip_forward = 0',
+            ].join('\n'),
+          ),
+        },
+      }),
+    );
+    expect(results['ip-forward']).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('zz-operator.conf sets 0'),
+    });
+  });
+
+  it('an /etc/sysctl.conf that disagrees warns — procps sysctl --system applies it last', async () => {
+    // The systemd boot order ends with our 1, but procps replays
+    // /etc/sysctl.conf after every sysctl.d file, symlink or not.
+    const { results, failed } = await runDoctor(
+      fakeHost({ files: { '/etc/sysctl.conf': 'net.ipv4.ip_forward = 0\n' } }),
+    );
+    expect(failed).toBe(false);
+    expect(results['ip-forward']).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('/etc/sysctl.conf sets 0'),
+    });
+    expect(results['ip-forward']?.detail).toContain('applies that file last');
+  });
+
+  it('an unverifiable boot config warns — the live value cannot expose this hazard', async () => {
+    // Both probe paths fail (the fake answers nothing for /lib either).
+    const { results, failed } = await runDoctor(
+      fakeHost({
+        commands: {
+          '/usr/lib/systemd/systemd-sysctl --cat-config': boom(
+            'No such file or directory',
+          ),
+        },
+      }),
+    );
+    expect(failed).toBe(false);
+    expect(results['ip-forward']).toMatchObject({
+      status: 'warn',
+      detail: expect.stringContaining('/lib/systemd/systemd-sysctl'),
+    });
+    // swappiness keeps passing on its live value: swappiness drift
+    // surfaces there after a reboot; ip_forward's never does.
+    expect(statusOf(results, 'swappiness')).toBe('pass');
+  });
+
+  it('falls back to /lib/systemd/systemd-sysctl when /usr/lib has no binary', async () => {
+    const { results } = await runDoctor(
+      fakeHost({
+        commands: {
+          '/usr/lib/systemd/systemd-sysctl --cat-config': boom(
+            'No such file or directory',
+          ),
+          '/lib/systemd/systemd-sysctl --cat-config': ok(CAT_CONFIG_GOOD),
+        },
+      }),
+    );
+    expect(results['ip-forward']).toMatchObject({
+      status: 'pass',
+      detail: expect.stringContaining(
+        'persisted by /etc/sysctl.d/99-dormice.conf',
+      ),
+    });
+  });
+
+  it('a CRLF config line agreeing with us is agreement, not a conflict', async () => {
+    // An /etc/sysctl.conf written on Windows: the naive read of the value
+    // is "1\r", which is not "1".
+    const { results } = await runDoctor(
+      fakeHost({ files: { '/etc/sysctl.conf': 'net.ipv4.ip_forward=1\r\n' } }),
+    );
+    expect(results['ip-forward']).toMatchObject({ status: 'pass' });
+  });
 });
 
 describe('daemon configuration', () => {
diff --git a/packages/cli/src/doctor.ts b/packages/cli/src/doctor.ts
index 48b1d6c..294e845 100644
--- a/packages/cli/src/doctor.ts
+++ b/packages/cli/src/doctor.ts
@@ -114,34 +114,89 @@ const FIREWALL_UNIT = '/etc/systemd/system/dormice-metadata-firewall.service';
 const METADATA_IP = '100.100.100.200';
 const METADATA_RANGE = '169.254.0.0/16';
 const SYSCTL_FILE = '/etc/sysctl.d/99-dormice.conf';
-// Not on PATH; /lib is merged into /usr/lib on every supported target.
-const SYSTEMD_SYSCTL = '/usr/lib/systemd/systemd-sysctl';
+// Not on PATH; same probe as install.sh — /usr/lib first, then /lib for
+// hosts without a merged /usr.
+const SYSTEMD_SYSCTL_PATHS = [
+  '/usr/lib/systemd/systemd-sysctl',
+  '/lib/systemd/systemd-sysctl',
+];
 
 /**
- * The file whose value for `key` wins at boot, parsed from
- * `systemd-sysctl --cat-config` — the authoritative application order,
- * with `# /path` lines marking each file. Last setter wins.
+ * The file whose value for `key` wins when `content` is replayed in
+ * order — last setter wins. `systemd-sysctl --cat-config` opens each file
+ * with a `# /path` marker: a comment that IS a path and nothing else; a
+ * comment merely starting with `# /` (the stock sysctl.conf header is one)
+ * is skipped like any other. Plain /etc/sysctl.conf content carries no
+ * markers, so callers name it via `initialFile`. Kept in sync by hand with
+ * the awk program in deploy/install.sh.
  */
 function sysctlBootWinner(
-  catConfig: string,
+  content: string,
   key: string,
+  initialFile = 'unknown',
 ): { file: string; value: string } | undefined {
-  let file = 'unknown';
+  let file = initialFile;
   let winner: { file: string; value: string } | undefined;
-  for (const line of catConfig.split('\n')) {
-    if (line.startsWith('# /')) {
-      file = line.slice(2).trim();
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    if (/^# \/\S+$/.test(line)) {
+      file = line.slice(2);
       continue;
     }
     if (/^\s*[#;]/.test(line)) continue;
     const eq = line.indexOf('=');
     if (eq < 0) continue;
-    const k = line.slice(0, eq).trim().replace(/^-/, '').replaceAll('/', '.');
+    const k = line
+      .slice(0, eq)
+      .replace(/\s+/g, '')
+      .replace(/^-/, '')
+      .replaceAll('/', '.');
     if (k === key) winner = { file, value: line.slice(eq + 1).trim() };
   }
   return winner;
 }
 
+/**
+ * Two replays can overwrite a sysctl after install.sh sets it:
+ * systemd-sysctl at boot (a global sort across the sysctl.d dirs), and
+ * procps `sysctl --system`, which reads /etc/sysctl.conf LAST — even
+ * without the Debian 99-sysctl.conf symlink. Both must end with the wanted
+ * value. Judged by value, not file: an operator file that sets the same
+ * value is agreement, not a conflict.
+ */
+async function sysctlReplayVerdict(
+  ctx: DoctorContext,
+  key: string,
+  want: string,
+): Promise<
+  | { kind: 'unreadable' }
+  | { kind: 'conflict'; file: string; value: string; order: 'boot' | 'procps' }
+  | { kind: 'agrees'; file?: string }
+> {
+  let catConfig: string | undefined;
+  for (const path of SYSTEMD_SYSCTL_PATHS) {
+    const res = await ctx.run(path, ['--cat-config']);
+    if (res.ok) {
+      catConfig = res.stdout;
+      break;
+    }
+  }
+  if (catConfig === undefined) return { kind: 'unreadable' };
+  const boot = sysctlBootWinner(catConfig, key);
+  if (boot !== undefined && boot.value !== want) {
+    return { kind: 'conflict', ...boot, order: 'boot' };
+  }
+  const conf = await ctx.readTextFile('/etc/sysctl.conf');
+  const last =
+    conf === undefined
+      ? undefined
+      : sysctlBootWinner(conf, key, '/etc/sysctl.conf');
+  if (last !== undefined && last.value !== want) {
+    return { kind: 'conflict', ...last, order: 'procps' };
+  }
+  return { kind: 'agrees', file: boot?.file };
+}
+
 async function daemonJson(
   ctx: DoctorContext,
 ): Promise<Record<string, unknown> | undefined> {
@@ -308,18 +363,31 @@ const CHECKS: DoctorCheck[] = [
     title: 'vm.swappiness = 100',
     needs: ['os-linux'],
     run: async (ctx) => {
-      // The live value, on purpose: some clouds ship swappiness=0 in their
-      // own sysctl.d file, so a config file existing proves nothing.
+      // The live value first, on purpose: some clouds ship swappiness=0 in
+      // their own sysctl.d file, so a config file existing proves nothing.
       const raw = await ctx.readTextFile('/proc/sys/vm/swappiness');
       const value = raw?.trim();
       if (value === undefined)
         return fail('cannot read /proc/sys/vm/swappiness');
-      return value === '100'
-        ? pass('100 (effective value)')
-        : fail(
-            `effective value is ${value} — below 100 the kernel refuses to swap gVisor's shmem-held sandbox memory (measured at 60: 0 bytes reclaimed)`,
-            `re-run install.sh — it persists 100 in ${SYSCTL_FILE}, applies it scoped, and verifies nothing later in the sysctl boot order overrides it`,
-          );
+      if (value !== '100') {
+        return fail(
+          `effective value is ${value} — below 100 the kernel refuses to swap gVisor's shmem-held sandbox memory (measured at 60: 0 bytes reclaimed)`,
+          `re-run install.sh — it persists 100 in ${SYSCTL_FILE}, applies it scoped, and verifies nothing later in the sysctl boot order overrides it`,
+        );
+      }
+      const verdict = await sysctlReplayVerdict(ctx, 'vm.swappiness', '100');
+      if (verdict.kind === 'conflict') {
+        return warn(
+          verdict.order === 'boot'
+            ? `100 now, but ${verdict.file} sets ${verdict.value} at boot — after the next reboot, freezing reclaims nothing`
+            : `100 now, but ${verdict.file} sets ${verdict.value} — procps sysctl --system applies that file last, so the next config replay drops it and freezing reclaims nothing`,
+          `drop vm.swappiness from ${verdict.file}, or re-run install.sh and let it verify the boot order`,
+        );
+      }
+      // An unreadable boot config still passes here, unlike ip_forward:
+      // nothing masks swappiness drift — a boot config saying otherwise
+      // surfaces in this live value after the next reboot.
+      return pass('100 (effective value)');
     },
   },
   {
@@ -342,23 +410,31 @@ const CHECKS: DoctorCheck[] = [
       // other installer's `sysctl --system`) re-applies it and cuts sandbox
       // networking until dockerd restarts. Unlike swappiness, whose drift
       // surfaces in the effective value after a reboot, this one can stay
-      // masked forever — so this check alone also reads the boot config, in
-      // systemd-sysctl's own application order.
-      const res = await ctx.run(SYSTEMD_SYSCTL, ['--cat-config']);
-      if (!res.ok) {
-        return pass('1 (effective value; boot config unreadable here)');
+      // masked forever — so this check alone reads the boot config in both
+      // orders that can replay it, and an unreadable boot config is a
+      // warn, not a pass: the live value cannot expose this hazard.
+      const verdict = await sysctlReplayVerdict(
+        ctx,
+        'net.ipv4.ip_forward',
+        '1',
+      );
+      if (verdict.kind === 'unreadable') {
+        return warn(
+          `1 now, but the boot config cannot be verified — systemd-sysctl --cat-config failed at both ${SYSTEMD_SYSCTL_PATHS.join(' and ')}; a boot config saying 0 stays masked by dockerd until the next sysctl replay cuts every sandbox's networking`,
+        );
       }
-      const winner = sysctlBootWinner(res.stdout, 'net.ipv4.ip_forward');
-      if (winner !== undefined && winner.value !== '1') {
+      if (verdict.kind === 'conflict') {
         return warn(
-          `1 now, but ${winner.file} sets ${winner.value} at boot — the next sysctl config replay cuts every sandbox's networking`,
-          `drop net.ipv4.ip_forward from ${winner.file}, or re-run install.sh and let it verify the boot order`,
+          verdict.order === 'boot'
+            ? `1 now, but ${verdict.file} sets ${verdict.value} at boot — the next sysctl config replay cuts every sandbox's networking`
+            : `1 now, but ${verdict.file} sets ${verdict.value} — procps sysctl --system applies that file last, so the next config replay cuts every sandbox's networking`,
+          `drop net.ipv4.ip_forward from ${verdict.file}, or re-run install.sh and let it verify the boot order`,
         );
       }
       return pass(
-        winner === undefined
+        verdict.file === undefined
           ? '1 (effective value; no boot config sets it — dockerd re-enables it at every start)'
-          : `1 (effective value, persisted by ${winner.file})`,
+          : `1 (effective value, persisted by ${verdict.file})`,
       );
     },
   },
diff --git a/website/content/docs/doctor.mdx b/website/content/docs/doctor.mdx
index 49a1991..e69f092 100644
--- a/website/content/docs/doctor.mdx
+++ b/website/content/docs/doctor.mdx
@@ -67,8 +67,10 @@ know why; the Linux terms in it are covered in
   check where the live value can lie: dockerd re-enables forwarding at
   every daemon start, masking a boot config that says 0 until the next
   sysctl config replay switches it back off — so it also reads the
-  boot config, in systemd-sysctl's own application order, and *warns*
-  naming the file that would turn it off.
+  boot config, in both orders that can replay it (systemd-sysctl's
+  boot order, and procps `sysctl --system`, which applies
+  `/etc/sysctl.conf` last), and *warns* naming the file that would
+  turn it off.
 - **cloud metadata firewall** — `DROP` rules in the `DOCKER-USER` chain
   for `169.254.0.0/16` and `100.100.100.200`; without them a sandbox
   can steal cloud credentials from the metadata service.

From 8fd008e57241f3cad6d6e5ef5a1d0d18f93e55ff Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Sun, 19 Jul 2026 18:51:28 -0700
Subject: [PATCH 119/133] The doctor docs page gains its missing ingress
 (Caddy) bullet
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The page promises "The list below explains what each check is
protecting" and then explained every check but one — so the gap was a
broken promise, a defect, not a style choice. The new bullet sits in
Configuration between zstd and base image, mirroring the check's
position in doctor.ts, and states only what the source does: skipped
without DORMICE_INGRESS_FILE, failing on a missing caddy binary or an
inactive caddy service, warning on a config file that does not exist
yet or that the daemon did not write. No total check count is stated
anywhere, same as before.

Closes #10
---
 website/content/docs/doctor.mdx | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/website/content/docs/doctor.mdx b/website/content/docs/doctor.mdx
index e69f092..3a226b3 100644
--- a/website/content/docs/doctor.mdx
+++ b/website/content/docs/doctor.mdx
@@ -90,6 +90,15 @@ know why; the Linux terms in it are covered in
   a half-configured archiver anyway).
 - **zstd available** — the archiver shells out to `tar -I zstd` on the
   host at every archive and restore.
+- **ingress (Caddy)** — skipped when `DORMICE_INGRESS_FILE` is not
+  set: the daemon manages no reverse proxy, and you bind domains by
+  editing your proxy config directly. Set, the `caddy` binary must be
+  installed and the caddy service active — a missing binary means
+  `setIngress` cannot reload anything, and an inactive service means
+  nothing proxies the outside world to the daemon. A config file that
+  doesn't exist yet is a *warn* (the first bind creates it), and so is
+  one the daemon did not write: `setIngress` refuses to overwrite it,
+  so web domain binding is effectively off.
 - **base image available** — present locally; the fix names
   `images/Dockerfile`, and doctor never pulls.
 - **docker-mode paths absolute** — a relative `DORMICE_DB_PATH` depends

From f6df4315ec349b4e39567a8c153636f99b893fdc Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Mon, 20 Jul 2026 10:32:29 +0800
Subject: [PATCH 120/133] =?UTF-8?q?=E4=B8=8B=E8=BD=BD=E9=9D=A2=E5=AD=A6?=
 =?UTF-8?q?=E4=BC=9A=20Range=20=E5=88=86=E6=AE=B5:=E8=A7=86=E9=A2=91?=
 =?UTF-8?q?=E6=92=AD=E6=94=BE=E4=B8=8E=E6=96=AD=E7=82=B9=E7=BB=AD=E4=BC=A0?=
 =?UTF-8?q?=E7=9A=84=E7=94=9F=E6=AD=BB=E7=BA=BF=E8=A1=A5=E4=B8=8A=E3=80=82?=
 =?UTF-8?q?=E6=97=A7=E8=A3=81=E5=86=B3(2026-07-18)=E6=98=AF"Range=20?=
 =?UTF-8?q?=E6=9C=AA=E5=AE=9E=E7=8E=B0=E6=95=85=E5=88=BB=E6=84=8F=E4=B8=8D?=
 =?UTF-8?q?=E5=8F=91=20accept-ranges,=E4=B8=8D=E8=99=9A=E6=8A=A5"=E2=80=94?=
 =?UTF-8?q?=E2=80=94=E8=AF=9A=E5=AE=9E=E4=BD=86=E6=8A=8A=E8=A7=86=E9=A2=91?=
 =?UTF-8?q?=E5=88=A4=E4=BA=86=E6=AD=BB=E5=88=91:mp4=20=E7=9A=84=20moov=20?=
 =?UTF-8?q?=E5=85=83=E6=95=B0=E6=8D=AE=E5=B8=B8=E5=9C=A8=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E5=B0=BE,=E6=92=AD=E6=94=BE=E5=99=A8=E7=9A=84=E7=AC=AC?=
 =?UTF-8?q?=E4=B8=80=E5=8A=A8=E4=BD=9C=E5=B0=B1=E6=98=AF=20Range=20?=
 =?UTF-8?q?=E5=8F=96=E5=B0=BE,=E6=8B=BF=E4=B8=8D=E5=88=B0=20206=20?=
 =?UTF-8?q?=E5=8F=AA=E8=83=BD=E5=85=A8=E9=87=8F=E4=B8=8B=E5=AE=8C=E6=89=8D?=
 =?UTF-8?q?=E5=87=BA=E7=AC=AC=E4=B8=80=E5=B8=A7;Safari=20=E5=85=88?=
 =?UTF-8?q?=E5=8F=91=20bytes=3D0-1=20=E6=8E=A2=E6=B5=8B,=E4=B8=8D=E8=A7=81?=
 =?UTF-8?q?=20206=20=E7=9B=B4=E6=8E=A5=E6=8B=92=E6=92=AD;=E6=8B=96?=
 =?UTF-8?q?=E8=BF=9B=E5=BA=A6=E6=9D=A1=3D=E4=BB=8E=E5=A4=B4=E9=87=8D?=
 =?UTF-8?q?=E4=B8=8B=E3=80=82=E8=BF=99=E6=AD=A3=E6=98=AF"=E7=9C=9F=20E2B?=
 =?UTF-8?q?=20=E4=B8=80=E7=82=B9=E4=B8=80=E7=82=B9=E5=8A=A0=E8=BD=BD?=
 =?UTF-8?q?=E3=80=81=E6=88=91=E4=BB=AC=E4=B8=80=E6=AC=A1=E5=85=A8=E9=87=8F?=
 =?UTF-8?q?=E5=8A=A0=E8=BD=BD"=E7=9A=84=E5=85=A8=E9=83=A8=E5=8E=9F?=
 =?UTF-8?q?=E5=9B=A0=E2=80=94=E2=80=94=E4=BC=A0=E8=BE=93=E9=93=BE=E6=9C=AC?=
 =?UTF-8?q?=E8=BA=AB=E6=97=A9=E5=B0=B1=E6=98=AF=E7=9C=9F=E6=B5=81=E5=BC=8F?=
 =?UTF-8?q?(cat=E2=86=92CallbackSink=E2=86=92raw=20=E5=9B=9E=E5=8E=8B?=
 =?UTF-8?q?=E5=85=A8=E7=A8=8B=E6=97=A0=E7=A7=AF=E6=94=92),=E6=85=A2?=
 =?UTF-8?q?=E7=9A=84=E4=B8=8D=E6=98=AF=E6=94=92=E6=98=AF=E7=BC=BA=20206?=
 =?UTF-8?q?=E3=80=82=E8=AF=AD=E4=B9=89=E4=B8=80=E5=88=80=E5=88=87=E5=9C=A8?=
 =?UTF-8?q?=20RFC=209110=20=E7=9A=84=E5=8E=9F=E6=95=99=E6=97=A8=E4=B8=8A:?=
 =?UTF-8?q?=E5=8F=AA=E8=AE=A4=E5=8D=95=E6=AE=B5=20bytes=3Da-b/a-/-n=20?=
 =?UTF-8?q?=E5=9B=9E=20206+content-range,=E5=A4=9A=E6=AE=B5/=E5=BC=82?=
 =?UTF-8?q?=E5=8D=95=E4=BD=8D/=E7=95=B8=E5=BD=A2=E6=8C=89"Range=20?=
 =?UTF-8?q?=E6=98=AF=E8=AF=B7=E6=B1=82=E4=BF=AE=E9=A5=B0=E8=AF=8D"?=
 =?UTF-8?q?=E5=90=88=E6=B3=95=E5=BF=BD=E7=95=A5=E5=9B=9E=E5=85=A8=E9=87=8F?=
 =?UTF-8?q?=20200(200=20=E6=81=92=E4=B8=BA=E6=AD=A3=E7=A1=AE=E7=AD=94?=
 =?UTF-8?q?=E6=A1=88,=E7=BB=9D=E4=B8=8D=E7=8C=9C);=E5=94=AF=E4=B8=80?=
 =?UTF-8?q?=E7=A1=AC=E6=8B=92=3D=E8=B5=B7=E7=82=B9=E8=B6=8A=E8=BF=87=20EOF?=
 =?UTF-8?q?=20=E2=86=92=20416+content-range:=20bytes=20*/size(=E5=AF=B9?=
 =?UTF-8?q?=E5=AE=83=E5=9B=9E=E5=85=A8=E9=87=8F=E4=BC=9A=E8=AE=A9=E6=9C=B4?=
 =?UTF-8?q?=E7=B4=A0=E7=BB=AD=E4=BC=A0=E5=99=A8=E6=AD=BB=E5=BE=AA=E7=8E=AF?=
 =?UTF-8?q?);=E5=B0=BE=E6=BA=A2=E5=87=BA=E7=9A=84=20end=20=E6=8C=89?=
 =?UTF-8?q?=E8=A7=84=E7=9F=A9=E9=92=B3=E5=88=B0=20EOF=E3=80=82=E8=A3=81?=
 =?UTF-8?q?=E5=86=B3=E7=82=B9=E5=8D=95=E4=B8=80:files.ts=20parseRangeHeade?=
 =?UTF-8?q?r=20=E5=AF=B9=E7=9D=80=20stat=20=E5=87=BA=E7=9A=84=E5=B0=BA?=
 =?UTF-8?q?=E5=AF=B8=E8=A7=A3=E6=9E=90,=E7=AD=BE=E5=90=8D=20URL=20?=
 =?UTF-8?q?=E9=97=A8=E4=B8=8E=20envd=20=E9=97=A8=E5=85=B1=E7=94=A8?=
 =?UTF-8?q?=E5=90=8C=E4=B8=80=E4=BB=BD=20serveFileDownload=20=E4=B8=80?=
 =?UTF-8?q?=E5=B9=B6=E5=8F=97=E7=9B=8A;=E6=89=A7=E8=A1=8C=E5=99=A8=20readF?=
 =?UTF-8?q?ileStream=20=E5=8A=A0=E5=8F=AF=E9=80=89=20{offset,length}=20?=
 =?UTF-8?q?=E5=AD=97=E8=8A=82=E5=8C=BA=E9=97=B4=E2=80=94=E2=80=94docker=20?=
 =?UTF-8?q?=E5=AE=B9=E5=99=A8=E5=86=85=E7=94=A8=20dd=20iflag=3Dskip=5Fbyte?=
 =?UTF-8?q?s,count=5Fbytes=20=E5=88=87(=E7=85=A7=E6=A0=B7=E6=B5=81?=
 =?UTF-8?q?=E5=BC=8F=E7=85=A7=E6=A0=B7=E5=9B=9E=E5=8E=8B;tail|head=20?=
 =?UTF-8?q?=E6=96=B9=E6=A1=88=E4=BC=9A=E6=92=9E=20SIGPIPE=20=E7=AB=9E?=
 =?UTF-8?q?=E6=80=81,=E5=88=BB=E6=84=8F=E4=B8=8D=E7=94=A8),fake=20subarray?=
 =?UTF-8?q?=20=E4=B8=80=E5=88=80=E3=80=82=E5=AE=9E=E7=8E=B0=E4=BA=86?=
 =?UTF-8?q?=E6=89=8D=E5=AE=A3=E5=91=8A:200=20=E4=B8=8E=20206=20=E9=BD=90?=
 =?UTF-8?q?=E5=8F=91=20accept-ranges:=20bytes,=E6=B3=A8=E9=87=8A=E9=87=8C"?=
 =?UTF-8?q?=E5=AE=A3=E5=91=8A=E4=B8=8D=E5=85=91=E7=8E=B0=E6=98=AF=E6=92=92?=
 =?UTF-8?q?=E8=B0=8E"=E7=9A=84=E9=A1=BE=E8=99=91=E5=B0=B1=E5=9C=B0?=
 =?UTF-8?q?=E8=A7=A3=E9=99=A4;hijack=20=E8=A3=B8=E5=86=99=E5=A4=B4?=
 =?UTF-8?q?=E5=8D=95=E7=8B=AC=E9=87=8D=E7=94=B3=20CORS=20=E5=85=A8?=
 =?UTF-8?q?=E5=A5=97,allowCorsOrigin=20=E9=9A=8F=E4=B9=8B=E8=A1=A5=20acces?=
 =?UTF-8?q?s-control-expose-headers:=20accept-ranges,=20content-range,=20c?=
 =?UTF-8?q?ontent-disposition(=E6=B5=8F=E8=A7=88=E5=99=A8=20JS=20=E8=B6=8A?=
 =?UTF-8?q?=E8=BF=87=E5=AE=89=E5=85=A8=E6=B8=85=E5=8D=95=E6=89=8D=E8=AF=BB?=
 =?UTF-8?q?=E5=BE=97=E5=88=B0=E8=BF=99=E4=BB=A8)=E3=80=82=E5=9B=9E?=
 =?UTF-8?q?=E5=BD=92=E9=92=89=E4=B8=89=E5=B1=82:=E5=90=88=E5=90=8C?=
 =?UTF-8?q?=E9=A2=98=E4=B8=80=E6=9E=9A(=E5=A4=B4/=E5=B0=BE/=E6=9C=AB?=
 =?UTF-8?q?=E5=AD=97=E8=8A=82/=E5=86=85=E9=83=A8=E5=9B=9B=E5=88=80?=
 =?UTF-8?q?=E5=AD=97=E8=8A=82=E7=B2=BE=E7=A1=AE,fake=20=E5=8D=B3=E5=88=BB?=
 =?UTF-8?q?=E8=80=83=E3=80=81docker=20=E7=95=99=E7=9C=9F=E6=9C=BA=E8=A1=A5?=
 =?UTF-8?q?=E8=80=83)=E3=80=81envd=20=E9=9D=A2=E5=85=AD=E6=80=81(200=20?=
 =?UTF-8?q?=E5=B8=A6=E5=AE=A3=E5=91=8A/=E5=86=85=E9=83=A8=E6=AE=B5/?=
 =?UTF-8?q?=E5=B0=BE=E7=BC=80=20moov=20=E5=BD=A2/=E5=BC=80=E5=8C=BA?=
 =?UTF-8?q?=E9=97=B4/end=20=E9=92=B3=E5=88=B6/416=20=E4=B8=8E=E5=A4=9A?=
 =?UTF-8?q?=E6=AE=B5=E5=BF=BD=E7=95=A5)=E3=80=81=E4=BB=A3=E7=90=86?=
 =?UTF-8?q?=E8=B1=81=E5=8F=A3=E7=AB=AF=E5=88=B0=E7=AB=AF=E4=B8=80=E5=8F=91?=
 =?UTF-8?q?(49983=20=E5=AD=90=E5=9F=9F=E7=AD=BE=E5=90=8D=20GET=20=E5=B8=A6?=
 =?UTF-8?q?=20Range=20=E5=9B=9E=20206+content-range+ACAO,=E6=AD=A3?=
 =?UTF-8?q?=E6=98=AF=20<video>=20=E6=B6=88=E8=B4=B9=20downloadUrl=20?=
 =?UTF-8?q?=E7=9A=84=E5=A7=BF=E5=8A=BF)=E3=80=82=E5=85=A8=E9=93=BE=20build?=
 =?UTF-8?q?/typecheck/lint=20=E5=B9=B2=E5=87=80,server=20511=E3=80=81sdk?=
 =?UTF-8?q?=2031=E3=80=81cli=2049=E3=80=81e2e=2084=20=E5=85=A8=E7=BB=BF;?=
 =?UTF-8?q?=E7=9C=9F=E6=9C=BA=E9=AA=8C=E6=94=B6(dd=20=E5=9C=A8=20gVisor=20?=
 =?UTF-8?q?=E5=AE=B9=E5=99=A8=E5=86=85=E5=88=87=E7=9C=9F=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?+=E6=B5=8F=E8=A7=88=E5=99=A8=E7=9C=9F=20mp4=20=E6=8B=96?=
 =?UTF-8?q?=E6=92=AD)=E7=95=99=E7=BB=99=E9=83=A8=E7=BD=B2=E5=90=8E?=
 =?UTF-8?q?=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/server/src/e2b/compat.test.ts        | 65 +++++++++++++++++
 packages/server/src/e2b/cors.ts               | 10 +++
 packages/server/src/e2b/envd/files.ts         | 71 +++++++++++++++++--
 .../server/src/executor/contract/files.ts     | 31 ++++++++
 .../server/src/executor/docker-scripts.ts     | 12 ++++
 packages/server/src/executor/docker.ts        |  6 +-
 packages/server/src/executor/executor.ts      | 12 ++++
 packages/server/src/executor/fake.ts          | 11 ++-
 packages/server/src/sandbox-proxy.test.ts     | 17 +++++
 website/content/docs/e2b-differences.mdx      |  1 +
 10 files changed, 227 insertions(+), 9 deletions(-)

diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 18f0cdb..8359011 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -798,6 +798,71 @@ describe('E2B envd surface', () => {
     expect(missing.json().code).toBe('not_found');
   });
 
+  it('honors single byte ranges on the download face — video playback lives here', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const content = '0123456789abcdefghij';
+    const up = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/files?path=range.txt&username=user',
+      headers: {
+        ...envdHeaders(t, sandboxID),
+        'content-type': 'application/octet-stream',
+      },
+      payload: content,
+    });
+    expect(up.statusCode).toBe(200);
+    const get = (range?: string) =>
+      t.app.inject({
+        method: 'GET',
+        url: '/e2b/envd/files?path=range.txt&username=user',
+        headers: { ...envdHeaders(t, sandboxID), ...(range ? { range } : {}) },
+      });
+
+    // The plain 200 now advertises ranges — the player's cue to even try.
+    const full = await get();
+    expect(full.statusCode).toBe(200);
+    expect(full.headers['accept-ranges']).toBe('bytes');
+    expect(full.headers['access-control-expose-headers']).toContain(
+      'content-range',
+    );
+
+    const slice = await get('bytes=2-5');
+    expect(slice.statusCode).toBe(206);
+    expect(slice.body).toBe('2345');
+    expect(slice.headers['content-range']).toBe('bytes 2-5/20');
+    expect(slice.headers['content-length']).toBe('4');
+
+    // The suffix form — an mp4 player's tail-of-file moov probe.
+    const tail = await get('bytes=-4');
+    expect(tail.statusCode).toBe(206);
+    expect(tail.body).toBe('ghij');
+    expect(tail.headers['content-range']).toBe('bytes 16-19/20');
+
+    // Open-ended — every seek is bytes=N-.
+    const open = await get('bytes=15-');
+    expect(open.statusCode).toBe(206);
+    expect(open.body).toBe('fghij');
+
+    // An end past EOF clamps (RFC's rule; players lean on it)…
+    const clamped = await get('bytes=18-9999');
+    expect(clamped.statusCode).toBe(206);
+    expect(clamped.body).toBe('ij');
+    expect(clamped.headers['content-range']).toBe('bytes 18-19/20');
+
+    // …but a START past EOF is the one hard refusal, naming the real size
+    // so a resuming client can recover instead of looping.
+    const past = await get('bytes=20-');
+    expect(past.statusCode).toBe(416);
+    expect(past.headers['content-range']).toBe('bytes */20');
+    expect(past.json().code).toBe('invalid_argument');
+
+    // Multi-range (and any other spec we don't speak) is lawfully ignored.
+    const multi = await get('bytes=0-1,4-5');
+    expect(multi.statusCode).toBe(200);
+    expect(multi.body).toBe(content);
+  });
+
   it('accepts octet-stream uploads with the path in the query', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t);
diff --git a/packages/server/src/e2b/cors.ts b/packages/server/src/e2b/cors.ts
index a86cf4a..806b1ab 100644
--- a/packages/server/src/e2b/cors.ts
+++ b/packages/server/src/e2b/cors.ts
@@ -15,8 +15,18 @@ import type { FastifyReply, FastifyRequest } from 'fastify';
  */
 export function allowCorsOrigin(reply: FastifyReply): void {
   reply.header('access-control-allow-origin', '*');
+  reply.header('access-control-expose-headers', EXPOSED_FILE_HEADERS);
 }
 
+/**
+ * Response headers browser JS may read beyond the CORS safelist:
+ * content-range/accept-ranges carry the Range contract (a JS video player
+ * or resuming downloader is blind without them), content-disposition
+ * carries the filename. The hijacked download head re-states this list.
+ */
+export const EXPOSED_FILE_HEADERS =
+  'accept-ranges, content-range, content-disposition';
+
 /**
  * The preflight answer, real E2B's shape (204 + methods + a 2h cache).
  * Unconditional by necessity: browsers send preflights credential-less,
diff --git a/packages/server/src/e2b/envd/files.ts b/packages/server/src/e2b/envd/files.ts
index 3c7571e..0a075d7 100644
--- a/packages/server/src/e2b/envd/files.ts
+++ b/packages/server/src/e2b/envd/files.ts
@@ -9,7 +9,7 @@ import {
   NotAFileError,
   type SandboxEntry,
 } from '../../executor/executor';
-import { sendPreflight } from '../cors';
+import { EXPOSED_FILE_HEADERS, sendPreflight } from '../cors';
 import { E2bError } from '../protocol';
 import {
   type EnvdContext,
@@ -106,12 +106,48 @@ function rfc5987(name: string): string {
   );
 }
 
+type ParsedRange =
+  | { kind: 'full' }
+  | { kind: 'unsatisfiable' }
+  | { kind: 'slice'; offset: number; end: number; length: number };
+
+/**
+ * One byte-range spec against a known size — what a video player actually
+ * sends (an mp4's tail-of-file moov probe, a seek, Safari's opening
+ * `bytes=0-1`). Multi-range, foreign units, and malformed specs are
+ * lawfully ignored (RFC 9110 §14.2: Range is a request *modifier*) — the
+ * full 200 is always a correct answer, so nothing here ever guesses.
+ * A spec that names only bytes past EOF is the one hard refusal: 416,
+ * because serving the full file for it would loop a naive resumer forever.
+ */
+function parseRangeHeader(
+  header: string | string[] | undefined,
+  size: number,
+): ParsedRange {
+  const raw = Array.isArray(header) ? header[0] : header;
+  if (!raw) return { kind: 'full' };
+  const match = /^bytes=(\d*)-(\d*)$/.exec(raw.trim());
+  if (!match || (match[1] === '' && match[2] === '')) return { kind: 'full' };
+  if (match[1] === '') {
+    // Suffix form: the last N bytes — the moov-atom fetch.
+    const n = Number(match[2]);
+    if (n === 0 || size === 0) return { kind: 'unsatisfiable' };
+    const offset = Math.max(0, size - n);
+    return { kind: 'slice', offset, end: size - 1, length: size - offset };
+  }
+  const offset = Number(match[1]);
+  if (offset >= size) return { kind: 'unsatisfiable' };
+  const end = match[2] === '' ? size - 1 : Math.min(Number(match[2]), size - 1);
+  if (end < offset) return { kind: 'full' };
+  return { kind: 'slice', offset, end, length: end - offset + 1 };
+}
+
 export async function serveFileDownload(
   ctx: EnvdContext,
   sandboxId: string,
   request: FastifyRequest,
   reply: FastifyReply,
-): Promise<void> {
+): Promise<unknown> {
   const { db, executor } = ctx;
   const query = request.query as { path?: string; username?: string };
   if (!query.path) {
@@ -138,20 +174,42 @@ export async function serveFileDownload(
       }
       throw error;
     }
+    const size = entry.sizeBytes;
+    const range = parseRangeHeader(request.headers.range, size);
+    if (range.kind === 'unsatisfiable') {
+      // Pre-hijack, so this rides the normal reply (the surface's CORS
+      // hook already stamped it); content-range names the real size —
+      // that is how a ranging client recovers.
+      return reply
+        .code(416)
+        .header('accept-ranges', 'bytes')
+        .header('content-range', `bytes */${size}`)
+        .send({
+          code: 'invalid_argument',
+          message: `range not satisfiable for a ${size}-byte file`,
+        });
+    }
+    const slice = range.kind === 'slice' ? range : undefined;
     // Size first, then stream: the SDK needs content-length (an empty
     // file is detected by `content-length: 0`), and nothing buffers here.
     reply.hijack();
-    // No accept-ranges here although real envd sends it: Range requests
-    // are not honored, and advertising bytes we won't serve is a lie.
-    reply.raw.writeHead(200, {
+    reply.raw.writeHead(slice ? 206 : 200, {
       'content-type': contentTypeOf(entry.name),
       'content-disposition': `inline; filename*=utf-8''${rfc5987(entry.name)}`,
-      'content-length': String(entry.sizeBytes),
+      'content-length': String(slice ? slice.length : size),
       'last-modified': new Date(entry.modifiedTime).toUTCString(),
+      // Real envd's promise, now kept: ranges are honored (video playback
+      // and download resume are impossible without them), so advertising
+      // them is the truth.
+      'accept-ranges': 'bytes',
+      ...(slice
+        ? { 'content-range': `bytes ${slice.offset}-${slice.end}/${size}` }
+        : {}),
       // The hijacked head bypasses reply.header(), so the CORS promise
       // (cors.ts: every file-face response is browser-readable) is
       // re-stated here.
       'access-control-allow-origin': '*',
+      'access-control-expose-headers': EXPOSED_FILE_HEADERS,
     });
     await executor.readFileStream(
       row.id,
@@ -166,6 +224,7 @@ export async function serveFileDownload(
         }
       },
       user,
+      slice ? { offset: slice.offset, length: slice.length } : undefined,
     );
     reply.raw.end();
   } catch (error) {
diff --git a/packages/server/src/executor/contract/files.ts b/packages/server/src/executor/contract/files.ts
index a64d955..d57c777 100644
--- a/packages/server/src/executor/contract/files.ts
+++ b/packages/server/src/executor/contract/files.ts
@@ -246,6 +246,37 @@ export function fileTests(ctx: ContractContext) {
       timeoutMs * 4,
     );
 
+    it(
+      'a byte range slices the stream exactly — offset and length, byte math',
+      async () => {
+        // The HTTP Range request's muscle: a video player's tail-of-file
+        // moov probe and a seek are both "give me exactly these bytes".
+        const id = await ctx.fresh();
+        const content = Buffer.from('0123456789abcdefghij');
+        await ctx.executor.writeFiles(id, [
+          { path: '/home/user/range.bin', content },
+        ]);
+        const read = async (offset: number, length: number) => {
+          const chunks: Buffer[] = [];
+          await ctx.executor.readFileStream(
+            id,
+            '/home/user/range.bin',
+            (c) => {
+              chunks.push(Buffer.from(c));
+            },
+            undefined,
+            { offset, length },
+          );
+          return Buffer.concat(chunks).toString('utf8');
+        };
+        expect(await read(0, 5)).toBe('01234'); // head
+        expect(await read(10, 10)).toBe('abcdefghij'); // tail, to EOF exactly
+        expect(await read(19, 1)).toBe('j'); // the last byte alone
+        expect(await read(7, 6)).toBe('789abc'); // an interior seek
+      },
+      timeoutMs,
+    );
+
     it(
       'streaming file verbs throw the same typed errors as the buffered ones',
       async () => {
diff --git a/packages/server/src/executor/docker-scripts.ts b/packages/server/src/executor/docker-scripts.ts
index da1c4e7..66fa63d 100644
--- a/packages/server/src/executor/docker-scripts.ts
+++ b/packages/server/src/executor/docker-scripts.ts
@@ -66,6 +66,18 @@ export const READ_FILE_STREAM_SCRIPT = [
   'exec cat -- "$1"',
 ].join('\n');
 
+/**
+ * $1 = absolute path, $2 = byte offset, $3 = byte count — the Range slice.
+ * dd is the one tool that takes both bounds in bytes and streams (bs-sized
+ * blocks, no buffering); a tail|head pipeline would work but dies by
+ * SIGPIPE races. GNU-only flags, like the find/stat scripts above.
+ */
+export const READ_FILE_RANGE_SCRIPT = [
+  `[ -e "$1" ] || exit ${NO_SUCH_FILE_EXIT}`,
+  `[ -f "$1" ] || exit ${NOT_A_FILE_EXIT}`,
+  'exec dd if="$1" iflag=skip_bytes,count_bytes skip="$2" count="$3" bs=65536 status=none',
+].join('\n');
+
 /**
  * $1 = absolute dir, $2 = depth. One NUL-terminated record per entry, tab
  * separated with the path last, so a path containing tabs still parses
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 8b31cfc..14f09c4 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -35,6 +35,7 @@ import {
   NOT_A_FILE_EXIT,
   PTY_WRAPPER,
   parseInotifyLine,
+  READ_FILE_RANGE_SCRIPT,
   READ_FILE_SCRIPT,
   READ_FILE_STREAM_SCRIPT,
   REMOVE_SCRIPT,
@@ -47,6 +48,7 @@ import {
 } from './docker-scripts';
 import { CallbackSink, CappedBuffer } from './docker-streams';
 import {
+  type ByteRange,
   type ContainerState,
   DiskFullError,
   type DiskUsage,
@@ -821,6 +823,7 @@ export class DockerExecutor implements Executor {
     path: string,
     onChunk: (chunk: Buffer) => void | Promise<void>,
     user?: string,
+    range?: ByteRange,
   ): Promise<void> {
     const resolved = resolveSandboxPath(path);
     const containerId = await this.expectState(sandboxId, 'running');
@@ -833,9 +836,10 @@ export class DockerExecutor implements Executor {
         String(STREAM_FILE_OP_TIMEOUT_SECONDS),
         'bash',
         '-c',
-        READ_FILE_STREAM_SCRIPT,
+        range ? READ_FILE_RANGE_SCRIPT : READ_FILE_STREAM_SCRIPT,
         'bash',
         resolved,
+        ...(range ? [String(range.offset), String(range.length)] : []),
       ],
       stdout: new CallbackSink(onChunk),
       stderr,
diff --git a/packages/server/src/executor/executor.ts b/packages/server/src/executor/executor.ts
index cdbc989..696564c 100644
--- a/packages/server/src/executor/executor.ts
+++ b/packages/server/src/executor/executor.ts
@@ -127,6 +127,12 @@ export interface FileToWrite {
   content: Buffer;
 }
 
+/** A byte span of a file, both bounds resolved and in-range by the caller. */
+export interface ByteRange {
+  offset: number;
+  length: number;
+}
+
 /**
  * One filesystem change under a watched directory — fsnotify's vocabulary,
  * because that is what the E2B wire speaks. A move fires 'rename' on the
@@ -416,12 +422,18 @@ export interface Executor {
    * shape's own rule and does not reach here). A returned promise from the
    * callback is awaited before the next chunk: backpressure travels through
    * to the in-container reader. Errors as readFile, minus the size gate.
+   *
+   * `range` slices the stream to exact bytes — the HTTP Range request's
+   * muscle (a video player fetching the mp4's tail-of-file metadata, a
+   * seek). The caller resolves the span against the file's stat'd size
+   * first; the executor just delivers offset..offset+length.
    */
   readFileStream(
     sandboxId: string,
     path: string,
     onChunk: (chunk: Buffer) => void | Promise<void>,
     user?: string,
+    range?: ByteRange,
   ): Promise<void>;
   /**
    * Streams content into one file, uncapped, parents created, overwriting —
diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index ceee8f9..1ba6f3d 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -7,6 +7,7 @@ import {
   resolveSandboxPath,
 } from '@dormice/shared';
 import {
+  type ByteRange,
   type ContainerState,
   type DiskUsage,
   type ExecOptions,
@@ -729,11 +730,17 @@ export class FakeExecutor implements Executor {
     sandboxId: string,
     path: string,
     onChunk: (chunk: Buffer) => void | Promise<void>,
+    _user?: string,
+    range?: ByteRange,
   ): Promise<void> {
     // The uncapped path: no size gate, one chunk (the fake has no reason to
-    // slice; chunking is the real pipe's business, not the contract's).
+    // slice into chunks; chunking is the real pipe's business, not the
+    // contract's). The range IS the contract: exact bytes or nothing.
     const node = this.fileNode(sandboxId, resolveSandboxPath(path));
-    await onChunk(Buffer.from(node.content));
+    const body = range
+      ? node.content.subarray(range.offset, range.offset + range.length)
+      : node.content;
+    await onChunk(Buffer.from(body));
   }
 
   async writeFileStream(
diff --git a/packages/server/src/sandbox-proxy.test.ts b/packages/server/src/sandbox-proxy.test.ts
index b5e48f8..9013730 100644
--- a/packages/server/src/sandbox-proxy.test.ts
+++ b/packages/server/src/sandbox-proxy.test.ts
@@ -235,6 +235,23 @@ describe('sandbox port proxy', () => {
     ]);
     expect(up.headers['access-control-allow-origin']).toBe('*');
 
+    // A ranged read through the same door — how a <video> tag actually
+    // consumes a signed downloadUrl: Range in, 206 + content-range out.
+    const readSig = `v1_${createHash('sha256')
+      .update([path, 'read', '', token, String(exp)].join(':'), 'utf8')
+      .digest('base64')
+      .replace(/=+$/, '')}`;
+    const ranged = await rawRequest(t.port, {
+      path: `/files?path=${encodeURIComponent(path)}&signature=${encodeURIComponent(readSig)}&signature_expiration=${exp}`,
+      host,
+      headers: { range: 'bytes=0-7' },
+    });
+    expect(ranged.status).toBe(206);
+    expect(ranged.body).toBe('straight');
+    expect(ranged.headers['content-range']).toBe('bytes 0-7/26');
+    expect(ranged.headers['accept-ranges']).toBe('bytes');
+    expect(ranged.headers['access-control-allow-origin']).toBe('*');
+
     // Only /files is carved out: any other path on the envd port still
     // dials the container (the fake's echo upstream answers, proving the
     // proxy handled it, not Fastify).
diff --git a/website/content/docs/e2b-differences.mdx b/website/content/docs/e2b-differences.mdx
index 08bd813..b3a08e0 100644
--- a/website/content/docs/e2b-differences.mdx
+++ b/website/content/docs/e2b-differences.mdx
@@ -24,6 +24,7 @@ daemon:
 | `pty.*` | `create` / `sendInput` / `resize` / `kill` — a real interactive bash |
 | `files` read / write | text or bytes, streamed, no artificial size cap — the disk quota is the cap |
 | `uploadUrl()` / `downloadUrl()` | signed URLs: expiry enforced, a tampered signature is a 401; CORS-open, so a browser can POST/GET them directly — with `DORMICE_SANDBOX_DOMAIN` set, E2B's `49983-<sandboxId>.<domain>/files` form works too |
+| Range requests on downloads | single-range `Range: bytes=…` gets a `206` with `content-range`; downloads advertise `accept-ranges: bytes` — so `<video>` streams and seeks instead of downloading the whole file, and interrupted downloads resume |
 | `files.list` / `exists` / `makeDir` / `rename` / `remove` | typed errors match the SDK's expectations |
 | `files.watchDir` | streamed events, and the polling watcher API the Python sync SDK uses |
 | `getHost(port)` | port proxy with wake-on-traffic (set `DORMICE_SANDBOX_DOMAIN`) |

From 2c0ad0f2ef424fd4fb570eada5017b8682875c68 Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Tue, 21 Jul 2026 20:13:36 +0800
Subject: [PATCH 121/133] =?UTF-8?q?=E5=AE=BF=E4=B8=BB=E6=9C=BA=E9=95=BF?=
 =?UTF-8?q?=E5=87=BA=E8=87=AA=E5=B7=B1=E7=9A=84=E5=8E=86=E5=8F=B2:CPU=20?=
 =?UTF-8?q?=E5=B3=B0=E5=80=BC=E4=BB=8E"=E6=B2=A1=E4=BA=BA=E8=AE=B0"?=
 =?UTF-8?q?=E5=8F=98=E6=88=90=E6=9C=89=E6=AD=A3=E9=97=A8=E5=8F=AF=E6=9F=A5?=
 =?UTF-8?q?=E3=80=82=E6=97=A7=E8=A3=81=E5=86=B3(2026-07-15)=E6=8E=A8?=
 =?UTF-8?q?=E7=BF=BB"=E4=B8=8D=E5=AD=98=E5=8E=86=E5=8F=B2"=E6=97=B6?=
 =?UTF-8?q?=E7=95=99=E4=BA=86=E4=B8=AA=E5=B0=BE=E5=B7=B4=E2=80=94=E2=80=94?=
 =?UTF-8?q?"=E5=AE=BF=E4=B8=BB=E7=BA=A7=E8=B6=8B=E5=8A=BF=E4=BB=8D?=
 =?UTF-8?q?=E5=BD=92=20Prometheus",=E6=9C=AC=E6=AC=A1(2026-07-21)=E6=8A=8A?=
 =?UTF-8?q?=E8=BF=99=E6=9C=80=E5=90=8E=E6=AE=8B=E7=95=99=E4=B8=80=E5=B9=B6?=
 =?UTF-8?q?=E6=8E=A8=E7=BF=BB:=E5=8D=95=E6=9C=BA=E8=87=AA=E6=89=98?=
 =?UTF-8?q?=E7=AE=A1=E6=B2=A1=E4=BA=BA=E6=9E=B6=20Prometheus,"=E5=BD=92=20?=
 =?UTF-8?q?Prometheus"=E5=AE=9E=E9=99=85=E7=AD=89=E4=BA=8E"=E6=B2=A1?=
 =?UTF-8?q?=E4=BA=BA=E7=AE=A1";=E8=80=8C=E6=8B=8D=E6=9D=BF=E8=BF=87?=
 =?UTF-8?q?=E7=9A=84=E7=A3=81=E7=9B=98=E8=B6=85=E5=8D=96=E7=AD=96=E7=95=A5?=
 =?UTF-8?q?=E6=AD=A3=E6=98=AF"=E4=B8=8A=E9=99=90=E7=89=A9=E7=90=86?=
 =?UTF-8?q?=E3=80=81=E8=B6=85=E5=8D=96=E9=9D=A0=E8=A7=82=E5=AF=9F"?=
 =?UTF-8?q?=E2=80=94=E2=80=94=E6=B2=A1=E6=9C=89=E5=8E=86=E5=8F=B2=E5=B0=B1?=
 =?UTF-8?q?=E6=B2=A1=E6=9C=89=E5=B3=B0=E5=80=BC,"=E8=BF=99=E5=8F=B0=2064G?=
 =?UTF-8?q?=20=E8=BF=98=E8=83=BD=E5=A1=9E=E5=A4=9A=E5=B0=91=E6=B2=99?=
 =?UTF-8?q?=E7=AE=B1"=E7=AD=94=E4=B8=8D=E4=BA=86;=E9=87=87=E6=A0=B7?=
 =?UTF-8?q?=E5=99=A8=E5=B7=B2=E5=9C=A8=E8=B7=91,=E5=A2=9E=E9=87=8F?=
 =?UTF-8?q?=E5=8F=AA=E6=98=AF=E6=AF=8F=20tick=20=E5=A4=9A=E4=B8=80?=
 =?UTF-8?q?=E8=A1=8C=E3=80=82=E8=90=BD=E6=B3=95:=E7=AC=AC=E4=B8=89?=
 =?UTF-8?q?=E5=BC=A0=E8=A1=A8=20host=5Fmetrics=5Fsamples(=E6=AF=8F=20tick?=
 =?UTF-8?q?=20=E4=B8=80=E8=A1=8C,=E6=81=92=E4=BF=9D=2030=20=E5=A4=A9?=
 =?UTF-8?q?=E4=B8=8E=20fleet=5Fsnapshots=20=E5=90=8C=E7=AA=97=E2=80=94?=
 =?UTF-8?q?=E2=80=94=E4=BB=AA=E8=A1=A8=E7=9B=98=E6=9C=80=E5=AE=BD=E6=A1=A3?=
 =?UTF-8?q?=E4=BD=8D=E5=AE=9A=E4=B9=89=E9=9C=80=E6=B1=82;=E4=B8=8D?=
 =?UTF-8?q?=E5=B9=B6=E5=85=A5=20fleet=20=E8=A1=A8:=E6=84=8F=E4=B9=89?=
 =?UTF-8?q?=E5=8D=95=E4=BD=8D=E4=B8=8D=E5=90=8C,=E7=8A=B6=E6=80=81?=
 =?UTF-8?q?=E8=AE=A1=E6=95=B0=20vs=20=E8=B5=84=E6=BA=90=E8=AF=BB=E6=95=B0)?=
 =?UTF-8?q?,=E8=AF=BB=E4=B8=8D=E5=88=B0=E7=9A=84=E8=AF=9A=E5=AE=9E=20null?=
 =?UTF-8?q?=20=E7=BB=9D=E4=B8=8D=E7=BC=96=E9=9B=B6(daemon=20=E5=88=9A?=
 =?UTF-8?q?=E5=90=AF=E5=8A=A8=E9=82=A3=20tick=20=E6=97=A0=20CPU=20?=
 =?UTF-8?q?=E5=B7=AE=E5=80=BC=E3=80=81Mac=20=E6=97=A0=20swap=E3=80=81?=
 =?UTF-8?q?=E6=95=B0=E6=8D=AE=E7=9B=AE=E5=BD=95=E6=9C=AA=E7=94=9F=E6=97=A0?=
 =?UTF-8?q?=E7=9B=98),=E4=B8=8E=E9=80=90=E6=B2=99=E7=AE=B1=E6=A0=B7?=
 =?UTF-8?q?=E6=9C=AC/=E8=88=B0=E9=98=9F=E5=BF=AB=E7=85=A7=E5=90=8C?=
 =?UTF-8?q?=E4=B8=80=E4=B8=AA=E5=90=8C=E6=AD=A5=E4=BA=8B=E5=8A=A1=E5=86=99?=
 =?UTF-8?q?=E5=85=A5=E3=80=81prune=20=E5=90=8C=E5=88=80=E3=80=82=E4=B8=80?=
 =?UTF-8?q?=E4=B8=AA=E7=BB=93=E6=9E=84=E6=80=A7=E5=9D=91=E5=BD=93=E5=9C=BA?=
 =?UTF-8?q?=E9=98=B2=E6=8E=89:CPU=20=E7=94=A8=E7=8E=87=3D=E4=B8=A4?=
 =?UTF-8?q?=E6=AC=A1=E9=87=87=E6=A0=B7=E5=8F=96=E5=B7=AE=E5=80=BC,?=
 =?UTF-8?q?=E5=B7=AE=E5=80=BC=E7=AA=97=E5=8F=A3=E6=98=AF"=E8=B7=9D?=
 =?UTF-8?q?=E8=AF=A5=E5=AE=9E=E4=BE=8B=E4=B8=8A=E6=AC=A1=E9=87=87=E6=A0=B7?=
 =?UTF-8?q?"=E2=80=94=E2=80=94ticker=20=E5=BF=85=E9=A1=BB=E7=8B=AC?=
 =?UTF-8?q?=E5=8D=A0=E8=87=AA=E5=B7=B1=E7=9A=84=20CpuSampler=20=E5=AE=9E?=
 =?UTF-8?q?=E4=BE=8B(main.ts=20=E5=BB=BA+=E9=A2=84=E7=83=AD),=E4=B8=8E=20g?=
 =?UTF-8?q?etHostMetrics=20=E8=B7=AF=E7=94=B1=E5=85=B1=E7=94=A8=E4=BC=9A?=
 =?UTF-8?q?=E8=A2=AB=20console=20=E6=AF=8F=205s=20=E7=9A=84=E8=BD=AE?=
 =?UTF-8?q?=E8=AF=A2=E5=81=B7=E8=B5=B0=E7=AA=97=E5=8F=A3,30s=20=E8=90=BD?=
 =?UTF-8?q?=E5=BA=93=E8=AF=BB=E6=95=B0=E5=85=A8=E6=88=90=E5=99=AA=E5=A3=B0?=
 =?UTF-8?q?=E3=80=82=E6=9F=A5=E8=AF=A2=E9=9D=A2:=E6=96=B0=E5=8A=A8?=
 =?UTF-8?q?=E8=AF=8D=20getHostMetricsHistory(start=3F,end=3F)=20=E7=BC=BA?=
 =?UTF-8?q?=E7=9C=81=E7=AA=97=2024h=20=E5=AF=B9=E9=BD=90=E8=88=B0=E9=98=9F?=
 =?UTF-8?q?=E6=97=B6=E9=97=B4=E7=BA=BF,=E8=B6=85=20360=20=E7=82=B9?=
 =?UTF-8?q?=E5=88=86=E6=A1=B6,=E6=A1=B6=E8=81=9A=E5=90=88=3D=E9=80=90?=
 =?UTF-8?q?=E5=AD=97=E6=AE=B5=E5=90=84=E5=8F=96=E8=87=AA=E5=B7=B1=E7=9A=84?=
 =?UTF-8?q?=E6=9C=80=E5=9D=8F=E6=83=85=E5=86=B5=E2=80=94=E2=80=94=E7=94=A8?=
 =?UTF-8?q?=E9=87=8F=20max=20=E4=BD=86=20available=20=E5=8F=96=20MIN:?=
 =?UTF-8?q?=E5=86=85=E5=AD=98=E5=8E=8B=E5=8A=9B=E7=9A=84=E5=B0=96=E5=B3=B0?=
 =?UTF-8?q?=E6=98=AF=20MemAvailable=20=E7=9A=84=E4=BD=8E=E7=82=B9,?=
 =?UTF-8?q?=E9=80=90=E5=AD=97=E6=AE=B5=20max=20=E4=BC=9A=E6=81=B0=E5=A5=BD?=
 =?UTF-8?q?=E6=8A=B9=E6=8E=89=E8=AF=BB=E8=80=85=E6=9D=A5=E6=89=BE=E7=9A=84?=
 =?UTF-8?q?=E4=B8=9C=E8=A5=BF(=E4=B8=8E=E9=80=90=E6=B2=99=E7=AE=B1"?=
 =?UTF-8?q?=E9=80=90=E5=AD=97=E6=AE=B5=20max"=E5=90=8C=E4=B8=80=E5=8A=A8?=
 =?UTF-8?q?=E6=9C=BA=E3=80=81=E4=B8=8D=E5=90=8C=E7=AC=A6=E5=8F=B7);peak=3D?=
 =?UTF-8?q?{cpuUsedPct,at}=20=E4=BB=8E=E5=8E=9F=E5=A7=8B=E8=A1=8C=E7=AE=97?=
 =?UTF-8?q?=E4=B8=8E=E5=88=86=E6=A1=B6=E8=A7=A3=E8=80=A6,null-CPU=20?=
 =?UTF-8?q?=E8=A1=8C=E4=B8=8D=E5=8F=82=E8=B5=9B,=E7=A9=BA=E7=AA=97?=
 =?UTF-8?q?=E8=AF=9A=E5=AE=9E=20null=E3=80=82SDK=20=E5=90=8C=E5=90=8D?=
 =?UTF-8?q?=E6=96=B9=E6=B3=95;console=20=E5=AE=BF=E4=B8=BB=E5=81=A5?=
 =?UTF-8?q?=E5=BA=B7=E7=AB=96=E5=8D=A1=E5=8D=B3=E6=97=B6=E5=80=BC(5s)?=
 =?UTF-8?q?=E7=AD=94"=E7=8E=B0=E5=9C=A8"=E3=80=81=E8=A1=8C=E5=86=85=20spar?=
 =?UTF-8?q?kline+CPU=20=E8=A1=8C=E7=9A=84=E7=AA=97=E5=8F=A3=E5=B3=B0?=
 =?UTF-8?q?=E5=80=BC=E6=B3=A8=E8=84=9A(30s=20=E8=BD=AE=E8=AF=A2,=E8=B7=9F?=
 =?UTF-8?q?=E9=9A=8F=E9=A1=B5=E5=A4=B4=201h~30d=20=E5=85=A8=E5=B1=80?=
 =?UTF-8?q?=E6=A1=A3=E4=BD=8D)=E7=AD=94"=E8=BF=99=E7=AA=97=E5=8F=A3?=
 =?UTF-8?q?=E5=8F=91=E7=94=9F=E8=BF=87=E4=BB=80=E4=B9=88",=E5=8E=86?=
 =?UTF-8?q?=E5=8F=B2=E8=AF=B7=E6=B1=82=E5=A4=B1=E8=B4=A5=E5=8F=AA=E7=BC=BA?=
 =?UTF-8?q?=E8=B5=B0=E5=8A=BF=E4=B8=8D=E6=8B=96=E5=9E=AE=E5=8D=B3=E6=97=B6?=
 =?UTF-8?q?=E8=AF=BB=E6=95=B0=E3=80=82=E5=9B=9E=E5=BD=92=E9=92=89=E4=B8=89?=
 =?UTF-8?q?=E5=B1=82:=E9=87=87=E6=A0=B7=E5=99=A8=E5=8D=95=E5=85=83(?=
 =?UTF-8?q?=E5=AE=BF=E4=B8=BB=E8=A1=8C=E5=90=8C=20tick=20=E8=90=BD?=
 =?UTF-8?q?=E5=BA=93+30=20=E5=A4=A9=E5=90=8C=E7=AA=97=E5=89=AA=E9=99=A4)?=
 =?UTF-8?q?=E3=80=81=E8=B7=AF=E7=94=B1=E4=BA=94=E6=80=81(=E7=A9=BA?=
 =?UTF-8?q?=E7=AA=97/=E5=9D=8F=E6=97=B6=E9=97=B4=E6=88=B3=20400/=E5=8D=87?=
 =?UTF-8?q?=E5=BA=8F=E5=88=87=E7=89=87=E5=90=AB=E8=AF=9A=E5=AE=9E=20null/?=
 =?UTF-8?q?=E5=88=86=E6=A1=B6=E6=9C=80=E5=9D=8F=E6=83=85=E5=86=B5=E5=8C=85?=
 =?UTF-8?q?=E7=BB=9C+=E5=B3=B0=E5=80=BC=E4=BB=8E=E5=8E=9F=E5=A7=8B?=
 =?UTF-8?q?=E8=A1=8C/null=20=E8=A1=8C=E4=B8=8D=E7=AB=9E=E5=B3=B0)=E3=80=81?=
 =?UTF-8?q?e2e=20=E7=9C=9F=20daemon=20=E4=B8=80=E5=8F=91(=E4=B8=A4=20tick?=
 =?UTF-8?q?=20=E5=90=8E=E5=B3=B0=E5=80=BC=E7=8E=B0=E8=BA=AB,=E9=A6=96=20ti?=
 =?UTF-8?q?ck=20null=20=E6=98=AF=E9=A2=84=E6=9C=9F)=E3=80=82=E5=85=A8?=
 =?UTF-8?q?=E9=93=BE=20build/typecheck/lint=20=E5=B9=B2=E5=87=80,server=20?=
 =?UTF-8?q?516=E3=80=81sdk=2031=E3=80=81cli=2059=E3=80=81e2e=2085=20?=
 =?UTF-8?q?=E5=85=A8=E7=BB=BF=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/src/native.test.ts                        |  22 +
 .../overview/components/HostHealthCard.tsx    |  59 +-
 .../overview/hooks/useHostTimeline.ts         |  25 +
 .../features/overview/pages/OverviewPage.tsx  |   2 +-
 packages/console/src/lib/api.ts               |   7 +
 packages/sdk/src/client.ts                    |  22 +
 .../drizzle/0016_host-metrics-history.sql     |  11 +
 .../server/drizzle/meta/0016_snapshot.json    | 713 ++++++++++++++++++
 packages/server/drizzle/meta/_journal.json    |   7 +
 packages/server/src/db/metrics.ts             | 137 +++-
 packages/server/src/db/schema.ts              |  45 +-
 packages/server/src/e2b/compat.test.ts        |  14 +-
 packages/server/src/host-metrics.ts           |  36 +
 packages/server/src/main.ts                   |  10 +
 packages/server/src/metrics-sampler.test.ts   |  70 +-
 packages/server/src/metrics-sampler.ts        |  36 +-
 packages/server/src/routes/host.ts            |  62 ++
 .../server/src/routes/observability.test.ts   | 170 ++++-
 packages/shared/src/host.ts                   | 100 ++-
 packages/shared/src/metrics.ts                |   2 +-
 20 files changed, 1496 insertions(+), 54 deletions(-)
 create mode 100644 packages/console/src/features/overview/hooks/useHostTimeline.ts
 create mode 100644 packages/server/drizzle/0016_host-metrics-history.sql
 create mode 100644 packages/server/drizzle/meta/0016_snapshot.json

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index 1474805..d949659 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -723,4 +723,26 @@ describe('the observability verbs over a real daemon', () => {
     }
     await client().destroySandbox('obs-timeline-key');
   });
+
+  it("getHostMetricsHistory reports the machine's past with a CPU peak", async () => {
+    // Wait for two ticks: the first after a daemon start has no CPU delta
+    // (an honest null), the second does — and with it the window's peak.
+    const deadline = Date.now() + 15_000;
+    let history = await client().getHostMetricsHistory();
+    while (
+      (history.points.length < 2 || history.peak === null) &&
+      Date.now() < deadline
+    ) {
+      await sleep(0.5);
+      history = await client().getHostMetricsHistory();
+    }
+    expect(history.points.length).toBeGreaterThanOrEqual(2);
+    expect(history.peak?.cpuUsedPct).toBeGreaterThanOrEqual(0);
+    // Real memory from the machine under the daemon; a short window comes
+    // back raw, not bucketed.
+    const newest = history.points.at(-1);
+    expect(newest?.memTotalBytes).toBeGreaterThan(0);
+    expect(newest?.memAvailableBytes).toBeGreaterThan(0);
+    expect(history.bucketSeconds).toBe(null);
+  });
 });
diff --git a/packages/console/src/features/overview/components/HostHealthCard.tsx b/packages/console/src/features/overview/components/HostHealthCard.tsx
index 6a74ff2..87e3bbe 100644
--- a/packages/console/src/features/overview/components/HostHealthCard.tsx
+++ b/packages/console/src/features/overview/components/HostHealthCard.tsx
@@ -15,9 +15,13 @@ import {
   CardTitle,
 } from '@/components/ui/card';
 import { Skeleton } from '@/components/ui/skeleton';
+import { ago } from '@/features/sandboxes/format';
 import { formatBytes, pctOf } from '@/lib/format';
 import { cn } from '@/lib/utils';
+import type { TimelineRangeKey } from '../hooks/useFleetTimeline';
 import { useHostMetrics } from '../hooks/useHostMetrics';
+import { useHostTimeline } from '../hooks/useHostTimeline';
+import { Sparkline } from './Sparkline';
 
 function HostRow({
   icon,
@@ -25,6 +29,7 @@ function HostRow({
   value,
   hint,
   pct,
+  trend,
 }: {
   icon: NonNullable<HugeiconsProps['icon']>;
   label: string;
@@ -32,6 +37,8 @@ function HostRow({
   hint: ReactNode;
   /** Meter percentage; null renders an empty track, undefined no meter. */
   pct?: number | null;
+  /** 窗口内走势;少于两点 Sparkline 自己不画,行高由占位符稳住。 */
+  trend?: number[];
 }) {
   return (
     <div className="flex flex-col gap-1.5">
@@ -49,6 +56,11 @@ function HostRow({
         </span>
       </div>
       {pct !== undefined && <Meter pct={pct} />}
+      {trend !== undefined && (
+        <div className="h-5">
+          <Sparkline data={trend} className="h-5" />
+        </div>
+      )}
       <div className="text-xs text-muted-foreground">{hint}</div>
     </div>
   );
@@ -59,18 +71,29 @@ function HostRow({
  * Swap 和数据盘与 CPU、内存平起平坐,因为在这个平台上它们才是要命的
  * 两个:swap 满了「空闲即免费」就完了,数据盘满了连创建都完了。沙箱
  * 磁盘的账单在页面底部一行 — 这张卡只讲机器本身。
+ *
+ * 每行的数值是即时读数(5s 轮询),行内 sparkline 与 CPU 峰值来自
+ * getHostMetricsHistory,跟随页面全局档位 — 即时值答"现在怎么样",
+ * 走势答"这个窗口里发生过什么",峰值从原始行来,分桶抹不平它。
  */
-export function HostHealthCard({ className }: { className?: string }) {
+export function HostHealthCard({
+  range,
+  className,
+}: {
+  range: TimelineRangeKey;
+  className?: string;
+}) {
   const query = useHostMetrics();
+  const history = useHostTimeline(range);
 
   return (
     <Card size="sm" className={cn('flex flex-col', className)}>
       <CardHeader>
         <CardTitle>宿主健康</CardTitle>
-        <CardDescription>这台机器的资源水位</CardDescription>
+        <CardDescription>这台机器的资源水位与走势</CardDescription>
       </CardHeader>
       <CardContent className="flex flex-1 flex-col justify-between gap-5">
-        <HostHealthRows query={query} />
+        <HostHealthRows query={query} history={history} />
       </CardContent>
     </Card>
   );
@@ -78,8 +101,10 @@ export function HostHealthCard({ className }: { className?: string }) {
 
 function HostHealthRows({
   query,
+  history,
 }: {
   query: ReturnType<typeof useHostMetrics>;
+  history: ReturnType<typeof useHostTimeline>;
 }) {
   if (query.isError) {
     return (
@@ -90,7 +115,7 @@ function HostHealthRows({
   }
 
   if (!query.data) {
-    // 骨架镜像真实行解剖(标签+数值 / 量表 / 说明),四行等高不跳动。
+    // 骨架镜像真实行解剖(标签+数值 / 量表 / 走势 / 说明),四行等高不跳动。
     return (
       <>
         {['cpu', 'memory', 'swap', 'data-disk'].map((slot) => (
@@ -100,6 +125,7 @@ function HostHealthRows({
               <Skeleton className="h-5 w-12" />
             </div>
             <Skeleton className="h-1.5 w-full rounded-full" />
+            <Skeleton className="h-5 w-full" />
             <Skeleton className="h-4 w-28" />
           </div>
         ))}
@@ -110,6 +136,21 @@ function HostHealthRows({
   const { host, dataDisk } = query.data;
   const memUsed = host.memTotalBytes - host.memAvailableBytes;
 
+  // 历史请求失败或还没答案时走势为空 — Sparkline 少于两点自己不画,
+  // 即时读数照常;历史的缺席不该拖垮当下。
+  const points = history.data?.points ?? [];
+  const peak = history.data?.peak ?? null;
+  const cpuTrend = points
+    .map((p) => p.cpuUsedPct)
+    .filter((v): v is number => v !== null);
+  const memTrend = points.map((p) => p.memTotalBytes - p.memAvailableBytes);
+  const swapTrend = points
+    .map((p) => p.swap?.usedBytes)
+    .filter((v): v is number => v !== undefined);
+  const diskTrend = points
+    .map((p) => p.dataDisk?.usedBytes)
+    .filter((v): v is number => v !== undefined);
+
   return (
     <>
       <HostRow
@@ -118,8 +159,13 @@ function HostHealthRows({
         value={
           host.cpuUsedPct === null ? '—' : `${Math.round(host.cpuUsedPct)}%`
         }
-        hint={`${host.cpuCount} 核`}
+        hint={
+          peak === null
+            ? `${host.cpuCount} 核`
+            : `${host.cpuCount} 核 · 窗口峰值 ${Math.round(peak.cpuUsedPct)}%(${ago(peak.at)})`
+        }
         pct={host.cpuUsedPct}
+        trend={cpuTrend}
       />
       <HostRow
         icon={RamMemoryIcon}
@@ -127,6 +173,7 @@ function HostHealthRows({
         value={formatBytes(memUsed)}
         hint={`共 ${formatBytes(host.memTotalBytes)} · 可用 ${formatBytes(host.memAvailableBytes)}`}
         pct={pctOf(memUsed, host.memTotalBytes)}
+        trend={memTrend}
       />
       {host.swap === null ? (
         <HostRow
@@ -153,6 +200,7 @@ function HostHealthRows({
           value={formatBytes(host.swap.usedBytes)}
           hint={`共 ${formatBytes(host.swap.totalBytes)} · 冻结的沙箱住在这里`}
           pct={pctOf(host.swap.usedBytes, host.swap.totalBytes)}
+          trend={swapTrend}
         />
       )}
       {dataDisk === null ? (
@@ -173,6 +221,7 @@ function HostHealthRows({
             </span>
           }
           pct={pctOf(dataDisk.usedBytes, dataDisk.totalBytes)}
+          trend={diskTrend}
         />
       )}
     </>
diff --git a/packages/console/src/features/overview/hooks/useHostTimeline.ts b/packages/console/src/features/overview/hooks/useHostTimeline.ts
new file mode 100644
index 0000000..6d703e1
--- /dev/null
+++ b/packages/console/src/features/overview/hooks/useHostTimeline.ts
@@ -0,0 +1,25 @@
+import { keepPreviousData, useQuery } from '@tanstack/react-query';
+import { getHostMetricsHistory } from '@/lib/api';
+import { rangeSpanMs, type TimelineRangeKey } from './useFleetTimeline';
+
+/**
+ * 宿主机的走势,跟随总览页的全局档位 — 节奏与 useFleetTimeline 完全同款:
+ * 30 秒一刷(同 daemon 采样间隔,更快只是重复读同一批样本)、窗口在
+ * queryFn 里现算随时间滑动、切档位时 keepPreviousData 顶住不塌骨架。
+ */
+export function useHostTimeline(range: TimelineRangeKey) {
+  return useQuery({
+    queryKey: ['hostTimeline', range],
+    queryFn: () => {
+      const end = Date.now();
+      const start = end - rangeSpanMs(range);
+      return getHostMetricsHistory(
+        new Date(start).toISOString(),
+        new Date(end).toISOString(),
+      );
+    },
+    refetchInterval: 30_000,
+    retry: false,
+    placeholderData: keepPreviousData,
+  });
+}
diff --git a/packages/console/src/features/overview/pages/OverviewPage.tsx b/packages/console/src/features/overview/pages/OverviewPage.tsx
index 2849d3e..adafd2c 100644
--- a/packages/console/src/features/overview/pages/OverviewPage.tsx
+++ b/packages/console/src/features/overview/pages/OverviewPage.tsx
@@ -25,7 +25,7 @@ export function OverviewPage() {
       <FleetStatCards range={range} />
       <div className="grid grid-cols-1 gap-4 lg:grid-cols-4">
         <FleetChart range={range} className="min-h-[420px] lg:col-span-3" />
-        <HostHealthCard className="min-h-[420px] lg:col-span-1" />
+        <HostHealthCard range={range} className="min-h-[420px] lg:col-span-1" />
       </div>
       <QuickConnectCard />
     </div>
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 05181ad..931e4f9 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -7,6 +7,7 @@ import type {
   CreateApiKeyResponse,
   GetConfigResponse,
   GetFleetTimelineResponse,
+  GetHostMetricsHistoryResponse,
   GetIngressResponse,
   GetSandboxMetricsHistoryResponse,
   GetSandboxMetricsResponse,
@@ -153,6 +154,12 @@ export const getSandboxMetricsHistory = (
 export const getFleetTimeline = (start: string, end: string) =>
   rpc<GetFleetTimelineResponse>('/getFleetTimeline', { start, end });
 
+// The machine's sampled past — the host health card's trend food. Buckets
+// keep each field's worst case (max usage, min available) so spikes
+// survive; peak carries the window's raw CPU high point.
+export const getHostMetricsHistory = (start: string, end: string) =>
+  rpc<GetHostMetricsHistoryResponse>('/getHostMetricsHistory', { start, end });
+
 // Every sandbox's image lineage: the born image of the current shell (null
 // when no shell exists), the image the next shell would boot, and whether a
 // rebuild would change anything — the window answering "who still runs an
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 705dd51..a1521ce 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -16,11 +16,13 @@ import {
   execCommandResponseSchema,
   type GetConfigResponse,
   type GetFleetTimelineResponse,
+  type GetHostMetricsHistoryResponse,
   type GetIngressResponse,
   type GetSandboxMetricsHistoryResponse,
   type GetUpgradeStatusResponse,
   getConfigResponseSchema,
   getFleetTimelineResponseSchema,
+  getHostMetricsHistoryResponseSchema,
   getIngressResponseSchema,
   getSandboxMetricsHistoryResponseSchema,
   getSandboxMetricsResponseSchema,
@@ -194,6 +196,26 @@ export class Dormice {
     return hostMetricsResponseSchema.parse(data);
   }
 
+  /**
+   * The host machine's sampled history, sliced by an optional ISO window
+   * (default: the last 24 hours). Past 360 points the server buckets the
+   * answer — `bucketSeconds` says how wide — keeping each field's worst
+   * case (max usage, min available), so spikes survive. `peak` carries the
+   * window's highest whole-machine CPU percentage from raw rows, immune to
+   * bucketing. Nulls inside a point are honest platform gaps, and a window
+   * the daemon was down for shows the gap.
+   */
+  async getHostMetricsHistory(options?: {
+    start?: string;
+    end?: string;
+  }): Promise<GetHostMetricsHistoryResponse> {
+    const data = await this.rpc('getHostMetricsHistory', {
+      start: options?.start,
+      end: options?.end,
+    });
+    return getHostMetricsHistoryResponseSchema.parse(data);
+  }
+
   /**
    * One sandbox's point-in-time resource reading (CPU, memory, disk).
    * Observation never wakes: a frozen sandbox is measured as it sleeps,
diff --git a/packages/server/drizzle/0016_host-metrics-history.sql b/packages/server/drizzle/0016_host-metrics-history.sql
new file mode 100644
index 0000000..c300aff
--- /dev/null
+++ b/packages/server/drizzle/0016_host-metrics-history.sql
@@ -0,0 +1,11 @@
+CREATE TABLE `host_metrics_samples` (
+	`at` text PRIMARY KEY NOT NULL,
+	`cpu_used_pct` real,
+	`mem_total_bytes` integer NOT NULL,
+	`mem_available_bytes` integer NOT NULL,
+	`swap_total_bytes` integer,
+	`swap_used_bytes` integer,
+	`disk_total_bytes` integer,
+	`disk_used_bytes` integer,
+	`disk_available_bytes` integer
+);
diff --git a/packages/server/drizzle/meta/0016_snapshot.json b/packages/server/drizzle/meta/0016_snapshot.json
new file mode 100644
index 0000000..140b36e
--- /dev/null
+++ b/packages/server/drizzle/meta/0016_snapshot.json
@@ -0,0 +1,713 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "8a64b919-3367-45fe-bba3-228f8df72c67",
+  "prevId": "6c48c760-a9db-401e-98e4-73405a8c4cac",
+  "tables": {
+    "activity": {
+      "name": "activity",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_name": {
+          "name": "sandbox_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "actor": {
+          "name": "actor",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "detail": {
+          "name": "detail",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "api_keys": {
+      "name": "api_keys",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "key_hash": {
+          "name": "key_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "prefix": {
+          "name": "prefix",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_used_at": {
+          "name": "last_used_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "disabled_at": {
+          "name": "disabled_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "revoked_at": {
+          "name": "revoked_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "api_keys_key_hash_unique": {
+          "name": "api_keys_key_hash_unique",
+          "columns": [
+            "key_hash"
+          ],
+          "isUnique": true
+        },
+        "api_keys_active_name_idx": {
+          "name": "api_keys_active_name_idx",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true,
+          "where": "\"api_keys\".\"revoked_at\" IS NULL"
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "console_account": {
+      "name": "console_account",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "username": {
+          "name": "username",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password_hash": {
+          "name": "password_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_secret": {
+          "name": "session_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "daemon_secrets": {
+      "name": "daemon_secrets",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "envd_signing_secret": {
+          "name": "envd_signing_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "fleet_snapshots": {
+      "name": "fleet_snapshots",
+      "columns": {
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active": {
+          "name": "active",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "frozen": {
+          "name": "frozen",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stopped": {
+          "name": "stopped",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archived": {
+          "name": "archived",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "restoring": {
+          "name": "restoring",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "total": {
+          "name": "total",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "host_metrics_samples": {
+      "name": "host_metrics_samples",
+      "columns": {
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_used_pct": {
+          "name": "cpu_used_pct",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "mem_total_bytes": {
+          "name": "mem_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_available_bytes": {
+          "name": "mem_available_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "swap_total_bytes": {
+          "name": "swap_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "swap_used_bytes": {
+          "name": "swap_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "disk_total_bytes": {
+          "name": "disk_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "disk_used_bytes": {
+          "name": "disk_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "disk_available_bytes": {
+          "name": "disk_available_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "runtime_settings": {
+      "name": "runtime_settings",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "max_sandboxes": {
+          "name": "max_sandboxes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_cpus": {
+          "name": "sandbox_cpus",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_memory_gb": {
+          "name": "sandbox_memory_gb",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "sandbox_disk_gb": {
+          "name": "sandbox_disk_gb",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "default_freeze_after_seconds": {
+          "name": "default_freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "default_stop_after_seconds": {
+          "name": "default_stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "default_archive_after_seconds": {
+          "name": "default_archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "swap_gb": {
+          "name": "swap_gb",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandbox_metrics_samples": {
+      "name": "sandbox_metrics_samples",
+      "columns": {
+        "sandbox_id": {
+          "name": "sandbox_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "at": {
+          "name": "at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_count": {
+          "name": "cpu_count",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cpu_used_pct": {
+          "name": "cpu_used_pct",
+          "type": "real",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_used_bytes": {
+          "name": "mem_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_total_bytes": {
+          "name": "mem_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mem_cache_bytes": {
+          "name": "mem_cache_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_used_bytes": {
+          "name": "disk_used_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "disk_total_bytes": {
+          "name": "disk_total_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "sandbox_metrics_samples_sandbox_at_idx": {
+          "name": "sandbox_metrics_samples_sandbox_at_idx",
+          "columns": [
+            "sandbox_id",
+            "at"
+          ],
+          "isUnique": false
+        },
+        "sandbox_metrics_samples_at_idx": {
+          "name": "sandbox_metrics_samples_at_idx",
+          "columns": [
+            "at"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sandboxes": {
+      "name": "sandboxes",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "node_id": {
+          "name": "node_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "freeze_after_seconds": {
+          "name": "freeze_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "stop_after_seconds": {
+          "name": "stop_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "archive_after_seconds": {
+          "name": "archive_after_seconds",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "template": {
+          "name": "template",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "envs": {
+          "name": "envs",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "deadline_at": {
+          "name": "deadline_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "on_deadline": {
+          "name": "on_deadline",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "paused_by_user": {
+          "name": "paused_by_user",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        }
+      },
+      "indexes": {
+        "sandboxes_name_unique": {
+          "name": "sandboxes_name_unique",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "templates": {
+      "name": "templates",
+      "columns": {
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
\ No newline at end of file
diff --git a/packages/server/drizzle/meta/_journal.json b/packages/server/drizzle/meta/_journal.json
index 609d6fd..322859b 100644
--- a/packages/server/drizzle/meta/_journal.json
+++ b/packages/server/drizzle/meta/_journal.json
@@ -113,6 +113,13 @@
       "when": 1784461661884,
       "tag": "0015_swap-target",
       "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "6",
+      "when": 1784632504378,
+      "tag": "0016_host-metrics-history",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/packages/server/src/db/metrics.ts b/packages/server/src/db/metrics.ts
index 4361535..c4727a3 100644
--- a/packages/server/src/db/metrics.ts
+++ b/packages/server/src/db/metrics.ts
@@ -1,19 +1,32 @@
-import { and, asc, desc, eq, gte, inArray, lt, lte } from 'drizzle-orm';
+import {
+  and,
+  asc,
+  desc,
+  eq,
+  gte,
+  inArray,
+  isNotNull,
+  lt,
+  lte,
+} from 'drizzle-orm';
 import type { SandboxMetrics } from '../executor/executor';
+import type { HostSample } from '../host-metrics';
 import type { Db } from './db';
 import {
   type FleetSnapshotRow,
   fleetSnapshots,
+  type HostMetricsSampleRow,
+  hostMetricsSamples,
   type SandboxMetricsSampleRow,
   sandboxes,
   sandboxMetricsSamples,
 } from './schema';
 
 /**
- * How long fleet snapshots live. Not a knob: the dashboard's widest range
- * (30 days) defines the need, and at one small row per tick the table stays
- * a few megabytes — nobody sizes an explanation window (ACTIVITY_KEEP's
- * reasoning). Per-sandbox samples DO get a knob
+ * How long fleet snapshots and host samples live. Not a knob: the
+ * dashboard's widest range (30 days) defines the need, and at one small row
+ * per tick each table stays a few megabytes — nobody sizes an explanation
+ * window (ACTIVITY_KEEP's reasoning). Per-sandbox samples DO get a knob
  * (DORMICE_METRICS_RETENTION_HOURS): their volume scales with fleet size.
  */
 export const FLEET_SNAPSHOT_KEEP_DAYS = 30;
@@ -39,6 +52,7 @@ export interface MetricsTickInput {
   /** ISO 8601 UTC — the tick's single timestamp, shared by every row. */
   at: string;
   fleetCounts: FleetCounts;
+  host: HostSample;
   samples: Array<{ sandboxId: string; metrics: SandboxMetrics }>;
   retentionHours: number;
 }
@@ -67,6 +81,10 @@ export function insertMetricsTick(db: Db, input: MetricsTickInput): void {
       .values({ at: input.at, ...input.fleetCounts })
       .run();
 
+    tx.insert(hostMetricsSamples)
+      .values({ at: input.at, ...input.host })
+      .run();
+
     if (input.samples.length > 0) {
       const liveIds = new Set(
         tx
@@ -93,6 +111,9 @@ export function insertMetricsTick(db: Db, input: MetricsTickInput): void {
       .where(lt(sandboxMetricsSamples.at, sampleCutoff))
       .run();
     tx.delete(fleetSnapshots).where(lt(fleetSnapshots.at, fleetCutoff)).run();
+    tx.delete(hostMetricsSamples)
+      .where(lt(hostMetricsSamples.at, fleetCutoff))
+      .run();
   });
 }
 
@@ -127,6 +148,56 @@ export function querySandboxSamples(
     .all();
 }
 
+/** Ascending slice of host samples. */
+export function queryHostSamples(
+  db: Db,
+  startIso: string,
+  endIso: string,
+): HostMetricsSampleRow[] {
+  return db
+    .select()
+    .from(hostMetricsSamples)
+    .where(
+      and(
+        gte(hostMetricsSamples.at, startIso),
+        lte(hostMetricsSamples.at, endIso),
+      ),
+    )
+    .orderBy(asc(hostMetricsSamples.at))
+    .all();
+}
+
+/**
+ * The window's host CPU peak, from raw rows so no bucketing can flatten
+ * it: highest whole-machine percentage, and the earliest instant it was
+ * observed. Null-CPU rows (the tick after a daemon start) don't compete.
+ */
+export function queryHostCpuPeak(
+  db: Db,
+  startIso: string,
+  endIso: string,
+): { cpuUsedPct: number; at: string } | null {
+  const row = db
+    .select({
+      cpuUsedPct: hostMetricsSamples.cpuUsedPct,
+      at: hostMetricsSamples.at,
+    })
+    .from(hostMetricsSamples)
+    .where(
+      and(
+        gte(hostMetricsSamples.at, startIso),
+        lte(hostMetricsSamples.at, endIso),
+        isNotNull(hostMetricsSamples.cpuUsedPct),
+      ),
+    )
+    .orderBy(desc(hostMetricsSamples.cpuUsedPct), asc(hostMetricsSamples.at))
+    .limit(1)
+    .get();
+  return row && row.cpuUsedPct !== null
+    ? { cpuUsedPct: row.cpuUsedPct, at: row.at }
+    : null;
+}
+
 /** Ascending slice of fleet snapshots. */
 export function queryFleetSnapshots(
   db: Db,
@@ -238,6 +309,62 @@ export function bucketSamples(
   return [...buckets.entries()].sort(([a], [b]) => a - b).map(([, row]) => row);
 }
 
+/** Per-field extreme where either side may be an honest null. */
+function extremeNullable(
+  pick: (a: number, b: number) => number,
+  a: number | null,
+  b: number | null,
+): number | null {
+  if (a === null) return b;
+  if (b === null) return a;
+  return pick(a, b);
+}
+
+/**
+ * Buckets host samples the per-sandbox way — a per-field envelope, because
+ * a reader of host history is hunting spikes. Each field keeps its own
+ * WORST case, which is max for usage but MIN for the "available" fields: a
+ * memory-pressure spike is a low point of MemAvailable, and a max would
+ * erase exactly what the reader came for. Nullable fields aggregate over
+ * non-null readings and stay null only when the whole bucket had nothing
+ * to say.
+ */
+export function bucketHostSamples(
+  rows: HostMetricsSampleRow[],
+  startMs: number,
+  bucketSeconds: number,
+): HostMetricsSampleRow[] {
+  const max = extremeNullable.bind(null, Math.max);
+  const min = extremeNullable.bind(null, Math.min);
+  const buckets = new Map<number, HostMetricsSampleRow>();
+  for (const row of rows) {
+    const idx = bucketIndex(row.at, startMs, bucketSeconds);
+    const seen = buckets.get(idx);
+    if (!seen) {
+      buckets.set(idx, {
+        ...row,
+        at: new Date(startMs + idx * bucketSeconds * 1000).toISOString(),
+      });
+      continue;
+    }
+    seen.cpuUsedPct = max(seen.cpuUsedPct, row.cpuUsedPct);
+    seen.memTotalBytes = Math.max(seen.memTotalBytes, row.memTotalBytes);
+    seen.memAvailableBytes = Math.min(
+      seen.memAvailableBytes,
+      row.memAvailableBytes,
+    );
+    seen.swapTotalBytes = max(seen.swapTotalBytes, row.swapTotalBytes);
+    seen.swapUsedBytes = max(seen.swapUsedBytes, row.swapUsedBytes);
+    seen.diskTotalBytes = max(seen.diskTotalBytes, row.diskTotalBytes);
+    seen.diskUsedBytes = max(seen.diskUsedBytes, row.diskUsedBytes);
+    seen.diskAvailableBytes = min(
+      seen.diskAvailableBytes,
+      row.diskAvailableBytes,
+    );
+  }
+  return [...buckets.entries()].sort(([a], [b]) => a - b).map(([, row]) => row);
+}
+
 /**
  * Buckets fleet snapshots by keeping each bucket's LAST raw row whole —
  * never per-state maxima, which would count a sandbox mid-transition twice
diff --git a/packages/server/src/db/schema.ts b/packages/server/src/db/schema.ts
index a2aaff1..e48107f 100644
--- a/packages/server/src/db/schema.ts
+++ b/packages/server/src/db/schema.ts
@@ -115,13 +115,13 @@ export type ActivityRow = typeof activity.$inferSelect;
  * DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS for each measurable (running or
  * paused) sandbox. The daemon keeps this history because it is a
  * compatibility contract — the E2B metrics endpoint slices by start/end —
- * and because nothing outside the ledger can measure per-sandbox; host
- * trends still belong to Prometheus.
+ * and because nothing outside the ledger can measure per-sandbox.
  *
- * Two tables, not one: this and fleet_snapshots differ in unit of meaning
- * (one sandbox's resources vs the whole fleet's state counts), retention
- * (DORMICE_METRICS_RETENTION_HOURS vs a fixed 30 days) and deletion path
- * (destroy cascades here, never there).
+ * Three tables, not one: this, fleet_snapshots and host_metrics_samples
+ * differ in unit of meaning (one sandbox's resources vs the fleet's state
+ * counts vs the machine's own resources), retention
+ * (DORMICE_METRICS_RETENTION_HOURS vs a fixed 30 days for the other two)
+ * and deletion path (destroy cascades here, never there).
  *
  * Keyed by the sandbox's platform id, not its name: rebuild replaces the
  * shell but keeps the id, so history stays continuous across rebuilds;
@@ -180,6 +180,39 @@ export const fleetSnapshots = sqliteTable('fleet_snapshots', {
 
 export type FleetSnapshotRow = typeof fleetSnapshots.$inferSelect;
 
+/**
+ * The host machine's own resource history, one row per sampler tick — the
+ * historical sibling of getHostMetrics' snapshot. The original ruling
+ * ("host trends belong to Prometheus") was overturned 2026-07-21: on a
+ * self-hosted single box nobody runs Prometheus, and overcommit-by-
+ * observation — the platform's own capacity story — is impossible without
+ * a peak to look at. Owned by no sandbox (destroy never touches it), kept
+ * a fixed 30 days like fleet_snapshots and for the same reason: the
+ * dashboard's widest range defines the need.
+ *
+ * Nullable columns are honest platform gaps, never zeros: cpu_used_pct is
+ * null on the tick after a daemon start (a delta needs two samples), swap
+ * is null where /proc/meminfo does not exist (Mac dev box), disk is null
+ * until the data directory does (fake executor, fresh install).
+ */
+export const hostMetricsSamples = sqliteTable('host_metrics_samples', {
+  /** ISO 8601 UTC; one row per tick, so time itself is the key. */
+  at: text('at').primaryKey(),
+  /** Percent of the whole machine, 0-100. */
+  cpuUsedPct: real('cpu_used_pct'),
+  memTotalBytes: integer('mem_total_bytes').notNull(),
+  /** /proc/meminfo MemAvailable semantics (counts reclaimable cache). */
+  memAvailableBytes: integer('mem_available_bytes').notNull(),
+  swapTotalBytes: integer('swap_total_bytes'),
+  swapUsedBytes: integer('swap_used_bytes'),
+  /** The filesystem holding DORMICE_DATA_DIR, df semantics. */
+  diskTotalBytes: integer('disk_total_bytes'),
+  diskUsedBytes: integer('disk_used_bytes'),
+  diskAvailableBytes: integer('disk_available_bytes'),
+});
+
+export type HostMetricsSampleRow = typeof hostMetricsSamples.$inferSelect;
+
 /**
  * The console's one human account (the fixed id makes "at most one row" a
  * schema fact, not a convention). The API token stays the root of trust:
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 8359011..74b742e 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -14,6 +14,7 @@ import { migrateDb, openDb } from '../db/db';
 import { findById, setDeadline } from '../db/ledger';
 import { getOrCreateSigningSecret } from '../db/secrets';
 import { FAKE_BASE_IMAGE, FakeExecutor } from '../executor/fake';
+import { CpuSampler } from '../host-metrics';
 import { KeyedQueue } from '../keyed-queue';
 import { sampleOnce } from '../metrics-sampler';
 import { scanOnce } from '../scanner';
@@ -22,6 +23,15 @@ import { mintEnvdToken } from './protocol';
 const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
 const TOKEN = 'test-token-test-token-test-token';
 
+/** One sampler tick's non-sandbox inputs (host reading lands as nulls). */
+function tickOpts() {
+  return {
+    retentionHours: 168,
+    hostCpu: new CpuSampler(),
+    dataDir: '/nowhere/dormice-compat-test',
+  };
+}
+
 function testApp(
   executor: FakeExecutor = new FakeExecutor(),
   env: Record<string, string> = {},
@@ -553,9 +563,7 @@ describe('E2B control plane', () => {
     // Three sampler ticks 30s apart, in the recent past.
     const t0 = Date.now() - 120_000;
     for (let i = 0; i < 3; i += 1) {
-      await sampleOnce(t.db, t.executor, new Date(t0 + i * 30_000), {
-        retentionHours: 168,
-      });
+      await sampleOnce(t.db, t.executor, new Date(t0 + i * 30_000), tickOpts());
     }
     // A window around the middle tick: exactly that sample, ISO and unix
     // spellings agreeing.
diff --git a/packages/server/src/host-metrics.ts b/packages/server/src/host-metrics.ts
index 4843a52..d629146 100644
--- a/packages/server/src/host-metrics.ts
+++ b/packages/server/src/host-metrics.ts
@@ -100,6 +100,42 @@ export interface DiskSpace {
   availableBytes: number;
 }
 
+/**
+ * One tick's whole-host reading, flattened to the shape of a
+ * host_metrics_samples row. Collected by the metrics sampler with its OWN
+ * CpuSampler instance: a CPU delta spans "since this instance's previous
+ * sample", so sharing the getHostMetrics route's instance would let every
+ * console poll steal the ticker's window and turn 30s readings into noise.
+ */
+export interface HostSample {
+  cpuUsedPct: number | null;
+  memTotalBytes: number;
+  memAvailableBytes: number;
+  swapTotalBytes: number | null;
+  swapUsedBytes: number | null;
+  diskTotalBytes: number | null;
+  diskUsedBytes: number | null;
+  diskAvailableBytes: number | null;
+}
+
+export async function readHostSample(
+  cpu: CpuSampler,
+  dataDir: string,
+): Promise<HostSample> {
+  const memory = await readHostMemory();
+  const disk = await readDiskSpace(dataDir);
+  return {
+    cpuUsedPct: cpu.sample(),
+    memTotalBytes: memory.memTotalBytes,
+    memAvailableBytes: memory.memAvailableBytes,
+    swapTotalBytes: memory.swap?.totalBytes ?? null,
+    swapUsedBytes: memory.swap?.usedBytes ?? null,
+    diskTotalBytes: disk?.totalBytes ?? null,
+    diskUsedBytes: disk?.usedBytes ?? null,
+    diskAvailableBytes: disk?.availableBytes ?? null,
+  };
+}
+
 /**
  * The filesystem holding `dirPath`, df semantics: available is what a
  * non-root writer can still use (bavail, not bfree). Null when the
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index ee0cce2..4af703a 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -14,6 +14,7 @@ import { ensureRuntimeSettings, readRuntimeSettings } from './db/settings';
 import { DockerExecutor } from './executor/docker';
 import type { Executor } from './executor/executor';
 import { FakeExecutor } from './executor/fake';
+import { CpuSampler } from './host-metrics';
 import { Ingress } from './ingress';
 import { KeyedQueue } from './keyed-queue';
 import { sampleOnce } from './metrics-sampler';
@@ -278,10 +279,19 @@ setTimeout(tick, config.DORMICE_SCAN_INTERVAL_SECONDS * 1000);
 // immediately: a restart's gap in the curves should equal the downtime, not
 // downtime plus one interval. Same failure stance as the heartbeat: log,
 // never fatal, next tick retries.
+//
+// The ticker's private CpuSampler, primed here so even the immediate first
+// tick has a (short) interval to report on. Private because a CPU delta
+// spans "since this instance's last sample": the getHostMetrics route owns
+// a separate instance, and sharing would let console polls steal windows.
+const hostCpu = new CpuSampler();
+hostCpu.sample();
 async function metricsTick() {
   try {
     await sampleOnce(db, executor, new Date(), {
       retentionHours: config.DORMICE_METRICS_RETENTION_HOURS,
+      hostCpu,
+      dataDir: config.DORMICE_DATA_DIR,
     });
   } catch (error) {
     app.log.error(error, 'metrics sampler tick failed');
diff --git a/packages/server/src/metrics-sampler.test.ts b/packages/server/src/metrics-sampler.test.ts
index 6a3fe2c..28d03b1 100644
--- a/packages/server/src/metrics-sampler.test.ts
+++ b/packages/server/src/metrics-sampler.test.ts
@@ -5,8 +5,13 @@ import { buildApp } from './app';
 import { CONFIG_KEYS, type ConfigSources, loadConfig } from './config';
 import { migrateDb, openDb } from './db/db';
 import { FLEET_SNAPSHOT_KEEP_DAYS, insertMetricsTick } from './db/metrics';
-import { fleetSnapshots, sandboxMetricsSamples } from './db/schema';
+import {
+  fleetSnapshots,
+  hostMetricsSamples,
+  sandboxMetricsSamples,
+} from './db/schema';
 import { FakeExecutor } from './executor/fake';
+import { CpuSampler, type HostSample } from './host-metrics';
 import { KeyedQueue } from './keyed-queue';
 import { freezeSandbox, stopSandbox } from './lifecycle';
 import { sampleOnce } from './metrics-sampler';
@@ -19,6 +24,29 @@ const MIGRATIONS = fileURLToPath(new URL('../drizzle', import.meta.url));
 const TOKEN = 'test-token-test-token-test-token';
 const authed = { authorization: `Bearer ${TOKEN}` };
 
+// One tick's non-sandbox inputs. A fresh CpuSampler per call is fine: its
+// delta-less first reading is an honest null — exactly what the tick after
+// a daemon start writes. The data dir doesn't exist, so disk is null too.
+function tickOpts() {
+  return {
+    retentionHours: 168,
+    hostCpu: new CpuSampler(),
+    dataDir: '/nowhere/dormice-metrics-test',
+  };
+}
+
+// A fixed host reading for straight-to-the-writer tests.
+const HOST: HostSample = {
+  cpuUsedPct: 12,
+  memTotalBytes: 4096,
+  memAvailableBytes: 2048,
+  swapTotalBytes: null,
+  swapUsedBytes: null,
+  diskTotalBytes: null,
+  diskUsedBytes: null,
+  diskAvailableBytes: null,
+};
+
 function fixedSources(): ConfigSources {
   const all = Object.fromEntries(
     Object.keys(CONFIG_KEYS).map((key) => [key, 'default']),
@@ -67,6 +95,10 @@ function fleetRows(db: ReturnType<typeof harness>['db']) {
   return db.select().from(fleetSnapshots).all();
 }
 
+function hostRows(db: ReturnType<typeof harness>['db']) {
+  return db.select().from(hostMetricsSamples).all();
+}
+
 describe('sampleOnce', () => {
   it('writes one fleet row and one sample per measurable sandbox', async () => {
     const { app, db, executor } = harness();
@@ -78,7 +110,7 @@ describe('sampleOnce', () => {
     await stopSandbox(db, executor, cold.id);
 
     const now = new Date('2026-07-15T10:00:00.000Z');
-    const result = await sampleOnce(db, executor, now, { retentionHours: 168 });
+    const result = await sampleOnce(db, executor, now, tickOpts());
 
     // Active and frozen are measured; stopped has no container and is not.
     expect(result).toEqual({ sampled: 2, skipped: 0 });
@@ -100,6 +132,15 @@ describe('sampleOnce', () => {
       expect(row.at).toBe(now.toISOString());
       expect(row.memTotalBytes).toBeGreaterThan(0);
     }
+    // The machine's own reading lands on the same tick: real memory, and
+    // honest nulls for what this run cannot read (a data dir that doesn't
+    // exist, a CPU delta the fresh sampler doesn't have yet).
+    const host = hostRows(db);
+    expect(host).toHaveLength(1);
+    expect(host[0]?.at).toBe(now.toISOString());
+    expect(host[0]?.memTotalBytes).toBeGreaterThan(0);
+    expect(host[0]?.memAvailableBytes).toBeGreaterThan(0);
+    expect(host[0]?.diskTotalBytes).toBe(null);
     // Observation is not activity: the frozen sandbox is still frozen.
     expect((await executor.listContainers()).get(napping.id)).toBe('paused');
   });
@@ -114,7 +155,7 @@ describe('sampleOnce', () => {
     await executor.stop(doomed.id);
 
     const now = new Date('2026-07-15T10:00:00.000Z');
-    const result = await sampleOnce(db, executor, now, { retentionHours: 168 });
+    const result = await sampleOnce(db, executor, now, tickOpts());
     expect(result).toEqual({ sampled: 1, skipped: 1 });
     expect(sampleRows(db)).toHaveLength(1);
     // The fleet row still lands: state counts come from the ledger, not
@@ -127,36 +168,44 @@ describe('sampleOnce', () => {
     await acquire(app, 'steady');
 
     const early = new Date('2026-07-01T00:00:00.000Z');
-    await sampleOnce(db, executor, early, { retentionHours: 168 });
+    await sampleOnce(db, executor, early, tickOpts());
 
     // One retention window plus a minute later: the early sample must fall,
     // the early fleet row (well within 30 days) must survive.
     const later = new Date(early.getTime() + 168 * 3600_000 + 60_000);
-    await sampleOnce(db, executor, later, { retentionHours: 168 });
+    await sampleOnce(db, executor, later, tickOpts());
     expect(sampleRows(db).map((r) => r.at)).toEqual([later.toISOString()]);
     expect(fleetRows(db).map((r) => r.at)).toEqual([
       early.toISOString(),
       later.toISOString(),
     ]);
 
-    // Past the fleet's own 30-day window the early fleet row falls too.
+    // Past the fleet's own 30-day window the early fleet row falls too,
+    // and the host samples share that window exactly.
     const ancientCutoff = new Date(
       early.getTime() + (FLEET_SNAPSHOT_KEEP_DAYS * 24 + 1) * 3600_000,
     );
-    await sampleOnce(db, executor, ancientCutoff, { retentionHours: 168 });
+    await sampleOnce(db, executor, ancientCutoff, tickOpts());
     expect(fleetRows(db).map((r) => r.at)).toEqual([
       later.toISOString(),
       ancientCutoff.toISOString(),
     ]);
+    expect(hostRows(db).map((r) => r.at)).toEqual([
+      later.toISOString(),
+      ancientCutoff.toISOString(),
+    ]);
   });
 
   it("destroy cascades to the sandbox's samples and nobody else's", async () => {
     const { app, db, executor } = harness();
     const victim = await acquire(app, 'victim');
     await acquire(app, 'bystander');
-    await sampleOnce(db, executor, new Date('2026-07-15T10:00:00.000Z'), {
-      retentionHours: 168,
-    });
+    await sampleOnce(
+      db,
+      executor,
+      new Date('2026-07-15T10:00:00.000Z'),
+      tickOpts(),
+    );
     expect(sampleRows(db)).toHaveLength(2);
 
     const res = await app.inject({
@@ -180,6 +229,7 @@ describe('sampleOnce', () => {
     // longer has a ledger row must be filtered inside the transaction.
     insertMetricsTick(db, {
       at: '2026-07-15T10:00:00.000Z',
+      host: HOST,
       fleetCounts: {
         active: 0,
         frozen: 0,
diff --git a/packages/server/src/metrics-sampler.ts b/packages/server/src/metrics-sampler.ts
index 33dbc08..6db5e23 100644
--- a/packages/server/src/metrics-sampler.ts
+++ b/packages/server/src/metrics-sampler.ts
@@ -2,17 +2,21 @@ import type { Db } from './db/db';
 import { countByState, listSandboxes } from './db/ledger';
 import { insertMetricsTick } from './db/metrics';
 import type { Executor, SandboxMetrics } from './executor/executor';
+import { type CpuSampler, readHostSample } from './host-metrics';
 
 /**
- * The metrics sampler: one tick reads every measurable sandbox and the
- * fleet's state census, and persists both. This is the daemon keeping
- * history — a reversal of the original "observation window, not a
- * monitoring system" stance, overturned for three reasons (2026-07-15):
- * the E2B metrics endpoint's start/end slice is a compatibility contract
- * we were answering with a single sample; per-sandbox readings cannot be
- * scraped from outside the ledger (host trends still belong to
- * Prometheus); and the console was hoarding session-local history in the
- * browser as a workaround. What did NOT reverse: observation never wakes a
+ * The metrics sampler: one tick reads every measurable sandbox, the
+ * fleet's state census and the host machine itself, and persists all
+ * three. This is the daemon keeping history — a reversal of the original
+ * "observation window, not a monitoring system" stance, overturned for
+ * three reasons (2026-07-15): the E2B metrics endpoint's start/end slice
+ * is a compatibility contract we were answering with a single sample;
+ * per-sandbox readings cannot be scraped from outside the ledger; and the
+ * console was hoarding session-local history in the browser as a
+ * workaround. Host history joined 2026-07-21 ("host trends belong to
+ * Prometheus" was the last holdout of that stance): on a self-hosted
+ * single box nobody runs Prometheus, and overcommit-by-observation needs
+ * a peak to observe. What did NOT reverse: observation never wakes a
  * sandbox — executor.metrics reads running and paused containers alike and
  * starts nothing — and a window the daemon slept through stays honestly
  * empty.
@@ -41,7 +45,17 @@ export async function sampleOnce(
   db: Db,
   executor: Executor,
   now: Date,
-  opts: { retentionHours: number },
+  opts: {
+    retentionHours: number;
+    /**
+     * The ticker's OWN CpuSampler (main.ts constructs it once and primes
+     * it) — never the getHostMetrics route's: a shared instance would let
+     * every console poll reset the delta window and turn the persisted
+     * 30s readings into noise.
+     */
+    hostCpu: CpuSampler;
+    dataDir: string;
+  },
 ): Promise<SampleResult> {
   const rows = listSandboxes(db);
   const { byState, total } = countByState(rows);
@@ -65,9 +79,11 @@ export async function sampleOnce(
     ),
   );
   const samples = readings.filter((reading) => reading !== null);
+  const host = await readHostSample(opts.hostCpu, opts.dataDir);
   insertMetricsTick(db, {
     at: now.toISOString(),
     fleetCounts: { ...byState, total },
+    host,
     samples,
     retentionHours: opts.retentionHours,
   });
diff --git a/packages/server/src/routes/host.ts b/packages/server/src/routes/host.ts
index fc759e9..ca733c1 100644
--- a/packages/server/src/routes/host.ts
+++ b/packages/server/src/routes/host.ts
@@ -2,6 +2,8 @@ import os from 'node:os';
 import {
   getFleetTimelineRequestSchema,
   getFleetTimelineResponseSchema,
+  getHostMetricsHistoryRequestSchema,
+  getHostMetricsHistoryResponseSchema,
   hostMetricsResponseSchema,
 } from '@dormice/shared';
 import type { FastifyPluginAsyncZod } from 'fastify-type-provider-zod';
@@ -9,9 +11,12 @@ import type { Config } from '../config';
 import type { Db } from '../db/db';
 import { countByState, listSandboxes } from '../db/ledger';
 import {
+  bucketHostSamples,
   bucketSnapshots,
   queryFleetPeak,
   queryFleetSnapshots,
+  queryHostCpuPeak,
+  queryHostSamples,
   resolveBucketSeconds,
   resolveWindow,
 } from '../db/metrics';
@@ -75,6 +80,63 @@ export const hostRoutes: FastifyPluginAsyncZod<HostRoutesOptions> = async (
     },
   );
 
+  // The machine's past: one host reading per sampler tick, sliced and
+  // (past 360 points) bucketed by per-field worst case — max for usage,
+  // min for the "available" fields. The CPU peak travels beside the points
+  // from raw rows, immune to bucketing. Nulls are platform gaps (no swap,
+  // no data dir, no delta on the first tick), and a window the daemon
+  // slept through has no rows: the gap IS the answer.
+  app.post(
+    '/getHostMetricsHistory',
+    {
+      schema: {
+        body: getHostMetricsHistoryRequestSchema,
+        response: { 200: getHostMetricsHistoryResponseSchema },
+      },
+    },
+    async (request) => {
+      const { startIso, endIso, startMs, endMs } = resolveWindow(
+        request.body.start,
+        request.body.end,
+        24 * 3600_000,
+        new Date(),
+      );
+      const rows = queryHostSamples(db, startIso, endIso);
+      const bucketSeconds = resolveBucketSeconds(rows.length, startMs, endMs);
+      const points =
+        bucketSeconds === null
+          ? rows
+          : bucketHostSamples(rows, startMs, bucketSeconds);
+      return {
+        points: points.map((row) => ({
+          at: row.at,
+          cpuUsedPct: row.cpuUsedPct,
+          memTotalBytes: row.memTotalBytes,
+          memAvailableBytes: row.memAvailableBytes,
+          swap:
+            row.swapTotalBytes !== null && row.swapUsedBytes !== null
+              ? {
+                  totalBytes: row.swapTotalBytes,
+                  usedBytes: row.swapUsedBytes,
+                }
+              : null,
+          dataDisk:
+            row.diskTotalBytes !== null &&
+            row.diskUsedBytes !== null &&
+            row.diskAvailableBytes !== null
+              ? {
+                  totalBytes: row.diskTotalBytes,
+                  usedBytes: row.diskUsedBytes,
+                  availableBytes: row.diskAvailableBytes,
+                }
+              : null,
+        })),
+        bucketSeconds,
+        peak: queryHostCpuPeak(db, startIso, endIso),
+      };
+    },
+  );
+
   // The fleet's past: state counts per sampler tick, sliced and (past 360
   // points) bucketed. Buckets carry whole raw snapshots — the last one in
   // the bucket — so byState always sums to total; the concurrency peak is
diff --git a/packages/server/src/routes/observability.test.ts b/packages/server/src/routes/observability.test.ts
index 503ad1d..70fc000 100644
--- a/packages/server/src/routes/observability.test.ts
+++ b/packages/server/src/routes/observability.test.ts
@@ -7,6 +7,7 @@ import {
   type ConfigEntry,
   getConfigResponseSchema,
   getFleetTimelineResponseSchema,
+  getHostMetricsHistoryResponseSchema,
   getSandboxMetricsHistoryResponseSchema,
   getSandboxMetricsResponseSchema,
   listActivityResponseSchema,
@@ -24,6 +25,7 @@ import { migrateDb, openDb } from '../db/db';
 import { insertMetricsTick, MAX_POINTS } from '../db/metrics';
 import { activity } from '../db/schema';
 import { FAKE_BASE_IMAGE, FakeExecutor } from '../executor/fake';
+import { CpuSampler, type HostSample } from '../host-metrics';
 import { KeyedQueue } from '../keyed-queue';
 import { freezeSandbox, stopSandbox } from '../lifecycle';
 import { sampleOnce } from '../metrics-sampler';
@@ -79,6 +81,34 @@ async function events(app: App): Promise<ActivityEvent[]> {
   return listActivityResponseSchema.parse(res.json()).events;
 }
 
+// One tick's non-sandbox inputs. A fresh CpuSampler per call is fine: its
+// delta-less first reading is an honest null; the data dir doesn't exist,
+// so disk is null too.
+function tickOpts() {
+  return {
+    retentionHours: 168,
+    hostCpu: new CpuSampler(),
+    dataDir: '/nowhere/dormice-observability-test',
+  };
+}
+
+// A fixed host reading for straight-to-the-writer tests; hostReading(cpu)
+// varies the one field the history assertions care about.
+const HOST: HostSample = hostReading(12);
+
+function hostReading(cpuUsedPct: number | null): HostSample {
+  return {
+    cpuUsedPct,
+    memTotalBytes: 4096,
+    memAvailableBytes: 2048,
+    swapTotalBytes: 1024,
+    swapUsedBytes: 256,
+    diskTotalBytes: null,
+    diskUsedBytes: null,
+    diskAvailableBytes: null,
+  };
+}
+
 describe('getConfig', () => {
   it('reports every knob with value and source, and validates', async () => {
     const { app } = testApp({ DORMICE_MAX_SANDBOXES: '7' });
@@ -334,9 +364,7 @@ describe('getSandboxMetricsHistory', () => {
     await rpc(app, '/acquireSandbox', { name: 'sliced' });
     const t0 = Date.parse('2026-07-15T10:00:00.000Z');
     for (let i = 0; i < 3; i += 1) {
-      await sampleOnce(db, executor, new Date(t0 + i * 30_000), {
-        retentionHours: 168,
-      });
+      await sampleOnce(db, executor, new Date(t0 + i * 30_000), tickOpts());
     }
     const res = await rpc(app, '/getSandboxMetricsHistory', {
       name: 'sliced',
@@ -362,6 +390,7 @@ describe('getSandboxMetricsHistory', () => {
     for (let i = 0; i < rows; i += 1) {
       insertMetricsTick(db, {
         at: new Date(t0 + i * 30_000).toISOString(),
+        host: HOST,
         fleetCounts: {
           active: 1,
           frozen: 0,
@@ -409,11 +438,9 @@ describe('getFleetTimeline', () => {
     const { app, db, executor } = testApp();
     await rpc(app, '/acquireSandbox', { name: 'one' });
     const t0 = Date.parse('2026-07-15T10:00:00.000Z');
-    await sampleOnce(db, executor, new Date(t0), { retentionHours: 168 });
+    await sampleOnce(db, executor, new Date(t0), tickOpts());
     await rpc(app, '/acquireSandbox', { name: 'two' });
-    await sampleOnce(db, executor, new Date(t0 + 30_000), {
-      retentionHours: 168,
-    });
+    await sampleOnce(db, executor, new Date(t0 + 30_000), tickOpts());
 
     const res = await rpc(app, '/getFleetTimeline', {
       start: new Date(t0 - 1000).toISOString(),
@@ -451,6 +478,7 @@ describe('getFleetTimeline', () => {
     for (let i = 0; i < rows; i += 1) {
       insertMetricsTick(db, {
         at: new Date(t0 + i * 30_000).toISOString(),
+        host: HOST,
         fleetCounts: counts(1),
         samples: [],
         retentionHours: 168,
@@ -461,12 +489,14 @@ describe('getFleetTimeline', () => {
     // field is the only honest carrier.
     insertMetricsTick(db, {
       at: new Date(t0 + 200 * 30_000 + 1000).toISOString(),
+      host: HOST,
       fleetCounts: counts(9),
       samples: [],
       retentionHours: 168,
     });
     insertMetricsTick(db, {
       at: new Date(t0 + 200 * 30_000 + 2000).toISOString(),
+      host: HOST,
       fleetCounts: counts(1),
       samples: [],
       retentionHours: 168,
@@ -492,6 +522,132 @@ describe('getFleetTimeline', () => {
   });
 });
 
+describe('getHostMetricsHistory', () => {
+  it('answers an empty window with no points and a null peak', async () => {
+    const { app } = testApp();
+    const res = await rpc(app, '/getHostMetricsHistory', {});
+    expect(res.statusCode).toBe(200);
+    const body = getHostMetricsHistoryResponseSchema.parse(res.json());
+    expect(body).toEqual({ points: [], bucketSeconds: null, peak: null });
+  });
+
+  it('rejects an unparseable timestamp at the door', async () => {
+    const { app } = testApp();
+    const res = await rpc(app, '/getHostMetricsHistory', {
+      start: 'yesterday-ish',
+    });
+    expect(res.statusCode).toBe(400);
+  });
+
+  it('slices ascending with real readings, nulls staying honest', async () => {
+    const { app, db, executor } = testApp();
+    const t0 = Date.parse('2026-07-15T10:00:00.000Z');
+    for (let i = 0; i < 3; i += 1) {
+      await sampleOnce(db, executor, new Date(t0 + i * 30_000), tickOpts());
+    }
+    const res = await rpc(app, '/getHostMetricsHistory', {
+      start: new Date(t0 + 15_000).toISOString(),
+      end: new Date(t0 + 65_000).toISOString(),
+    });
+    const { points, bucketSeconds } = getHostMetricsHistoryResponseSchema.parse(
+      res.json(),
+    );
+    expect(bucketSeconds).toBe(null);
+    expect(points.map((p) => p.at)).toEqual([
+      new Date(t0 + 30_000).toISOString(),
+      new Date(t0 + 60_000).toISOString(),
+    ]);
+    for (const point of points) {
+      // Real memory from this very machine; honest nulls for the missing
+      // data dir and the CPU delta a fresh sampler doesn't have.
+      expect(point.memTotalBytes).toBeGreaterThan(0);
+      expect(point.memAvailableBytes).toBeGreaterThan(0);
+      expect(point.dataDisk).toBe(null);
+      expect(point.cpuUsedPct).toBe(null);
+    }
+  });
+
+  it('buckets by per-field worst case and carries the CPU peak raw', async () => {
+    const { app, db } = testApp();
+    const t0 = Date.parse('2026-07-15T00:00:00.000Z');
+    const rows = MAX_POINTS + 40;
+    for (let i = 0; i < rows; i += 1) {
+      insertMetricsTick(db, {
+        at: new Date(t0 + i * 30_000).toISOString(),
+        // One reading spikes; every neighbor idles. Averaging would bury it.
+        host: hostReading(i === 200 ? 95 : 5),
+        fleetCounts: {
+          active: 0,
+          frozen: 0,
+          stopped: 0,
+          archived: 0,
+          restoring: 0,
+          total: 0,
+        },
+        samples: [],
+        retentionHours: 168,
+      });
+    }
+    const res = await rpc(app, '/getHostMetricsHistory', {
+      start: new Date(t0).toISOString(),
+      end: new Date(t0 + rows * 30_000).toISOString(),
+    });
+    const { points, bucketSeconds, peak } =
+      getHostMetricsHistoryResponseSchema.parse(res.json());
+    expect(bucketSeconds).not.toBe(null);
+    expect(points.length).toBeLessThanOrEqual(MAX_POINTS);
+    // Ascending, and the bucket holding the spike reports the spike.
+    const times = points.map((p) => Date.parse(p.at));
+    expect([...times].sort((a, b) => a - b)).toEqual(times);
+    expect(Math.max(...points.map((p) => p.cpuUsedPct ?? 0))).toBe(95);
+    // The peak is computed from raw rows, at the raw instant — not the
+    // bucket's synthetic start.
+    expect(peak).toEqual({
+      cpuUsedPct: 95,
+      at: new Date(t0 + 200 * 30_000).toISOString(),
+    });
+  });
+
+  it('a null-CPU tick never competes for the peak', async () => {
+    const { app, db } = testApp();
+    const t0 = Date.parse('2026-07-15T10:00:00.000Z');
+    const counts = {
+      active: 0,
+      frozen: 0,
+      stopped: 0,
+      archived: 0,
+      restoring: 0,
+      total: 0,
+    };
+    insertMetricsTick(db, {
+      at: new Date(t0).toISOString(),
+      host: hostReading(null),
+      fleetCounts: counts,
+      samples: [],
+      retentionHours: 168,
+    });
+    insertMetricsTick(db, {
+      at: new Date(t0 + 30_000).toISOString(),
+      host: hostReading(40),
+      fleetCounts: counts,
+      samples: [],
+      retentionHours: 168,
+    });
+    const res = await rpc(app, '/getHostMetricsHistory', {
+      start: new Date(t0).toISOString(),
+      end: new Date(t0 + 60_000).toISOString(),
+    });
+    const { points, peak } = getHostMetricsHistoryResponseSchema.parse(
+      res.json(),
+    );
+    expect(points).toHaveLength(2);
+    expect(peak).toEqual({
+      cpuUsedPct: 40,
+      at: new Date(t0 + 30_000).toISOString(),
+    });
+  });
+});
+
 describe('listSandboxMetrics', () => {
   it('measures active and frozen sandboxes; colder states are absent', async () => {
     const { app, db, executor } = testApp();
diff --git a/packages/shared/src/host.ts b/packages/shared/src/host.ts
index 32c97ed..ad695f5 100644
--- a/packages/shared/src/host.ts
+++ b/packages/shared/src/host.ts
@@ -3,12 +3,8 @@ import { z } from 'zod';
 /**
  * getHostMetrics() — the observation window into the machine itself: is the
  * host healthy, and what do the sandboxes collectively cost it? A single
- * point-in-time snapshot: host-level trends (CPU, memory, disk) remain a
- * monitoring system's job — point Prometheus at the box. What the daemon
- * does keep is its own domain history — per-sandbox samples and fleet state
- * counts (getFleetTimeline in metrics.ts), which no external monitor can
- * reconstruct from outside the ledger. Observation never wakes a sandbox
- * and never touches lifecycle.
+ * point-in-time snapshot; for the machine's past see getHostMetricsHistory
+ * below. Observation never wakes a sandbox and never touches lifecycle.
  *
  * Readings a platform cannot produce are null, honestly — never zero, never
  * invented: swap and /proc are Linux facts, and the data directory only
@@ -82,3 +78,95 @@ export const hostMetricsResponseSchema = z.object({
 });
 
 export type HostMetricsResponse = z.infer<typeof hostMetricsResponseSchema>;
+
+/**
+ * getHostMetricsHistory(start?, end?) — the machine's sampled past: the
+ * host-level sibling of getSandboxMetricsHistory, written by the same
+ * background sampler tick and kept a fixed 30 days. This verb exists
+ * because the original "host trends belong to Prometheus" ruling was
+ * overturned (2026-07-21): on a self-hosted single box nobody runs
+ * Prometheus, and the platform's own capacity story — overcommit by
+ * observation — needs a CPU peak to observe.
+ *
+ * Wire honesty follows the sibling verbs:
+ * - start/end are ISO 8601. Defaults: end = now, start = end - 24h (the
+ *   fleet timeline's window, not the per-sandbox verb's 1h — both feed the
+ *   same dashboard).
+ * - Raw rows up to 360 points, bucketed past that (bucketSeconds says how
+ *   wide). Buckets keep a per-field envelope of the WORST case: max for
+ *   usage fields, min for the "available" fields — a memory-pressure spike
+ *   is a low point of MemAvailable, and averaging (or a max) would erase
+ *   exactly what the reader came for. Bucket timestamps are synthetic
+ *   (the bucket's start).
+ * - The window's CPU peak is computed from raw rows and travels beside the
+ *   points, immune to bucketing. Null when the window holds no CPU reading.
+ * - Gaps are real: a daemon that was down sampled nothing. Nulls inside a
+ *   point are platform gaps (no swap on this box, no data dir yet, no CPU
+ *   delta on the first tick after a start), never zeros.
+ */
+export const hostTimelinePointSchema = z.object({
+  /** ISO 8601 UTC — sample time, or the bucket's start once bucketed. */
+  at: z.string(),
+  /** Percent of the whole machine, 0-100. */
+  cpuUsedPct: z.number().nullable(),
+  memTotalBytes: z.number(),
+  memAvailableBytes: z.number(),
+  swap: z
+    .object({
+      totalBytes: z.number(),
+      usedBytes: z.number(),
+    })
+    .nullable(),
+  dataDisk: z
+    .object({
+      totalBytes: z.number(),
+      usedBytes: z.number(),
+      availableBytes: z.number(),
+    })
+    .nullable(),
+});
+
+export type HostTimelinePoint = z.infer<typeof hostTimelinePointSchema>;
+
+/**
+ * A parseable timestamp, rejected at the door — same rule as the metrics
+ * verbs: a malformed start/end must 400, never become NaN arithmetic.
+ */
+const isoTimestampSchema = z
+  .string()
+  .refine((value) => !Number.isNaN(Date.parse(value)), {
+    message: 'must be an ISO 8601 timestamp',
+  });
+
+export const getHostMetricsHistoryRequestSchema = z.object({
+  /** ISO 8601; defaults to 24 hours before `end`. */
+  start: isoTimestampSchema.optional(),
+  /** ISO 8601; defaults to now. */
+  end: isoTimestampSchema.optional(),
+});
+
+export type GetHostMetricsHistoryRequest = z.infer<
+  typeof getHostMetricsHistoryRequestSchema
+>;
+
+export const getHostMetricsHistoryResponseSchema = z.object({
+  /** Ascending by timestamp. */
+  points: z.array(hostTimelinePointSchema),
+  /** Null when raw samples were returned unbucketed. */
+  bucketSeconds: z.number().int().positive().nullable(),
+  /**
+   * Highest whole-machine CPU percentage in the window, from raw rows (not
+   * buckets), with the earliest instant it was observed. Null when the
+   * window holds no CPU reading at all.
+   */
+  peak: z
+    .object({
+      cpuUsedPct: z.number(),
+      at: z.string(),
+    })
+    .nullable(),
+});
+
+export type GetHostMetricsHistoryResponse = z.infer<
+  typeof getHostMetricsHistoryResponseSchema
+>;
diff --git a/packages/shared/src/metrics.ts b/packages/shared/src/metrics.ts
index 91d4fad..dd690cf 100644
--- a/packages/shared/src/metrics.ts
+++ b/packages/shared/src/metrics.ts
@@ -79,7 +79,7 @@ export type ListSandboxMetricsResponse = z.infer<
  * verb slices that history. History exists because it is a compatibility
  * contract (the E2B metrics endpoint takes start/end) and because no
  * external monitor can measure per-sandbox from outside the ledger —
- * host-level trends still belong to Prometheus.
+ * host-level history lives beside it (getHostMetricsHistory in host.ts).
  *
  * Wire honesty rules:
  * - start/end are ISO 8601 (unix seconds are the E2B surface's dialect,

From 7d4ab1e6a798c7f01b25b544d88a6620a18b393a Mon Sep 17 00:00:00 2001
From: Annactswell <annactswell@qq.com>
Date: Wed, 22 Jul 2026 19:51:25 +0800
Subject: [PATCH 122/133] =?UTF-8?q?=E5=86=B7=E5=94=A4=E9=86=92=E6=94=B6?=
 =?UTF-8?q?=E6=95=9B=E5=88=B0=E6=A8=A1=E6=9D=BF=E5=BD=93=E5=89=8D=E9=95=9C?=
 =?UTF-8?q?=E5=83=8F:=E6=A8=A1=E6=9D=BF=E5=8D=87=E7=BA=A7=E4=BB=8E"?=
 =?UTF-8?q?=E5=8F=AA=E6=83=A0=E5=8F=8A=E6=96=B0=E6=B2=99=E7=AE=B1"?=
 =?UTF-8?q?=E5=8F=98=E6=88=90"=E5=AD=98=E9=87=8F=E4=B8=8B=E6=AC=A1?=
 =?UTF-8?q?=E9=86=92=E6=9D=A5=E8=87=AA=E5=8A=A8=E5=85=91=E7=8E=B0"?=
 =?UTF-8?q?=E3=80=82=E7=A9=BA=E7=BC=BA=E7=9A=84=E5=AE=9E=E7=9B=B8(2026-07-?=
 =?UTF-8?q?22=20=E6=A0=B8=E5=AE=9E):=E6=A8=A1=E6=9D=BF=E9=87=8D=E6=B3=A8?=
 =?UTF-8?q?=E5=86=8C=E5=90=8E,frozen=20=E5=94=A4=E9=86=92=E8=B5=B0=20unpau?=
 =?UTF-8?q?se=20=E5=8E=9F=E5=A3=B3=E5=A4=8D=E6=B4=BB=E6=B0=B8=E4=B8=8D?=
 =?UTF-8?q?=E7=9C=8B=E9=95=9C=E5=83=8F,stopped=20=E5=B8=A6=E5=AD=98?=
 =?UTF-8?q?=E6=B4=BB=E5=A3=B3=E7=9A=84=E5=94=A4=E9=86=92=E4=B9=9F=E4=B8=80?=
 =?UTF-8?q?=E6=A0=B7=E2=80=94=E2=80=94docker=20stop=20=E6=98=AF=20kill=20?=
 =?UTF-8?q?=E4=B8=8D=20remove,=E5=A3=B3=E8=BF=98=E5=9C=A8=E6=97=B6=20start?=
 =?UTF-8?q?=20=E5=8F=AA=E6=98=AF=E5=90=AF=E5=8A=A8=E3=80=81image=20?=
 =?UTF-8?q?=E5=8F=82=E6=95=B0=E6=A0=B9=E6=9C=AC=E7=94=A8=E4=B8=8D=E4=B8=8A?=
 =?UTF-8?q?(start=20=E5=8F=AA=E5=9C=A8=E5=A3=B3=E8=A2=AB=20prune=20?=
 =?UTF-8?q?=E8=92=B8=E5=8F=91=E5=90=8E=E6=89=8D=E7=94=A8=E5=BD=93=E5=89=8D?=
 =?UTF-8?q?=E9=95=9C=E5=83=8F=E9=87=8D=E5=BB=BA);=E8=80=8C=E9=97=B2?=
 =?UTF-8?q?=E7=BD=AE=E6=B2=99=E7=AE=B1=E7=9A=84=E5=B8=B8=E9=A9=BB=E5=BD=A2?=
 =?UTF-8?q?=E6=80=81=E6=81=B0=E6=98=AF=20frozen,=E7=BB=93=E6=9E=9C?=
 =?UTF-8?q?=E5=AD=98=E9=87=8F=E5=AE=9E=E9=99=85=E6=B0=B8=E4=B8=8D=E5=8D=87?=
 =?UTF-8?q?=E7=BA=A7,=E5=8F=AA=E8=83=BD=E4=BA=BA=E5=B7=A5=E9=80=90?=
 =?UTF-8?q?=E5=8F=B0=20rebuildSandbox=E3=80=82=E4=BC=A0=E8=AF=9D=E6=96=B9?=
 =?UTF-8?q?=E6=A1=88=E5=8F=AA=E6=8F=90=20frozen,=E6=A0=B8=E4=BB=A3?=
 =?UTF-8?q?=E7=A0=81=E6=97=B6=E6=8A=8A=20stopped=20=E8=BF=99=E5=8D=8A?=
 =?UTF-8?q?=E4=B8=AA=E6=B4=9E=E4=B8=80=E5=B9=B6=E6=8F=AA=E5=87=BA,?=
 =?UTF-8?q?=E6=94=B6=E6=95=9B=E8=A7=84=E5=88=99=E4=B8=80=E5=88=80=E5=88=87?=
 =?UTF-8?q?:=E4=B8=80=E5=88=87=E5=86=B7=E5=90=AF=E5=8A=A8=E4=B8=8E?=
 =?UTF-8?q?=E8=A7=A3=E5=86=BB=E9=83=BD=E7=94=A8=E6=A8=A1=E6=9D=BF=E5=BD=93?=
 =?UTF-8?q?=E5=89=8D=E9=95=9C=E5=83=8F=E3=80=82=E8=90=BD=E6=B3=95(?=
 =?UTF-8?q?=E5=8D=95=E4=B8=80=E8=A3=81=E5=86=B3=E7=82=B9,lifecycle.ts=20?=
 =?UTF-8?q?=E4=B8=80=E5=A4=84):wakeSandbox=20=E5=AF=B9=20frozen/stopped=20?=
 =?UTF-8?q?=E4=B8=A4=E5=86=B7=E6=80=81=E5=94=A4=E9=86=92=E5=89=8D=E5=81=9A?=
 =?UTF-8?q?=20stale=20=E5=88=A4=E5=AE=9A=E2=80=94=E2=80=94executor.imageOf?=
 =?UTF-8?q?(=E5=A3=B3=E7=9A=84=E5=87=BA=E7=94=9F=E9=95=9C=E5=83=8F)?=
 =?UTF-8?q?=E5=AF=B9=E6=AF=94=20resolveImage=20=3F=3F=20executor.baseImage?=
 =?UTF-8?q?,=E4=B8=8E=20listSandboxImages=20=E7=9A=84=20upgradable=20?=
 =?UTF-8?q?=E8=A3=81=E5=86=B3=E5=90=8C=E4=B8=80=E5=8F=A3=E5=BE=84;imageOf?=
 =?UTF-8?q?=20null(=E5=A3=B3=E6=B6=88=E5=A4=B1=E4=B8=AD)=E4=B8=8D=E5=88=A4?=
 =?UTF-8?q?=20stale,=E4=B8=8B=E6=AC=A1=20start=20=E6=9C=AC=E6=9D=A5?=
 =?UTF-8?q?=E5=B0=B1=E7=94=A8=E5=BD=93=E5=89=8D=E9=95=9C=E5=83=8F,?=
 =?UTF-8?q?=E8=AF=AD=E4=B9=89=E8=87=AA=E6=B4=BD=E3=80=82=E4=B8=80=E8=87=B4?=
 =?UTF-8?q?=E2=86=92=E5=8E=9F=E8=B7=AF=E5=88=86=E6=AF=AB=E4=B8=8D=E5=8A=A8?=
 =?UTF-8?q?(frozen=20=E6=AF=AB=E7=A7=92=E7=BA=A7=20unpause=20/=20stopped?=
 =?UTF-8?q?=20=E5=8E=9F=E5=AE=B9=E5=99=A8=20start,=E5=8F=AA=E5=A4=9A?=
 =?UTF-8?q?=E4=B8=80=E6=AC=A1=E6=9C=AC=E6=9C=BA=20inspect);=E4=B8=8D?=
 =?UTF-8?q?=E4=B8=80=E8=87=B4=E2=86=92=E5=A4=8D=E7=94=A8=20rebuildSandbox?=
 =?UTF-8?q?=20=E5=88=A0=E5=A3=B3(activity=20=E8=AE=B0=20rebuilt,detail=20?=
 =?UTF-8?q?=E5=86=99=E6=98=8E=20stale=20shell=20swapped=20at=20wake:=20?=
 =?UTF-8?q?=E6=97=A7=20->=20=E6=96=B0)=E5=90=8E=E8=90=BD=E5=85=A5=20stoppe?=
 =?UTF-8?q?d=20=E5=88=86=E6=94=AF=E7=94=A8=E5=BD=93=E5=89=8D=E9=95=9C?=
 =?UTF-8?q?=E5=83=8F=E8=B5=B7=E5=A3=B3,activity=20=E5=86=8D=E8=AE=B0=20wok?=
 =?UTF-8?q?en=E2=80=94=E2=80=94=E5=88=BB=E6=84=8F=E4=B8=8D=E5=8F=A6?=
 =?UTF-8?q?=E5=86=99=E6=8D=A2=E5=A3=B3=E9=80=BB=E8=BE=91:reality-first=20?=
 =?UTF-8?q?=E7=BA=AA=E5=BE=8B=E4=B8=8D=E7=A0=B4,=E5=AE=A1=E8=AE=A1?=
 =?UTF-8?q?=E5=85=8D=E8=B4=B9,=E5=88=A0=E5=A3=B3=E4=B8=8E=E8=B5=B7?=
 =?UTF-8?q?=E5=A3=B3=E4=B9=8B=E9=97=B4=E5=B4=A9=E6=BA=83=E8=A1=8C=E8=AF=9A?=
 =?UTF-8?q?=E5=AE=9E=E8=90=BD=E5=9C=A8=20stopped=20=E4=B8=8B=E6=AC=A1?=
 =?UTF-8?q?=E8=A7=A6=E7=A2=B0=E8=87=AA=E7=84=B6=E7=BB=AD=E8=B5=B7,?=
 =?UTF-8?q?=E9=9B=B6=E6=96=B0=E5=A2=9E=E5=A4=B1=E8=B4=A5=E5=85=9C=E5=BA=95?=
 =?UTF-8?q?=E3=80=82=E5=B9=B6=E5=8F=91=E9=9D=A2=E9=9B=B6=E6=96=B0=E5=A2=9E?=
 =?UTF-8?q?:=E5=85=A8=E9=83=A8=E4=B8=83=E4=B8=AA=E5=94=A4=E9=86=92?=
 =?UTF-8?q?=E5=85=A5=E5=8F=A3(=E5=8E=9F=E7=94=9F=20acquire/wakeForUse?=
 =?UTF-8?q?=E3=80=81envd=C3=972=E3=80=81e2b=20control=C3=972=E3=80=81?=
 =?UTF-8?q?=E7=AB=AF=E5=8F=A3=E4=BB=A3=E7=90=86)=E9=80=90=E4=B8=AA?=
 =?UTF-8?q?=E6=A0=B8=E5=AE=9E=E9=83=BD=E5=9C=A8=20per-sandbox=20=E9=94=81?=
 =?UTF-8?q?=E6=A7=BD=E5=86=85;removeContainer=20=E5=AF=B9=20paused=20gViso?=
 =?UTF-8?q?r=20=E5=A3=B3=E5=85=88=20unpause=20=E5=86=8D=20kill=20=E7=9A=84?=
 =?UTF-8?q?=E6=97=A2=E6=9C=89=E5=A4=84=E7=90=86=E7=9B=B4=E6=8E=A5=E5=8F=97?=
 =?UTF-8?q?=E7=9B=8A=E3=80=82=E8=AF=9A=E5=AE=9E=E4=BB=A3=E4=BB=B7=E8=AE=B0?=
 =?UTF-8?q?=E6=A1=A3:frozen=20=E6=98=AF=20docker=20pause,=E8=BF=9B?=
 =?UTF-8?q?=E7=A8=8B=E4=B8=8E=E5=86=85=E5=AD=98=E9=83=BD=E6=B4=BB=E7=9D=80?=
 =?UTF-8?q?,=E6=8D=A2=E5=A3=B3=E6=9D=80=E6=8E=89=E5=AE=83=E4=BB=AC?=
 =?UTF-8?q?=E2=80=94=E2=80=94=E5=9C=A8=20crash-only=20=E5=A5=91=E7=BA=A6?=
 =?UTF-8?q?=E5=86=85(=E4=BB=A3=E7=A0=81=E6=9C=AC=E5=B0=B1=E8=A6=81?=
 =?UTF-8?q?=E6=B4=BB=E8=BF=87=E5=AE=B9=E5=99=A8=E8=92=B8=E5=8F=91),?=
 =?UTF-8?q?=E4=B8=94=E5=8F=AA=E7=94=B1=E8=BF=90=E8=90=A5=E8=80=85=E9=87=8D?=
 =?UTF-8?q?=E6=B3=A8=E5=86=8C=E6=A8=A1=E6=9D=BF=E8=BF=99=E4=B8=AA=E6=98=BE?=
 =?UTF-8?q?=E5=BC=8F=E5=8A=A8=E4=BD=9C=E8=A7=A6=E5=8F=91;"stopAfterSeconds?=
 =?UTF-8?q?:null=20=E5=B8=B8=E9=A9=BB=20frozen=20=E6=AF=AB=E7=A7=92?=
 =?UTF-8?q?=E7=BA=A7=E5=94=A4=E9=86=92"=E7=9A=84=E6=89=BF=E8=AF=BA?=
 =?UTF-8?q?=E4=BB=8E=E6=AD=A4=E6=9C=89=E5=94=AF=E4=B8=80=E4=BE=8B=E5=A4=96?=
 =?UTF-8?q?=3D=E5=8D=87=E7=BA=A7=E5=90=8E=E7=AC=AC=E4=B8=80=E6=AC=A1?=
 =?UTF-8?q?=E5=94=A4=E9=86=92=E4=BB=98=E4=B8=80=E6=AC=A1=E6=8D=A2=E5=A3=B3?=
 =?UTF-8?q?(1~3s,=E9=95=9C=E5=83=8F=E5=B7=B2=E5=9C=A8=E6=9C=AC=E6=9C=BA?=
 =?UTF-8?q?=E6=97=A0=E6=8B=89=E5=8F=96,=E4=B8=8E=20stopped=20=E5=86=B7?=
 =?UTF-8?q?=E5=90=AF=E5=8A=A8=E5=90=8C=E9=87=8F=E7=BA=A7),=E4=B9=8B?=
 =?UTF-8?q?=E5=90=8E=E5=9B=9E=E5=88=B0=E5=8E=9F=E8=B7=AF=E3=80=82=E8=BF=9E?=
 =?UTF-8?q?=E5=B8=A6=E8=AF=AD=E4=B9=89:removeTemplate=20=E5=90=8E=E8=AF=A5?=
 =?UTF-8?q?=E6=A8=A1=E6=9D=BF=E7=9A=84=E5=86=B7=E6=80=81=E6=B2=99=E7=AE=B1?=
 =?UTF-8?q?=E4=B8=8B=E6=AC=A1=E5=94=A4=E9=86=92=E6=94=B6=E6=95=9B=E5=88=B0?=
 =?UTF-8?q?=E5=9F=BA=E7=A1=80=E9=95=9C=E5=83=8F(=E4=B8=8E=20upgradable=20?=
 =?UTF-8?q?=E4=BB=8A=E5=A4=A9=E5=B0=B1=E6=A0=87=E8=BF=99=E7=A7=8D=E8=A1=8C?=
 =?UTF-8?q?=E5=AE=8C=E5=85=A8=E4=B8=80=E8=87=B4);=E5=BD=92=E6=A1=A3?=
 =?UTF-8?q?=E6=81=A2=E5=A4=8D=E6=9C=AC=E6=9D=A5=E5=B0=B1=E6=98=AF=E5=BD=93?=
 =?UTF-8?q?=E5=89=8D=E9=95=9C=E5=83=8F=E8=B5=B7=E5=A3=B3,=E4=B8=8D?=
 =?UTF-8?q?=E5=8A=A8=E3=80=82rebuildSandbox=20=E5=8E=9F=E6=A0=B7=E4=BF=9D?=
 =?UTF-8?q?=E7=95=99=E4=B8=BA"=E4=B8=8D=E7=AD=89=E4=B8=8B=E6=AC=A1?=
 =?UTF-8?q?=E5=86=BB=E7=BB=93=E3=80=81=E7=AB=8B=E5=8D=B3=E5=BC=BA=E5=88=B6?=
 =?UTF-8?q?"=E7=9A=84=E5=89=8D=E9=97=A8(=E5=8A=A0=E5=8F=AF=E9=80=89=20deta?=
 =?UTF-8?q?il=20=E5=8F=82=E6=95=B0=E4=BE=9B=E8=87=AA=E5=8A=A8=E6=8D=A2?=
 =?UTF-8?q?=E5=A3=B3=E8=87=AA=E6=8A=A5=E5=AE=B6=E9=97=A8)=E3=80=82?=
 =?UTF-8?q?=E5=9B=9E=E5=BD=92=E9=92=89=E4=B8=89=E5=B1=82:=E5=8D=95?=
 =?UTF-8?q?=E6=B5=8B=E4=BA=94=E6=80=81(frozen+stale=20=E6=8D=A2=E5=A3=B3?=
 =?UTF-8?q?=E4=B8=94=E6=95=B0=E6=8D=AE/=E5=AE=A1=E8=AE=A1=E4=BF=B1?=
 =?UTF-8?q?=E5=85=A8=E3=80=81frozen+fresh=20=E5=8E=9F=E5=A3=B3=E4=B8=8D?=
 =?UTF-8?q?=E5=A4=9A=E4=BB=98=E5=88=A0=E5=A3=B3=E3=80=81stopped+stale=20?=
 =?UTF-8?q?=E5=90=8C=E6=A0=B7=E6=94=B6=E6=95=9B=E3=80=81=E6=97=A0=E6=A8=A1?=
 =?UTF-8?q?=E6=9D=BF=E6=B2=99=E7=AE=B1=E5=AF=B9=E6=AF=94=20baseImage=20?=
 =?UTF-8?q?=E4=B8=8D=E8=AF=AF=E5=88=A4=E3=80=81=E5=A3=B3=E6=B6=88=E5=A4=B1?=
 =?UTF-8?q?=E4=B8=8D=E5=88=A4=20stale=20=E4=BD=86=20start=20=E8=87=AA?=
 =?UTF-8?q?=E5=B7=B1=E6=94=B6=E6=95=9B=E4=B8=94=E4=B8=8D=E8=B0=8E=E6=8A=A5?=
 =?UTF-8?q?=20rebuilt);e2e=20=E4=B8=80=E5=8F=91=E7=9C=9F=20daemon=20?=
 =?UTF-8?q?=E7=9C=9F=20scanner(=E5=86=BB=E7=BB=93=E2=86=92=E9=87=8D?=
 =?UTF-8?q?=E6=B3=A8=E5=86=8C=E2=86=92readFile=20=E8=A7=A6=E7=A2=B0?=
 =?UTF-8?q?=E2=86=92=E6=96=B0=E9=95=9C=E5=83=8F+=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E5=AE=8C=E5=A5=BD+upgradable=20=E6=B8=85=E9=9B=B6+rebuilt/woke?=
 =?UTF-8?q?n=20=E6=9C=89=E5=BA=8F),docker=20=E6=A8=A1=E5=BC=8F=E8=B7=B3?=
 =?UTF-8?q?=E8=BF=87=E2=80=94=E2=80=94=E7=AC=AC=E4=BA=8C=E9=95=9C=E5=83=8F?=
 =?UTF-8?q?=E6=98=AF=E6=9C=AA=E6=9E=84=E5=BB=BA=E5=AD=97=E7=AC=A6=E4=B8=B2?=
 =?UTF-8?q?,=E6=8D=A2=E5=A3=B3=E7=89=A9=E7=90=86=E5=B7=B2=E7=94=B1?=
 =?UTF-8?q?=E7=9C=9F=E6=9C=BA=E5=90=88=E5=90=8C=20image=20=E7=AB=A0=20altI?=
 =?UTF-8?q?mage=20=E5=9B=9B=E9=A2=98+removeContainer=20=E4=BB=8E=20paused?=
 =?UTF-8?q?=20=E6=94=BE=E5=80=92=E9=92=89=E6=AD=BB,=E4=B8=8D=E7=BC=BA?=
 =?UTF-8?q?=E7=9C=9F=E6=9C=BA=E8=A6=86=E7=9B=96;website=20=E4=B8=89?=
 =?UTF-8?q?=E9=A1=B5(templates/lifecycle/resident-agents)=E6=8A=8A"?=
 =?UTF-8?q?=E6=8D=A2=E5=A3=B3=E6=9D=80=E6=B4=BB=E8=BF=9B=E7=A8=8B"?=
 =?UTF-8?q?=E4=B8=8E"=E5=88=A0=E6=A8=A1=E6=9D=BF=E6=8D=A2=E5=9F=BA?=
 =?UTF-8?q?=E7=A1=80=E9=95=9C=E5=83=8F"=E5=86=99=E7=BB=99=E7=94=A8?=
 =?UTF-8?q?=E6=88=B7=E3=80=82=E5=85=A8=E9=93=BE=20build/typecheck/lint=20?=
 =?UTF-8?q?=E5=B9=B2=E5=87=80,server=20521=E3=80=81sdk=2031=E3=80=81cli=20?=
 =?UTF-8?q?59=E3=80=81e2e=2086=20=E5=85=A8=E7=BB=BF=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 e2e/src/native.test.ts                   |  67 ++++++++++
 packages/server/src/app.test.ts          | 151 ++++++++++++++++++++++-
 packages/server/src/lifecycle.ts         |  67 ++++++++--
 website/content/docs/lifecycle.mdx       |   6 +
 website/content/docs/resident-agents.mdx |   5 +-
 website/content/docs/templates.mdx       |  21 ++--
 6 files changed, 294 insertions(+), 23 deletions(-)

diff --git a/e2e/src/native.test.ts b/e2e/src/native.test.ts
index d949659..8dfd563 100644
--- a/e2e/src/native.test.ts
+++ b/e2e/src/native.test.ts
@@ -530,6 +530,73 @@ describe('native API over a real daemon', () => {
     });
   });
 
+  // The swap needs a second image the engine could actually boot, and only
+  // the fake plays arbitrary names — so docker mode skips this exam. Its
+  // physics are pinned on the real machine by the executor contract's
+  // altImage questions (rebuilt shell boots the requested image over the
+  // same disk; removeContainer takes a paused container down).
+  it.skipIf(process.env.DORMICE_EXECUTOR === 'docker')(
+    'a template upgrade reaches a frozen sandbox on its next touch: shell swapped, data kept, audited',
+    async () => {
+      await client().registerTemplate('swap-tpl', 'img:swap-v1');
+      await client().acquireSandbox('swap-key', {
+        template: 'swap-tpl',
+        policy: {
+          freezeAfterSeconds: 1,
+          stopAfterSeconds: null,
+          archiveAfterSeconds: null,
+        },
+      });
+      await client().writeFiles('swap-key', [
+        { path: 'keep.txt', content: 'survives the swap' },
+      ]);
+      // Watch it actually freeze from outside, on real wall-clock time.
+      const deadline = Date.now() + 15_000;
+      for (;;) {
+        const cold = (await client().listSandboxes()).find(
+          (s) => s.name === 'swap-key',
+        );
+        if (cold?.state === 'frozen') break;
+        if (Date.now() > deadline) {
+          throw new Error(
+            `sandbox never reached frozen; last observed: ${cold?.state}`,
+          );
+        }
+        await sleep(0.25);
+      }
+
+      // Operator re-points the template; the frozen shell is now stale.
+      await client().registerTemplate('swap-tpl', 'img:swap-v2');
+
+      // The touch is an ordinary use verb — every wake entry (native, envd,
+      // port proxy) funnels into the same wakeSandbox, and the read itself
+      // proves /home/user crossed the swap intact.
+      const read = await client().readFile('swap-key', 'keep.txt');
+      expect(new TextDecoder().decode(read.content)).toBe('survives the swap');
+
+      // The deployment check: the lineage row reports the new image and the
+      // upgradable flag has cleared.
+      expect(
+        (await client().listSandboxImages()).find(
+          (e) => e.sandboxName === 'swap-key',
+        ),
+      ).toMatchObject({ image: 'img:swap-v2', upgradable: false });
+
+      // Both halves of the move made the audit trail, in order.
+      const story = (await client().listActivity({ limit: 500 })).filter(
+        (e) => e.sandboxName === 'swap-key',
+      );
+      const kinds = story.map((e) => e.kind);
+      expect(kinds.slice(0, 2)).toEqual(['woken', 'rebuilt']);
+      expect(story[1]?.detail).toBe(
+        'stale shell swapped at wake: img:swap-v1 -> img:swap-v2',
+      );
+
+      await client().destroySandbox('swap-key');
+      await client().removeTemplate('swap-tpl');
+    },
+  );
+
   // Registration never checks the image; only a real engine can show what
   // happens when the promise is broken at create time.
   it.runIf(process.env.DORMICE_EXECUTOR === 'docker')(
diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index b6443d0..a2ce5b3 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -1465,7 +1465,7 @@ describe('templates', () => {
     });
   });
 
-  it('re-point then rebuild moves the sandbox onto the new image — the upgrade front door', async () => {
+  it('re-point then rebuild moves the sandbox onto the new image — the immediate front door', async () => {
     const { app, executor } = testApp();
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
     const created = (
@@ -1473,8 +1473,9 @@ describe('templates', () => {
     ).json().sandbox;
     expect(await executor.imageOf(created.id)).toBe('img-v1');
 
-    // Operator builds a new image and re-points the name; the stock moves
-    // per sandbox, on its own rebuild — never behind its back.
+    // Operator builds a new image and re-points the name; a running shell
+    // is never touched behind the sandbox's back — the stock moves on an
+    // explicit rebuild (here) or on the next cold wake (tests below).
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });
     expect(await executor.imageOf(created.id)).toBe('img-v1');
 
@@ -1486,6 +1487,150 @@ describe('templates', () => {
   });
 });
 
+describe('cold wakes converge onto the current image', () => {
+  it('frozen + stale: the wake swaps the shell, keeps the data, and records the swap', async () => {
+    const { app, db, executor, locks } = testApp();
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
+    const created = (
+      await acquire(app, { name: 'alice', template: 'py' })
+    ).json().sandbox;
+    await rpc(app, '/writeFiles', {
+      name: 'alice',
+      files: [
+        {
+          path: 'keep.txt',
+          contentBase64: Buffer.from('survives').toString('base64'),
+        },
+      ],
+    });
+    await scanOnce(
+      db,
+      executor,
+      locks,
+      after(created.lastActiveAt, DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds),
+    );
+    expect(executor.stateOf(created.id)).toBe('paused');
+
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });
+    const woken = (await acquire(app, { name: 'alice' })).json().sandbox;
+    expect(woken.id).toBe(created.id);
+    expect(woken.state).toBe('active');
+    // The new shell, the old body.
+    expect(await executor.imageOf(created.id)).toBe('img-v2');
+    const read = await rpc(app, '/readFile', {
+      name: 'alice',
+      path: 'keep.txt',
+    });
+    expect(Buffer.from(read.json().contentBase64, 'base64').toString()).toBe(
+      'survives',
+    );
+    // The audit trail names both halves of the move.
+    const kinds = (await rpc(app, '/listActivity'))
+      .json()
+      .events.map((e: { kind: string }) => e.kind);
+    expect(kinds.slice(0, 2)).toEqual(['woken', 'rebuilt']);
+    const rebuilt = (await rpc(app, '/listActivity'))
+      .json()
+      .events.find((e: { kind: string }) => e.kind === 'rebuilt');
+    expect(rebuilt.detail).toBe(
+      'stale shell swapped at wake: img-v1 -> img-v2',
+    );
+  });
+
+  it('frozen + fresh: a plain unpause, no shell removed', async () => {
+    const { app, db, executor, locks } = testApp();
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
+    const created = (
+      await acquire(app, { name: 'alice', template: 'py' })
+    ).json().sandbox;
+    await scanOnce(
+      db,
+      executor,
+      locks,
+      after(created.lastActiveAt, DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds),
+    );
+
+    const woken = (await acquire(app, { name: 'alice' })).json().sandbox;
+    expect(woken.state).toBe('active');
+    expect(await executor.imageOf(created.id)).toBe('img-v1');
+    const kinds = (await rpc(app, '/listActivity'))
+      .json()
+      .events.map((e: { kind: string }) => e.kind);
+    expect(kinds).not.toContain('rebuilt');
+  });
+
+  it('stopped + stale: the same convergence — stop kept the old shell, the wake replaces it', async () => {
+    const { app, db, executor, locks } = testApp();
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
+    const created = (
+      await acquire(app, {
+        name: 'alice',
+        template: 'py',
+        policy: { freezeAfterSeconds: 60, stopAfterSeconds: 120 },
+      })
+    ).json().sandbox;
+    await scanOnce(db, executor, locks, after(created.lastActiveAt, 60));
+    await scanOnce(db, executor, locks, after(created.lastActiveAt, 120));
+    // The stopped container object survives, still born from the old image.
+    expect(executor.stateOf(created.id)).toBe('stopped');
+    expect(await executor.imageOf(created.id)).toBe('img-v1');
+
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });
+    const woken = (await acquire(app, { name: 'alice' })).json().sandbox;
+    expect(woken.state).toBe('active');
+    expect(await executor.imageOf(created.id)).toBe('img-v2');
+    const kinds = (await rpc(app, '/listActivity'))
+      .json()
+      .events.map((e: { kind: string }) => e.kind);
+    expect(kinds.slice(0, 2)).toEqual(['woken', 'rebuilt']);
+  });
+
+  it('a template-less sandbox is judged against the base image — fresh, so untouched', async () => {
+    const { app, db, executor, locks } = testApp();
+    const created = (await acquire(app, { name: 'alice' })).json().sandbox;
+    await scanOnce(
+      db,
+      executor,
+      locks,
+      after(created.lastActiveAt, DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds),
+    );
+
+    const woken = (await acquire(app, { name: 'alice' })).json().sandbox;
+    expect(woken.state).toBe('active');
+    expect(await executor.imageOf(created.id)).toBe(executor.baseImage);
+    const kinds = (await rpc(app, '/listActivity'))
+      .json()
+      .events.map((e: { kind: string }) => e.kind);
+    expect(kinds).not.toContain('rebuilt');
+  });
+
+  it('a vanished shell is not judged stale — the start builds from the current image by itself', async () => {
+    const { app, db, executor, locks } = testApp();
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v1' });
+    const created = (
+      await acquire(app, {
+        name: 'alice',
+        template: 'py',
+        policy: { freezeAfterSeconds: 60, stopAfterSeconds: 120 },
+      })
+    ).json().sandbox;
+    await scanOnce(db, executor, locks, after(created.lastActiveAt, 60));
+    await scanOnce(db, executor, locks, after(created.lastActiveAt, 120));
+    executor.vanishContainer(created.id);
+
+    await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });
+    const woken = (await acquire(app, { name: 'alice' })).json().sandbox;
+    expect(woken.state).toBe('active');
+    // Converged all the same, but through start's own rebuild — no shell
+    // was removed, so no 'rebuilt' entry claims one was.
+    expect(await executor.imageOf(created.id)).toBe('img-v2');
+    const kinds = (await rpc(app, '/listActivity'))
+      .json()
+      .events.map((e: { kind: string }) => e.kind);
+    expect(kinds).not.toContain('rebuilt');
+  });
+});
+
 describe('POST /getHostMetrics', () => {
   it('sits behind the token like every API verb', async () => {
     const res = await testApp().app.inject({
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index 1061522..a505126 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -137,15 +137,17 @@ export async function destroySandbox(
  * path builds a fresh container from the surviving disk, and therefore from
  * the *current* image of the sandbox's template (or the daemon's current
  * base image). This is how an existing sandbox picks up new shared layers
- * without losing a byte of /home/user. Already-stopped rows skip the ledger
- * write: removing a pruned-away container is a no-op and stopped -> stopped
- * is not a transition.
+ * without losing a byte of /home/user — immediately, without waiting for
+ * the next wake's own stale-shell convergence (wakeSandbox). Already-stopped
+ * rows skip the ledger write: removing a pruned-away container is a no-op
+ * and stopped -> stopped is not a transition.
  */
 export async function rebuildSandbox(
   db: Db,
   executor: Executor,
   row: SandboxRow,
   actor?: string | null,
+  detail?: string,
 ): Promise<SandboxRow> {
   await executor.removeContainer(row.id);
   recordActivity(db, {
@@ -154,6 +156,7 @@ export async function rebuildSandbox(
     sandboxId: row.id,
     actor,
     detail:
+      detail ??
       'shell removed, disk kept — next wake builds from the current image',
   });
   if (row.state === 'stopped') {
@@ -162,7 +165,27 @@ export async function rebuildSandbox(
   return transition(db, row.id, 'stopped');
 }
 
-/** Brings a sandbox in any cold state back to active. No-op when already active. */
+/**
+ * Brings a sandbox in any cold state back to active. No-op when already
+ * active.
+ *
+ * Every cold wake first converges the shell onto the template's *current*
+ * image — the same verdict listSandboxImages calls `upgradable` (imageOf
+ * against resolveImage ?? baseImage; a null imageOf is not stale: a shell
+ * that does not exist boots the current image by itself). A stale shell is
+ * swapped through rebuildSandbox — removed, ledger to stopped — and the
+ * stopped arm builds the new one; a fresh shell keeps its millisecond
+ * unpause / restart path untouched. This is what makes `dor template add`
+ * reach existing sandboxes: without it a frozen or stopped shell revives
+ * as-is and the fleet never upgrades short of a manual rebuildSandbox
+ * (which stays the front door for "swap now, don't wait for a wake").
+ *
+ * The honest cost: a frozen sandbox is a paused container — its processes
+ * and memory are alive — and the swap kills them for a cold start. That is
+ * within the crash-only contract (code must survive the container
+ * vanishing anyway) and only ever triggered by an operator deliberately
+ * re-registering the template.
+ */
 export async function wakeSandbox(
   db: Db,
   executor: Executor,
@@ -173,15 +196,35 @@ export async function wakeSandbox(
     case 'active':
       return row;
     case 'frozen':
-      await executor.unfreeze(row.id);
-      return awaken(db, row, 'from frozen (memory back out of swap)', actor);
-    case 'stopped':
-      // If the container object was pruned away, start rebuilds the shell —
-      // from the template's current image, resolved here at wake time.
-      await executor.start(row.id, {
-        image: resolveImage(db, row.template),
+    case 'stopped': {
+      const next = resolveImage(db, row.template) ?? executor.baseImage;
+      const born = await executor.imageOf(row.id);
+      const fresh =
+        born !== null && born !== next
+          ? await rebuildSandbox(
+              db,
+              executor,
+              row,
+              actor,
+              `stale shell swapped at wake: ${born} -> ${next}`,
+            )
+          : row;
+      if (fresh.state === 'frozen') {
+        await executor.unfreeze(fresh.id);
+        return awaken(
+          db,
+          fresh,
+          'from frozen (memory back out of swap)',
+          actor,
+        );
+      }
+      // If no container object exists (pruned away, or the stale shell was
+      // just removed), start rebuilds it from the current image.
+      await executor.start(fresh.id, {
+        image: resolveImage(db, fresh.template),
       });
-      return awaken(db, row, 'cold start from the surviving disk', actor);
+      return awaken(db, fresh, 'cold start from the surviving disk', actor);
+    }
     case 'archived':
     case 'restoring':
       // Every legitimate path branches to the archiver before landing here
diff --git a/website/content/docs/lifecycle.mdx b/website/content/docs/lifecycle.mdx
index cfc82c6..8f756f3 100644
--- a/website/content/docs/lifecycle.mdx
+++ b/website/content/docs/lifecycle.mdx
@@ -109,6 +109,12 @@ wake — and never decays to a cold start. Its processes are never killed
 by idleness; they suspend and resume mid-flight, indefinitely. See
 [Resident agents](/docs/resident-agents) for the full pattern.
 
+The one exception: after you [re-register the sandbox's
+template](/docs/templates#update-a-template) onto a new image, its next
+wake swaps the container for one built from that image — a one-time
+cold start that replaces the suspended processes. You asked for the
+upgrade; the wake is when it lands.
+
 ## What counts as activity
 
 Running commands, file operations, and `acquireSandbox` reset the idle
diff --git a/website/content/docs/resident-agents.mdx b/website/content/docs/resident-agents.mdx
index 1cf5220..87d528d 100644
--- a/website/content/docs/resident-agents.mdx
+++ b/website/content/docs/resident-agents.mdx
@@ -30,7 +30,10 @@ processes. A runnable version of this pattern lives at
 A frozen sandbox's processes stop mid-flight and resume exactly where
 they were: a REPL (an interactive language session) keeps its state, a
 dev server its connections, an agent process its memory. Nothing
-running in a resident sandbox is ever killed by idleness.
+running in a resident sandbox is ever killed by idleness. (One deliberate
+exception: [upgrading the sandbox's
+template](/docs/templates#update-a-template) swaps the container on the
+next wake, which restarts it cold.)
 
 **The flip side:** a background process does not *keep* its sandbox
 warm. Once nothing is watching it, the idle clock runs, the sandbox
diff --git a/website/content/docs/templates.mdx b/website/content/docs/templates.mdx
index cab154c..d245d2c 100644
--- a/website/content/docs/templates.mdx
+++ b/website/content/docs/templates.mdx
@@ -46,21 +46,28 @@ surface — never silently substituted with the base image.
 
 ## Update a template
 
-Re-registering a name points it at a new image. Sandboxes pick up the
-new image the next time their container is built — on a rebuild, a cold
-start, or a restore from archive:
+Re-registering a name points it at a new image. Existing sandboxes
+converge onto it on their next wake from any cold state — frozen,
+stopped, or archived — each paying one container swap (a few seconds, no
+image pull) the first time, then back to millisecond wakes:
 
 ```sh
 docker build -t my-agent-env:v2 .
 dor template add my-agent-env my-agent-env:v2  # re-registering re-points the name
-dor sandbox rebuild user-42                    # per sandbox: new container, same /home/user
+dor sandbox rebuild user-42                    # optional: swap one sandbox NOW, don't wait for its next wake
 ```
 
-Until rebuilt (or cold-started), existing sandboxes keep running the
-image they were born on. Through a rebuild, `/home/user` carries over
-untouched and everything outside it resets onto the new image — see
+A running sandbox is never touched behind its back: the swap happens
+only when the sandbox is next woken (or explicitly rebuilt). Through the
+swap, `/home/user` carries over untouched and everything outside it
+resets onto the new image — including any processes a frozen sandbox
+had alive, which is within the platform's crash-only contract (sandboxed
+code must survive its container being replaced anyway). See
 [Rebuild a sandbox](/docs/persistence#rebuild-a-sandbox).
 
+Removing a template's registration follows the same rule: its sandboxes
+converge onto the daemon's base image at their next cold wake.
+
 You can ask which sandboxes still run an old image with the
 `listSandboxImages` verb (SDK method of the same name), or look for the
 "upgradable" marker in the [console](/docs/console)'s sandbox list.

From 3d70399eb598081a69d78ac798f152a87d3ac1eb Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Wed, 22 Jul 2026 06:16:42 -0700
Subject: [PATCH 123/133] Use the current idle clock in the stale-image test

---
 packages/server/src/app.test.ts | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/packages/server/src/app.test.ts b/packages/server/src/app.test.ts
index a2ce5b3..e23358e 100644
--- a/packages/server/src/app.test.ts
+++ b/packages/server/src/app.test.ts
@@ -15,7 +15,7 @@ import { objectKey } from './archive/store';
 import { CONSOLE_HEADER, SESSION_COOKIE } from './auth';
 import { loadConfig } from './config';
 import { migrateDb, openDb } from './db/db';
-import { transition } from './db/ledger';
+import { findById, transition } from './db/ledger';
 import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
 import { ARCHIVE_DEFAULT_SECONDS } from './policy';
@@ -1503,12 +1503,16 @@ describe('cold wakes converge onto the current image', () => {
         },
       ],
     });
-    await scanOnce(
+    const current = findById(db, created.id);
+    if (!current) throw new Error('sandbox disappeared after write');
+    const sweep = await scanOnce(
       db,
       executor,
       locks,
-      after(created.lastActiveAt, DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds),
+      after(current.lastActiveAt, DEFAULT_LIFECYCLE_POLICY.freezeAfterSeconds),
     );
+    expect(sweep.frozen).toBe(1);
+    expect(sweep.failures).toEqual([]);
     expect(executor.stateOf(created.id)).toBe('paused');
 
     await rpc(app, '/registerTemplate', { name: 'py', image: 'img-v2' });

From 07d37ed069fa63b4fd4ff2fdea37041aea3ac3f8 Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Tue, 21 Jul 2026 21:34:20 -0700
Subject: [PATCH 124/133] Keep expired console sessions on the login path

Once a protected RPC proves the session is gone, route the document to login and keep every concurrent caller from surfacing query errors or mutation toasts during teardown. The redirect replaces the stale history entry, preserves the full return URL, and malformed success bodies now retain route and status context instead of leaking a bare JSON parser error.\n\nFocused transport tests establish the redirect, concurrency, auth-form, and strict JSON contracts.
---
 packages/console/package.json        |   1 +
 packages/console/src/lib/api.test.ts | 183 +++++++++++++++++++++++++++
 packages/console/src/lib/api.ts      |  39 ++++--
 3 files changed, 215 insertions(+), 8 deletions(-)
 create mode 100644 packages/console/src/lib/api.test.ts

diff --git a/packages/console/package.json b/packages/console/package.json
index 36ba05f..29692a3 100644
--- a/packages/console/package.json
+++ b/packages/console/package.json
@@ -9,6 +9,7 @@
     "build": "vite build",
     "dev": "vite",
     "seed": "node scripts/seed.mjs",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
diff --git a/packages/console/src/lib/api.test.ts b/packages/console/src/lib/api.test.ts
new file mode 100644
index 0000000..5e16ddb
--- /dev/null
+++ b/packages/console/src/lib/api.test.ts
@@ -0,0 +1,183 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+function stubBrowser(options: { signedIn?: boolean } = {}) {
+  const storage = new Map<string, string>();
+  if (options.signedIn) storage.set('dormice.console.signed-in', '1');
+
+  vi.stubGlobal('localStorage', {
+    getItem: (key: string) => storage.get(key) ?? null,
+    setItem: (key: string, value: string) => storage.set(key, value),
+    removeItem: (key: string) => storage.delete(key),
+  });
+
+  const redirects: string[] = [];
+  const location = {
+    pathname: '/console/sandboxes/alice',
+    search: '?tab=files',
+    hash: '#preview',
+    replace: (value: string) => redirects.push(value),
+  };
+  vi.stubGlobal('window', { location });
+  return { storage, redirects };
+}
+
+const jsonResponse = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+
+async function expectPending(promise: Promise<unknown>) {
+  const fulfilled = vi.fn();
+  const rejected = vi.fn();
+  void promise.then(fulfilled, rejected);
+
+  await Promise.resolve();
+  await Promise.resolve();
+  expect(fulfilled).not.toHaveBeenCalled();
+  expect(rejected).not.toHaveBeenCalled();
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  vi.resetModules();
+});
+
+describe('console RPC transport', () => {
+  it('returns a valid JSON response', async () => {
+    stubBrowser();
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(jsonResponse({ sandboxes: [] })),
+    );
+    const { listSandboxes } = await import('./api');
+
+    await expect(listSandboxes()).resolves.toEqual({ sandboxes: [] });
+  });
+
+  it('throws a named ApiError with the daemon message', async () => {
+    stubBrowser();
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(jsonResponse({ message: 'nope' }, 403)),
+    );
+    const { listSandboxes } = await import('./api');
+
+    await expect(listSandboxes()).rejects.toMatchObject({
+      name: 'ApiError',
+      status: 403,
+      message: 'nope',
+    });
+  });
+
+  it('falls back to route and status for a malformed error body', async () => {
+    stubBrowser();
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(new Response('not json', { status: 500 })),
+    );
+    const { listSandboxes } = await import('./api');
+
+    await expect(listSandboxes()).rejects.toMatchObject({
+      name: 'ApiError',
+      status: 500,
+      message: '/listSandboxes failed with 500',
+    });
+  });
+
+  it.each([
+    ['empty 200', new Response(null, { status: 200 })],
+    ['malformed 200', new Response('not json', { status: 200 })],
+    ['empty 204', new Response(null, { status: 204 })],
+  ])('rejects %s instead of inventing a typed success', async (_label, res) => {
+    stubBrowser();
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(res));
+    const { listSandboxes } = await import('./api');
+
+    await expect(listSandboxes()).rejects.toMatchObject({
+      name: 'ApiError',
+      status: res.status,
+      message: `/listSandboxes returned invalid JSON with ${res.status}`,
+      cause: expect.anything(),
+    });
+  });
+
+  it('redirects an expired session without settling the RPC', async () => {
+    const { storage, redirects } = stubBrowser({ signedIn: true });
+    vi.stubGlobal(
+      'fetch',
+      vi
+        .fn()
+        .mockResolvedValue(
+          jsonResponse({ message: 'missing or invalid API token' }, 401),
+        ),
+    );
+    const { listSandboxes } = await import('./api');
+
+    const request = listSandboxes();
+    await expectPending(request);
+    expect(storage.has('dormice.console.signed-in')).toBe(false);
+    expect(redirects).toEqual([
+      '/console/login?redirect=%2Fconsole%2Fsandboxes%2Falice%3Ftab%3Dfiles%23preview',
+    ]);
+  });
+
+  it('holds concurrent 401s behind the same single redirect', async () => {
+    const { redirects } = stubBrowser({ signedIn: true });
+    vi.stubGlobal(
+      'fetch',
+      vi
+        .fn()
+        .mockResolvedValue(
+          jsonResponse({ message: 'missing or invalid API token' }, 401),
+        ),
+    );
+    const { getConfig, listSandboxes } = await import('./api');
+
+    const first = listSandboxes();
+    const second = getConfig();
+    await expectPending(first);
+    await expectPending(second);
+    expect(redirects).toHaveLength(1);
+  });
+
+  it('rejects a protected 401 when no signed-in marker exists', async () => {
+    const { redirects } = stubBrowser();
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(jsonResponse({ message: 'unauthorized' }, 401)),
+    );
+    const { listSandboxes } = await import('./api');
+
+    await expect(listSandboxes()).rejects.toMatchObject({
+      name: 'ApiError',
+      status: 401,
+      message: 'unauthorized',
+    });
+    expect(redirects).toEqual([]);
+  });
+
+  it('keeps login 401s local to the form', async () => {
+    const { storage, redirects } = stubBrowser({ signedIn: true });
+    vi.stubGlobal(
+      'fetch',
+      vi
+        .fn()
+        .mockResolvedValue(
+          jsonResponse({ message: 'invalid username or password' }, 401),
+        ),
+    );
+    const { login } = await import('./api');
+
+    await expect(
+      login({ username: 'x', password: 'wrongpass' }),
+    ).rejects.toMatchObject({
+      name: 'ApiError',
+      status: 401,
+      message: 'invalid username or password',
+    });
+    expect(storage.has('dormice.console.signed-in')).toBe(true);
+    expect(redirects).toEqual([]);
+  });
+});
diff --git a/packages/console/src/lib/api.ts b/packages/console/src/lib/api.ts
index 931e4f9..f314f33 100644
--- a/packages/console/src/lib/api.ts
+++ b/packages/console/src/lib/api.ts
@@ -37,11 +37,16 @@ export class ApiError extends Error {
   constructor(
     message: string,
     readonly status: number,
+    options?: ErrorOptions,
   ) {
-    super(message);
+    super(message, options);
+    this.name = 'ApiError';
   }
 }
 
+const redirectingUnauthorized = new Promise<never>(() => {});
+let unauthorizedRedirectStarted = false;
+
 /**
  * Session-expiry backstop, in one place instead of per page: any business
  * call answered 401 while we believed we were signed in means the cookie
@@ -49,12 +54,22 @@ export class ApiError extends Error {
  * do a full-page jump to the login route — a reload guarantees no leftover
  * query cache or component state survives, and the redirect param brings
  * the operator back to where they were.
+ *
+ * The latch covers concurrent calls: the first response clears the marker,
+ * so later 401s cannot use the marker alone to know a redirect is underway.
  */
-function interceptUnauthorized(): void {
-  if (!hasSessionMarker()) return;
+function interceptUnauthorized(): boolean {
+  if (unauthorizedRedirectStarted) return true;
+  if (!hasSessionMarker()) return false;
+
+  unauthorizedRedirectStarted = true;
   clearSessionMarker();
-  const here = window.location.pathname + window.location.search;
-  window.location.href = `/console/login?redirect=${encodeURIComponent(here)}`;
+  const here =
+    window.location.pathname + window.location.search + window.location.hash;
+  window.location.replace(
+    `/console/login?redirect=${encodeURIComponent(here)}`,
+  );
+  return true;
 }
 
 async function rpc<T>(
@@ -70,8 +85,8 @@ async function rpc<T>(
     },
     body: JSON.stringify(body),
   });
-  if (res.status === 401 && intercept401) {
-    interceptUnauthorized();
+  if (res.status === 401 && intercept401 && interceptUnauthorized()) {
+    return redirectingUnauthorized;
   }
   if (!res.ok) {
     const message = await res
@@ -83,7 +98,15 @@ async function rpc<T>(
       res.status,
     );
   }
-  return res.json() as Promise<T>;
+  try {
+    return (await res.json()) as T;
+  } catch (cause) {
+    throw new ApiError(
+      `${path} returned invalid JSON with ${res.status}`,
+      res.status,
+      { cause },
+    );
+  }
 }
 
 // Whether setup has happened — the login page's fork: no account yet means

From 58159f51bd01ad0daf5049f3957c6a8b4767c792 Mon Sep 17 00:00:00 2001
From: MoonWindow <MoonWindow@users.noreply.github.com>
Date: Tue, 21 Jul 2026 05:05:54 +0800
Subject: [PATCH 125/133] Remove watcher created after directory effect
 teardown

useDirectoryWatch used to assign watcherId only after CreateWatcher returned. If the effect was torn down during that round trip, cleanup saw no ID and the returned inotify watcher became unreachable.\n\nTrack disposal and retire an ID that arrives after teardown instead of publishing it into a dead effect generation.
---
 .../src/features/sandboxes/hooks/useEnvd.ts       | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/packages/console/src/features/sandboxes/hooks/useEnvd.ts b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
index b7cde65..479cd63 100644
--- a/packages/console/src/features/sandboxes/hooks/useEnvd.ts
+++ b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
@@ -124,12 +124,24 @@ export function useDirectoryWatch(
   useEffect(() => {
     if (!opts.enabled || !auth) return;
     let watcherId: string | null = null;
+    let disposed = false;
     let busy = false;
 
     const arm = async () => {
       if (!activeRef.current) return; // 冻结/停止:武装会唤醒,等真实使用
       try {
-        watcherId = await createWatcher(auth, path);
+        const id = await createWatcher(auth, path);
+        if (disposed) {
+          // effect 已在建监听的往返途中被拆(切目录或卸载);这个 id 归
+          // 属已死的闭包,同步 cleanup 那时读到的还是 null,拆不掉它 ——
+          // 在此补拆,别把 inotifywait 漏在容器里。active 闸同 cleanup:
+          // 沙箱睡了就留给容器随手回收。
+          if (activeRef.current) {
+            void removeWatcher(auth, id).catch(() => undefined);
+          }
+          return;
+        }
+        watcherId = id;
       } catch {
         watcherId = null; // 冷启动窗口或目录暂不可达;下一拍再试
       }
@@ -162,6 +174,7 @@ export function useDirectoryWatch(
     }, 2000);
 
     return () => {
+      disposed = true;
       clearInterval(timer);
       // 只有沙箱还醒着才顺手拆(RemoveWatcher 要容器活着);睡了就留给
       // 容器回收 — 一个 inotifywait 活不过下一次停止。

From 4610bf14cedea33011bc7112fdfd8233a2e2a021 Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Tue, 21 Jul 2026 23:38:33 -0700
Subject: [PATCH 126/133] Make directory watcher cleanup single-owner

Serialize watcher creation and cleanup with sandbox lifecycle operations, retain watcher identity across transient polls and freezes, and defer cold cleanup until a legitimate wake. Reserve server capacity before asynchronous starts and centralize finalization across stop races.
---
 .../sandboxes/hooks/directory-watcher.test.ts | 154 ++++++++++++++++
 .../sandboxes/hooks/directory-watcher.ts      |  90 ++++++++++
 .../src/features/sandboxes/hooks/useEnvd.ts   |  86 +++------
 packages/server/src/app.ts                    |  14 +-
 packages/server/src/e2b/compat.test.ts        | 130 ++++++++++++++
 packages/server/src/e2b/control.ts            |  10 +-
 packages/server/src/e2b/envd/shared.ts        |  51 +++++-
 packages/server/src/e2b/envd/watch.ts         |  57 +++---
 packages/server/src/e2b/watcher-table.test.ts | 166 ++++++++++++++++++
 packages/server/src/e2b/watcher-table.ts      | 158 +++++++++++++----
 packages/server/src/lifecycle.ts              |   5 +
 packages/server/src/routes/sandboxes.ts       |   8 +-
 packages/server/src/sandbox-proxy.ts          |   6 +-
 13 files changed, 797 insertions(+), 138 deletions(-)
 create mode 100644 packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts
 create mode 100644 packages/console/src/features/sandboxes/hooks/directory-watcher.ts
 create mode 100644 packages/server/src/e2b/watcher-table.test.ts

diff --git a/packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts b/packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts
new file mode 100644
index 0000000..3b098d7
--- /dev/null
+++ b/packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts
@@ -0,0 +1,154 @@
+import { describe, expect, it, vi } from 'vitest';
+import { EnvdError, type EnvdWatchEvent } from '../envd-client';
+import {
+  DirectoryWatcherController,
+  type DirectoryWatcherDeps,
+} from './directory-watcher';
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function harness(overrides: Partial<DirectoryWatcherDeps> = {}) {
+  const create = vi.fn<() => Promise<string>>().mockResolvedValue('watch-1');
+  const poll = vi
+    .fn<(id: string) => Promise<EnvdWatchEvent[]>>()
+    .mockResolvedValue([]);
+  const remove = vi.fn<(id: string) => Promise<void>>().mockResolvedValue();
+  const onDirty = vi.fn();
+  let active = true;
+  const controller = new DirectoryWatcherController({
+    create,
+    poll,
+    remove,
+    isActive: () => active,
+    isNotFound: (error) =>
+      error instanceof EnvdError && error.code === 'not_found',
+    onDirty,
+    ...overrides,
+  });
+  return {
+    controller,
+    create,
+    poll,
+    remove,
+    onDirty,
+    setActive(value: boolean) {
+      active = value;
+    },
+  };
+}
+
+describe('DirectoryWatcherController', () => {
+  it('removes the watcher exactly once after normal disposal', async () => {
+    const t = harness();
+    await t.controller.tick();
+    t.controller.dispose();
+    t.controller.dispose();
+    await vi.waitFor(() => expect(t.remove).toHaveBeenCalledWith('watch-1'));
+    expect(t.remove).toHaveBeenCalledTimes(1);
+  });
+
+  it('retires an ID returned after disposal', async () => {
+    const pending = deferred<string>();
+    const t = harness({ create: () => pending.promise });
+    const tick = t.controller.tick();
+    t.controller.dispose();
+    pending.resolve('late');
+    await tick;
+    expect(t.remove).toHaveBeenCalledWith('late');
+  });
+
+  it('keeps create single-flight across repeated timer ticks', async () => {
+    const pending = deferred<string>();
+    const create = vi.fn(() => pending.promise);
+    const t = harness({ create });
+    const first = t.controller.tick();
+    const second = t.controller.tick();
+    expect(create).toHaveBeenCalledTimes(1);
+    expect(second).toBe(first);
+    pending.resolve('slow');
+    await first;
+  });
+
+  it('does not arm while inactive and preserves an existing watcher through freeze', async () => {
+    const t = harness();
+    t.setActive(false);
+    await t.controller.tick();
+    expect(t.create).not.toHaveBeenCalled();
+
+    t.setActive(true);
+    await t.controller.tick();
+    t.setActive(false);
+    await t.controller.tick();
+    expect(t.poll).toHaveBeenCalledWith('watch-1');
+    expect(t.create).toHaveBeenCalledTimes(1);
+  });
+
+  it('retains the watcher after a transient poll error', async () => {
+    const t = harness();
+    await t.controller.tick();
+    t.poll.mockRejectedValueOnce(new Error('temporary network failure'));
+    await t.controller.tick();
+    await t.controller.tick();
+    expect(t.poll).toHaveBeenCalledTimes(2);
+    expect(t.create).toHaveBeenCalledTimes(1);
+    expect(t.onDirty).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports events while frozen without creating another watcher', async () => {
+    const t = harness();
+    await t.controller.tick();
+    t.setActive(false);
+    t.poll.mockResolvedValueOnce([
+      { name: 'queued.txt', type: 'EVENT_TYPE_CREATE' },
+    ]);
+    await t.controller.tick();
+    expect(t.onDirty).toHaveBeenCalledTimes(1);
+    expect(t.create).toHaveBeenCalledTimes(1);
+  });
+
+  it('rearms only after a confirmed not_found response', async () => {
+    const t = harness();
+    t.create.mockResolvedValueOnce('old').mockResolvedValueOnce('new');
+    await t.controller.tick();
+    t.poll.mockRejectedValueOnce(new EnvdError('gone', 'not_found', 404));
+    await t.controller.tick();
+    await t.controller.tick();
+    expect(t.create).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not invalidate or rearm after disposal during a poll', async () => {
+    const pending = deferred<EnvdWatchEvent[]>();
+    const t = harness({ poll: () => pending.promise });
+    await t.controller.tick();
+    const polling = t.controller.tick();
+    t.controller.dispose();
+    pending.resolve([{ name: 'late.txt', type: 'EVENT_TYPE_CREATE' }]);
+    await polling;
+    await t.controller.tick();
+    expect(t.onDirty).not.toHaveBeenCalled();
+    expect(t.create).toHaveBeenCalledTimes(1);
+  });
+
+  it('isolates rapid effect generations', async () => {
+    const oldCreate = deferred<string>();
+    const old = harness({ create: () => oldCreate.promise });
+    const oldTick = old.controller.tick();
+    old.controller.dispose();
+
+    const next = harness({ create: async () => 'new' });
+    await next.controller.tick();
+    oldCreate.resolve('old');
+    await oldTick;
+
+    expect(old.remove).toHaveBeenCalledWith('old');
+    expect(next.remove).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/console/src/features/sandboxes/hooks/directory-watcher.ts b/packages/console/src/features/sandboxes/hooks/directory-watcher.ts
new file mode 100644
index 0000000..c147b75
--- /dev/null
+++ b/packages/console/src/features/sandboxes/hooks/directory-watcher.ts
@@ -0,0 +1,90 @@
+import type { EnvdWatchEvent } from '../envd-client';
+
+export interface DirectoryWatcherDeps {
+  create(): Promise<string>;
+  poll(watcherId: string): Promise<EnvdWatchEvent[]>;
+  remove(watcherId: string): Promise<void>;
+  isActive(): boolean;
+  isNotFound(error: unknown): boolean;
+  onDirty(): void;
+}
+
+/**
+ * One effect generation's ownership of one polling watcher. Every arm/poll
+ * goes through the same single-flight tick; dispose takes the published ID,
+ * while an ID still in flight is retired by the create continuation itself.
+ */
+export class DirectoryWatcherController {
+  private watcherId: string | null = null;
+  private disposed = false;
+  private inFlight: Promise<void> | null = null;
+
+  constructor(private readonly deps: DirectoryWatcherDeps) {}
+
+  tick(): Promise<void> {
+    if (this.disposed) return Promise.resolve();
+    if (this.inFlight) return this.inFlight;
+
+    const run = this.runTick();
+    this.inFlight = run;
+    void run.finally(() => {
+      if (this.inFlight === run) this.inFlight = null;
+    });
+    return run;
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    const id = this.takeWatcher();
+    if (id) void this.release(id);
+  }
+
+  private async runTick(): Promise<void> {
+    const current = this.watcherId;
+    if (current === null) {
+      if (!this.deps.isActive()) return;
+      let created: string;
+      try {
+        created = await this.deps.create();
+      } catch {
+        return;
+      }
+      if (this.disposed) {
+        await this.release(created);
+        return;
+      }
+      this.watcherId = created;
+      return;
+    }
+
+    try {
+      const events = await this.deps.poll(current);
+      if (!this.disposed && this.watcherId === current && events.length > 0) {
+        this.deps.onDirty();
+      }
+    } catch (error) {
+      if (this.deps.isNotFound(error) && this.watcherId === current) {
+        this.watcherId = null;
+      } else if (!this.disposed && this.watcherId === current) {
+        // Drain is destructive at the daemon. A lost response may have eaten
+        // events, so the directory must converge even though this ID remains.
+        this.deps.onDirty();
+      }
+    }
+  }
+
+  private takeWatcher(): string | null {
+    const id = this.watcherId;
+    this.watcherId = null;
+    return id;
+  }
+
+  private async release(watcherId: string): Promise<void> {
+    try {
+      await this.deps.remove(watcherId);
+    } catch {
+      // Gone already is the cleanup goal; lifecycle races are expected here.
+    }
+  }
+}
diff --git a/packages/console/src/features/sandboxes/hooks/useEnvd.ts b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
index 479cd63..97150d4 100644
--- a/packages/console/src/features/sandboxes/hooks/useEnvd.ts
+++ b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
@@ -5,6 +5,7 @@ import {
   createWatcher,
   downloadFile,
   type EnvdAuth,
+  EnvdError,
   getWatcherEvents,
   killProcess,
   listDir,
@@ -15,6 +16,7 @@ import {
   removeWatcher,
   uploadFile,
 } from '../envd-client';
+import { DirectoryWatcherController } from './directory-watcher';
 
 /**
  * 一个沙箱的 envd 面数据层:token、文件、进程。token 是无状态 HMAC,
@@ -106,11 +108,10 @@ export function useFileMutations(auth: EnvdAuth | undefined) {
  * → RemoveWatcher),沙箱里(agent、终端)动了文件,面板 2 秒内自己跟上。
  *
  * 唤醒纪律是这个 hook 的全部难点:GetWatcherEvents 不唤醒(读 daemon
- * 内存,冻结沙箱的盘也不会变),可以放心轮询;但 Create/Remove 都要容器
- * 活着(容器里有个 inotifywait 要起/停)— 所以**只在沙箱 active 时武装
- * 或拆除**。沙箱睡了就让监听器随容器一起消亡(404 是预期收场),等它下
- * 次因真实使用而醒来再重新武装;绝不为"接着看"或"收拾干净"把沙箱吵醒。
- * active 走 ref:降温/回暖不重跑 effect,轮询循环自己看当下的状态。
+ * 内存,冻结沙箱的盘也不会变),可以放心轮询;Create 只在 active 时发。
+ * Remove 交给服务端按物理状态裁决,清理本身绝不唤醒。active 走 ref:
+ * 降温/回暖不重跑 effect,单一所有者循环自己看当下状态;冻结保留既有
+ * watcher,只有 not_found 才放下旧 ID 并在真实回暖后重建。
  */
 export function useDirectoryWatch(
   auth: EnvdAuth | undefined,
@@ -123,64 +124,31 @@ export function useDirectoryWatch(
 
   useEffect(() => {
     if (!opts.enabled || !auth) return;
-    let watcherId: string | null = null;
-    let disposed = false;
-    let busy = false;
-
-    const arm = async () => {
-      if (!activeRef.current) return; // 冻结/停止:武装会唤醒,等真实使用
-      try {
-        const id = await createWatcher(auth, path);
-        if (disposed) {
-          // effect 已在建监听的往返途中被拆(切目录或卸载);这个 id 归
-          // 属已死的闭包,同步 cleanup 那时读到的还是 null,拆不掉它 ——
-          // 在此补拆,别把 inotifywait 漏在容器里。active 闸同 cleanup:
-          // 沙箱睡了就留给容器随手回收。
-          if (activeRef.current) {
-            void removeWatcher(auth, id).catch(() => undefined);
-          }
-          return;
-        }
-        watcherId = id;
-      } catch {
-        watcherId = null; // 冷启动窗口或目录暂不可达;下一拍再试
-      }
-    };
-
-    void arm();
-    const timer = setInterval(() => {
-      if (busy) return;
-      busy = true;
-      void (async () => {
-        if (watcherId === null) {
-          await arm();
-          return;
-        }
-        try {
-          const events = await getWatcherEvents(auth, watcherId);
-          if (events.length > 0) {
-            void queryClient.invalidateQueries({
-              queryKey: ['envdDir', auth.sandboxId, path],
-            });
-          }
-        } catch {
-          // 404:监听器随容器没了(停止/重建)。回到未武装态,由 arm
-          // 的 active 闸决定何时重来 — 绝不在这里直接重建。
-          watcherId = null;
+    const watcher = new DirectoryWatcherController({
+      create: () => createWatcher(auth, path),
+      poll: (watcherId) => getWatcherEvents(auth, watcherId),
+      remove: async (watcherId) => {
+        await removeWatcher(auth, watcherId);
+      },
+      isActive: () => activeRef.current,
+      isNotFound: (error) =>
+        error instanceof EnvdError && error.code === 'not_found',
+      onDirty: () => {
+        const queryKey = ['envdDir', auth.sandboxId, path];
+        if (activeRef.current) {
+          void queryClient.invalidateQueries({ queryKey });
+        } else {
+          // Mark stale without refetching: ListDir would wake a frozen sandbox.
+          void queryClient.invalidateQueries({ queryKey, refetchType: 'none' });
         }
-      })().finally(() => {
-        busy = false;
-      });
-    }, 2000);
+      },
+    });
 
+    void watcher.tick();
+    const timer = setInterval(() => void watcher.tick(), 2000);
     return () => {
-      disposed = true;
       clearInterval(timer);
-      // 只有沙箱还醒着才顺手拆(RemoveWatcher 要容器活着);睡了就留给
-      // 容器回收 — 一个 inotifywait 活不过下一次停止。
-      if (watcherId !== null && activeRef.current) {
-        void removeWatcher(auth, watcherId).catch(() => undefined);
-      }
+      watcher.dispose();
     };
   }, [auth, path, opts.enabled, queryClient]);
 }
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 1acc792..c09db9f 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -136,6 +136,11 @@ export function buildApp({
   // call shapes would give the instance two different types.
   const loggerInstance =
     typeof logger === 'boolean' ? pino({ enabled: logger }) : logger;
+  // Process and watcher tables are per-daemon state. The watcher table is
+  // also the single deferred-cleanup registry every wake path consults.
+  const processes = new ProcessTable();
+  const watchers = new WatcherTable();
+
   // The sandbox port proxy sits in front of routing — it triages by Host
   // header, so it must see the request before Fastify's router 404s a
   // wildcard host's arbitrary path. Only with the domain knob set; without
@@ -143,7 +148,7 @@ export function buildApp({
   // the factory, so the proxy is exercised over real sockets only.
   let serverFactory: FastifyServerFactory | undefined;
   if (config.DORMICE_SANDBOX_DOMAIN) {
-    const proxy = createSandboxProxy({ config, db, executor, locks });
+    const proxy = createSandboxProxy({ config, db, executor, locks, watchers });
     serverFactory = (handler) => {
       const server = http.createServer((req, res) => {
         if (proxy.matches(req)) proxy.handleRequest(req, res);
@@ -253,6 +258,7 @@ export function buildApp({
       db,
       executor,
       locks,
+      watchers,
       archiver,
       archiveDefaultSeconds,
     });
@@ -299,11 +305,7 @@ export function buildApp({
   });
 
   // The E2B compatibility surface lives beside the native API with its own
-  // auth (X-API-KEY / X-Access-Token) and its own error dialect. The process
-  // and watcher tables are per-daemon state, born with the app and gone
-  // with it — a restart honestly empties them.
-  const processes = new ProcessTable();
-  const watchers = new WatcherTable();
+  // auth (X-API-KEY / X-Access-Token) and its own error dialect.
   app.register(async (compat) => {
     await registerE2bCompat(compat, {
       config,
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 74b742e..7e07682 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -16,6 +16,7 @@ import { getOrCreateSigningSecret } from '../db/secrets';
 import { FAKE_BASE_IMAGE, FakeExecutor } from '../executor/fake';
 import { CpuSampler } from '../host-metrics';
 import { KeyedQueue } from '../keyed-queue';
+import { freezeSandbox, stopSandbox } from '../lifecycle';
 import { sampleOnce } from '../metrics-sampler';
 import { scanOnce } from '../scanner';
 import { mintEnvdToken } from './protocol';
@@ -1592,6 +1593,135 @@ describe('E2B envd surface', () => {
     });
   });
 
+  it('removing a frozen watcher stays cold and the next real use reaps it', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const created = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/CreateWatcher',
+      { path: '/home/user' },
+    );
+    const { watcherId } = created.json() as { watcherId: string };
+    await t.locks.run('e2b-test', async () => {
+      await freezeSandbox(t.db, t.executor, sandboxID);
+    });
+
+    const removed = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/RemoveWatcher',
+      { watcherId },
+    );
+    expect(removed.statusCode).toBe(200);
+    expect(t.executor.stateOf(sandboxID)).toBe('paused');
+
+    const used = await envdRpc(t, sandboxID, '/filesystem.Filesystem/MakeDir', {
+      path: '/home/user/awake',
+    });
+    expect(used.statusCode).toBe(200);
+    expect(t.executor.stateOf(sandboxID)).toBe('running');
+    const gone = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/GetWatcherEvents',
+      { watcherId },
+    );
+    expect(gone.statusCode).toBe(404);
+  });
+
+  it('control-plane connect also reaps a frozen retired watcher', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const created = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/CreateWatcher',
+      { path: '/home/user' },
+    );
+    const { watcherId } = created.json() as { watcherId: string };
+    await t.locks.run('e2b-test', async () => {
+      await freezeSandbox(t.db, t.executor, sandboxID);
+    });
+    expect(
+      (
+        await envdRpc(t, sandboxID, '/filesystem.Filesystem/RemoveWatcher', {
+          watcherId,
+        })
+      ).statusCode,
+    ).toBe(200);
+
+    const connected = await control(
+      t,
+      'POST',
+      `/sandboxes/${sandboxID}/connect`,
+      {
+        timeout: 60,
+      },
+    );
+    expect(connected.statusCode).toBe(200);
+    const gone = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/GetWatcherEvents',
+      { watcherId },
+    );
+    expect(gone.statusCode).toBe(404);
+  });
+
+  it('removing while logically paused still retires without waking', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const created = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/CreateWatcher',
+      { path: '/home/user' },
+    );
+    const { watcherId } = created.json() as { watcherId: string };
+    const paused = await control(
+      t,
+      'POST',
+      `/sandboxes/${sandboxID}/pause`,
+      {},
+    );
+    expect(paused.statusCode).toBe(204);
+
+    const removed = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/RemoveWatcher',
+      { watcherId },
+    );
+    expect(removed.statusCode).toBe(200);
+    expect(t.executor.stateOf(sandboxID)).toBe('paused');
+  });
+
+  it('removing after stop does not restart the container', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const created = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/CreateWatcher',
+      { path: '/home/user' },
+    );
+    const { watcherId } = created.json() as { watcherId: string };
+    await t.locks.run('e2b-test', async () => {
+      await freezeSandbox(t.db, t.executor, sandboxID);
+      await stopSandbox(t.db, t.executor, sandboxID);
+    });
+
+    const removed = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/RemoveWatcher',
+      { watcherId },
+    );
+    expect(removed.statusCode).toBe(404);
+    expect(t.executor.stateOf(sandboxID)).toBe('stopped');
+  });
+
   it('a polled watcher dies with its container: the next poll answers not_found', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t);
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index 87e4559..c75e6f1 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -98,6 +98,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     db,
     executor,
     locks,
+    watchers,
     archiver,
     archiveDefaultSeconds,
     envdSigningSecret,
@@ -313,6 +314,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
             executor,
             existing,
             request.actor,
+            watchers,
           );
           extendDeadline(awake, timeoutSeconds);
           return touch(db, awake.id);
@@ -392,7 +394,13 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
         if (!fresh || e2bView(fresh, new Date()) === 'dead') {
           throw notFound(id);
         }
-        const awake = await wakeSandbox(db, executor, fresh, request.actor);
+        const awake = await wakeSandbox(
+          db,
+          executor,
+          fresh,
+          request.actor,
+          watchers,
+        );
         extendDeadline(awake, request.body.timeout ?? DEFAULT_TIMEOUT_SECONDS);
         return touch(db, awake.id);
       });
diff --git a/packages/server/src/e2b/envd/shared.ts b/packages/server/src/e2b/envd/shared.ts
index c45c4a7..e4d7dd3 100644
--- a/packages/server/src/e2b/envd/shared.ts
+++ b/packages/server/src/e2b/envd/shared.ts
@@ -122,6 +122,11 @@ export interface EnvdContext extends E2bDeps {
     sandboxId: string,
     work: (row: SandboxRow) => Promise<T>,
   ): Promise<T>;
+  /** Serializes daemon-memory work without waking or touching the sandbox. */
+  withoutWake<T>(
+    sandboxId: string,
+    work: (row: SandboxRow) => Promise<T>,
+  ): Promise<T>;
   /** Wake-for-use with streaming-dialect errors: streamError, not thrown JSON. */
   wakeForStream(
     request: FastifyRequest,
@@ -196,7 +201,13 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
     await joinRestore(sandboxId);
     return locks.run(before.name, async () => {
       const fresh = requireRunningRow(sandboxId);
-      const awake = await wakeSandbox(db, executor, fresh);
+      const awake = await wakeSandbox(
+        db,
+        executor,
+        fresh,
+        undefined,
+        deps.watchers,
+      );
       return touch(db, awake.id);
     });
   }
@@ -209,7 +220,13 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
     await joinRestore(sandboxId);
     return locks.run(before.name, async () => {
       const fresh = requireRunningRow(sandboxId);
-      const awake = await wakeSandbox(db, executor, fresh);
+      const awake = await wakeSandbox(
+        db,
+        executor,
+        fresh,
+        undefined,
+        deps.watchers,
+      );
       const row = touch(db, awake.id);
       try {
         return await work(row);
@@ -219,6 +236,27 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
     });
   }
 
+  async function withoutWake<T>(
+    sandboxId: string,
+    work: (row: SandboxRow) => Promise<T>,
+  ): Promise<T> {
+    const before = findById(db, sandboxId);
+    if (!before) {
+      throw new E2bError(502, 'unavailable', 'sandbox not found');
+    }
+    return locks.run(before.name, async () => {
+      const fresh = findById(db, sandboxId);
+      if (!fresh) {
+        throw new E2bError(502, 'unavailable', 'sandbox not found');
+      }
+      try {
+        return await work(fresh);
+      } catch (error) {
+        throw toConnectError(error);
+      }
+    });
+  }
+
   async function wakeForStream(
     request: FastifyRequest,
     reply: FastifyReply,
@@ -241,5 +279,12 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
     }
   }
 
-  return { ...deps, requireRunningRow, wakeForUse, inSlot, wakeForStream };
+  return {
+    ...deps,
+    requireRunningRow,
+    wakeForUse,
+    inSlot,
+    withoutWake,
+    wakeForStream,
+  };
 }
diff --git a/packages/server/src/e2b/envd/watch.ts b/packages/server/src/e2b/envd/watch.ts
index 028bf29..363a401 100644
--- a/packages/server/src/e2b/envd/watch.ts
+++ b/packages/server/src/e2b/envd/watch.ts
@@ -176,22 +176,24 @@ export function registerWatchRoutes(
   app.post('/filesystem.Filesystem/CreateWatcher', async (request) => {
     const body = request.body as { path?: string; recursive?: boolean };
     if (!body.path) throw connectError('invalid_argument', 'missing path');
-    const row = await ctx.wakeForUse(sandboxIdOf(request));
-    try {
-      const watcherId = await watchers.create({
-        executor,
-        sandboxId: row.id,
-        path: body.path,
-        recursive: body.recursive === true,
-      });
-      return { watcherId };
-    } catch (error) {
-      if (error instanceof WatcherLimitError) {
-        throw connectError('resource_exhausted', error.message);
+    const path = body.path;
+    return ctx.inSlot(sandboxIdOf(request), async (row) => {
+      try {
+        const watcherId = await watchers.create({
+          executor,
+          sandboxId: row.id,
+          path,
+          recursive: body.recursive === true,
+        });
+        return { watcherId };
+      } catch (error) {
+        if (error instanceof WatcherLimitError) {
+          throw connectError('resource_exhausted', error.message);
+        }
+        const { code, message } = watchStartError(error);
+        throw connectError(code, message);
       }
-      const { code, message } = watchStartError(error);
-      throw connectError(code, message);
-    }
+    });
   });
 
   app.post('/filesystem.Filesystem/GetWatcherEvents', async (request) => {
@@ -222,15 +224,20 @@ export function registerWatchRoutes(
     if (!body.watcherId) {
       throw connectError('invalid_argument', 'missing watcher id');
     }
-    // Wakes: stopping the in-container inotifywait needs the container up.
-    const row = await ctx.wakeForUse(sandboxIdOf(request));
-    const removed = await watchers.remove(row.id, body.watcherId);
-    if (!removed) {
-      throw connectError(
-        'not_found',
-        `watcher with id ${body.watcherId} not found`,
-      );
-    }
-    return {};
+    return ctx.withoutWake(sandboxIdOf(request), async (row) => {
+      // A frozen watcher survives physically. Retire it in daemon memory now
+      // and let the next real wake reap it; cleanup must not wake by itself.
+      const removed =
+        row.state === 'active'
+          ? await watchers.remove(row.id, body.watcherId as string)
+          : watchers.retire(row.id, body.watcherId as string);
+      if (!removed) {
+        throw connectError(
+          'not_found',
+          `watcher with id ${body.watcherId} not found`,
+        );
+      }
+      return {};
+    });
   });
 }
diff --git a/packages/server/src/e2b/watcher-table.test.ts b/packages/server/src/e2b/watcher-table.test.ts
new file mode 100644
index 0000000..8b3e946
--- /dev/null
+++ b/packages/server/src/e2b/watcher-table.test.ts
@@ -0,0 +1,166 @@
+import { describe, expect, it, vi } from 'vitest';
+import type {
+  Executor,
+  WatchDirHandle,
+  WatchDirOptions,
+} from '../executor/executor';
+import {
+  MAX_WATCHERS_PER_SANDBOX,
+  WatcherLimitError,
+  WatcherTable,
+} from './watcher-table';
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+const args = (executor: Executor) => ({
+  executor,
+  sandboxId: 'sandbox-1',
+  path: '/home/user',
+  recursive: false,
+});
+
+describe('WatcherTable', () => {
+  it('reserves capacity before concurrent starts complete', async () => {
+    const pending: Array<ReturnType<typeof deferred<WatchDirHandle>>> = [];
+    const executor = {
+      watchDir: vi.fn((_id: string, _opts: WatchDirOptions) => {
+        const next = deferred<WatchDirHandle>();
+        pending.push(next);
+        return next.promise;
+      }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const starts = Array.from({ length: MAX_WATCHERS_PER_SANDBOX }, () =>
+      table.create(args(executor)),
+    );
+
+    await expect(table.create(args(executor))).rejects.toBeInstanceOf(
+      WatcherLimitError,
+    );
+    expect(executor.watchDir).toHaveBeenCalledTimes(MAX_WATCHERS_PER_SANDBOX);
+    for (const item of pending) item.resolve({ stop: async () => {} });
+    await Promise.all(starts);
+  });
+
+  it('releases a reservation when start fails', async () => {
+    const executor = {
+      watchDir: vi.fn().mockRejectedValueOnce(new Error('start failed')),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+
+    await expect(table.create(args(executor))).rejects.toThrow('start failed');
+    expect(table.count('sandbox-1')).toBe(0);
+  });
+
+  it('does not publish an ID when onEnd wins during startup', async () => {
+    const stop = vi.fn().mockResolvedValue(undefined);
+    const executor = {
+      watchDir: vi.fn(async (_id: string, opts: WatchDirOptions) => {
+        opts.onEnd(new Error('died while starting'));
+        return { stop };
+      }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+
+    await expect(table.create(args(executor))).rejects.toThrow(
+      'died while starting',
+    );
+    expect(stop).toHaveBeenCalledTimes(1);
+    expect(table.count('sandbox-1')).toBe(0);
+  });
+
+  it('finalizes explicit removal exactly once when onEnd races it', async () => {
+    let onEnd!: WatchDirOptions['onEnd'];
+    const stop = vi.fn(async () => onEnd(new Error('ended')));
+    const executor = {
+      watchDir: vi.fn(async (_id: string, opts: WatchDirOptions) => {
+        onEnd = opts.onEnd;
+        return { stop };
+      }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const id = await table.create(args(executor));
+
+    await expect(table.remove('sandbox-1', id)).resolves.toBe(true);
+    expect(stop).toHaveBeenCalledTimes(1);
+    expect(table.count('sandbox-1')).toBe(0);
+    await expect(table.remove('sandbox-1', id)).resolves.toBe(false);
+  });
+
+  it('shares one physical stop across concurrent cleanup paths', async () => {
+    const pending = deferred<void>();
+    const stop = vi.fn(() => pending.promise);
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const id = await table.create(args(executor));
+    table.retire('sandbox-1', id);
+
+    const first = table.remove('sandbox-1', id);
+    const second = table.reapRetired('sandbox-1');
+    expect(stop).toHaveBeenCalledTimes(1);
+    pending.resolve();
+    await Promise.all([first, second]);
+    expect(table.count('sandbox-1')).toBe(0);
+  });
+
+  it('keeps a failed active removal retired and retries on the next use', async () => {
+    const stop = vi
+      .fn<() => Promise<void>>()
+      .mockRejectedValueOnce(new Error('signal did not land'))
+      .mockResolvedValueOnce(undefined);
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const id = await table.create(args(executor));
+
+    await expect(table.remove('sandbox-1', id)).rejects.toThrow(
+      'signal did not land',
+    );
+    expect(table.count('sandbox-1')).toBe(1);
+    expect(table.drain('sandbox-1', id)).toBeUndefined();
+    await expect(table.reapRetired('sandbox-1')).resolves.toBeUndefined();
+    expect(stop).toHaveBeenCalledTimes(2);
+    expect(table.count('sandbox-1')).toBe(0);
+  });
+
+  it('retires without stopping, then reaps after a legitimate wake', async () => {
+    const stop = vi.fn().mockResolvedValue(undefined);
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const id = await table.create(args(executor));
+
+    expect(table.retire('sandbox-1', id)).toBe(true);
+    expect(stop).not.toHaveBeenCalled();
+    expect(table.drain('sandbox-1', id)).toBeUndefined();
+    expect(table.count('sandbox-1')).toBe(1);
+
+    await table.reapRetired('sandbox-1');
+    expect(stop).toHaveBeenCalledTimes(1);
+    expect(table.count('sandbox-1')).toBe(0);
+  });
+
+  it('keeps watcher IDs scoped to their sandbox', async () => {
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop: async () => {} }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const id = await table.create(args(executor));
+
+    expect(table.drain('sandbox-2', id)).toBeUndefined();
+    expect(table.retire('sandbox-2', id)).toBe(false);
+    await expect(table.remove('sandbox-2', id)).resolves.toBe(false);
+  });
+});
diff --git a/packages/server/src/e2b/watcher-table.ts b/packages/server/src/e2b/watcher-table.ts
index 7d3a5ba..2ffaaff 100644
--- a/packages/server/src/e2b/watcher-table.ts
+++ b/packages/server/src/e2b/watcher-table.ts
@@ -8,7 +8,7 @@ import type {
 /**
  * The polling half of directory watching — what the sync SDKs use instead
  * of the WatchDir stream: CreateWatcher parks a watcher here, GetWatcherEvents
- * drains its buffer, RemoveWatcher stops it. Daemon memory, like the process
+ * drains its buffer, RemoveWatcher retires it. Daemon memory, like the process
  * table: a daemon restart empties it honestly, and a watcher's death (its
  * container stopping) deletes its record through physical conduction — the
  * next poll answers not_found, no lifecycle hooks involved.
@@ -18,7 +18,9 @@ import type {
  * this table lives in the host-side daemon, where unbounded means one
  * sandbox writing files in a loop grows the host's memory. The buffer keeps
  * the newest events (oldest dropped first); the per-sandbox watcher count
- * refuses with resource_exhausted.
+ * refuses with resource_exhausted. Starting and retired records count too:
+ * reservations make the ceiling true under concurrent creates, and retired
+ * handles still own a physical process until the next legitimate wake reaps it.
  */
 export const MAX_EVENTS_PER_WATCHER = 8192;
 export const MAX_WATCHERS_PER_SANDBOX = 128;
@@ -30,16 +32,16 @@ interface WatcherRecord {
   watcherId: string;
   sandboxId: string;
   events: WatchEvent[];
-  handle: WatchDirHandle;
+  state: 'starting' | 'active' | 'retired' | 'ended';
+  handle?: WatchDirHandle;
+  endError?: Error;
+  stopPromise?: Promise<void>;
 }
 
 export class WatcherTable {
   private readonly records = new Map<string, WatcherRecord>();
 
-  /**
-   * Starts a watcher and parks it. Path errors (missing, not a directory)
-   * surface as the executor's typed errors, exactly like the streaming face.
-   */
+  /** Starts a watcher, reserving capacity before the executor can yield. */
   async create(args: {
     executor: Executor;
     sandboxId: string;
@@ -47,52 +49,130 @@ export class WatcherTable {
     recursive: boolean;
   }): Promise<string> {
     const { executor, sandboxId, path, recursive } = args;
-    let count = 0;
-    for (const record of this.records.values()) {
-      if (record.sandboxId === sandboxId) count++;
-    }
-    if (count >= MAX_WATCHERS_PER_SANDBOX) {
+    if (this.count(sandboxId) >= MAX_WATCHERS_PER_SANDBOX) {
       throw new WatcherLimitError(
         `sandbox ${sandboxId} already has ${MAX_WATCHERS_PER_SANDBOX} watchers — remove some before creating more`,
       );
     }
-    const watcherId = randomUUID();
-    const events: WatchEvent[] = [];
-    const handle = await executor.watchDir(sandboxId, {
-      path,
-      recursive,
-      onEvent: (event) => {
-        events.push(event);
-        if (events.length > MAX_EVENTS_PER_WATCHER) events.shift();
-      },
-      // The watcher died with its container: the record goes with it, so
-      // the next poll answers not_found — the closest honest translation
-      // of "the envd you were polling is gone".
-      onEnd: () => {
-        this.records.delete(watcherId);
-      },
-    });
-    this.records.set(watcherId, { watcherId, sandboxId, events, handle });
-    return watcherId;
+
+    const record: WatcherRecord = {
+      watcherId: randomUUID(),
+      sandboxId,
+      events: [],
+      state: 'starting',
+    };
+    this.records.set(record.watcherId, record);
+
+    try {
+      const handle = await executor.watchDir(sandboxId, {
+        path,
+        recursive,
+        onEvent: (event) => {
+          if (record.state !== 'starting' && record.state !== 'active') return;
+          record.events.push(event);
+          if (record.events.length > MAX_EVENTS_PER_WATCHER) {
+            record.events.shift();
+          }
+        },
+        onEnd: (error) => {
+          record.endError = error;
+          this.finalize(record);
+        },
+      });
+      record.handle = handle;
+      if (record.state !== 'starting') {
+        const failure =
+          record.endError ?? new Error('watcher retired while starting');
+        record.state = 'retired';
+        await this.stopRetired(record);
+        throw failure;
+      }
+      record.state = 'active';
+      return record.watcherId;
+    } catch (error) {
+      this.finalize(record);
+      throw error;
+    }
   }
 
-  /**
-   * Drains and returns the buffered events — real envd's read-and-reset.
-   * undefined when the watcher does not exist for this sandbox; ids are
-   * sandbox-scoped like pids, so one sandbox cannot poll another's watcher.
-   */
+  /** Living, published watcher events; retired/starting IDs read as absent. */
   drain(sandboxId: string, watcherId: string): WatchEvent[] | undefined {
     const record = this.records.get(watcherId);
-    if (!record || record.sandboxId !== sandboxId) return undefined;
+    if (
+      !record ||
+      record.sandboxId !== sandboxId ||
+      record.state !== 'active'
+    ) {
+      return undefined;
+    }
     return record.events.splice(0, record.events.length);
   }
 
-  /** Stops and forgets a watcher. False when there is nothing to remove. */
+  /**
+   * Retires without touching the container. Frozen cleanup stays cold; the
+   * next real wake calls reapRetired before serving user work.
+   */
+  retire(sandboxId: string, watcherId: string): boolean {
+    const record = this.records.get(watcherId);
+    if (!record || record.sandboxId !== sandboxId) return false;
+    record.state = 'retired';
+    record.events.length = 0;
+    return true;
+  }
+
+  /** Stops now. A failed stop remains retired so the next wake can retry. */
   async remove(sandboxId: string, watcherId: string): Promise<boolean> {
     const record = this.records.get(watcherId);
     if (!record || record.sandboxId !== sandboxId) return false;
-    this.records.delete(watcherId);
-    await record.handle.stop();
+    record.state = 'retired';
+    record.events.length = 0;
+    await this.stopRetired(record);
     return true;
   }
+
+  /** Reaps deferred frozen cleanup after a legitimate wake made it runnable. */
+  async reapRetired(sandboxId: string): Promise<void> {
+    const retired = [...this.records.values()].filter(
+      (record) => record.sandboxId === sandboxId && record.state === 'retired',
+    );
+    for (const record of retired) {
+      try {
+        await this.stopRetired(record);
+      } catch {
+        // Cleanup is subordinate to the user work that caused this wake.
+        // The record stays retired and the next legitimate wake retries it.
+      }
+    }
+  }
+
+  count(sandboxId: string): number {
+    let count = 0;
+    for (const record of this.records.values()) {
+      if (record.sandboxId === sandboxId && record.state !== 'ended') count++;
+    }
+    return count;
+  }
+
+  private async stopRetired(record: WatcherRecord): Promise<void> {
+    if (record.state === 'ended') return;
+    const handle = record.handle;
+    if (!handle) return;
+    if (!record.stopPromise) {
+      record.stopPromise = handle.stop().then(
+        () => this.finalize(record),
+        (error) => {
+          record.stopPromise = undefined;
+          throw error;
+        },
+      );
+    }
+    await record.stopPromise;
+  }
+
+  private finalize(record: WatcherRecord): void {
+    if (record.state === 'ended') return;
+    record.state = 'ended';
+    this.records.delete(record.watcherId);
+    record.events.length = 0;
+  }
 }
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index a505126..47c8d29 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -10,6 +10,7 @@ import {
 import { deleteSandboxMetricsSamples } from './db/metrics';
 import type { SandboxRow } from './db/schema';
 import { resolveImage } from './db/templates';
+import type { WatcherTable } from './e2b/watcher-table';
 import type { Executor } from './executor/executor';
 
 /**
@@ -191,9 +192,11 @@ export async function wakeSandbox(
   executor: Executor,
   row: SandboxRow,
   actor?: string | null,
+  watchers?: WatcherTable,
 ): Promise<SandboxRow> {
   switch (row.state) {
     case 'active':
+      await watchers?.reapRetired(row.id);
       return row;
     case 'frozen':
     case 'stopped': {
@@ -211,6 +214,7 @@ export async function wakeSandbox(
           : row;
       if (fresh.state === 'frozen') {
         await executor.unfreeze(fresh.id);
+        await watchers?.reapRetired(fresh.id);
         return awaken(
           db,
           fresh,
@@ -223,6 +227,7 @@ export async function wakeSandbox(
       await executor.start(fresh.id, {
         image: resolveImage(db, fresh.template),
       });
+      await watchers?.reapRetired(fresh.id);
       return awaken(db, fresh, 'cold start from the surviving disk', actor);
     }
     case 'archived':
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index c8f6e60..e13443e 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -61,6 +61,7 @@ import {
 import type { SandboxRow } from '../db/schema';
 import { readRuntimeSettings } from '../db/settings';
 import { findTemplate, resolveImage } from '../db/templates';
+import type { WatcherTable } from '../e2b/watcher-table';
 import { startExecHeartbeat } from '../exec-heartbeat';
 import {
   type Executor,
@@ -78,6 +79,7 @@ export interface SandboxRoutesOptions {
   db: Db;
   executor: Executor;
   locks: KeyedQueue;
+  watchers: WatcherTable;
   /** Absent = no S3 configured: archiving and restores are honestly off. */
   archiver?: Archiver;
   /** buildApp's one adjudication of the archive policy default (null = off). */
@@ -127,7 +129,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
   SandboxRoutesOptions
 > = async (
   app,
-  { config, db, executor, locks, archiver, archiveDefaultSeconds },
+  { config, db, executor, locks, watchers, archiver, archiveDefaultSeconds },
 ) => {
   // Every sandbox lives on this daemon today, so the endpoint is our own
   // address; with sharding it may point at another node.
@@ -183,7 +185,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
       // Requested template and metadata are not applied: like policy, they
       // take effect only when this acquire creates the sandbox (metadata
       // has its own update verb, updateMetadata).
-      const awake = await wakeSandbox(db, executor, existing, actor);
+      const awake = await wakeSandbox(db, executor, existing, actor, watchers);
       return { status: 'ready', created: false, row: touch(db, awake.id) };
     }
 
@@ -245,7 +247,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
         `sandbox "${name}" is ${existing.state} — call acquireSandbox and poll until it is ready`,
       );
     }
-    const awake = await wakeSandbox(db, executor, existing, actor);
+    const awake = await wakeSandbox(db, executor, existing, actor, watchers);
     return touch(db, awake.id);
   }
 
diff --git a/packages/server/src/sandbox-proxy.ts b/packages/server/src/sandbox-proxy.ts
index d610906..4d1167d 100644
--- a/packages/server/src/sandbox-proxy.ts
+++ b/packages/server/src/sandbox-proxy.ts
@@ -7,6 +7,7 @@ import type { Db } from './db/db';
 import { findById, touch } from './db/ledger';
 import type { SandboxRow } from './db/schema';
 import { e2bView } from './e2b/view';
+import type { WatcherTable } from './e2b/watcher-table';
 import { startExecHeartbeat } from './exec-heartbeat';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
@@ -76,6 +77,7 @@ export interface SandboxProxyDeps {
   db: Db;
   executor: Executor;
   locks: KeyedQueue;
+  watchers: WatcherTable;
 }
 
 export interface SandboxProxy {
@@ -88,7 +90,7 @@ export interface SandboxProxy {
 class ProxyRefusal extends Error {}
 
 export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
-  const { config, db, executor, locks } = deps;
+  const { config, db, executor, locks, watchers } = deps;
   const domain = config.DORMICE_SANDBOX_DOMAIN ?? '';
 
   function liveRow(sandboxId: string): SandboxRow {
@@ -118,7 +120,7 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
     const before = liveRow(parsed.sandboxId);
     const row = await locks.run(before.name, async () => {
       const fresh = liveRow(parsed.sandboxId);
-      const awake = await wakeSandbox(db, executor, fresh);
+      const awake = await wakeSandbox(db, executor, fresh, undefined, watchers);
       return touch(db, awake.id);
     });
     const target = await executor.resolvePortTarget(row.id, parsed.port);

From fe2714f2a4c2fc93eb28cbbc85b555e65fd10a41 Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Wed, 22 Jul 2026 00:53:00 -0700
Subject: [PATCH 127/133] Close watcher cleanup retry gaps

Refresh stale directory queries when a frozen sandbox becomes active again, and distinguish paused or gone containers from transient Docker signaling failures so cleanup ownership remains retryable.
---
 .../src/features/sandboxes/hooks/useEnvd.ts   | 12 ++++++++++
 packages/server/src/executor/docker.ts        | 22 +++++++++++++------
 2 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/packages/console/src/features/sandboxes/hooks/useEnvd.ts b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
index 97150d4..eeea1c1 100644
--- a/packages/console/src/features/sandboxes/hooks/useEnvd.ts
+++ b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
@@ -120,8 +120,20 @@ export function useDirectoryWatch(
 ) {
   const queryClient = useQueryClient();
   const activeRef = useRef(opts.active);
+  const previousActiveRef = useRef(opts.active);
   activeRef.current = opts.active;
 
+  useEffect(() => {
+    const wasActive = previousActiveRef.current;
+    previousActiveRef.current = opts.active;
+    if (!opts.enabled) return;
+    if (!wasActive && opts.active && auth) {
+      void queryClient.invalidateQueries({
+        queryKey: ['envdDir', auth.sandboxId, path],
+      });
+    }
+  }, [auth, opts.active, opts.enabled, path, queryClient]);
+
   useEffect(() => {
     if (!opts.enabled || !auth) return;
     const watcher = new DirectoryWatcherController({
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 14f09c4..97a3c8c 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -1164,16 +1164,24 @@ export class DockerExecutor implements Executor {
     return {
       stop: async () => {
         if (stopped) return;
-        stopped = true;
         try {
           await this.signalProcess(container, sandboxId, pidfile, 'SIGKILL');
-        } catch {
-          // The container is paused or gone: the signal cannot land, so
-          // waiting for the exit would hang. The stopped flag already
-          // silences the watcher; the process itself is reaped by the
-          // container's own death or the 24h backstop.
-          return;
+        } catch (error) {
+          const state = await container.inspect().then(
+            (info) => info.State,
+            () => undefined,
+          );
+          if (!state?.Running || state.Paused) {
+            // A paused/gone container cannot run the signal exec. Keep the
+            // watcher silent; lifecycle death or the 24h backstop reaps it.
+            stopped = true;
+            return;
+          }
+          // The container is still runnable: preserve ownership so a later
+          // legitimate wake/use can retry instead of orphaning inotifywait.
+          throw error;
         }
+        stopped = true;
         await exitInfo;
       },
     };

From 3c8f9a805281a6fb23a8a9e2d259a2bd73b5c2db Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Wed, 22 Jul 2026 01:24:11 -0700
Subject: [PATCH 128/133] Keep watcher stops single-owner

---
 .../sandboxes/hooks/directory-watcher.test.ts |  18 ++-
 .../sandboxes/hooks/directory-watcher.ts      |  17 ++-
 .../src/features/sandboxes/hooks/useEnvd.ts   |  16 +--
 packages/server/src/executor/docker.ts        |  57 +++-----
 .../src/executor/watch-lifecycle.test.ts      | 133 ++++++++++++++++++
 .../server/src/executor/watch-lifecycle.ts    |  75 ++++++++++
 6 files changed, 264 insertions(+), 52 deletions(-)
 create mode 100644 packages/server/src/executor/watch-lifecycle.test.ts
 create mode 100644 packages/server/src/executor/watch-lifecycle.ts

diff --git a/packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts b/packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts
index 3b098d7..79dfc21 100644
--- a/packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts
+++ b/packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts
@@ -110,10 +110,26 @@ describe('DirectoryWatcherController', () => {
       { name: 'queued.txt', type: 'EVENT_TYPE_CREATE' },
     ]);
     await t.controller.tick();
-    expect(t.onDirty).toHaveBeenCalledTimes(1);
+    expect(t.onDirty).toHaveBeenCalledWith(false);
     expect(t.create).toHaveBeenCalledTimes(1);
   });
 
+  it('refreshes once after a dirty frozen watcher becomes active again', async () => {
+    const t = harness();
+    await t.controller.tick();
+    t.setActive(false);
+    t.poll.mockResolvedValueOnce([
+      { name: 'queued.txt', type: 'EVENT_TYPE_CREATE' },
+    ]);
+    await t.controller.tick();
+
+    t.setActive(true);
+    await t.controller.tick();
+    await t.controller.tick();
+
+    expect(t.onDirty.mock.calls).toEqual([[false], [true]]);
+  });
+
   it('rearms only after a confirmed not_found response', async () => {
     const t = harness();
     t.create.mockResolvedValueOnce('old').mockResolvedValueOnce('new');
diff --git a/packages/console/src/features/sandboxes/hooks/directory-watcher.ts b/packages/console/src/features/sandboxes/hooks/directory-watcher.ts
index c147b75..a3d9d11 100644
--- a/packages/console/src/features/sandboxes/hooks/directory-watcher.ts
+++ b/packages/console/src/features/sandboxes/hooks/directory-watcher.ts
@@ -6,7 +6,7 @@ export interface DirectoryWatcherDeps {
   remove(watcherId: string): Promise<void>;
   isActive(): boolean;
   isNotFound(error: unknown): boolean;
-  onDirty(): void;
+  onDirty(active: boolean): void;
 }
 
 /**
@@ -17,12 +17,17 @@ export interface DirectoryWatcherDeps {
 export class DirectoryWatcherController {
   private watcherId: string | null = null;
   private disposed = false;
+  private inactiveDirty = false;
   private inFlight: Promise<void> | null = null;
 
   constructor(private readonly deps: DirectoryWatcherDeps) {}
 
   tick(): Promise<void> {
     if (this.disposed) return Promise.resolve();
+    if (this.deps.isActive() && this.inactiveDirty) {
+      this.inactiveDirty = false;
+      this.deps.onDirty(true);
+    }
     if (this.inFlight) return this.inFlight;
 
     const run = this.runTick();
@@ -61,7 +66,7 @@ export class DirectoryWatcherController {
     try {
       const events = await this.deps.poll(current);
       if (!this.disposed && this.watcherId === current && events.length > 0) {
-        this.deps.onDirty();
+        this.reportDirty();
       }
     } catch (error) {
       if (this.deps.isNotFound(error) && this.watcherId === current) {
@@ -69,11 +74,17 @@ export class DirectoryWatcherController {
       } else if (!this.disposed && this.watcherId === current) {
         // Drain is destructive at the daemon. A lost response may have eaten
         // events, so the directory must converge even though this ID remains.
-        this.deps.onDirty();
+        this.reportDirty();
       }
     }
   }
 
+  private reportDirty(): void {
+    const active = this.deps.isActive();
+    if (!active) this.inactiveDirty = true;
+    this.deps.onDirty(active);
+  }
+
   private takeWatcher(): string | null {
     const id = this.watcherId;
     this.watcherId = null;
diff --git a/packages/console/src/features/sandboxes/hooks/useEnvd.ts b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
index eeea1c1..4cb7449 100644
--- a/packages/console/src/features/sandboxes/hooks/useEnvd.ts
+++ b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
@@ -120,20 +120,8 @@ export function useDirectoryWatch(
 ) {
   const queryClient = useQueryClient();
   const activeRef = useRef(opts.active);
-  const previousActiveRef = useRef(opts.active);
   activeRef.current = opts.active;
 
-  useEffect(() => {
-    const wasActive = previousActiveRef.current;
-    previousActiveRef.current = opts.active;
-    if (!opts.enabled) return;
-    if (!wasActive && opts.active && auth) {
-      void queryClient.invalidateQueries({
-        queryKey: ['envdDir', auth.sandboxId, path],
-      });
-    }
-  }, [auth, opts.active, opts.enabled, path, queryClient]);
-
   useEffect(() => {
     if (!opts.enabled || !auth) return;
     const watcher = new DirectoryWatcherController({
@@ -145,9 +133,9 @@ export function useDirectoryWatch(
       isActive: () => activeRef.current,
       isNotFound: (error) =>
         error instanceof EnvdError && error.code === 'not_found',
-      onDirty: () => {
+      onDirty: (active) => {
         const queryKey = ['envdDir', auth.sandboxId, path];
-        if (activeRef.current) {
+        if (active) {
           void queryClient.invalidateQueries({ queryKey });
         } else {
           // Mark stale without refetching: ListDir would wake a frozen sandbox.
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 97a3c8c..bfc4559 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -69,6 +69,7 @@ import {
   type WatchDirHandle,
   type WatchDirOptions,
 } from './executor';
+import { WatchProcessLifecycle } from './watch-lifecycle';
 
 /**
  * Label that marks a container as ours, holding the sandbox id. Listing by
@@ -1086,9 +1087,7 @@ export class DockerExecutor implements Executor {
     const container = this.docker.getContainer(containerId);
     const pidfile = `/tmp/.dormice-exec-${randomUUID()}.pid`;
 
-    // Once true, arriving lines drain and drop — after stop() nothing is
-    // delivered, even the pipe's stragglers.
-    let stopped = false;
+    let lifecycle: WatchProcessLifecycle | undefined;
     let pending = '';
     const onStdout = async (chunk: Buffer) => {
       pending += chunk.toString('utf8');
@@ -1099,7 +1098,7 @@ export class DockerExecutor implements Executor {
         pending = pending.slice(eol + 1);
         for (const event of parseInotifyLine(line, resolved)) {
           // Awaited: backpressure travels through to inotifywait's pipe.
-          if (!stopped) await opts.onEvent(event);
+          if (lifecycle?.delivering !== false) await opts.onEvent(event);
         }
       }
     };
@@ -1153,38 +1152,28 @@ export class DockerExecutor implements Executor {
       );
     }
 
-    void exitInfo.then(({ exitCode, error }) => {
-      if (stopped) return;
-      stopped = true;
-      opts.onEnd(
-        error ?? new Error(`watcher on ${resolved} exited with ${exitCode}`),
-      );
+    lifecycle = new WatchProcessLifecycle({
+      exit: exitInfo,
+      stopProcess: () =>
+        this.signalProcess(container, sandboxId, pidfile, 'SIGKILL'),
+      canRetryStop: async () => {
+        const state = await container.inspect().then(
+          (info) => info.State,
+          () => undefined,
+        );
+        // A paused/gone container cannot run the signal exec. Keep the watcher
+        // silent; lifecycle death or the 24h backstop reaps it. A runnable
+        // container keeps ownership so a later legitimate use can retry.
+        return state?.Running === true && !state.Paused;
+      },
+      onNaturalEnd: ({ exitCode, error }) => {
+        opts.onEnd(
+          error ?? new Error(`watcher on ${resolved} exited with ${exitCode}`),
+        );
+      },
     });
 
-    return {
-      stop: async () => {
-        if (stopped) return;
-        try {
-          await this.signalProcess(container, sandboxId, pidfile, 'SIGKILL');
-        } catch (error) {
-          const state = await container.inspect().then(
-            (info) => info.State,
-            () => undefined,
-          );
-          if (!state?.Running || state.Paused) {
-            // A paused/gone container cannot run the signal exec. Keep the
-            // watcher silent; lifecycle death or the 24h backstop reaps it.
-            stopped = true;
-            return;
-          }
-          // The container is still runnable: preserve ownership so a later
-          // legitimate wake/use can retry instead of orphaning inotifywait.
-          throw error;
-        }
-        stopped = true;
-        await exitInfo;
-      },
-    };
+    return { stop: () => lifecycle?.stop() ?? Promise.resolve() };
   }
 
   /** The buffered face of the exec pipeline: capped sinks, awaited to the end. */
diff --git a/packages/server/src/executor/watch-lifecycle.test.ts b/packages/server/src/executor/watch-lifecycle.test.ts
new file mode 100644
index 0000000..60211a2
--- /dev/null
+++ b/packages/server/src/executor/watch-lifecycle.test.ts
@@ -0,0 +1,133 @@
+import { describe, expect, it, vi } from 'vitest';
+import { WatchProcessLifecycle } from './watch-lifecycle';
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+const cleanExit = { exitCode: 137, error: undefined };
+
+describe('WatchProcessLifecycle', () => {
+  it('suppresses onEnd when the process exits during explicit stop', async () => {
+    const exited = deferred<typeof cleanExit>();
+    const onNaturalEnd = vi.fn();
+    const lifecycle = new WatchProcessLifecycle({
+      exit: exited.promise,
+      stopProcess: async () => exited.resolve(cleanExit),
+      canRetryStop: async () => true,
+      onNaturalEnd,
+    });
+
+    await lifecycle.stop();
+
+    expect(onNaturalEnd).not.toHaveBeenCalled();
+    expect(lifecycle.delivering).toBe(false);
+  });
+
+  it('shares one physical stop attempt across concurrent callers', async () => {
+    const exited = deferred<typeof cleanExit>();
+    const signaled = deferred<void>();
+    const stopProcess = vi.fn(() => signaled.promise);
+    const lifecycle = new WatchProcessLifecycle({
+      exit: exited.promise,
+      stopProcess,
+      canRetryStop: async () => true,
+      onNaturalEnd: vi.fn(),
+    });
+
+    const first = lifecycle.stop();
+    const second = lifecycle.stop();
+    await vi.waitFor(() => expect(stopProcess).toHaveBeenCalledTimes(1));
+    expect(second).toBe(first);
+    signaled.resolve();
+    exited.resolve(cleanExit);
+    await first;
+  });
+
+  it('hands ownership back after a runnable transient signal failure', async () => {
+    const exited = deferred<typeof cleanExit>();
+    const onNaturalEnd = vi.fn();
+    const stopProcess = vi
+      .fn<() => Promise<void>>()
+      .mockRejectedValueOnce(new Error('docker exec unavailable'))
+      .mockImplementationOnce(async () => exited.resolve(cleanExit));
+    const lifecycle = new WatchProcessLifecycle({
+      exit: exited.promise,
+      stopProcess,
+      canRetryStop: async () => true,
+      onNaturalEnd,
+    });
+
+    await expect(lifecycle.stop()).rejects.toThrow('docker exec unavailable');
+    expect(lifecycle.delivering).toBe(true);
+    await lifecycle.stop();
+
+    expect(stopProcess).toHaveBeenCalledTimes(2);
+    expect(onNaturalEnd).not.toHaveBeenCalled();
+  });
+
+  it('settles cleanup when a failed signal finds the container unavailable', async () => {
+    const exited = deferred<typeof cleanExit>();
+    const onNaturalEnd = vi.fn();
+    const lifecycle = new WatchProcessLifecycle({
+      exit: exited.promise,
+      stopProcess: async () => {
+        throw new Error('container paused');
+      },
+      canRetryStop: async () => false,
+      onNaturalEnd,
+    });
+
+    await lifecycle.stop();
+    exited.resolve(cleanExit);
+    await Promise.resolve();
+
+    expect(lifecycle.delivering).toBe(false);
+    expect(onNaturalEnd).not.toHaveBeenCalled();
+  });
+
+  it('makes a later stop observe an in-progress non-retryable cleanup', async () => {
+    const exited = deferred<typeof cleanExit>();
+    const inspected = deferred<boolean>();
+    const stopProcess = vi
+      .fn<() => Promise<void>>()
+      .mockRejectedValue(new Error('container paused'));
+    const lifecycle = new WatchProcessLifecycle({
+      exit: exited.promise,
+      stopProcess,
+      canRetryStop: () => inspected.promise,
+      onNaturalEnd: vi.fn(),
+    });
+
+    const first = lifecycle.stop();
+    const second = lifecycle.stop();
+    expect(second).toBe(first);
+    inspected.resolve(false);
+    await Promise.all([first, second]);
+
+    expect(stopProcess).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports a natural exit exactly once', async () => {
+    const exited = deferred<typeof cleanExit>();
+    const onNaturalEnd = vi.fn();
+    const lifecycle = new WatchProcessLifecycle({
+      exit: exited.promise,
+      stopProcess: vi.fn(),
+      canRetryStop: async () => true,
+      onNaturalEnd,
+    });
+
+    exited.resolve(cleanExit);
+    await vi.waitFor(() =>
+      expect(onNaturalEnd).toHaveBeenCalledWith(cleanExit),
+    );
+    await lifecycle.stop();
+
+    expect(onNaturalEnd).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/server/src/executor/watch-lifecycle.ts b/packages/server/src/executor/watch-lifecycle.ts
new file mode 100644
index 0000000..3a3363e
--- /dev/null
+++ b/packages/server/src/executor/watch-lifecycle.ts
@@ -0,0 +1,75 @@
+interface WatchExit {
+  exitCode: number;
+  error: Error | undefined;
+}
+
+interface WatchProcessLifecycleOptions {
+  exit: Promise<WatchExit>;
+  stopProcess(): Promise<void>;
+  /** True only while another stop attempt can still reach the process. */
+  canRetryStop(): Promise<boolean>;
+  onNaturalEnd(outcome: WatchExit): void;
+}
+
+/**
+ * Arbitrates one physical watcher process between natural exit and explicit
+ * stop. Marking `stopping` before signaling is the identity point: an exit in
+ * that window belongs to stop(), not onNaturalEnd. A failed signal hands that
+ * identity back only while the process is still reachable for a later retry.
+ */
+export class WatchProcessLifecycle {
+  private state: 'running' | 'stopping' | 'stopped' = 'running';
+  private exited = false;
+  private stopPromise: Promise<void> | undefined;
+
+  constructor(private readonly opts: WatchProcessLifecycleOptions) {
+    void opts.exit.then((outcome) => {
+      this.exited = true;
+      if (this.state !== 'running') {
+        this.state = 'stopped';
+        return;
+      }
+      this.state = 'stopped';
+      opts.onNaturalEnd(outcome);
+    });
+  }
+
+  get delivering(): boolean {
+    return this.state === 'running';
+  }
+
+  stop(): Promise<void> {
+    if (this.state === 'stopped') return Promise.resolve();
+    if (this.stopPromise) return this.stopPromise;
+
+    this.state = 'stopping';
+    const attempt = this.stopOnce();
+    this.stopPromise = attempt;
+    void attempt.then(
+      () => {
+        if (this.stopPromise === attempt) this.stopPromise = undefined;
+      },
+      () => {
+        if (this.stopPromise === attempt) this.stopPromise = undefined;
+      },
+    );
+    return attempt;
+  }
+
+  private async stopOnce(): Promise<void> {
+    if (this.exited) return;
+    try {
+      await this.opts.stopProcess();
+    } catch (error) {
+      const canRetry = this.exited ? false : await this.opts.canRetryStop();
+      if (this.exited || !canRetry) {
+        this.state = 'stopped';
+        return;
+      }
+      this.state = 'running';
+      throw error;
+    }
+    await this.opts.exit;
+    this.state = 'stopped';
+  }
+}

From 808f5e4940df82dbd55121b3b4fc8de2090c12e7 Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Wed, 22 Jul 2026 06:53:52 -0700
Subject: [PATCH 129/133] Keep watcher cleanup retryable after uncertain
 inspection

Treat failed Docker inspection as unknown rather than proof that a watcher is gone, so the daemon retains cleanup ownership and retries on a later legitimate wake. Add state-machine and watcher-table counterproofs, and cover stale-image replacement together with deferred and natural watcher finalization through both envd and control-plane wake paths.
---
 packages/server/src/app.ts                    |   4 +-
 packages/server/src/e2b/compat.test.ts        | 132 +++++++++++++++---
 packages/server/src/e2b/watcher-table.test.ts |  34 +++++
 packages/server/src/executor/docker.ts        |  22 +--
 .../src/executor/watch-lifecycle.test.ts      |  71 ++++++++--
 .../server/src/executor/watch-lifecycle.ts    |  28 +++-
 6 files changed, 242 insertions(+), 49 deletions(-)

diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index c09db9f..309ad95 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -56,6 +56,8 @@ export interface AppDeps {
    * before anything that needs it.
    */
   logger?: boolean | Logger;
+  /** Tests may inspect the one daemon-wide watcher registry. */
+  watchers?: WatcherTable;
   /**
    * Where the built web console lives; main.ts resolves the monorepo
    * layout, tests inject a fixture. Absent means /console answers an
@@ -113,6 +115,7 @@ export function buildApp({
   executor,
   locks,
   logger = true,
+  watchers = new WatcherTable(),
   consoleDistDir,
   archiver,
   ingress,
@@ -139,7 +142,6 @@ export function buildApp({
   // Process and watcher tables are per-daemon state. The watcher table is
   // also the single deferred-cleanup registry every wake path consults.
   const processes = new ProcessTable();
-  const watchers = new WatcherTable();
 
   // The sandbox port proxy sits in front of routing — it triages by Host
   // header, so it must see the request before Fastify's router 404s a
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 7e07682..1bf3854 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -20,6 +20,7 @@ import { freezeSandbox, stopSandbox } from '../lifecycle';
 import { sampleOnce } from '../metrics-sampler';
 import { scanOnce } from '../scanner';
 import { mintEnvdToken } from './protocol';
+import { WatcherTable } from './watcher-table';
 
 const MIGRATIONS = fileURLToPath(new URL('../../drizzle', import.meta.url));
 const TOKEN = 'test-token-test-token-test-token';
@@ -46,8 +47,16 @@ function testApp(
     ...env,
   });
   const locks = new KeyedQueue();
-  const app = buildApp({ config, db, executor, locks, logger: false });
-  return { app, db, executor, locks };
+  const watchers = new WatcherTable();
+  const app = buildApp({
+    config,
+    db,
+    executor,
+    locks,
+    watchers,
+    logger: false,
+  });
+  return { app, db, executor, locks, watchers };
 }
 
 type TestApp = ReturnType<typeof testApp>;
@@ -77,6 +86,16 @@ async function createSandbox(
   return res.json();
 }
 
+async function registerTemplate(t: TestApp, name: string, image: string) {
+  const res = await t.app.inject({
+    method: 'POST',
+    url: '/registerTemplate',
+    headers: { authorization: `Bearer ${TOKEN}` },
+    payload: { name, image },
+  });
+  expect(res.statusCode).toBe(200);
+}
+
 // The envd token derives from the app's ledger-stored signing secret, not
 // the API token — get-or-create returns the one buildApp already minted.
 function envdHeaders(t: TestApp, sandboxID: string) {
@@ -1593,9 +1612,14 @@ describe('E2B envd surface', () => {
     });
   });
 
-  it('removing a frozen watcher stays cold and the next real use reaps it', async () => {
+  it('stale frozen wake swaps the shell and reaps its retired watcher', async () => {
     const t = testApp();
-    const { sandboxID } = await createSandbox(t);
+    await registerTemplate(t, 'watch-tpl', 'img-v1');
+    const name = 'watch-reap';
+    const { sandboxID } = await createSandbox(t, {
+      templateID: 'watch-tpl',
+      metadata: { name },
+    });
     const created = await envdRpc(
       t,
       sandboxID,
@@ -1603,7 +1627,10 @@ describe('E2B envd surface', () => {
       { path: '/home/user' },
     );
     const { watcherId } = created.json() as { watcherId: string };
-    await t.locks.run('e2b-test', async () => {
+    await t.executor.writeFiles(sandboxID, [
+      { path: 'keep.txt', content: Buffer.from('survives') },
+    ]);
+    await t.locks.run(name, async () => {
       await freezeSandbox(t.db, t.executor, sandboxID);
     });
 
@@ -1615,12 +1642,19 @@ describe('E2B envd surface', () => {
     );
     expect(removed.statusCode).toBe(200);
     expect(t.executor.stateOf(sandboxID)).toBe('paused');
+    expect(t.watchers.count(sandboxID)).toBe(1);
 
+    await registerTemplate(t, 'watch-tpl', 'img-v2');
     const used = await envdRpc(t, sandboxID, '/filesystem.Filesystem/MakeDir', {
       path: '/home/user/awake',
     });
     expect(used.statusCode).toBe(200);
     expect(t.executor.stateOf(sandboxID)).toBe('running');
+    expect(await t.executor.imageOf(sandboxID)).toBe('img-v2');
+    expect((await t.executor.readFile(sandboxID, 'keep.txt')).toString()).toBe(
+      'survives',
+    );
+    expect(t.watchers.count(sandboxID)).toBe(0);
     const gone = await envdRpc(
       t,
       sandboxID,
@@ -1630,9 +1664,14 @@ describe('E2B envd surface', () => {
     expect(gone.statusCode).toBe(404);
   });
 
-  it('control-plane connect also reaps a frozen retired watcher', async () => {
+  it('control connect swaps a stale frozen shell and reaps its watcher', async () => {
     const t = testApp();
-    const { sandboxID } = await createSandbox(t);
+    await registerTemplate(t, 'connect-tpl', 'img-v1');
+    const name = 'connect-reap';
+    const { sandboxID } = await createSandbox(t, {
+      templateID: 'connect-tpl',
+      metadata: { name },
+    });
     const created = await envdRpc(
       t,
       sandboxID,
@@ -1640,7 +1679,7 @@ describe('E2B envd surface', () => {
       { path: '/home/user' },
     );
     const { watcherId } = created.json() as { watcherId: string };
-    await t.locks.run('e2b-test', async () => {
+    await t.locks.run(name, async () => {
       await freezeSandbox(t.db, t.executor, sandboxID);
     });
     expect(
@@ -1650,16 +1689,17 @@ describe('E2B envd surface', () => {
         })
       ).statusCode,
     ).toBe(200);
+    await registerTemplate(t, 'connect-tpl', 'img-v2');
 
     const connected = await control(
       t,
       'POST',
       `/sandboxes/${sandboxID}/connect`,
-      {
-        timeout: 60,
-      },
+      { timeout: 60 },
     );
     expect(connected.statusCode).toBe(200);
+    expect(await t.executor.imageOf(sandboxID)).toBe('img-v2');
+    expect(t.watchers.count(sandboxID)).toBe(0);
     const gone = await envdRpc(
       t,
       sandboxID,
@@ -1669,6 +1709,61 @@ describe('E2B envd surface', () => {
     expect(gone.statusCode).toBe(404);
   });
 
+  it('stale shell replacement finalizes a live watcher through natural end', async () => {
+    const t = testApp();
+    await registerTemplate(t, 'natural-tpl', 'img-v1');
+    const name = 'natural-end';
+    const { sandboxID } = await createSandbox(t, {
+      templateID: 'natural-tpl',
+      metadata: { name },
+    });
+    const created = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/CreateWatcher',
+      { path: '/home/user' },
+    );
+    const { watcherId } = created.json() as { watcherId: string };
+    await t.locks.run(name, async () => {
+      await freezeSandbox(t.db, t.executor, sandboxID);
+    });
+    await registerTemplate(t, 'natural-tpl', 'img-v2');
+
+    const connected = await control(
+      t,
+      'POST',
+      `/sandboxes/${sandboxID}/connect`,
+      { timeout: 60 },
+    );
+    expect(connected.statusCode).toBe(200);
+    expect(await t.executor.imageOf(sandboxID)).toBe('img-v2');
+    expect(t.watchers.count(sandboxID)).toBe(0);
+    expect(
+      (
+        await envdRpc(t, sandboxID, '/filesystem.Filesystem/GetWatcherEvents', {
+          watcherId,
+        })
+      ).statusCode,
+    ).toBe(404);
+
+    const replacement = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/CreateWatcher',
+      { path: '/home/user' },
+    );
+    expect(replacement.statusCode).toBe(200);
+    expect(t.watchers.count(sandboxID)).toBe(1);
+    expect(
+      (
+        await envdRpc(t, sandboxID, '/filesystem.Filesystem/RemoveWatcher', {
+          watcherId: replacement.json().watcherId,
+        })
+      ).statusCode,
+    ).toBe(200);
+    expect(t.watchers.count(sandboxID)).toBe(0);
+  });
+
   it('removing while logically paused still retires without waking', async () => {
     const t = testApp();
     const { sandboxID } = await createSandbox(t);
@@ -2303,17 +2398,6 @@ describe('browser-direct signed files: the 49983 subdomain form and CORS', () =>
 });
 
 describe('E2B templates', () => {
-  // Registration is a native verb; the compat surface only consumes it.
-  async function registerTemplate(t: TestApp, name: string, image: string) {
-    const res = await t.app.inject({
-      method: 'POST',
-      url: '/registerTemplate',
-      headers: { authorization: `Bearer ${TOKEN}` },
-      payload: { name, image },
-    });
-    expect(res.statusCode).toBe(200);
-  }
-
   it('creates from a registered templateID: its image boots, name echoes as templateID and alias', async () => {
     const t = testApp();
     await registerTemplate(t, 'py311', 'img-py');
@@ -2414,6 +2498,7 @@ describe('E2B surface vs the archiver', () => {
       DORMICE_API_TOKEN: TOKEN,
     });
     const locks = new KeyedQueue();
+    const watchers = new WatcherTable();
     const store = new MemStore();
     const archiver = new Archiver({
       db,
@@ -2427,10 +2512,11 @@ describe('E2B surface vs the archiver', () => {
       db,
       executor,
       locks,
+      watchers,
       logger: false,
       archiver,
     });
-    return { app, db, executor, locks, store, archiver };
+    return { app, db, executor, locks, watchers, store, archiver };
   }
 
   /**
diff --git a/packages/server/src/e2b/watcher-table.test.ts b/packages/server/src/e2b/watcher-table.test.ts
index 8b3e946..b762cd4 100644
--- a/packages/server/src/e2b/watcher-table.test.ts
+++ b/packages/server/src/e2b/watcher-table.test.ts
@@ -4,6 +4,7 @@ import type {
   WatchDirHandle,
   WatchDirOptions,
 } from '../executor/executor';
+import { WatchProcessLifecycle } from '../executor/watch-lifecycle';
 import {
   MAX_WATCHERS_PER_SANDBOX,
   WatcherLimitError,
@@ -134,6 +135,39 @@ describe('WatcherTable', () => {
     expect(table.count('sandbox-1')).toBe(0);
   });
 
+  it('retains the record when signal and inspection fail, then reaps it', async () => {
+    const exited = deferred<{ exitCode: number; error: undefined }>();
+    const stopProcess = vi
+      .fn<() => Promise<void>>()
+      .mockRejectedValueOnce(new Error('signal failed'))
+      .mockImplementationOnce(async () =>
+        exited.resolve({ exitCode: 137, error: undefined }),
+      );
+    const lifecycle = new WatchProcessLifecycle({
+      exit: exited.promise,
+      stopProcess,
+      classifyFailedStop: vi
+        .fn()
+        .mockRejectedValue(new Error('inspect failed')),
+      onNaturalEnd: vi.fn(),
+    });
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop: () => lifecycle.stop() }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const id = await table.create(args(executor));
+
+    await expect(table.remove('sandbox-1', id)).rejects.toThrow(
+      'container state is unknown',
+    );
+    expect(table.count('sandbox-1')).toBe(1);
+    expect(table.drain('sandbox-1', id)).toBeUndefined();
+
+    await table.reapRetired('sandbox-1');
+    expect(stopProcess).toHaveBeenCalledTimes(2);
+    expect(table.count('sandbox-1')).toBe(0);
+  });
+
   it('retires without stopping, then reaps after a legitimate wake', async () => {
     const stop = vi.fn().mockResolvedValue(undefined);
     const executor = {
diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index bfc4559..5cf0c1c 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -1156,15 +1156,19 @@ export class DockerExecutor implements Executor {
       exit: exitInfo,
       stopProcess: () =>
         this.signalProcess(container, sandboxId, pidfile, 'SIGKILL'),
-      canRetryStop: async () => {
-        const state = await container.inspect().then(
-          (info) => info.State,
-          () => undefined,
-        );
-        // A paused/gone container cannot run the signal exec. Keep the watcher
-        // silent; lifecycle death or the 24h backstop reaps it. A runnable
-        // container keeps ownership so a later legitimate use can retry.
-        return state?.Running === true && !state.Paused;
+      classifyFailedStop: async () => {
+        try {
+          const { State: state } = await container.inspect();
+          // A paused watcher still exists and becomes signalable after the
+          // next legitimate unfreeze. Only proved death releases ownership.
+          return state.Running ? 'retry' : 'terminal';
+        } catch (error) {
+          if (isDockerApiError(error) && error.statusCode === 404) {
+            return 'terminal';
+          }
+          // Unknown is not gone: retain ownership so a later reap can retry.
+          throw error;
+        }
       },
       onNaturalEnd: ({ exitCode, error }) => {
         opts.onEnd(
diff --git a/packages/server/src/executor/watch-lifecycle.test.ts b/packages/server/src/executor/watch-lifecycle.test.ts
index 60211a2..59ce6b8 100644
--- a/packages/server/src/executor/watch-lifecycle.test.ts
+++ b/packages/server/src/executor/watch-lifecycle.test.ts
@@ -3,10 +3,12 @@ import { WatchProcessLifecycle } from './watch-lifecycle';
 
 function deferred<T>() {
   let resolve!: (value: T) => void;
-  const promise = new Promise<T>((res) => {
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
     resolve = res;
+    reject = rej;
   });
-  return { promise, resolve };
+  return { promise, resolve, reject };
 }
 
 const cleanExit = { exitCode: 137, error: undefined };
@@ -18,7 +20,7 @@ describe('WatchProcessLifecycle', () => {
     const lifecycle = new WatchProcessLifecycle({
       exit: exited.promise,
       stopProcess: async () => exited.resolve(cleanExit),
-      canRetryStop: async () => true,
+      classifyFailedStop: async () => 'retry',
       onNaturalEnd,
     });
 
@@ -35,7 +37,7 @@ describe('WatchProcessLifecycle', () => {
     const lifecycle = new WatchProcessLifecycle({
       exit: exited.promise,
       stopProcess,
-      canRetryStop: async () => true,
+      classifyFailedStop: async () => 'retry',
       onNaturalEnd: vi.fn(),
     });
 
@@ -58,7 +60,7 @@ describe('WatchProcessLifecycle', () => {
     const lifecycle = new WatchProcessLifecycle({
       exit: exited.promise,
       stopProcess,
-      canRetryStop: async () => true,
+      classifyFailedStop: async () => 'retry',
       onNaturalEnd,
     });
 
@@ -70,6 +72,55 @@ describe('WatchProcessLifecycle', () => {
     expect(onNaturalEnd).not.toHaveBeenCalled();
   });
 
+  it('keeps cleanup retryable when signal and container inspection both fail', async () => {
+    const exited = deferred<typeof cleanExit>();
+    const signalError = new Error('docker exec unavailable');
+    const inspectError = new Error('docker socket unavailable');
+    const stopProcess = vi
+      .fn<() => Promise<void>>()
+      .mockRejectedValueOnce(signalError)
+      .mockImplementationOnce(async () => exited.resolve(cleanExit));
+    const onNaturalEnd = vi.fn();
+    const lifecycle = new WatchProcessLifecycle({
+      exit: exited.promise,
+      stopProcess,
+      classifyFailedStop: vi.fn().mockRejectedValue(inspectError),
+      onNaturalEnd,
+    });
+
+    const failed = lifecycle.stop().catch((error) => error);
+    await expect(failed).resolves.toMatchObject({
+      message: 'watcher stop failed and container state is unknown',
+      errors: [signalError, inspectError],
+    });
+    expect(lifecycle.delivering).toBe(true);
+    await lifecycle.stop();
+
+    expect(stopProcess).toHaveBeenCalledTimes(2);
+    expect(onNaturalEnd).not.toHaveBeenCalled();
+  });
+
+  it('settles when process exit wins while failed-stop inspection is pending', async () => {
+    const exited = deferred<typeof cleanExit>();
+    const inspected = deferred<'retry'>();
+    const onNaturalEnd = vi.fn();
+    const lifecycle = new WatchProcessLifecycle({
+      exit: exited.promise,
+      stopProcess: vi.fn().mockRejectedValue(new Error('signal failed')),
+      classifyFailedStop: () => inspected.promise,
+      onNaturalEnd,
+    });
+
+    const stopping = lifecycle.stop();
+    exited.resolve(cleanExit);
+    await Promise.resolve();
+    inspected.reject(new Error('inspect failed'));
+    await stopping;
+
+    expect(lifecycle.delivering).toBe(false);
+    expect(onNaturalEnd).not.toHaveBeenCalled();
+  });
+
   it('settles cleanup when a failed signal finds the container unavailable', async () => {
     const exited = deferred<typeof cleanExit>();
     const onNaturalEnd = vi.fn();
@@ -78,7 +129,7 @@ describe('WatchProcessLifecycle', () => {
       stopProcess: async () => {
         throw new Error('container paused');
       },
-      canRetryStop: async () => false,
+      classifyFailedStop: async () => 'terminal',
       onNaturalEnd,
     });
 
@@ -92,21 +143,21 @@ describe('WatchProcessLifecycle', () => {
 
   it('makes a later stop observe an in-progress non-retryable cleanup', async () => {
     const exited = deferred<typeof cleanExit>();
-    const inspected = deferred<boolean>();
+    const inspected = deferred<'terminal'>();
     const stopProcess = vi
       .fn<() => Promise<void>>()
       .mockRejectedValue(new Error('container paused'));
     const lifecycle = new WatchProcessLifecycle({
       exit: exited.promise,
       stopProcess,
-      canRetryStop: () => inspected.promise,
+      classifyFailedStop: () => inspected.promise,
       onNaturalEnd: vi.fn(),
     });
 
     const first = lifecycle.stop();
     const second = lifecycle.stop();
     expect(second).toBe(first);
-    inspected.resolve(false);
+    inspected.resolve('terminal');
     await Promise.all([first, second]);
 
     expect(stopProcess).toHaveBeenCalledTimes(1);
@@ -118,7 +169,7 @@ describe('WatchProcessLifecycle', () => {
     const lifecycle = new WatchProcessLifecycle({
       exit: exited.promise,
       stopProcess: vi.fn(),
-      canRetryStop: async () => true,
+      classifyFailedStop: async () => 'retry',
       onNaturalEnd,
     });
 
diff --git a/packages/server/src/executor/watch-lifecycle.ts b/packages/server/src/executor/watch-lifecycle.ts
index 3a3363e..ae3972f 100644
--- a/packages/server/src/executor/watch-lifecycle.ts
+++ b/packages/server/src/executor/watch-lifecycle.ts
@@ -3,11 +3,12 @@ interface WatchExit {
   error: Error | undefined;
 }
 
+export type FailedStopDisposition = 'retry' | 'terminal';
+
 interface WatchProcessLifecycleOptions {
   exit: Promise<WatchExit>;
   stopProcess(): Promise<void>;
-  /** True only while another stop attempt can still reach the process. */
-  canRetryStop(): Promise<boolean>;
+  classifyFailedStop(): Promise<FailedStopDisposition>;
   onNaturalEnd(outcome: WatchExit): void;
 }
 
@@ -60,14 +61,29 @@ export class WatchProcessLifecycle {
     if (this.exited) return;
     try {
       await this.opts.stopProcess();
-    } catch (error) {
-      const canRetry = this.exited ? false : await this.opts.canRetryStop();
-      if (this.exited || !canRetry) {
+    } catch (signalError) {
+      let disposition: FailedStopDisposition;
+      try {
+        disposition = this.exited
+          ? 'terminal'
+          : await this.opts.classifyFailedStop();
+      } catch (inspectError) {
+        if (this.exited) {
+          this.state = 'stopped';
+          return;
+        }
+        this.state = 'running';
+        throw new AggregateError(
+          [signalError, inspectError],
+          'watcher stop failed and container state is unknown',
+        );
+      }
+      if (this.exited || disposition === 'terminal') {
         this.state = 'stopped';
         return;
       }
       this.state = 'running';
-      throw error;
+      throw signalError;
     }
     await this.opts.exit;
     this.state = 'stopped';

From d40f604a78238caaa58f27420db1e9b6bb8b8c29 Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Wed, 22 Jul 2026 07:27:38 -0700
Subject: [PATCH 130/133] Allow both settled watcher removal outcomes after
 stop

Container death owns watcher finalization, but the Docker exec exit can arrive after the stopped state is visible. Keep the compatibility assertion focused on the no-wake contract while accepting either not-found or an idempotent goal-state removal during that race.
---
 packages/server/src/e2b/compat.test.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index 1bf3854..b2f88ad 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -1813,7 +1813,10 @@ describe('E2B envd surface', () => {
       '/filesystem.Filesystem/RemoveWatcher',
       { watcherId },
     );
-    expect(removed.statusCode).toBe(404);
+    // Container death owns finalization. The fake conducts it synchronously and
+    // answers not_found; Docker may accept the goal-state remove while its exec
+    // exit is still arriving. Neither path may restart the stopped container.
+    expect([200, 404]).toContain(removed.statusCode);
     expect(t.executor.stateOf(sandboxID)).toBe('stopped');
   });
 

From 336b72211c96e82bf1d7c02c1fff5b70689130de Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Wed, 22 Jul 2026 11:00:12 -0700
Subject: [PATCH 131/133] Make watcher operations converge after lost responses

---
 .claude/skills/verify/SKILL.md                |  13 +
 e2e/src/e2b.test.ts                           |  24 +-
 .../src/features/sandboxes/envd-client.ts     |  36 +-
 .../sandboxes/hooks/directory-watcher.test.ts |  82 +++-
 .../sandboxes/hooks/directory-watcher.ts      |  98 +++-
 .../src/features/sandboxes/hooks/useEnvd.ts   |  24 +-
 packages/server/src/app.ts                    |   6 +
 packages/server/src/archive/archiver.test.ts  |  43 +-
 packages/server/src/archive/archiver.ts       |   5 +
 packages/server/src/e2b/compat.test.ts        | 116 ++++-
 packages/server/src/e2b/control.ts            |  19 +-
 packages/server/src/e2b/envd/shared.ts        |   7 +
 packages/server/src/e2b/envd/watch.ts         | 111 ++++-
 packages/server/src/e2b/watcher-table.test.ts | 244 ++++++++++
 packages/server/src/e2b/watcher-table.ts      | 456 +++++++++++++++---
 packages/server/src/lifecycle.ts              |  14 +-
 packages/server/src/main.ts                   |  78 ++-
 packages/server/src/reconciler.test.ts        |  20 +-
 packages/server/src/reconciler.ts             |   5 +
 packages/server/src/routes/sandboxes.ts       |  10 +-
 packages/server/src/scanner.ts                |   5 +
 website/content/docs/e2b-differences.mdx      |  12 +-
 website/content/docs/upgrading.mdx            |  13 +-
 23 files changed, 1282 insertions(+), 159 deletions(-)
 create mode 100644 .claude/skills/verify/SKILL.md

diff --git a/.claude/skills/verify/SKILL.md b/.claude/skills/verify/SKILL.md
new file mode 100644
index 0000000..22db799
--- /dev/null
+++ b/.claude/skills/verify/SKILL.md
@@ -0,0 +1,13 @@
+---
+name: verify
+summary: Drive Dormice's built daemon over its public HTTP and E2B surfaces.
+---
+
+# Verify Dormice runtime behavior
+
+1. Run `pnpm build` before verification; the black-box surface is `packages/server/dist/main.js`.
+2. Launch an isolated fake daemon with an unused port, a temporary absolute `DORMICE_DB_PATH`/`DORMICE_DATA_DIR`, a 64-hex `DORMICE_API_TOKEN`, and `DORMICE_EXECUTOR=fake`.
+3. Wait for `GET /healthz`, then drive native or E2B routes only over HTTP. E2B control auth is `X-API-KEY: e2b_<token>`; envd requests use the returned `sandboxID`/`envdAccessToken` as `E2b-Sandbox-Id` and `X-Access-Token`.
+4. Connect streaming requests use one envelope: flag byte `0`, four-byte big-endian JSON length, then JSON bytes. Parse responses as repeated envelopes.
+5. Capture response status/body inline. Probe malformed input, replay/concurrency, and resource cleanup around the claimed flow.
+6. Stop the daemon and remove its temporary directory. Docker/gVisor process facts require the Linux test host and cannot be established with the fake executor.
diff --git a/e2e/src/e2b.test.ts b/e2e/src/e2b.test.ts
index 366af7b..13a737c 100644
--- a/e2e/src/e2b.test.ts
+++ b/e2e/src/e2b.test.ts
@@ -624,7 +624,11 @@ describe('official e2b SDK against the daemon', () => {
       const { envdAccessToken } = (await connectRes.json()) as {
         envdAccessToken: string;
       };
-      const rpc = async (method: string, body: Record<string, unknown>) => {
+      const rpc = async (
+        method: string,
+        body: Record<string, unknown>,
+        headers: Record<string, string> = {},
+      ) => {
         const res = await fetch(
           `${inject('dormiceEndpoint')}/e2b/envd/filesystem.Filesystem/${method}`,
           {
@@ -633,6 +637,7 @@ describe('official e2b SDK against the daemon', () => {
               'content-type': 'application/json',
               'e2b-sandbox-id': sbx.sandboxId,
               'x-access-token': envdAccessToken,
+              ...headers,
             },
             body: JSON.stringify(body),
           },
@@ -642,9 +647,21 @@ describe('official e2b SDK against the daemon', () => {
           json: (await res.json()) as Record<string, unknown>,
         };
       };
-      const created = await rpc('CreateWatcher', { path: '/home/user' });
+      const operationId = crypto.randomUUID();
+      const created = await rpc(
+        'CreateWatcher',
+        { path: '/home/user' },
+        { 'x-dormice-watcher-operation-id': operationId },
+      );
       expect(created.status).toBe(200);
       const watcherId = created.json.watcherId as string;
+      // Model a lost first response by issuing the same operation again.
+      const replayed = await rpc(
+        'CreateWatcher',
+        { path: '/home/user/./' },
+        { 'x-dormice-watcher-operation-id': operationId },
+      );
+      expect(replayed).toEqual({ status: 200, json: { watcherId } });
 
       await sbx.files.write('polled.txt', 'x');
       // Poll like a sync SDK: drain until the event shows up.
@@ -665,6 +682,9 @@ describe('official e2b SDK against the daemon', () => {
 
       const removed = await rpc('RemoveWatcher', { watcherId });
       expect(removed.status).toBe(200);
+      // A retry after the successful response was lost is still success.
+      const removedAgain = await rpc('RemoveWatcher', { watcherId });
+      expect(removedAgain.status).toBe(200);
       const gone = await rpc('GetWatcherEvents', { watcherId });
       expect(gone.status).toBe(404);
       expect(gone.json.code).toBe('not_found');
diff --git a/packages/console/src/features/sandboxes/envd-client.ts b/packages/console/src/features/sandboxes/envd-client.ts
index 7cdf84f..e2fbcba 100644
--- a/packages/console/src/features/sandboxes/envd-client.ts
+++ b/packages/console/src/features/sandboxes/envd-client.ts
@@ -29,8 +29,9 @@ export class EnvdError extends Error {
     message: string,
     readonly code: string | undefined,
     readonly status: number,
+    options?: ErrorOptions,
   ) {
-    super(message);
+    super(message, options);
   }
 }
 
@@ -38,10 +39,15 @@ async function unary<T>(
   auth: EnvdAuth,
   rpc: string,
   body: unknown,
+  extraHeaders: Record<string, string> = {},
 ): Promise<T> {
   const res = await fetch(`${ENVD}/${rpc}`, {
     method: 'POST',
-    headers: { ...headersOf(auth), 'content-type': 'application/json' },
+    headers: {
+      ...headersOf(auth),
+      ...extraHeaders,
+      'content-type': 'application/json',
+    },
     body: JSON.stringify(body),
   });
   if (!res.ok) {
@@ -54,7 +60,16 @@ async function unary<T>(
       res.status,
     );
   }
-  return res.json() as Promise<T>;
+  try {
+    return (await res.json()) as T;
+  } catch (error) {
+    throw new EnvdError(
+      `${rpc} 响应无效`,
+      undefined,
+      0,
+      error instanceof Error ? { cause: error } : undefined,
+    );
+  }
 }
 
 // ---- Filesystem(unary Connect RPC,JSON 编码)---------------------------
@@ -104,10 +119,17 @@ export interface EnvdWatchEvent {
   type: string;
 }
 
-export const createWatcher = (auth: EnvdAuth, path: string) =>
-  unary<{ watcherId: string }>(auth, 'filesystem.Filesystem/CreateWatcher', {
-    path,
-  }).then((r) => r.watcherId);
+export const createWatcher = (
+  auth: EnvdAuth,
+  path: string,
+  operationId: string,
+) =>
+  unary<{ watcherId: string }>(
+    auth,
+    'filesystem.Filesystem/CreateWatcher',
+    { path },
+    { 'x-dormice-watcher-operation-id': operationId },
+  ).then((r) => r.watcherId);
 
 /** 只读不唤醒(与 Process/List 同一原则):挂着监听不养沙箱的体温。 */
 export const getWatcherEvents = (auth: EnvdAuth, watcherId: string) =>
diff --git a/packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts b/packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts
index 79dfc21..a6e3f56 100644
--- a/packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts
+++ b/packages/console/src/features/sandboxes/hooks/directory-watcher.test.ts
@@ -16,7 +16,9 @@ function deferred<T>() {
 }
 
 function harness(overrides: Partial<DirectoryWatcherDeps> = {}) {
-  const create = vi.fn<() => Promise<string>>().mockResolvedValue('watch-1');
+  const create = vi
+    .fn<(operationId: string) => Promise<string>>()
+    .mockResolvedValue('watch-1');
   const poll = vi
     .fn<(id: string) => Promise<EnvdWatchEvent[]>>()
     .mockResolvedValue([]);
@@ -30,6 +32,9 @@ function harness(overrides: Partial<DirectoryWatcherDeps> = {}) {
     isActive: () => active,
     isNotFound: (error) =>
       error instanceof EnvdError && error.code === 'not_found',
+    isRetryable: (error) => !(error instanceof EnvdError),
+    operationId: () => 'operation-1',
+    delay: async () => {},
     onDirty,
     ...overrides,
   });
@@ -91,6 +96,81 @@ describe('DirectoryWatcherController', () => {
     expect(t.create).toHaveBeenCalledTimes(1);
   });
 
+  it('reuses one operation ID while retrying an ambiguous create outcome', async () => {
+    const create = vi
+      .fn<(operationId: string) => Promise<string>>()
+      .mockRejectedValueOnce(new Error('response lost'))
+      .mockResolvedValueOnce('watch-1');
+    const t = harness({ create });
+
+    await t.controller.tick();
+
+    expect(create).toHaveBeenCalledTimes(2);
+    expect(create.mock.calls).toEqual([['operation-1'], ['operation-1']]);
+  });
+
+  it('recovers and removes an ambiguous create after disposal', async () => {
+    const create = vi
+      .fn<(operationId: string) => Promise<string>>()
+      .mockRejectedValueOnce(new Error('response lost 1'))
+      .mockRejectedValueOnce(new Error('response lost 2'))
+      .mockRejectedValueOnce(new Error('response lost 3'))
+      .mockResolvedValueOnce('watch-1');
+    const t = harness({ create });
+    await t.controller.tick();
+    expect(create).toHaveBeenCalledTimes(3);
+
+    t.controller.dispose();
+
+    await vi.waitFor(() => expect(t.remove).toHaveBeenCalledWith('watch-1'));
+    expect(create.mock.calls).toEqual([
+      ['operation-1'],
+      ['operation-1'],
+      ['operation-1'],
+      ['operation-1'],
+    ]);
+  });
+
+  it('does not retry a deterministic create error', async () => {
+    const create = vi
+      .fn<(operationId: string) => Promise<string>>()
+      .mockRejectedValue(new EnvdError('bad path', 'invalid_argument', 400));
+    const t = harness({ create });
+
+    await t.controller.tick();
+
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries ambiguous remove outcomes with bounded backoff', async () => {
+    const remove = vi
+      .fn<(id: string) => Promise<void>>()
+      .mockRejectedValueOnce(new Error('response lost'))
+      .mockResolvedValueOnce(undefined);
+    const delay = vi.fn().mockResolvedValue(undefined);
+    const t = harness({ remove, delay });
+    await t.controller.tick();
+
+    t.controller.dispose();
+
+    await vi.waitFor(() => expect(remove).toHaveBeenCalledTimes(2));
+    expect(remove).toHaveBeenNthCalledWith(1, 'watch-1');
+    expect(remove).toHaveBeenNthCalledWith(2, 'watch-1');
+    expect(delay).toHaveBeenCalledWith(100);
+  });
+
+  it('does not retry deterministic remove errors', async () => {
+    const remove = vi
+      .fn<(id: string) => Promise<void>>()
+      .mockRejectedValue(new EnvdError('unauthorized', 'unauthenticated', 401));
+    const t = harness({ remove });
+    await t.controller.tick();
+
+    t.controller.dispose();
+
+    await vi.waitFor(() => expect(remove).toHaveBeenCalledTimes(1));
+  });
+
   it('retains the watcher after a transient poll error', async () => {
     const t = harness();
     await t.controller.tick();
diff --git a/packages/console/src/features/sandboxes/hooks/directory-watcher.ts b/packages/console/src/features/sandboxes/hooks/directory-watcher.ts
index a3d9d11..8bcd378 100644
--- a/packages/console/src/features/sandboxes/hooks/directory-watcher.ts
+++ b/packages/console/src/features/sandboxes/hooks/directory-watcher.ts
@@ -1,24 +1,38 @@
 import type { EnvdWatchEvent } from '../envd-client';
 
 export interface DirectoryWatcherDeps {
-  create(): Promise<string>;
+  create(operationId: string): Promise<string>;
   poll(watcherId: string): Promise<EnvdWatchEvent[]>;
   remove(watcherId: string): Promise<void>;
   isActive(): boolean;
   isNotFound(error: unknown): boolean;
+  isRetryable(error: unknown): boolean;
+  operationId(): string;
+  delay(milliseconds: number): Promise<void>;
   onDirty(active: boolean): void;
 }
 
+const MAX_CREATE_ATTEMPTS = 3;
+const MAX_REMOVE_ATTEMPTS = 3;
+const retryDelayMs = (attempt: number) => Math.min(100 * 2 ** attempt, 400);
+
 /**
  * One effect generation's ownership of one polling watcher. Every arm/poll
  * goes through the same single-flight tick; dispose takes the published ID,
  * while an ID still in flight is retired by the create continuation itself.
+ *
+ * A create generation also owns one operation UUID: ambiguous HTTP outcomes
+ * replay with that UUID, so a response lost after server success recovers the
+ * same watcher instead of allocating another. Cleanup retries only ambiguous
+ * transport/server outcomes and remains private fire-and-forget to React.
  */
 export class DirectoryWatcherController {
   private watcherId: string | null = null;
+  private operationId: string | null = null;
   private disposed = false;
   private inactiveDirty = false;
   private inFlight: Promise<void> | null = null;
+  private releasePromise: Promise<void> | null = null;
 
   constructor(private readonly deps: DirectoryWatcherDeps) {}
 
@@ -42,19 +56,42 @@ export class DirectoryWatcherController {
     if (this.disposed) return;
     this.disposed = true;
     const id = this.takeWatcher();
-    if (id) void this.release(id);
+    if (id) {
+      void this.release(id);
+      return;
+    }
+    const operationId = this.operationId;
+    this.operationId = null;
+    if (operationId && !this.inFlight) {
+      void this.recoverAndRelease(operationId);
+    }
   }
 
   private async runTick(): Promise<void> {
     const current = this.watcherId;
     if (current === null) {
       if (!this.deps.isActive()) return;
-      let created: string;
-      try {
-        created = await this.deps.create();
-      } catch {
-        return;
+      const operationId = this.operationId ?? this.deps.operationId();
+      this.operationId = operationId;
+      let created: string | undefined;
+      for (let attempt = 0; attempt < MAX_CREATE_ATTEMPTS; attempt++) {
+        try {
+          created = await this.deps.create(operationId);
+          break;
+        } catch (error) {
+          if (!this.deps.isRetryable(error)) return;
+          if (attempt === MAX_CREATE_ATTEMPTS - 1) {
+            if (this.disposed) {
+              this.operationId = null;
+              void this.recoverAndRelease(operationId);
+            }
+            return;
+          }
+          await this.deps.delay(retryDelayMs(attempt));
+        }
       }
+      if (!created) return;
+      this.operationId = null;
       if (this.disposed) {
         await this.release(created);
         return;
@@ -71,6 +108,7 @@ export class DirectoryWatcherController {
     } catch (error) {
       if (this.deps.isNotFound(error) && this.watcherId === current) {
         this.watcherId = null;
+        this.operationId = null;
       } else if (!this.disposed && this.watcherId === current) {
         // Drain is destructive at the daemon. A lost response may have eaten
         // events, so the directory must converge even though this ID remains.
@@ -79,6 +117,24 @@ export class DirectoryWatcherController {
     }
   }
 
+  private async recoverAndRelease(operationId: string): Promise<void> {
+    for (let attempt = 0; attempt < MAX_CREATE_ATTEMPTS; attempt++) {
+      try {
+        const watcherId = await this.deps.create(operationId);
+        await this.release(watcherId);
+        return;
+      } catch (error) {
+        if (
+          !this.deps.isRetryable(error) ||
+          attempt === MAX_CREATE_ATTEMPTS - 1
+        ) {
+          return;
+        }
+        await this.deps.delay(retryDelayMs(attempt));
+      }
+    }
+  }
+
   private reportDirty(): void {
     const active = this.deps.isActive();
     if (!active) this.inactiveDirty = true;
@@ -91,11 +147,29 @@ export class DirectoryWatcherController {
     return id;
   }
 
-  private async release(watcherId: string): Promise<void> {
-    try {
-      await this.deps.remove(watcherId);
-    } catch {
-      // Gone already is the cleanup goal; lifecycle races are expected here.
+  private release(watcherId: string): Promise<void> {
+    if (this.releasePromise) return this.releasePromise;
+    const release = this.releaseWithRetry(watcherId).finally(() => {
+      if (this.releasePromise === release) this.releasePromise = null;
+    });
+    this.releasePromise = release;
+    return release;
+  }
+
+  private async releaseWithRetry(watcherId: string): Promise<void> {
+    for (let attempt = 0; attempt < MAX_REMOVE_ATTEMPTS; attempt++) {
+      try {
+        await this.deps.remove(watcherId);
+        return;
+      } catch (error) {
+        if (
+          !this.deps.isRetryable(error) ||
+          attempt === MAX_REMOVE_ATTEMPTS - 1
+        ) {
+          return;
+        }
+        await this.deps.delay(retryDelayMs(attempt));
+      }
     }
   }
 }
diff --git a/packages/console/src/features/sandboxes/hooks/useEnvd.ts b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
index 4cb7449..67e5578 100644
--- a/packages/console/src/features/sandboxes/hooks/useEnvd.ts
+++ b/packages/console/src/features/sandboxes/hooks/useEnvd.ts
@@ -18,6 +18,20 @@ import {
 } from '../envd-client';
 import { DirectoryWatcherController } from './directory-watcher';
 
+function operationId(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  bytes.set([((bytes.at(6) ?? 0) & 0x0f) | 0x40], 6);
+  bytes.set([((bytes.at(8) ?? 0) & 0x3f) | 0x80], 8);
+  const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, '0'));
+  return [
+    hex.slice(0, 4).join(''),
+    hex.slice(4, 6).join(''),
+    hex.slice(6, 8).join(''),
+    hex.slice(8, 10).join(''),
+    hex.slice(10).join(''),
+  ].join('-');
+}
+
 /**
  * 一个沙箱的 envd 面数据层:token、文件、进程。token 是无状态 HMAC,
  * 不过期 — 铸一次缓存整个会话(轮换 API token 才作废,那时 401 拦截兜底)。
@@ -125,7 +139,7 @@ export function useDirectoryWatch(
   useEffect(() => {
     if (!opts.enabled || !auth) return;
     const watcher = new DirectoryWatcherController({
-      create: () => createWatcher(auth, path),
+      create: (operationId) => createWatcher(auth, path, operationId),
       poll: (watcherId) => getWatcherEvents(auth, watcherId),
       remove: async (watcherId) => {
         await removeWatcher(auth, watcherId);
@@ -133,6 +147,14 @@ export function useDirectoryWatch(
       isActive: () => activeRef.current,
       isNotFound: (error) =>
         error instanceof EnvdError && error.code === 'not_found',
+      isRetryable: (error) =>
+        !(error instanceof EnvdError) ||
+        error.status === 408 ||
+        error.status === 429 ||
+        error.status >= 500,
+      operationId,
+      delay: (milliseconds) =>
+        new Promise<void>((resolve) => setTimeout(resolve, milliseconds)),
       onDirty: (active) => {
         const queryKey = ['envdDir', auth.sandboxId, path];
         if (active) {
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 309ad95..0402b28 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -171,6 +171,12 @@ export function buildApp({
   }).withTypeProvider<ZodTypeProvider>();
   app.setValidatorCompiler(validatorCompiler);
   app.setSerializerCompiler(serializerCompiler);
+  // Streaming WatchDir requests stay open until their watcher is stopped;
+  // preClose must cut those resources before Fastify waits for in-flight
+  // requests to drain. onClose would never be reached while a stream is live.
+  app.addHook('preClose', async () => {
+    await watchers.shutdown();
+  });
 
   // The single arbiter for the wire's error shape: every non-2xx body is
   // { message }, whoever produced the error. Without this, Fastify's own
diff --git a/packages/server/src/archive/archiver.test.ts b/packages/server/src/archive/archiver.test.ts
index af6e64d..530f523 100644
--- a/packages/server/src/archive/archiver.test.ts
+++ b/packages/server/src/archive/archiver.test.ts
@@ -4,10 +4,12 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_LIFECYCLE_POLICY } from '@dormice/shared';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { type Db, migrateDb, openDb } from '../db/db';
 import { createSandbox, findByName, transition } from '../db/ledger';
 import type { SandboxRow } from '../db/schema';
+import { WatcherTable } from '../e2b/watcher-table';
+import type { Executor } from '../executor/executor';
 import { FakeExecutor } from '../executor/fake';
 import { KeyedQueue } from '../keyed-queue';
 import { Archiver } from './archiver';
@@ -23,8 +25,16 @@ function setup() {
   const locks = new KeyedQueue();
   const store = new MemStore();
   const tmpDir = mkdtempSync(path.join(tmpdir(), 'dormice-archiver-'));
-  const archiver = new Archiver({ db, executor, locks, store, tmpDir });
-  return { db, executor, locks, store, tmpDir, archiver };
+  const watchers = new WatcherTable();
+  const archiver = new Archiver({
+    db,
+    executor,
+    locks,
+    store,
+    tmpDir,
+    watchers,
+  });
+  return { db, executor, locks, store, tmpDir, watchers, archiver };
 }
 
 /** A stopped sandbox with a marker file — the archiver's raw material. */
@@ -171,6 +181,33 @@ describe('Archiver.beginRestore', () => {
     expect(readdirSync(tmpDir)).toEqual([]);
   });
 
+  it('reaps deferred watcher cleanup before restored user work resumes', async () => {
+    const { db, executor, watchers, archiver } = setup();
+    const row = await seedStopped(db, executor, 'alice');
+    await archiver.archive(row);
+    const stop = vi
+      .fn<() => Promise<void>>()
+      .mockRejectedValueOnce(new Error('cleanup deferred'))
+      .mockResolvedValueOnce(undefined);
+    const watcherExecutor = {
+      watchDir: vi.fn().mockResolvedValue({ stop }),
+    } as unknown as Executor;
+    const watcherId = await watchers.create({
+      executor: watcherExecutor,
+      sandboxId: row.id,
+      path: '/home/user',
+      recursive: false,
+    });
+    await expect(
+      watchers.removeGoal(row.id, watcherId, { runnable: true }),
+    ).rejects.toThrow('cleanup deferred');
+
+    await archiver.restoreJoin(row.id);
+
+    expect(stop).toHaveBeenCalledTimes(2);
+    expect(watchers.count(row.id)).toBe(0);
+  });
+
   it('a missing archive object reverts the row to archived', async () => {
     const { db, executor, store, tmpDir, archiver } = setup();
     const row = await seedStopped(db, executor, 'alice');
diff --git a/packages/server/src/archive/archiver.ts b/packages/server/src/archive/archiver.ts
index 0d04b78..c442f76 100644
--- a/packages/server/src/archive/archiver.ts
+++ b/packages/server/src/archive/archiver.ts
@@ -5,6 +5,7 @@ import type { Db } from '../db/db';
 import { findById, setPausedByUser, touch, transition } from '../db/ledger';
 import type { SandboxRow } from '../db/schema';
 import { resolveImage } from '../db/templates';
+import type { WatcherTable } from '../e2b/watcher-table';
 import type { Executor } from '../executor/executor';
 import type { KeyedQueue } from '../keyed-queue';
 import { type ArchiveStore, objectKey } from './store';
@@ -36,6 +37,7 @@ export interface ArchiverDeps {
    */
   tmpDir: string;
   log?: (msg: string) => void;
+  watchers?: WatcherTable;
 }
 
 function clampPercent(fraction: number): number {
@@ -56,6 +58,7 @@ export class Archiver {
   private readonly locks: KeyedQueue;
   private readonly tmpDir: string;
   private readonly log: (msg: string) => void;
+  private readonly watchers: WatcherTable | undefined;
   private readonly restores = new Map<string, RestoreEntry>();
 
   constructor(deps: ArchiverDeps) {
@@ -65,6 +68,7 @@ export class Archiver {
     this.store = deps.store;
     this.tmpDir = deps.tmpDir;
     this.log = deps.log ?? (() => {});
+    this.watchers = deps.watchers;
   }
 
   /**
@@ -221,6 +225,7 @@ export class Archiver {
         await this.executor.start(sandboxId, {
           image: resolveImage(this.db, fresh.template),
         });
+        await this.watchers?.reapDeferred(sandboxId);
         // Awaken semantics, like every wake: an awake sandbox is by
         // definition not paused — without this, an autoPause-archived row
         // would restore into a logically-paused sandbox no one can reach.
diff --git a/packages/server/src/e2b/compat.test.ts b/packages/server/src/e2b/compat.test.ts
index b2f88ad..247312b 100644
--- a/packages/server/src/e2b/compat.test.ts
+++ b/packages/server/src/e2b/compat.test.ts
@@ -1612,6 +1612,114 @@ describe('E2B envd surface', () => {
     });
   });
 
+  it('replays CreateWatcher by operation ID and rejects a mismatched payload', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const operationId = '11111111-1111-4111-8111-111111111111';
+    const create = (path: string, recursive = false) =>
+      t.app.inject({
+        method: 'POST',
+        url: '/e2b/envd/filesystem.Filesystem/CreateWatcher',
+        headers: {
+          ...envdHeaders(t, sandboxID),
+          'x-dormice-watcher-operation-id': operationId,
+        },
+        payload: { path, recursive },
+      });
+
+    // Treat the first response as lost: the replay still recovers its ID.
+    const first = await create('/home/user');
+    const replay = await create('/home/user/./');
+    expect(replay.statusCode).toBe(200);
+    expect(replay.json()).toEqual(first.json());
+    expect(t.watchers.count(sandboxID)).toBe(1);
+
+    const conflict = await create('/home/user/other');
+    expect(conflict.statusCode).toBe(409);
+    expect(conflict.json().code).toBe('already_exists');
+    expect(t.watchers.count(sandboxID)).toBe(1);
+
+    const removed = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/RemoveWatcher',
+      first.json() as { watcherId: string },
+    );
+    expect(removed.statusCode).toBe(200);
+  });
+
+  it('validates operation and watcher IDs at the envd boundary', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const malformedOperation = await t.app.inject({
+      method: 'POST',
+      url: '/e2b/envd/filesystem.Filesystem/CreateWatcher',
+      headers: {
+        ...envdHeaders(t, sandboxID),
+        'x-dormice-watcher-operation-id': 'not-a-uuid',
+      },
+      payload: { path: '/home/user' },
+    });
+    expect(malformedOperation.statusCode).toBe(400);
+    expect(malformedOperation.json().code).toBe('invalid_argument');
+
+    const malformedWatcher = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/RemoveWatcher',
+      { watcherId: 'not-a-uuid' },
+    );
+    expect(malformedWatcher.statusCode).toBe(400);
+    expect(malformedWatcher.json().code).toBe('invalid_argument');
+  });
+
+  it('RemoveWatcher is a goal-state operation after lost responses and across sandboxes', async () => {
+    const t = testApp();
+    const { sandboxID } = await createSandbox(t);
+    const { sandboxID: otherSandbox } = await createSandbox(t);
+    const created = await envdRpc(
+      t,
+      sandboxID,
+      '/filesystem.Filesystem/CreateWatcher',
+      { path: '/home/user' },
+    );
+    const { watcherId } = created.json() as { watcherId: string };
+
+    // The other sandbox must not learn that this ID exists or affect it.
+    const crossSandbox = await envdRpc(
+      t,
+      otherSandbox,
+      '/filesystem.Filesystem/RemoveWatcher',
+      { watcherId },
+    );
+    expect(crossSandbox.statusCode).toBe(200);
+    expect(t.watchers.count(sandboxID)).toBe(1);
+
+    // Discard the first successful response, then replay after finalization.
+    expect(
+      (
+        await envdRpc(t, sandboxID, '/filesystem.Filesystem/RemoveWatcher', {
+          watcherId,
+        })
+      ).statusCode,
+    ).toBe(200);
+    expect(
+      (
+        await envdRpc(t, sandboxID, '/filesystem.Filesystem/RemoveWatcher', {
+          watcherId,
+        })
+      ).statusCode,
+    ).toBe(200);
+    expect(
+      (
+        await envdRpc(t, sandboxID, '/filesystem.Filesystem/RemoveWatcher', {
+          watcherId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+        })
+      ).statusCode,
+    ).toBe(200);
+    expect(t.watchers.count(sandboxID)).toBe(0);
+  });
+
   it('stale frozen wake swaps the shell and reaps its retired watcher', async () => {
     const t = testApp();
     await registerTemplate(t, 'watch-tpl', 'img-v1');
@@ -1813,10 +1921,9 @@ describe('E2B envd surface', () => {
       '/filesystem.Filesystem/RemoveWatcher',
       { watcherId },
     );
-    // Container death owns finalization. The fake conducts it synchronously and
-    // answers not_found; Docker may accept the goal-state remove while its exec
-    // exit is still arriving. Neither path may restart the stopped container.
-    expect([200, 404]).toContain(removed.statusCode);
+    // Container death owns physical finalization; goal-state remove is stable
+    // whether its exit conduction already arrived or is still in flight.
+    expect(removed.statusCode).toBe(200);
     expect(t.executor.stateOf(sandboxID)).toBe('stopped');
   });
 
@@ -2509,6 +2616,7 @@ describe('E2B surface vs the archiver', () => {
       locks,
       store,
       tmpDir: mkdtempSync(path.join(tmpdir(), 'dormice-compat-')),
+      watchers,
     });
     const app = buildApp({
       config,
diff --git a/packages/server/src/e2b/control.ts b/packages/server/src/e2b/control.ts
index c75e6f1..348842e 100644
--- a/packages/server/src/e2b/control.ts
+++ b/packages/server/src/e2b/control.ts
@@ -332,6 +332,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
               cause: 'protocol-dead row reaped by E2B create',
               actor: request.actor,
             },
+            watchers,
           );
         }
 
@@ -535,11 +536,18 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
     await locks.run(row.name, async () => {
       const fresh = findById(db, id);
       if (!fresh) throw notFound(id);
-      await destroySandbox(db, executor, fresh.id, archiver?.store ?? null, {
-        kind: 'destroyed',
-        cause: 'via E2B kill',
-        actor: request.actor,
-      });
+      await destroySandbox(
+        db,
+        executor,
+        fresh.id,
+        archiver?.store ?? null,
+        {
+          kind: 'destroyed',
+          cause: 'via E2B kill',
+          actor: request.actor,
+        },
+        watchers,
+      );
     });
     return reply.code(204).send();
   });
@@ -596,6 +604,7 @@ export const e2bControlRoutes: FastifyPluginAsyncZod<E2bDeps> = async (
             current.id,
             'paused via E2B (memory discarded)',
             request.actor,
+            watchers,
           );
         }
         setPausedByUser(db, fresh.id, true);
diff --git a/packages/server/src/e2b/envd/shared.ts b/packages/server/src/e2b/envd/shared.ts
index e4d7dd3..128ae62 100644
--- a/packages/server/src/e2b/envd/shared.ts
+++ b/packages/server/src/e2b/envd/shared.ts
@@ -115,6 +115,8 @@ export function streamError(
 export interface EnvdContext extends E2bDeps {
   /** The protocol-liveness gate: only a logically-running sandbox serves envd traffic. */
   requireRunningRow(sandboxId: string): SandboxRow;
+  /** Current ledger state says the container can receive a cleanup signal. */
+  isRunnable(sandboxId: string): boolean;
   /** Wake under the key's slot, like every native verb. */
   wakeForUse(sandboxId: string): Promise<SandboxRow>;
   /** Unary filesystem RPCs run entirely in the key's slot, like native file verbs. */
@@ -193,6 +195,10 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
    * Wake under the key's slot, like every native verb: physical wake-ups
    * take seconds and must not race the scanner or a destroy.
    */
+  function isRunnable(sandboxId: string): boolean {
+    return findById(db, sandboxId)?.state === 'active';
+  }
+
   async function wakeForUse(sandboxId: string): Promise<SandboxRow> {
     // The logical gate first: a paused-by-deadline sandbox answers 502
     // whether it is frozen or archived — restoring it for a request that
@@ -282,6 +288,7 @@ export function createEnvdContext(deps: E2bDeps): EnvdContext {
   return {
     ...deps,
     requireRunningRow,
+    isRunnable,
     wakeForUse,
     inSlot,
     withoutWake,
diff --git a/packages/server/src/e2b/envd/watch.ts b/packages/server/src/e2b/envd/watch.ts
index 363a401..774deb0 100644
--- a/packages/server/src/e2b/envd/watch.ts
+++ b/packages/server/src/e2b/envd/watch.ts
@@ -1,5 +1,5 @@
 import type { Buffer } from 'node:buffer';
-import type { FastifyInstance } from 'fastify';
+import type { FastifyInstance, FastifyRequest } from 'fastify';
 import {
   FileNotFoundError,
   NotADirectoryError,
@@ -12,7 +12,11 @@ import {
   FLAG_MESSAGE,
   readFirstMessage,
 } from '../protocol';
-import { WatcherLimitError } from '../watcher-table';
+import {
+  WatcherLimitError,
+  WatcherOperationConflictError,
+  WatcherOperationLimitError,
+} from '../watcher-table';
 import {
   type EnvdContext,
   MAX_KEEPALIVE_SECONDS,
@@ -31,6 +35,34 @@ const WATCH_EVENT_WIRE: Record<WatchEvent['type'], string> = {
   chmod: 'EVENT_TYPE_CHMOD',
 };
 
+export const WATCHER_OPERATION_HEADER = 'x-dormice-watcher-operation-id';
+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;
+
+function operationIdOf(request: FastifyRequest): string | undefined {
+  const header = request.headers[WATCHER_OPERATION_HEADER];
+  const value = Array.isArray(header) ? header[0] : header;
+  if (value === undefined) return undefined;
+  const normalized = value.toLowerCase();
+  if (!UUID.test(normalized)) {
+    throw connectError(
+      'invalid_argument',
+      `${WATCHER_OPERATION_HEADER} must be a UUID`,
+    );
+  }
+  return normalized;
+}
+
+function watcherIdOf(body: { watcherId?: string }): string {
+  if (!body.watcherId) {
+    throw connectError('invalid_argument', 'missing watcher id');
+  }
+  if (!UUID.test(body.watcherId)) {
+    throw connectError('invalid_argument', 'watcher id must be a UUID');
+  }
+  return body.watcherId.toLowerCase();
+}
+
 /**
  * Path validation errors travel differently on the two watch surfaces
  * (in-stream frame vs unary throw), but the codes and messages are one
@@ -78,8 +110,27 @@ export function registerWatchRoutes(
     if (!message.path) {
       return streamError(reply, 'invalid_argument', 'missing path');
     }
-    const row = await ctx.wakeForStream(request, reply);
-    if (!row) return;
+    const sandboxId = sandboxIdOf(request);
+    let reservationId: string;
+    try {
+      reservationId = watchers.reserveStreaming(sandboxId);
+    } catch (error) {
+      if (error instanceof WatcherLimitError) {
+        return streamError(reply, 'resource_exhausted', error.message);
+      }
+      throw error;
+    }
+    let row: Awaited<ReturnType<typeof ctx.wakeForStream>>;
+    try {
+      row = await ctx.wakeForStream(request, reply);
+    } catch (error) {
+      watchers.cancelStreamingReservation(sandboxId, reservationId);
+      throw error;
+    }
+    if (!row) {
+      watchers.cancelStreamingReservation(sandboxId, reservationId);
+      return;
+    }
 
     const write = rawWriter(reply);
     // Events hold at this gate until the start frame is on the wire — the
@@ -93,9 +144,12 @@ export function registerWatchRoutes(
     const ended = new Promise<Error>((resolve) => {
       settleEnd = resolve;
     });
-    let watcher: Awaited<ReturnType<typeof executor.watchDir>>;
+    let watcherId: string;
     try {
-      watcher = await executor.watchDir(row.id, {
+      watcherId = await watchers.createStreaming({
+        executor,
+        sandboxId: row.id,
+        reservationId,
         path: message.path,
         recursive: message.recursive === true,
         onEvent: async (event) => {
@@ -113,6 +167,9 @@ export function registerWatchRoutes(
           settleEnd(error ?? new Error('watcher ended unexpectedly')),
       });
     } catch (error) {
+      if (error instanceof WatcherLimitError) {
+        return streamError(reply, 'resource_exhausted', error.message);
+      }
       const { code, message: text } = watchStartError(error);
       return streamError(reply, code, text);
     }
@@ -162,9 +219,11 @@ export function registerWatchRoutes(
       clearInterval(keepalive);
       clearTimeout(deadlineTimer);
       try {
-        await watcher.stop();
-      } catch {
-        // The sandbox died under the watcher; its ending already spoke.
+        await watchers.closeStreaming(row.id, watcherId, {
+          runnable: ctx.isRunnable(row.id),
+        });
+      } catch (error) {
+        request.log.warn(error, 'streaming watcher cleanup deferred');
       }
       reply.raw.end();
     }
@@ -177,6 +236,7 @@ export function registerWatchRoutes(
     const body = request.body as { path?: string; recursive?: boolean };
     if (!body.path) throw connectError('invalid_argument', 'missing path');
     const path = body.path;
+    const operationId = operationIdOf(request);
     return ctx.inSlot(sandboxIdOf(request), async (row) => {
       try {
         const watcherId = await watchers.create({
@@ -184,12 +244,19 @@ export function registerWatchRoutes(
           sandboxId: row.id,
           path,
           recursive: body.recursive === true,
+          operationId,
         });
         return { watcherId };
       } catch (error) {
-        if (error instanceof WatcherLimitError) {
+        if (
+          error instanceof WatcherLimitError ||
+          error instanceof WatcherOperationLimitError
+        ) {
           throw connectError('resource_exhausted', error.message);
         }
+        if (error instanceof WatcherOperationConflictError) {
+          throw connectError('already_exists', error.message);
+        }
         const { code, message } = watchStartError(error);
         throw connectError(code, message);
       }
@@ -220,23 +287,15 @@ export function registerWatchRoutes(
   });
 
   app.post('/filesystem.Filesystem/RemoveWatcher', async (request) => {
-    const body = request.body as { watcherId?: string };
-    if (!body.watcherId) {
-      throw connectError('invalid_argument', 'missing watcher id');
-    }
+    const watcherId = watcherIdOf(request.body as { watcherId?: string });
     return ctx.withoutWake(sandboxIdOf(request), async (row) => {
-      // A frozen watcher survives physically. Retire it in daemon memory now
-      // and let the next real wake reap it; cleanup must not wake by itself.
-      const removed =
-        row.state === 'active'
-          ? await watchers.remove(row.id, body.watcherId as string)
-          : watchers.retire(row.id, body.watcherId as string);
-      if (!removed) {
-        throw connectError(
-          'not_found',
-          `watcher with id ${body.watcherId} not found`,
-        );
-      }
+      // The verb expresses the goal "this ID is absent from this sandbox".
+      // Unknown and cross-sandbox IDs already satisfy it and deliberately look
+      // alike. Only a physically active sandbox can accept a signal now; every
+      // colder or protocol-dead state retires in memory without waking.
+      await watchers.removeGoal(row.id, watcherId, {
+        runnable: row.state === 'active',
+      });
       return {};
     });
   });
diff --git a/packages/server/src/e2b/watcher-table.test.ts b/packages/server/src/e2b/watcher-table.test.ts
index b762cd4..d2e6254 100644
--- a/packages/server/src/e2b/watcher-table.test.ts
+++ b/packages/server/src/e2b/watcher-table.test.ts
@@ -8,6 +8,8 @@ import { WatchProcessLifecycle } from '../executor/watch-lifecycle';
 import {
   MAX_WATCHERS_PER_SANDBOX,
   WatcherLimitError,
+  WatcherOperationConflictError,
+  WatcherOperationLimitError,
   WatcherTable,
 } from './watcher-table';
 
@@ -186,6 +188,248 @@ describe('WatcherTable', () => {
     expect(table.count('sandbox-1')).toBe(0);
   });
 
+  it('replays one operation sequentially and concurrently without another watcher', async () => {
+    const pending = deferred<WatchDirHandle>();
+    const executor = {
+      watchDir: vi.fn(() => pending.promise),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const operationId = '11111111-1111-4111-8111-111111111111';
+
+    const first = table.create({ ...args(executor), operationId });
+    const concurrent = table.create({
+      ...args(executor),
+      path: '/home/user/./',
+      operationId,
+    });
+    expect(executor.watchDir).toHaveBeenCalledTimes(1);
+    expect(table.count('sandbox-1')).toBe(1);
+    pending.resolve({ stop: async () => {} });
+
+    const [watcherId, replayed] = await Promise.all([first, concurrent]);
+    expect(replayed).toBe(watcherId);
+    await expect(
+      table.create({ ...args(executor), operationId }),
+    ).resolves.toBe(watcherId);
+    expect(executor.watchDir).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects an operation replay with a different canonical request', async () => {
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop: async () => {} }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const operationId = '22222222-2222-4222-8222-222222222222';
+    const watcherId = await table.create({ ...args(executor), operationId });
+
+    await expect(
+      table.create({
+        ...args(executor),
+        path: '/home/user/other',
+        operationId,
+      }),
+    ).rejects.toBeInstanceOf(WatcherOperationConflictError);
+    await expect(
+      table.create({ ...args(executor), recursive: true, operationId }),
+    ).rejects.toBeInstanceOf(WatcherOperationConflictError);
+    expect(table.drain('sandbox-1', watcherId)).toEqual([]);
+    expect(executor.watchDir).toHaveBeenCalledTimes(1);
+  });
+
+  it('retains a live operation across expiry and prunes only its completed tombstone', async () => {
+    let now = 0;
+    const stop = vi.fn().mockResolvedValue(undefined);
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop }),
+    } as unknown as Executor;
+    const table = new WatcherTable({
+      now: () => now,
+      operationRetentionMs: 10,
+    });
+    const operationId = '33333333-3333-4333-8333-333333333333';
+    const watcherId = await table.create({ ...args(executor), operationId });
+
+    now = 100;
+    await expect(
+      table.create({ ...args(executor), operationId }),
+    ).resolves.toBe(watcherId);
+    expect(executor.watchDir).toHaveBeenCalledTimes(1);
+
+    await table.removeGoal('sandbox-1', watcherId);
+    expect(table.count('sandbox-1')).toBe(0);
+    expect(table.operationCount('sandbox-1')).toBe(1);
+    await expect(
+      table.create({ ...args(executor), operationId }),
+    ).resolves.toBe(watcherId);
+
+    now = 111;
+    expect(table.operationCount('sandbox-1')).toBe(0);
+    const replacement = await table.create({ ...args(executor), operationId });
+    expect(replacement).not.toBe(watcherId);
+    expect(executor.watchDir).toHaveBeenCalledTimes(2);
+  });
+
+  it('releases a failed operation and bounds retained operation state', async () => {
+    const executor = {
+      watchDir: vi
+        .fn()
+        .mockRejectedValueOnce(new Error('start failed'))
+        .mockResolvedValue({ stop: async () => {} }),
+    } as unknown as Executor;
+    const table = new WatcherTable({ maxOperationsPerSandbox: 1 });
+    const firstId = '44444444-4444-4444-8444-444444444444';
+    await expect(
+      table.create({ ...args(executor), operationId: firstId }),
+    ).rejects.toThrow('start failed');
+    expect(table.operationCount('sandbox-1')).toBe(0);
+    await table.create({ ...args(executor), operationId: firstId });
+
+    await expect(
+      table.create({
+        ...args(executor),
+        operationId: '55555555-5555-4555-8555-555555555555',
+      }),
+    ).rejects.toBeInstanceOf(WatcherOperationLimitError);
+  });
+
+  it('makes repeated and cross-sandbox goal removal converge without another stop', async () => {
+    const stop = vi.fn().mockResolvedValue(undefined);
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const id = await table.create(args(executor));
+
+    await table.removeGoal('sandbox-2', id);
+    expect(stop).not.toHaveBeenCalled();
+    await Promise.all([
+      table.removeGoal('sandbox-1', id),
+      table.removeGoal('sandbox-1', id),
+    ]);
+    await table.removeGoal('sandbox-1', id);
+    await table.removeGoal('sandbox-1', 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa');
+    expect(stop).toHaveBeenCalledTimes(1);
+  });
+
+  it('reserves streaming capacity before physical start and releases a refused wake', () => {
+    const table = new WatcherTable();
+    for (let index = 0; index < MAX_WATCHERS_PER_SANDBOX; index++) {
+      table.reserveStreaming('sandbox-1');
+    }
+    expect(() => table.reserveStreaming('sandbox-1')).toThrow(
+      WatcherLimitError,
+    );
+
+    table.disposeSandbox('sandbox-1');
+    expect(table.count('sandbox-1')).toBe(0);
+    const reservation = table.reserveStreaming('sandbox-1');
+    table.cancelStreamingReservation('sandbox-1', reservation);
+    expect(table.count('sandbox-1')).toBe(0);
+  });
+
+  it('owns failed streaming cleanup until a legitimate reap succeeds', async () => {
+    const stop = vi
+      .fn<() => Promise<void>>()
+      .mockRejectedValueOnce(new Error('signal failed'))
+      .mockResolvedValueOnce(undefined);
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const id = await table.createStreaming({
+      ...args(executor),
+      onEvent: async () => {},
+      onEnd: vi.fn(),
+    });
+
+    await expect(
+      table.closeStreaming('sandbox-1', id, { runnable: true }),
+    ).resolves.toBeUndefined();
+    expect(stop).toHaveBeenCalledTimes(2);
+    expect(table.count('sandbox-1')).toBe(0);
+  });
+
+  it('keeps cold streaming cleanup deferred until a legitimate reap', async () => {
+    const stop = vi.fn().mockResolvedValue(undefined);
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const id = await table.createStreaming({
+      ...args(executor),
+      onEvent: async () => {},
+      onEnd: vi.fn(),
+    });
+
+    await table.closeStreaming('sandbox-1', id, { runnable: false });
+    expect(stop).not.toHaveBeenCalled();
+    expect(table.count('sandbox-1')).toBe(1);
+
+    await table.reapDeferred('sandbox-1');
+    expect(stop).toHaveBeenCalledTimes(1);
+    expect(table.count('sandbox-1')).toBe(0);
+  });
+
+  it('ends every streaming route before shutdown waits for physical stops', async () => {
+    const secondStop = deferred<void>();
+    const stop = vi
+      .fn<() => Promise<void>>()
+      .mockResolvedValueOnce(undefined)
+      .mockResolvedValueOnce(undefined)
+      .mockImplementationOnce(() => secondStop.promise);
+    const onEnd = vi.fn();
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    await table.createStreaming({
+      ...args(executor),
+      onEvent: async () => {},
+      onEnd,
+    });
+
+    table.disposeSandbox('sandbox-1');
+    expect(onEnd).toHaveBeenCalledTimes(1);
+    expect(onEnd.mock.calls[0]?.[0]).toBeInstanceOf(Error);
+    expect(table.count('sandbox-1')).toBe(0);
+
+    const shutdownEnd = vi.fn();
+    await table.createStreaming({
+      ...args(executor),
+      onEvent: async () => {},
+      onEnd: shutdownEnd,
+    });
+    const pendingEnd = vi.fn();
+    await table.createStreaming({
+      ...args(executor),
+      path: '/home/user/other',
+      onEvent: async () => {},
+      onEnd: pendingEnd,
+    });
+
+    const shutdown = table.shutdown();
+    expect(shutdownEnd).toHaveBeenCalledTimes(1);
+    expect(pendingEnd).toHaveBeenCalledTimes(1);
+    expect(stop).toHaveBeenCalledTimes(2);
+    secondStop.resolve();
+    await shutdown;
+  });
+
+  it('drops an operation binding when container death makes its watcher unrecoverable', async () => {
+    const executor = {
+      watchDir: vi.fn().mockResolvedValue({ stop: async () => {} }),
+    } as unknown as Executor;
+    const table = new WatcherTable();
+    const operationId = '66666666-6666-4666-8666-666666666666';
+    const before = await table.create({ ...args(executor), operationId });
+
+    table.disposeSandbox('sandbox-1');
+    const after = await table.create({ ...args(executor), operationId });
+
+    expect(after).not.toBe(before);
+    expect(executor.watchDir).toHaveBeenCalledTimes(2);
+  });
+
   it('keeps watcher IDs scoped to their sandbox', async () => {
     const executor = {
       watchDir: vi.fn().mockResolvedValue({ stop: async () => {} }),
diff --git a/packages/server/src/e2b/watcher-table.ts b/packages/server/src/e2b/watcher-table.ts
index 2ffaaff..084f3ce 100644
--- a/packages/server/src/e2b/watcher-table.ts
+++ b/packages/server/src/e2b/watcher-table.ts
@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { resolveSandboxPath } from '@dormice/shared';
 import type {
   Executor,
   WatchDirHandle,
@@ -6,101 +7,196 @@ import type {
 } from '../executor/executor';
 
 /**
- * The polling half of directory watching — what the sync SDKs use instead
- * of the WatchDir stream: CreateWatcher parks a watcher here, GetWatcherEvents
- * drains its buffer, RemoveWatcher retires it. Daemon memory, like the process
- * table: a daemon restart empties it honestly, and a watcher's death (its
- * container stopping) deletes its record through physical conduction — the
- * next poll answers not_found, no lifecycle hooks involved.
+ * The daemon-owned half of directory watching. Polling watchers publish an ID
+ * whose event buffer can be drained; streaming watchers attach their delivery
+ * callback directly. Both kinds park their physical handle here so request
+ * teardown, natural process exit, sandbox lifecycle, and daemon shutdown all
+ * converge through one owner.
  *
  * Two ceilings real envd does not have, on purpose: envd runs inside the
- * sandbox, so its unbounded buffer can only blow up the sandbox itself —
- * this table lives in the host-side daemon, where unbounded means one
- * sandbox writing files in a loop grows the host's memory. The buffer keeps
- * the newest events (oldest dropped first); the per-sandbox watcher count
- * refuses with resource_exhausted. Starting and retired records count too:
- * reservations make the ceiling true under concurrent creates, and retired
- * handles still own a physical process until the next legitimate wake reaps it.
+ * sandbox, so its unbounded state can only blow up the sandbox itself — this
+ * registry lives in the host-side daemon. Starting and retired records count
+ * too: reservations make the watcher ceiling true under concurrent starts,
+ * and retired handles still own a physical process until a legitimate wake
+ * reaps them.
  */
 export const MAX_EVENTS_PER_WATCHER = 8192;
 export const MAX_WATCHERS_PER_SANDBOX = 128;
 
-/** Refused watcher creation: the per-sandbox ceiling. */
+/** Five minutes comfortably covers a bounded client retry sequence. */
+export const WATCHER_OPERATION_RETENTION_MS = 5 * 60 * 1000;
+/** Live bindings plus completed tombstones; live bindings are never evicted. */
+export const MAX_WATCHER_OPERATIONS_PER_SANDBOX = 256;
+
+/** Refused watcher creation: the per-sandbox physical watcher ceiling. */
 export class WatcherLimitError extends Error {}
+/** Refused opt-in create: its bounded operation ledger is full. */
+export class WatcherOperationLimitError extends Error {}
+/** The same operation identity was reused for a different canonical request. */
+export class WatcherOperationConflictError extends Error {}
+
+interface OperationIdentity {
+  id: string;
+  fingerprint: string;
+}
 
 interface WatcherRecord {
   watcherId: string;
   sandboxId: string;
+  kind: 'polling' | 'streaming';
   events: WatchEvent[];
   state: 'starting' | 'active' | 'retired' | 'ended';
+  operation?: OperationIdentity;
+  published: boolean;
   handle?: WatchDirHandle;
   endError?: Error;
+  startPromise?: Promise<string>;
   stopPromise?: Promise<void>;
+  streamEnd?: (error?: Error) => void;
+  streamEndNotified?: boolean;
+}
+
+interface OperationTombstone extends OperationIdentity {
+  kind: 'tombstone';
+  sandboxId: string;
+  watcherId: string;
+  expiresAt: number;
+}
+
+type OperationEntry =
+  | { kind: 'live'; record: WatcherRecord }
+  | OperationTombstone;
+
+export interface WatcherTableOptions {
+  now?: () => number;
+  operationRetentionMs?: number;
+  maxOperationsPerSandbox?: number;
+  retryDelay?: (milliseconds: number) => Promise<void>;
+}
+
+interface CreateArgs {
+  executor: Executor;
+  sandboxId: string;
+  path: string;
+  recursive: boolean;
+  operationId?: string;
+}
+
+interface CreateStreamingArgs extends Omit<CreateArgs, 'operationId'> {
+  reservationId?: string;
+  onEvent: (event: WatchEvent) => void | Promise<void>;
+  onEnd(error?: Error): void;
 }
 
 export class WatcherTable {
   private readonly records = new Map<string, WatcherRecord>();
+  private readonly operations = new Map<string, OperationEntry>();
+  private readonly now: () => number;
+  private readonly operationRetentionMs: number;
+  private readonly maxOperationsPerSandbox: number;
+  private readonly retryDelay: (milliseconds: number) => Promise<void>;
+  private closed = false;
 
-  /** Starts a watcher, reserving capacity before the executor can yield. */
-  async create(args: {
-    executor: Executor;
-    sandboxId: string;
-    path: string;
-    recursive: boolean;
-  }): Promise<string> {
-    const { executor, sandboxId, path, recursive } = args;
-    if (this.count(sandboxId) >= MAX_WATCHERS_PER_SANDBOX) {
-      throw new WatcherLimitError(
-        `sandbox ${sandboxId} already has ${MAX_WATCHERS_PER_SANDBOX} watchers — remove some before creating more`,
+  constructor(opts: WatcherTableOptions = {}) {
+    this.now = opts.now ?? Date.now;
+    this.operationRetentionMs =
+      opts.operationRetentionMs ?? WATCHER_OPERATION_RETENTION_MS;
+    this.maxOperationsPerSandbox =
+      opts.maxOperationsPerSandbox ?? MAX_WATCHER_OPERATIONS_PER_SANDBOX;
+    this.retryDelay =
+      opts.retryDelay ??
+      ((milliseconds) =>
+        new Promise<void>((resolve) => setTimeout(resolve, milliseconds)));
+  }
+
+  /**
+   * Starts a polling watcher. An optional Dormice operation ID makes the
+   * result replay-safe without changing official envd's protobuf message.
+   */
+  async create(args: CreateArgs): Promise<string> {
+    this.pruneOperations();
+    const operation = args.operationId
+      ? {
+          id: args.operationId,
+          fingerprint: this.fingerprint(args.path, args.recursive),
+        }
+      : undefined;
+
+    if (operation) {
+      const existing = this.operations.get(
+        this.operationKey(args.sandboxId, operation.id),
       );
+      if (existing) return this.replay(existing, operation);
+      if (this.operationCount(args.sandboxId) >= this.maxOperationsPerSandbox) {
+        throw new WatcherOperationLimitError(
+          `sandbox ${args.sandboxId} already has ${this.maxOperationsPerSandbox} retained watcher operations — retry after the replay window expires`,
+        );
+      }
     }
 
-    const record: WatcherRecord = {
-      watcherId: randomUUID(),
-      sandboxId,
-      events: [],
-      state: 'starting',
-    };
-    this.records.set(record.watcherId, record);
-
-    try {
-      const handle = await executor.watchDir(sandboxId, {
-        path,
-        recursive,
-        onEvent: (event) => {
-          if (record.state !== 'starting' && record.state !== 'active') return;
-          record.events.push(event);
-          if (record.events.length > MAX_EVENTS_PER_WATCHER) {
-            record.events.shift();
-          }
-        },
-        onEnd: (error) => {
-          record.endError = error;
-          this.finalize(record);
-        },
-      });
-      record.handle = handle;
-      if (record.state !== 'starting') {
-        const failure =
-          record.endError ?? new Error('watcher retired while starting');
-        record.state = 'retired';
-        await this.stopRetired(record);
-        throw failure;
+    const record = this.reserve(args.sandboxId, 'polling', operation);
+    const started = this.start(record, args, (event) => {
+      if (record.state !== 'starting' && record.state !== 'active') return;
+      record.events.push(event);
+      if (record.events.length > MAX_EVENTS_PER_WATCHER) {
+        record.events.shift();
       }
-      record.state = 'active';
-      return record.watcherId;
-    } catch (error) {
+    });
+    record.startPromise = started;
+    return started;
+  }
+
+  /** Reserves one registry slot for a streaming watcher before physical start. */
+  reserveStreaming(sandboxId: string): string {
+    return this.reserve(sandboxId, 'streaming').watcherId;
+  }
+
+  /** Releases an unpublished streaming reservation after wake/start refusal. */
+  cancelStreamingReservation(sandboxId: string, watcherId: string): void {
+    const record = this.records.get(watcherId);
+    if (
+      record?.sandboxId === sandboxId &&
+      record.kind === 'streaming' &&
+      record.state === 'starting' &&
+      !record.published
+    ) {
       this.finalize(record);
-      throw error;
     }
   }
 
-  /** Living, published watcher events; retired/starting IDs read as absent. */
+  /** Starts a streaming watcher under the same capacity and cleanup owner. */
+  async createStreaming(args: CreateStreamingArgs): Promise<string> {
+    const reserved = args.reservationId
+      ? this.records.get(args.reservationId)
+      : undefined;
+    if (
+      args.reservationId &&
+      (!reserved ||
+        reserved.sandboxId !== args.sandboxId ||
+        reserved.kind !== 'streaming' ||
+        reserved.state !== 'starting')
+    ) {
+      throw new Error(
+        `streaming watcher reservation ${args.reservationId} is not live`,
+      );
+    }
+    const record = reserved ?? this.reserve(args.sandboxId, 'streaming');
+    record.streamEnd = args.onEnd;
+    const started = this.start(record, args, async (event) => {
+      if (record.state !== 'starting' && record.state !== 'active') return;
+      await args.onEvent(event);
+    });
+    record.startPromise = started;
+    return started;
+  }
+
+  /** Living, published polling events; every other ID reads as absent. */
   drain(sandboxId: string, watcherId: string): WatchEvent[] | undefined {
     const record = this.records.get(watcherId);
     if (
       !record ||
       record.sandboxId !== sandboxId ||
+      record.kind !== 'polling' ||
       record.state !== 'active'
     ) {
       return undefined;
@@ -109,29 +205,54 @@ export class WatcherTable {
   }
 
   /**
-   * Retires without touching the container. Frozen cleanup stays cold; the
-   * next real wake calls reapRetired before serving user work.
+   * Makes one well-formed watcher ID absent from this sandbox. Unknown and
+   * cross-sandbox IDs already satisfy that goal and deliberately look alike.
+   * A cold sandbox retires without touching its container.
    */
-  retire(sandboxId: string, watcherId: string): boolean {
+  async removeGoal(
+    sandboxId: string,
+    watcherId: string,
+    opts: { runnable: boolean; attempts?: number } = { runnable: true },
+  ): Promise<void> {
     const record = this.records.get(watcherId);
-    if (!record || record.sandboxId !== sandboxId) return false;
+    if (!record || record.sandboxId !== sandboxId) return;
     record.state = 'retired';
     record.events.length = 0;
-    return true;
+    if (!opts.runnable) return;
+
+    const attempts = Math.max(1, opts.attempts ?? 1);
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      try {
+        await this.stopRetired(record);
+        return;
+      } catch (error) {
+        if (attempt === attempts || !this.records.has(record.watcherId)) {
+          throw error;
+        }
+        await this.retryDelay(Math.min(25 * 2 ** (attempt - 1), 100));
+      }
+    }
   }
 
-  /** Stops now. A failed stop remains retired so the next wake can retry. */
+  /** Backward-compatible spelling for existing callers and focused tests. */
   async remove(sandboxId: string, watcherId: string): Promise<boolean> {
+    const record = this.records.get(watcherId);
+    if (!record || record.sandboxId !== sandboxId) return false;
+    await this.removeGoal(sandboxId, watcherId, { runnable: true });
+    return true;
+  }
+
+  /** Retires without touching the container; a legitimate wake reaps it. */
+  retire(sandboxId: string, watcherId: string): boolean {
     const record = this.records.get(watcherId);
     if (!record || record.sandboxId !== sandboxId) return false;
     record.state = 'retired';
     record.events.length = 0;
-    await this.stopRetired(record);
     return true;
   }
 
-  /** Reaps deferred frozen cleanup after a legitimate wake made it runnable. */
-  async reapRetired(sandboxId: string): Promise<void> {
+  /** Reaps all deferred polling and streaming cleanup after a legitimate wake. */
+  async reapDeferred(sandboxId: string): Promise<void> {
     const retired = [...this.records.values()].filter(
       (record) => record.sandboxId === sandboxId && record.state === 'retired',
     );
@@ -139,12 +260,61 @@ export class WatcherTable {
       try {
         await this.stopRetired(record);
       } catch {
-        // Cleanup is subordinate to the user work that caused this wake.
-        // The record stays retired and the next legitimate wake retries it.
+        // Cleanup is subordinate to the user work that caused this wake. The
+        // record stays retired and the next legitimate wake retries it.
       }
     }
   }
 
+  /** Backward-compatible name while lifecycle call sites migrate. */
+  reapRetired(sandboxId: string): Promise<void> {
+    return this.reapDeferred(sandboxId);
+  }
+
+  /** A proven container stop/destroy ends every watcher without signaling it. */
+  disposeSandbox(sandboxId: string): void {
+    for (const record of [...this.records.values()]) {
+      if (record.sandboxId !== sandboxId) continue;
+      this.notifyStreamEnd(record, new Error('sandbox container ended'));
+      this.finalize(record, false);
+    }
+  }
+
+  /** Stops a route-owned streaming watcher while retaining failed cleanup. */
+  closeStreaming(
+    sandboxId: string,
+    watcherId: string,
+    opts: { runnable: boolean },
+  ): Promise<void> {
+    return this.removeGoal(sandboxId, watcherId, {
+      runnable: opts.runnable,
+      attempts: opts.runnable ? 3 : 1,
+    });
+  }
+
+  /** Bounded best-effort teardown for Fastify/daemon shutdown. */
+  async shutdown(timeoutMs = 5000): Promise<void> {
+    this.closed = true;
+    const records = [...this.records.values()];
+    for (const record of records) {
+      record.state = 'retired';
+      record.events.length = 0;
+      this.notifyStreamEnd(record);
+    }
+    const stopping = Promise.allSettled(
+      records.map((record) => this.stopRetired(record)),
+    );
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    await Promise.race([
+      stopping,
+      new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+      }),
+    ]);
+    if (timer) clearTimeout(timer);
+    for (const record of records) this.finalize(record);
+  }
+
   count(sandboxId: string): number {
     let count = 0;
     for (const record of this.records.values()) {
@@ -153,26 +323,162 @@ export class WatcherTable {
     return count;
   }
 
+  operationCount(sandboxId: string): number {
+    this.pruneOperations();
+    let count = 0;
+    for (const entry of this.operations.values()) {
+      const owner =
+        entry.kind === 'live' ? entry.record.sandboxId : entry.sandboxId;
+      if (owner === sandboxId) count++;
+    }
+    return count;
+  }
+
+  private reserve(
+    sandboxId: string,
+    kind: WatcherRecord['kind'],
+    operation?: OperationIdentity,
+  ): WatcherRecord {
+    if (this.closed) throw new Error('watcher registry is shutting down');
+    if (this.count(sandboxId) >= MAX_WATCHERS_PER_SANDBOX) {
+      throw new WatcherLimitError(
+        `sandbox ${sandboxId} already has ${MAX_WATCHERS_PER_SANDBOX} watchers — remove some before creating more`,
+      );
+    }
+    const record: WatcherRecord = {
+      watcherId: randomUUID(),
+      sandboxId,
+      kind,
+      events: [],
+      state: 'starting',
+      operation,
+      published: false,
+    };
+    this.records.set(record.watcherId, record);
+    if (operation) {
+      this.operations.set(this.operationKey(sandboxId, operation.id), {
+        kind: 'live',
+        record,
+      });
+    }
+    return record;
+  }
+
+  private async start(
+    record: WatcherRecord,
+    args: Omit<CreateArgs, 'operationId'>,
+    onEvent: (event: WatchEvent) => void | Promise<void>,
+  ): Promise<string> {
+    try {
+      const handle = await args.executor.watchDir(args.sandboxId, {
+        path: resolveSandboxPath(args.path),
+        recursive: args.recursive,
+        onEvent,
+        onEnd: (error) => {
+          record.endError = error;
+          const published = record.published;
+          if (published) this.notifyStreamEnd(record, error);
+          this.finalize(record);
+        },
+      });
+      record.handle = handle;
+      if (record.state !== 'starting') {
+        const failure =
+          record.endError ?? new Error('watcher retired while starting');
+        record.state = 'retired';
+        await this.stopRetired(record);
+        throw failure;
+      }
+      record.state = 'active';
+      record.published = true;
+      return record.watcherId;
+    } catch (error) {
+      this.finalize(record);
+      throw error;
+    }
+  }
+
+  private replay(
+    existing: OperationEntry,
+    operation: OperationIdentity,
+  ): Promise<string> {
+    const fingerprint =
+      existing.kind === 'live'
+        ? existing.record.operation?.fingerprint
+        : existing.fingerprint;
+    if (fingerprint !== operation.fingerprint) {
+      throw new WatcherOperationConflictError(
+        `watcher operation ${operation.id} was already used with different path or options`,
+      );
+    }
+    if (existing.kind === 'tombstone') {
+      return Promise.resolve(existing.watcherId);
+    }
+    return (
+      existing.record.startPromise ?? Promise.resolve(existing.record.watcherId)
+    );
+  }
+
   private async stopRetired(record: WatcherRecord): Promise<void> {
     if (record.state === 'ended') return;
     const handle = record.handle;
     if (!handle) return;
     if (!record.stopPromise) {
-      record.stopPromise = handle.stop().then(
+      const attempt = handle.stop().then(
         () => this.finalize(record),
         (error) => {
-          record.stopPromise = undefined;
+          if (record.stopPromise === attempt) record.stopPromise = undefined;
           throw error;
         },
       );
+      record.stopPromise = attempt;
     }
     await record.stopPromise;
   }
 
-  private finalize(record: WatcherRecord): void {
+  private notifyStreamEnd(record: WatcherRecord, error?: Error): void {
+    if (record.kind !== 'streaming' || record.streamEndNotified) return;
+    record.streamEndNotified = true;
+    record.streamEnd?.(error);
+  }
+
+  private finalize(record: WatcherRecord, retainOperation = true): void {
     if (record.state === 'ended') return;
     record.state = 'ended';
     this.records.delete(record.watcherId);
     record.events.length = 0;
+    if (!record.operation) return;
+
+    const key = this.operationKey(record.sandboxId, record.operation.id);
+    const entry = this.operations.get(key);
+    if (entry?.kind !== 'live' || entry.record !== record) return;
+    if (!record.published || !retainOperation) {
+      this.operations.delete(key);
+      return;
+    }
+    this.operations.set(key, {
+      kind: 'tombstone',
+      sandboxId: record.sandboxId,
+      watcherId: record.watcherId,
+      ...record.operation,
+      expiresAt: this.now() + this.operationRetentionMs,
+    });
+  }
+
+  private pruneOperations(): void {
+    const now = this.now();
+    for (const [key, entry] of this.operations) {
+      if (entry.kind === 'tombstone' && entry.expiresAt <= now) {
+        this.operations.delete(key);
+      }
+    }
+  }
+
+  private fingerprint(path: string, recursive: boolean): string {
+    return JSON.stringify([resolveSandboxPath(path), recursive]);
+  }
+
+  private operationKey(sandboxId: string, operationId: string): string {
+    return `${sandboxId}\0${operationId}`;
   }
 }
diff --git a/packages/server/src/lifecycle.ts b/packages/server/src/lifecycle.ts
index 47c8d29..06ef052 100644
--- a/packages/server/src/lifecycle.ts
+++ b/packages/server/src/lifecycle.ts
@@ -57,8 +57,10 @@ export async function stopSandbox(
   sandboxId: string,
   cause?: string,
   actor?: string | null,
+  watchers?: WatcherTable,
 ): Promise<SandboxRow> {
   await executor.stop(sandboxId);
+  watchers?.disposeSandbox(sandboxId);
   const row = transition(db, sandboxId, 'stopped');
   recordActivity(db, {
     kind: 'stopped',
@@ -96,6 +98,7 @@ export async function destroySandbox(
     kind: 'destroyed',
     cause: 'via destroySandbox',
   },
+  watchers?: WatcherTable,
 ): Promise<void> {
   const row = findById(db, sandboxId);
   if (row?.state === 'archived') {
@@ -105,6 +108,7 @@ export async function destroySandbox(
       );
     }
     await store.delete(objectKey(sandboxId));
+    watchers?.disposeSandbox(sandboxId);
     deleteSandbox(db, sandboxId);
     // With the disk gone its metrics history has no owner; fleet snapshots
     // belong to no sandbox and stay.
@@ -119,6 +123,7 @@ export async function destroySandbox(
     return;
   }
   await executor.destroy(sandboxId);
+  watchers?.disposeSandbox(sandboxId);
   deleteSandbox(db, sandboxId);
   deleteSandboxMetricsSamples(db, sandboxId);
   if (row) {
@@ -149,8 +154,10 @@ export async function rebuildSandbox(
   row: SandboxRow,
   actor?: string | null,
   detail?: string,
+  watchers?: WatcherTable,
 ): Promise<SandboxRow> {
   await executor.removeContainer(row.id);
+  watchers?.disposeSandbox(row.id);
   recordActivity(db, {
     kind: 'rebuilt',
     sandboxName: row.name,
@@ -196,7 +203,7 @@ export async function wakeSandbox(
 ): Promise<SandboxRow> {
   switch (row.state) {
     case 'active':
-      await watchers?.reapRetired(row.id);
+      await watchers?.reapDeferred(row.id);
       return row;
     case 'frozen':
     case 'stopped': {
@@ -210,11 +217,12 @@ export async function wakeSandbox(
               row,
               actor,
               `stale shell swapped at wake: ${born} -> ${next}`,
+              watchers,
             )
           : row;
       if (fresh.state === 'frozen') {
         await executor.unfreeze(fresh.id);
-        await watchers?.reapRetired(fresh.id);
+        await watchers?.reapDeferred(fresh.id);
         return awaken(
           db,
           fresh,
@@ -227,7 +235,7 @@ export async function wakeSandbox(
       await executor.start(fresh.id, {
         image: resolveImage(db, fresh.template),
       });
-      await watchers?.reapRetired(fresh.id);
+      await watchers?.reapDeferred(fresh.id);
       return awaken(db, fresh, 'cold start from the surviving disk', actor);
     }
     case 'archived':
diff --git a/packages/server/src/main.ts b/packages/server/src/main.ts
index 4af703a..7223bef 100644
--- a/packages/server/src/main.ts
+++ b/packages/server/src/main.ts
@@ -11,6 +11,7 @@ import { migrateDb, openDb } from './db/db';
 import { listSandboxes } from './db/ledger';
 import { acquireSingleWriterLock } from './db/lock';
 import { ensureRuntimeSettings, readRuntimeSettings } from './db/settings';
+import { WatcherTable } from './e2b/watcher-table';
 import { DockerExecutor } from './executor/docker';
 import type { Executor } from './executor/executor';
 import { FakeExecutor } from './executor/fake';
@@ -93,6 +94,7 @@ const executor = buildExecutor(config, (msg) => log.info(msg));
 // One queue for the whole daemon: HTTP verbs and the heartbeat's actors
 // must share the same per-sandbox slots or the serialization means nothing.
 const locks = new KeyedQueue();
+const watchers = new WatcherTable();
 
 // The archiver exists exactly when S3 is configured; without it the daemon
 // is byte-for-byte the archive-less daemon. Temp transfers stage next to
@@ -107,6 +109,7 @@ if (s3 !== null) {
     store: new S3Store(s3),
     tmpDir: path.join(config.DORMICE_DATA_DIR, 'tmp'),
     log: (msg) => log.info(msg),
+    watchers,
   });
   await archiver.init();
   log.info(`archiver enabled: bucket ${s3.bucket} at ${s3.endpoint}`);
@@ -195,6 +198,7 @@ const app = buildApp({
   ingress,
   swap,
   updater,
+  watchers,
 });
 
 // Before trusting the pairing of this ledger and this reality, check it:
@@ -217,7 +221,14 @@ if (refusal !== null) {
 // should not pretend to manage it. The archiver's restore tracker is empty
 // at boot, so this pass is also what repairs restoring zombies — before
 // listen, so no request ever observes one.
-const repaired = await reconcile(db, executor, locks, undefined, archiver);
+const repaired = await reconcile(
+  db,
+  executor,
+  locks,
+  undefined,
+  archiver,
+  watchers,
+);
 app.log.info(repaired, 'startup reconcile');
 recordActivity(db, {
   kind: 'daemon-started',
@@ -232,6 +243,32 @@ recordActivity(db, {
 // the daemon to the outside world is a reverse proxy's job.
 await app.listen({ host: '127.0.0.1', port: config.DORMICE_PORT });
 
+// systemd stops the daemon with SIGTERM. Route both terminal signals through
+// Fastify so preClose can end long-lived streams and reap watcher ownership
+// before Node exits. The first signal owns shutdown; a second one still has
+// the platform's default behavior instead of leaving a wedged process forever.
+let closing = false;
+let heartbeatTimer: NodeJS.Timeout | undefined;
+let metricsTimer: NodeJS.Timeout | undefined;
+const close = async (signal: NodeJS.Signals) => {
+  if (closing) return;
+  closing = true;
+  process.removeListener('SIGTERM', onSigterm);
+  process.removeListener('SIGINT', onSigint);
+  clearTimeout(heartbeatTimer);
+  clearTimeout(metricsTimer);
+  try {
+    await app.close();
+  } catch (error) {
+    app.log.error(error, `graceful shutdown after ${signal} failed`);
+    process.exitCode = 1;
+  }
+};
+const onSigterm = () => void close('SIGTERM');
+const onSigint = () => void close('SIGINT');
+process.once('SIGTERM', onSigterm);
+process.once('SIGINT', onSigint);
+
 // The daemon's heartbeat: reconcile, then scan. Reconciling every tick is
 // what keeps the ledger honest while the daemon runs — a sandbox whose
 // container died under it (a gVisor box exits whole on OOM, leaving an
@@ -249,7 +286,14 @@ await app.listen({ host: '127.0.0.1', port: config.DORMICE_PORT });
 let suspects: ReadonlySet<string> = new Set();
 async function tick() {
   try {
-    const drift = await reconcile(db, executor, locks, suspects, archiver);
+    const drift = await reconcile(
+      db,
+      executor,
+      locks,
+      suspects,
+      archiver,
+      watchers,
+    );
     suspects = new Set(drift.suspects);
     if (
       drift.repairedStates +
@@ -261,17 +305,29 @@ async function tick() {
     ) {
       app.log.warn(drift, 'runtime reconcile repaired drift');
     }
-    const scan = await scanOnce(db, executor, locks, new Date(), archiver);
+    const scan = await scanOnce(
+      db,
+      executor,
+      locks,
+      new Date(),
+      archiver,
+      watchers,
+    );
     for (const failure of scan.failures) {
       app.log.error(failure, 'idle scan: sandbox transition failed');
     }
   } catch (error) {
     app.log.error(error, 'heartbeat tick failed');
   } finally {
-    setTimeout(tick, config.DORMICE_SCAN_INTERVAL_SECONDS * 1000);
+    if (!closing) {
+      heartbeatTimer = setTimeout(
+        tick,
+        config.DORMICE_SCAN_INTERVAL_SECONDS * 1000,
+      );
+    }
   }
 }
-setTimeout(tick, config.DORMICE_SCAN_INTERVAL_SECONDS * 1000);
+heartbeatTimer = setTimeout(tick, config.DORMICE_SCAN_INTERVAL_SECONDS * 1000);
 
 // The metrics sampler's own chained ticker — deliberately not a passenger
 // on the heartbeat, whose ticks legitimately run 45s+ (memory.reclaim) and
@@ -296,10 +352,12 @@ async function metricsTick() {
   } catch (error) {
     app.log.error(error, 'metrics sampler tick failed');
   } finally {
-    setTimeout(
-      metricsTick,
-      config.DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS * 1000,
-    );
+    if (!closing) {
+      metricsTimer = setTimeout(
+        metricsTick,
+        config.DORMICE_METRICS_SAMPLE_INTERVAL_SECONDS * 1000,
+      );
+    }
   }
 }
-setTimeout(metricsTick, 0);
+metricsTimer = setTimeout(metricsTick, 0);
diff --git a/packages/server/src/reconciler.test.ts b/packages/server/src/reconciler.test.ts
index 097c252..c1023bb 100644
--- a/packages/server/src/reconciler.test.ts
+++ b/packages/server/src/reconciler.test.ts
@@ -5,6 +5,7 @@ import { describe, expect, it } from 'vitest';
 import { type Db, migrateDb, openDb } from './db/db';
 import { createSandbox, findByName, transition } from './db/ledger';
 import type { SandboxRow } from './db/schema';
+import { WatcherTable } from './e2b/watcher-table';
 import { FakeExecutor } from './executor/fake';
 import { KeyedQueue } from './keyed-queue';
 import { reconcile } from './reconciler';
@@ -66,17 +67,32 @@ describe('startup reconcile', () => {
     expect(findByName(db, 'alice')?.state).toBe('frozen');
   });
 
-  it('repairs across rungs the transition table would forbid', async () => {
+  it('repairs across rungs and drops ownership when reality is stopped', async () => {
     const { db, executor, locks } = setup();
     // Ledger says active, container is fully stopped — a two-rung gap that
     // transition() would reject. The reconciler records facts, not moves.
     const row = await seed(db, executor, 'alice');
+    const watchers = new WatcherTable();
+    await watchers.create({
+      executor,
+      sandboxId: row.id,
+      path: '/home/user',
+      recursive: false,
+    });
     await executor.freeze(row.id);
     await executor.stop(row.id);
 
-    const result = await reconcile(db, executor, locks);
+    const result = await reconcile(
+      db,
+      executor,
+      locks,
+      undefined,
+      undefined,
+      watchers,
+    );
     expect(result).toEqual({ ...NONE, repairedStates: 1 });
     expect(findByName(db, 'alice')?.state).toBe('stopped');
+    expect(watchers.count(row.id)).toBe(0);
   });
 
   it('keeps the row of a pruned container: the disk is the sandbox', async () => {
diff --git a/packages/server/src/reconciler.ts b/packages/server/src/reconciler.ts
index dfb21b5..27e242e 100644
--- a/packages/server/src/reconciler.ts
+++ b/packages/server/src/reconciler.ts
@@ -8,6 +8,7 @@ import {
   overwriteState,
 } from './db/ledger';
 import type { SandboxRow } from './db/schema';
+import type { WatcherTable } from './e2b/watcher-table';
 import type { ContainerState, Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
 
@@ -98,6 +99,7 @@ export async function reconcile(
   locks: KeyedQueue,
   priorSuspects?: ReadonlySet<string>,
   archiver?: { hasLiveRestore(sandboxId: string): boolean },
+  watchers?: WatcherTable,
 ): Promise<ReconcileResult> {
   const rows = listSandboxes(db);
   const containers = await executor.listContainers();
@@ -191,6 +193,7 @@ export async function reconcile(
       owners.add(row.id);
       if (LEDGER_STATE[observed] !== row.state) {
         await repairUnderLock(row, () => {
+          if (observed === 'stopped') watchers?.disposeSandbox(row.id);
           overwriteState(db, row.id, LEDGER_STATE[observed]);
           result.repairedStates += 1;
           note(
@@ -203,6 +206,7 @@ export async function reconcile(
       owners.add(row.id);
       if (row.state !== 'stopped') {
         await repairUnderLock(row, () => {
+          watchers?.disposeSandbox(row.id);
           overwriteState(db, row.id, 'stopped');
           result.repairedStates += 1;
           note(
@@ -213,6 +217,7 @@ export async function reconcile(
       }
     } else {
       await repairUnderLock(row, () => {
+        watchers?.disposeSandbox(row.id);
         deleteSandbox(db, row.id);
         result.deletedRows += 1;
         note(row, 'container and disk both gone — row deleted, key freed');
diff --git a/packages/server/src/routes/sandboxes.ts b/packages/server/src/routes/sandboxes.ts
index e13443e..74771f4 100644
--- a/packages/server/src/routes/sandboxes.ts
+++ b/packages/server/src/routes/sandboxes.ts
@@ -721,7 +721,14 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
             `sandbox "${name}" is ${existing.state} — it has no container to rebuild`,
           );
         }
-        const row = await rebuildSandbox(db, executor, existing, request.actor);
+        const row = await rebuildSandbox(
+          db,
+          executor,
+          existing,
+          request.actor,
+          undefined,
+          watchers,
+        );
         return { sandbox: toSandbox(row, endpoint) };
       });
     },
@@ -902,6 +909,7 @@ export const sandboxRoutes: FastifyPluginAsyncZod<
             cause: 'via destroySandbox',
             actor: request.actor,
           },
+          watchers,
         );
         return { destroyed: true };
       });
diff --git a/packages/server/src/scanner.ts b/packages/server/src/scanner.ts
index afd4bb0..de8a7fe 100644
--- a/packages/server/src/scanner.ts
+++ b/packages/server/src/scanner.ts
@@ -2,6 +2,7 @@ import type { Archiver } from './archive/archiver';
 import type { Db } from './db/db';
 import { findById, listSandboxes } from './db/ledger';
 import type { SandboxRow } from './db/schema';
+import type { WatcherTable } from './e2b/watcher-table';
 import type { Executor } from './executor/executor';
 import type { KeyedQueue } from './keyed-queue';
 import { destroySandbox, freezeSandbox, stopSandbox } from './lifecycle';
@@ -110,6 +111,7 @@ export async function scanOnce(
   locks: KeyedQueue,
   now: Date,
   archiver?: Archiver,
+  watchers?: WatcherTable,
 ): Promise<ScanResult> {
   const result: ScanResult = {
     frozen: 0,
@@ -143,6 +145,7 @@ export async function scanOnce(
             fresh.id,
             archiver?.store ?? null,
             { kind: 'expired-killed', cause: 'E2B deadline (kill) reached' },
+            watchers,
           );
           result.expiredKilled += 1;
           return;
@@ -172,6 +175,8 @@ export async function scanOnce(
             executor,
             fresh.id,
             `idle ${fresh.stopAfterSeconds}s reached — container torn down, disk kept (scanner)`,
+            undefined,
+            watchers,
           );
           result.stopped += 1;
         }
diff --git a/website/content/docs/e2b-differences.mdx b/website/content/docs/e2b-differences.mdx
index b3a08e0..4af6f48 100644
--- a/website/content/docs/e2b-differences.mdx
+++ b/website/content/docs/e2b-differences.mdx
@@ -26,7 +26,7 @@ daemon:
 | `uploadUrl()` / `downloadUrl()` | signed URLs: expiry enforced, a tampered signature is a 401; CORS-open, so a browser can POST/GET them directly — with `DORMICE_SANDBOX_DOMAIN` set, E2B's `49983-<sandboxId>.<domain>/files` form works too |
 | Range requests on downloads | single-range `Range: bytes=…` gets a `206` with `content-range`; downloads advertise `accept-ranges: bytes` — so `<video>` streams and seeks instead of downloading the whole file, and interrupted downloads resume |
 | `files.list` / `exists` / `makeDir` / `rename` / `remove` | typed errors match the SDK's expectations |
-| `files.watchDir` | streamed events, and the polling watcher API the Python sync SDK uses |
+| `files.watchDir` | streamed events, and the polling watcher API the Python sync SDK uses; failed cleanup stays daemon-owned until it converges |
 | `getHost(port)` | port proxy with wake-on-traffic (set `DORMICE_SANDBOX_DOMAIN`) |
 | `getMetrics()` | one live sample; observing never wakes a frozen sandbox |
 | Templates by name | `Sandbox.create('name')` resolves a registered template; an unregistered name is an honest 404 |
@@ -46,6 +46,16 @@ daemon:
 - **`metadata.name`** turns `Sandbox.create` into Dormice's
   idempotent acquire — see
   [Using the official E2B SDKs](/docs/e2b-sdks).
+- **Replay-safe polling watches are opt-in.** `CreateWatcher` accepts the
+  Dormice extension header `x-dormice-watcher-operation-id` with a UUID.
+  Within one sandbox, reusing it with the same normalized path and
+  `recursive` value returns the original watcher ID; changing either is a
+  `409`. The binding lives as long as its watcher, then for a bounded
+  five-minute replay window. The header is outside the protobuf message,
+  so official SDKs remain wire-compatible and keep their native behavior.
+  `RemoveWatcher` is a goal-state operation: any well-formed ID succeeds
+  once it is absent, including retries after cleanup. A daemon restart
+  clears this in-memory identity state, like the process and watcher tables.
 - **One domain, not one subdomain per sandbox.** The SDK addresses
   sandboxes through a header on a single endpoint, so no wildcard DNS is
   needed for the API itself — only `getHost()` preview URLs want a
diff --git a/website/content/docs/upgrading.mdx b/website/content/docs/upgrading.mdx
index 7b130ac..47e5f1b 100644
--- a/website/content/docs/upgrading.mdx
+++ b/website/content/docs/upgrading.mdx
@@ -40,12 +40,13 @@ the repo.
   listening it reconciles its records against what Docker actually
   shows, so restarting it is always safe.
 
-Two footnotes. The E2B process and watcher tables live in daemon
-memory: processes started over that surface keep running inside their
-containers across a restart, but the fresh daemon no longer lists them
-([details](/docs/e2b-differences)). And the pinned toolchain (Node,
-gVisor) is only *installed* when missing — an already-present gVisor is
-kept as-is, not upgraded.
+Two footnotes. The E2B process and watcher registries live in daemon
+memory: processes and in-container watcher processes may outlive a hard
+daemon crash, but the fresh daemon no longer lists or controls those old
+handles; normal graceful shutdown first makes a bounded best-effort
+cleanup pass ([details](/docs/e2b-differences)). And the pinned toolchain
+(Node, gVisor) is only *installed* when missing — an already-present
+gVisor is kept as-is, not upgraded.
 
 ## Upgrade sandbox images
 

From f26ba3748e79c7225f4aafb757c6f9f1f6b2d733 Mon Sep 17 00:00:00 2001
From: Cornna <96944678+ymylive@users.noreply.github.com>
Date: Mon, 27 Jul 2026 01:44:23 -0700
Subject: [PATCH 132/133] Give the upgrade socket an error listener before it
 can be reset
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The http server drops its own socket error handler before emitting
'upgrade', so handleUpgrade receives a bare socket — and then awaited
resolveTarget, which walks locks.run into wakeSandbox and can sit there
for seconds on a cold wake, before attaching any listener of its own. A
TCP reset inside that window is a listener-less 'error' event, which
throws; nothing in the server installs an uncaughtException handler, so
the daemon exits and every in-flight exec, restore and archive dies with
it. handleRequest never had the problem: its ServerResponse keeps the
server's own cleanup.

Only a reset does this — a graceful FIN does not — and an HTTP reverse
proxy absorbs a client's reset rather than passing it upstream, so with
the daemon bound to loopback this is a local robustness defect, not a
remotely reachable one. The realistic trigger is a local client aborting
during a wake.

The listener moves to the first statement, before any await. Its 'error'
twin further down goes away rather than being kept in parallel: the new
listener destroys the socket, and a destroyed socket always reaches
'close', which already runs the same settle() and upstream.destroy().

Verifying the fix against a real daemon turned up the same bug a second
time, in the fake: its echo upstream self-pipes the upgrade socket with
no error listener, so tearing the connection down after a client reset
re-emits 'error' on a pipe destination with zero listeners. The real
executor's upstream is a separate process and cannot take the daemon
down that way, which made the stand-in deadlier than the thing it stands
in for. Both tests are red without their own fix: one resets while the
wake is held in the key slot, the other after the handshake, staggered,
because a single well-timed close does not reproduce it.
---
 packages/server/src/executor/fake.ts      |   6 ++
 packages/server/src/sandbox-proxy.test.ts | 105 ++++++++++++++++++++++
 packages/server/src/sandbox-proxy.ts      |  12 ++-
 3 files changed, 119 insertions(+), 4 deletions(-)

diff --git a/packages/server/src/executor/fake.ts b/packages/server/src/executor/fake.ts
index 1ba6f3d..0f7314f 100644
--- a/packages/server/src/executor/fake.ts
+++ b/packages/server/src/executor/fake.ts
@@ -442,6 +442,12 @@ export class FakeExecutor implements Executor {
         );
       });
       upstream.on('upgrade', (_req, socket) => {
+        // The echo pipe's destination is this socket, so a reset reaching
+        // it would re-emit 'error' with no listener and take the daemon
+        // down — the real executor's upstream is another process and
+        // cannot do that, so without this the fake is deadlier than what
+        // it stands in for.
+        socket.on('error', () => socket.destroy());
         socket.write(
           'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n\r\n',
         );
diff --git a/packages/server/src/sandbox-proxy.test.ts b/packages/server/src/sandbox-proxy.test.ts
index 9013730..4fabc9f 100644
--- a/packages/server/src/sandbox-proxy.test.ts
+++ b/packages/server/src/sandbox-proxy.test.ts
@@ -260,6 +260,111 @@ describe('sandbox port proxy', () => {
     expect(JSON.parse(other.body)).toMatchObject({ sandboxId });
   });
 
+  it('survives a client reset while the upgrade is still waking the sandbox', async () => {
+    const t = await listeningApp();
+    const sandboxId = await createSandbox(t.port);
+    const name = findById(t.db, sandboxId)?.name;
+    if (name === undefined) throw new Error('no sandbox row');
+
+    // Hold the sandbox's lock slot so resolveTarget's own locks.run queues
+    // behind it: the seconds-long window a cold wake really has, made
+    // deterministic. A reset — not a graceful close — is what raises
+    // 'error'; with no listener yet attached it throws out of the
+    // EventEmitter, and the daemon has no uncaughtException handler.
+    let release!: () => void;
+    const occupied = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const slot = t.locks.run(name, () => occupied);
+
+    const crashes: unknown[] = [];
+    const onUncaught = (err: unknown) => crashes.push(err);
+    process.on('uncaughtException', onUncaught);
+    try {
+      const socket = net.connect(t.port, '127.0.0.1', () => {
+        socket.write(
+          [
+            'GET /ws HTTP/1.1',
+            `Host: 5173-${sandboxId}.${DOMAIN}`,
+            'Connection: Upgrade',
+            'Upgrade: websocket',
+            '',
+            '',
+          ].join('\r\n'),
+        );
+      });
+      socket.on('error', () => {
+        // The client end of the reset we are about to send.
+      });
+      // Let the request arrive and park inside handleUpgrade, then reset.
+      await new Promise((r) => setTimeout(r, 100));
+      socket.resetAndDestroy();
+      await new Promise((r) => setTimeout(r, 100));
+      release();
+      await slot;
+      await new Promise((r) => setTimeout(r, 100));
+      expect(crashes).toEqual([]);
+    } finally {
+      process.off('uncaughtException', onUncaught);
+      release();
+    }
+
+    // Still serving: the reset took its own connection down, nothing else.
+    const after = await rawGet(t.port, '/healthz', 'localhost');
+    expect(after.status).toBe(200);
+  });
+
+  it('survives a client reset after the upgrade is established', async () => {
+    const t = await listeningApp();
+    const sandboxId = await createSandbox(t.port);
+
+    // The other half of the window: once the handshake lands, both the
+    // proxy's socket and the upstream's are piped. A reset here reaches
+    // the upstream end too — for the fake that end lives in this process,
+    // so it must be as unkillable as a real container's would be.
+    // Staggered across the handshake rather than one clean case: the reset
+    // has to land while bytes are still moving for the upstream end to see
+    // it as an error, and a single well-timed close does not reproduce it.
+    const crashes: unknown[] = [];
+    const onUncaught = (err: unknown) => crashes.push(err);
+    process.on('uncaughtException', onUncaught);
+    try {
+      await Promise.all(
+        Array.from(
+          { length: 60 },
+          (_, i) =>
+            new Promise<void>((resolve) => {
+              const socket = net.connect(t.port, '127.0.0.1', () => {
+                socket.write(
+                  [
+                    'GET /ws HTTP/1.1',
+                    `Host: 5173-${sandboxId}.${DOMAIN}`,
+                    'Connection: Upgrade',
+                    'Upgrade: websocket',
+                    '',
+                    '',
+                  ].join('\r\n'),
+                );
+                setTimeout(() => {
+                  socket.resetAndDestroy();
+                  resolve();
+                }, i % 10);
+              });
+              socket.on('error', () => resolve());
+              setTimeout(resolve, 3000);
+            }),
+        ),
+      );
+      await new Promise((r) => setTimeout(r, 300));
+      expect(crashes).toEqual([]);
+    } finally {
+      process.off('uncaughtException', onUncaught);
+    }
+
+    const after = await rawGet(t.port, '/healthz', 'localhost');
+    expect(after.status).toBe(200);
+  });
+
   it('passes WebSocket upgrades through, both directions', async () => {
     const t = await listeningApp();
     const sandboxId = await createSandbox(t.port);
diff --git a/packages/server/src/sandbox-proxy.ts b/packages/server/src/sandbox-proxy.ts
index 4d1167d..7bca1a4 100644
--- a/packages/server/src/sandbox-proxy.ts
+++ b/packages/server/src/sandbox-proxy.ts
@@ -209,6 +209,12 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
     },
 
     handleUpgrade(req, socket, head) {
+      // The http server drops its own socket error handler before emitting
+      // 'upgrade', so until this line the socket is one reset away from
+      // throwing a listener-less 'error' and taking the daemon with it —
+      // and resolveTarget below can wait seconds on a cold wake. This is
+      // what handleRequest gets for free from its ServerResponse.
+      socket.on('error', () => socket.destroy());
       void (async () => {
         let resolved: Awaited<ReturnType<typeof resolveTarget>>;
         try {
@@ -256,10 +262,8 @@ export function createSandboxProxy(deps: SandboxProxyDeps): SandboxProxy {
           settle();
           socket.destroy();
         });
-        socket.on('error', () => {
-          settle();
-          upstream.destroy();
-        });
+        // No 'error' twin here: the listener above already destroys the
+        // socket, and a destroyed socket always reaches 'close'.
         socket.on('close', () => {
           settle();
           upstream.destroy();

From 556c91141cfc4c7461aeec88e37b540849b31cfb Mon Sep 17 00:00:00 2001
From: Harsh Jain <hjain4815@gmail.com>
Date: Mon, 27 Jul 2026 21:14:54 +0530
Subject: [PATCH 133/133] fix(executor): return full inspect payload from
 expectState to avoid duplicate container inspect

expectState already performs a full ContainerInspect internally but only
returned the container id, forcing resolvePortTarget to inspect the same
container a second time just to read NetworkSettings. This doubled the
Docker Engine round-trip on every proxied HTTP request and WebSocket
upgrade in sandbox-proxy.

expectState now returns the full ContainerInspectInfo payload. All
existing call sites are updated to read .Id off the returned object.
resolvePortTarget reads NetworkSettings from the same payload instead
of calling .inspect() again. The rejection message contract remains
sole-sourced in contract/lifecycle.ts.
---
 packages/server/src/executor/docker.ts | 59 ++++++++++++++++----------
 1 file changed, 36 insertions(+), 23 deletions(-)

diff --git a/packages/server/src/executor/docker.ts b/packages/server/src/executor/docker.ts
index 5cf0c1c..fe8cf94 100644
--- a/packages/server/src/executor/docker.ts
+++ b/packages/server/src/executor/docker.ts
@@ -174,19 +174,22 @@ export class DockerExecutor implements Executor {
   }
 
   async freeze(sandboxId: string): Promise<void> {
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     await this.docker.getContainer(containerId).pause();
     await this.reclaimMemory(containerId);
   }
 
   async unfreeze(sandboxId: string): Promise<void> {
-    const containerId = await this.expectState(sandboxId, 'paused');
+    const info = await this.expectState(sandboxId, 'paused');
+    const containerId = info.Id;
     // Milliseconds; memory swaps back in lazily, on demand.
     await this.docker.getContainer(containerId).unpause();
   }
 
   async stop(sandboxId: string): Promise<void> {
-    const containerId = await this.expectState(sandboxId, 'paused');
+    const info = await this.expectState(sandboxId, 'paused');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     // Unpause first: a signal cannot be delivered into a paused gVisor
     // sandbox — its guest kernel is stopped along with everything else
@@ -426,8 +429,7 @@ export class DockerExecutor implements Executor {
     sandboxId: string,
     port: number,
   ): Promise<{ host: string; port: number }> {
-    const containerId = await this.expectState(sandboxId, 'running');
-    const info = await this.docker.getContainer(containerId).inspect();
+    const info = await this.expectState(sandboxId, 'running');
     // The bridge address: icc:false only blocks container-to-container
     // traffic, host-to-container stays open (measured on the test machine).
     const networks = info.NetworkSettings?.Networks ?? {};
@@ -498,7 +500,8 @@ export class DockerExecutor implements Executor {
   }
 
   async exec(sandboxId: string, opts: ExecOptions): Promise<ExecResult> {
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     // The deadline lives in-container, via GNU timeout: closing the
     // host-side stream cannot kill the in-container process (measured in
@@ -530,7 +533,8 @@ export class DockerExecutor implements Executor {
     sandboxId: string,
     opts: ExecStreamOptions,
   ): Promise<ExecStreamHandle> {
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     // The pidfile is the handle's way back to the process: /tmp is the
     // sandbox's own, so a leftover file is the sandbox's own garbage — it
@@ -737,7 +741,8 @@ export class DockerExecutor implements Executor {
     files: FileToWrite[],
     user?: string,
   ): Promise<void> {
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     // In array order, failing fast — the batch saves round-trips, it is not
     // a transaction; earlier files stay written, as the protocol documents.
@@ -775,7 +780,8 @@ export class DockerExecutor implements Executor {
     user?: string,
   ): Promise<Buffer> {
     const resolved = resolveSandboxPath(path);
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     const run = await this.runInContainer(container, sandboxId, {
       cmd: [
@@ -827,7 +833,8 @@ export class DockerExecutor implements Executor {
     range?: ByteRange,
   ): Promise<void> {
     const resolved = resolveSandboxPath(path);
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     const stderr = new CappedBuffer(EXEC_OUTPUT_LIMIT_BYTES);
     const started = await this.startInContainer(container, sandboxId, {
@@ -867,7 +874,8 @@ export class DockerExecutor implements Executor {
     user?: string,
   ): Promise<void> {
     const resolved = resolveSandboxPath(path);
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     const run = await this.runInContainer(container, sandboxId, {
       cmd: [
@@ -905,7 +913,8 @@ export class DockerExecutor implements Executor {
     user?: string,
   ): Promise<SandboxEntry[]> {
     const resolved = resolveSandboxPath(path);
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     const run = await this.runInContainer(container, sandboxId, {
       cmd: [
@@ -954,7 +963,8 @@ export class DockerExecutor implements Executor {
     user?: string,
   ): Promise<SandboxEntry> {
     const resolved = resolveSandboxPath(path);
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     const run = await this.runInContainer(container, sandboxId, {
       cmd: [
@@ -987,7 +997,8 @@ export class DockerExecutor implements Executor {
     user?: string,
   ): Promise<boolean> {
     const resolved = resolveSandboxPath(path);
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     const run = await this.runInContainer(container, sandboxId, {
       cmd: [
@@ -1022,7 +1033,8 @@ export class DockerExecutor implements Executor {
   ): Promise<SandboxEntry> {
     const source = resolveSandboxPath(from);
     const destination = resolveSandboxPath(to);
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     const run = await this.runInContainer(container, sandboxId, {
       cmd: [
@@ -1052,7 +1064,8 @@ export class DockerExecutor implements Executor {
 
   async remove(sandboxId: string, path: string, user?: string): Promise<void> {
     const resolved = resolveSandboxPath(path);
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     const run = await this.runInContainer(container, sandboxId, {
       cmd: [
@@ -1083,7 +1096,8 @@ export class DockerExecutor implements Executor {
     opts: WatchDirOptions,
   ): Promise<WatchDirHandle> {
     const resolved = resolveSandboxPath(opts.path);
-    const containerId = await this.expectState(sandboxId, 'running');
+    const info = await this.expectState(sandboxId, 'running');
+    const containerId = info.Id;
     const container = this.docker.getContainer(containerId);
     const pidfile = `/tmp/.dormice-exec-${randomUUID()}.pid`;
 
@@ -1429,24 +1443,23 @@ export class DockerExecutor implements Executor {
   private async expectState(
     sandboxId: string,
     wanted: ContainerState,
-  ): Promise<string> {
+  ): Promise<Docker.ContainerInspectInfo> {
     let actual: ContainerState | undefined;
-    let containerId: string | null = null;
+    let info: Docker.ContainerInspectInfo | null = null;
     try {
-      const info = await this.docker
+      info = await this.docker
         .getContainer(containerName(sandboxId))
         .inspect();
-      containerId = info.Id;
       actual = containerStateFromDocker(info.State.Status);
     } catch (err) {
       if (!isDockerApiError(err) || err.statusCode !== 404) throw err;
     }
-    if (containerId === null || actual !== wanted) {
+    if (info === null || actual !== wanted) {
       throw new Error(
         `container ${sandboxId} is ${actual ?? 'absent'}, expected ${wanted}`,
       );
     }
-    return containerId;
+    return info;
   }
 
   /**